Impostazione della generazione aumentata di recupero (RAG)

watsonx Code Assistant Piano standard

Il RAG è il processo di ottimizzazione dell'output del modello linguistico di grandi dimensioni (LLM) attraverso l'aumento del prompt con il contesto aggiuntivo. Se si invia una query, watsonx Code Assistant utilizza gli strumenti RAG per recuperare le informazioni dalle basi di codice o dalla documentazione. Questo contesto rilevante viene aggiunto alla query prima che venga inviata al modello LLM. Il sistema RAG determina le fonti che devono essere incluse o escluse per generare una risposta con le informazioni più utili.

RAG richiede il piano standard watsonx Code Assistant e l'estensione Visual Studio Code. Non è disponibile per l'uso con il plug-in Eclipse.

IBM watsonx Code Assistant supporta il RAG che migliora la qualità delle risposte alle interrogazioni degli utenti in un contesto pertinente e aggiornato dalle basi di codice e dalla documentazione. Il RAG riduce le allucinazioni del modello e migliora l'accuratezza delle risposte generate.

È possibile configurare watsonx Code Assistant con repository di codice e documentazione di progetto specifici che non sono memorizzati nel repository Git, utilizzando RAG per estrarre le informazioni rilevanti per il messaggio di chat. È possibile configurare la documentazione come documenti API, file readme, documenti tecnici e di progettazione, Markdown, PDF, Word e PowerPoint.

La figura seguente illustra la procedura di configurazione di RAG per watsonx Code Assistant:

Procedura per la creazione di RAG in watsonx Code Assistant

Abilitazione del RAG

Per abilitare il RAG:

Predisporre un archivio vettoriale su IBM Cloud.
1. Predisporre un'istanza del negozio vettoriale Milvus o Elasticsearch sul sito IBM Cloud. Se il negozio di vettori è già disponibile sul vostro IBM Cloud, potete saltare questo passaggio.
  - Per eseguire il provisioning di un'istanza dell'archivio vettoriale Elasticsearch, vedere Provisioning Databases for Elasticsearch.
  - Per eseguire il provisioning di un'istanza dell'archivio vettoriale Milvus, vedere Provisioning watsonx.data.
    
    Milvus è una parte di IBM watsonx.data. È possibile eseguire il provisioning di un'istanza di Milvus con il piano aziendale watsonx.data.
2. Facoltativo: Predisporre un'istanza di IBM watsonx.ai Studio per indicizzare il repository di codice.
Indicizzare o aggiornare i repository di codice in Milvus o Elasticsearch. Per ulteriori informazioni, vedere Indicizzazione dei repository di codice con IBM watsonx.ai Studio.

Impostare le risorse di connessione:
1. Utilizzare lo spazio di distribuzione esistente nell'istanza del servizio watsonx Code Assistant.
2. Creare una risorsa di connessione per ogni indice creato nell'archivio vettoriale. Per ulteriori informazioni, vedere Creazione di una risorsa di connessione.
Impostare il token di accesso personale Git in Visual Studio Code e utilizzare i prompt abilitati per il RAG.
1. Fate clic sull'icona del vostro profilo in GitHub e andate su Impostazioni > Impostazioni sviluppatore > Gettoni di accesso personali > Gettoni (classici).
2. Copiare il token di accesso personale.
3. In Visual Studio Code, fare clic su Visualizza, quindi su Tavolozza dei comandi.
4. Cercare WCA, quindi fare clic su Inserisci GitHub Personal Access Token per WCA.
5. Inserire il token di accesso personale GitHub e premere Enter o Return.
6. Nei messaggi di chat, immettere @repo < instruction > o @docs < instruction > per generare una risposta che utilizza il contesto del repository di riferimento o i documenti dell'archivio vettoriale. Sostituire il parametro < instruction > con un messaggio di richiesta.
- Esempio di sintassi per utilizzare il repository di riferimento:
```
@repo how is a chat message processed?
```
  watsonx Code Assistant utilizza i repository indicizzati in base alle seguenti condizioni:
  - Se un repository è aperto in Visual Studio Code, watsonx Code Assistant cerca il contesto nel repository aperto come predefinito.
  - Se in Visual Studio Code sono aperti più repository, watsonx Code Assistant cerca il contesto del repository associato al file di recente accesso.
  - Watsonx Code Assistant controlla la presenza del file repo.yaml nel repository indicizzato quando si inserisce la sintassi @repo < instruction > nella chat. Se sono configurati uno o più file di configurazione YAML, watsonx Code Assistant utilizza tutti i repository configurati per generare una risposta. Se la configurazione YAML non è configurata, watsonx Code Assistant utilizza il repository selezionato.
- Esempio di sintassi per utilizzare la raccolta di documenti di riferimento:
```
@docs What are the steps to setup a connection to the user data store?
```
  Watsonx Code Assistant utilizza le raccolte di documenti indicizzati in base alle seguenti condizioni:
  - Se il documento viene aperto in Visual Studio Code, watsonx Code Assistant cerca il contesto nel repository aperto come predefinito.
  - Se in Visual Studio Code vengono aperte più raccolte di documenti, watsonx Code Assistant cerca il contesto del documento consultato più di recente.
  - Watsonx Code Assistant controlla la presenza del file docs.yaml nel repository indicizzato quando si inserisce la sintassi @docs < instruction > nella chat. Se sono configurati uno o più file di configurazione YAML, watsonx Code Assistant utilizza tutte le raccolte di documenti configurate per generare una risposta. Se la configurazione YAML non è configurata, watsonx Code Assistant utilizza tutti i documenti con il nome docs_<filename> nello spazio di distribuzione.
Opzionale: se è necessario impostare la configurazione YAML per i repository indicizzati o le raccolte di documenti, vedere Impostazione della configurazione YAML per RAG.

Impostazione della configurazione YAML per RAG

È possibile impostare la configurazione YAML in modo opzionale per consentire a watsonx Code Assistant di cercare più repository contemporaneamente o di usare lo specifico repository di codice indicizzato o il documento nell'archivio vettoriale. Se non si imposta la configurazione YAML, watsonx Code Assistant utilizza il repository aperto in Visual Studio Code come predefinito.

watsonx Code Assistant utilizza il metodo di autorizzazione della chiave API per garantire che si possa accedere solo ai repository o alle raccolte di documenti autorizzati.

Per impostare la configurazione YAML per un repository indicizzato specifico, completare i seguenti passaggi:

Creare una cartella .wca/repo al livello principale del repository.
Creare un file YAML con i seguenti campi:
```
repo:
   - url: git@github.ibm.com:code-assistant/<my-code>.git
```
Se si deve configurare watsonx Code Assistant con più repository, creare un file repo.yaml per ogni repository che deve essere usato per generare una risposta.

Per impostare la configurazione YAML per raccolte di documenti specifiche, completare i passaggi seguenti:

Creare una cartella .wca/docs al livello principale del repository.
Creare un file YAML con i seguenti campi:
```
docs:
   - url: my_collection
```

Scenari d'uso

Gli scenari dei casi d'uso spiegano come funziona RAG e come vengono recuperati i dati da archivi o documenti indicizzati.

Utilizzo di un unico repository di codice

Se si lavora in un singolo repository e si desidera utilizzare il codice di questo repository come contesto per le conversazioni in chat, completare i passaggi seguenti:

Assicurarsi di avere accesso al repository in GitHub.
Indicizza il repository nell'archivio vettoriale. Per maggiori informazioni, vedere Indicizzazione del repository di codice con IBM watsonx.ai Studio
Creare una risorsa di connessione per il repository. Per ulteriori informazioni, vedere Creazione di una risorsa di connessione.
Generare un token di accesso personale Git dal proprio account GitHub e completare la configurazione in Visual Studio Code.
Aprite il repository in Visual Studio Code.
Utilizzare il comando @repo in chat per generare una risposta che utilizzi il contesto del repository.

Utilizzo di più repository di codice

Se si lavora su un repository che ha dipendenze da un altro repository, si può usare il codice di entrambi i repository come contesto per le conversazioni in chat. Per utilizzare entrambi i repository, completare i passaggi seguenti:

Assicurarsi di avere accesso a entrambi i repository in GitHub.
Indicizzare ogni deposito nell'archivio vettoriale separatamente. Per ulteriori informazioni, vedere Indicizzazione del repository di codice con IBM watsonx.ai Studio.
Creare due risorse di connessione per ogni archivio vettoriale. Per ulteriori informazioni, vedere Creazione di una risorsa di connessione.
Generare un token di accesso personale Git dal proprio account GitHub e completare la configurazione in Visual Studio Code.
Nel primo repository, impostare la configurazione YAML per elencare entrambi i repository.
Utilizzare il comando @repo in chat per generare una risposta che utilizzi il contesto di entrambi i repository.

Se si usa lo stesso indice per entrambi i repository, il controllo dell'accesso a GitHub non viene usato per il secondo repository. Se non si ha accesso a uno dei repository, watsonx Code Assistant genera il contesto solo dal repository autorizzato.

Permettere a tutti gli utenti di un team di accedere ai repository della documentazione del progetto

È possibile consentire a tutti gli utenti di un team di accedere agli archivi della documentazione del progetto e utilizzare i documenti come contesto per le conversazioni in chat.

Per abilitare l'accesso a tutti gli utenti:

Indicizza i repository della documentazione del progetto nell'archivio vettoriale. Per ulteriori informazioni, vedere Indicizzazione del repository di codice con IBM watsonx.ai Studio.

È possibile utilizzare lo stesso indice per tutti i repository di documentazione se tutti gli utenti hanno accesso ai repository di documentazione del progetto indicizzati. Se gli utenti hanno una restrizione di accesso per il repository indicizzato, vedere Abilitazione degli utenti di un altro sottoteam ad accedere ai repository della documentazione del progetto.
Creare un asset di connessione per l'indice di documentazione nello spazio di distribuzione che includa tutti gli utenti del team. Per ulteriori informazioni, vedere Creazione di una risorsa di connessione.
Usare il comando @docs in chat per generare una risposta che utilizzi il contesto dall'indice della documentazione.

I token di accesso personali GitHub non vengono utilizzati per verificare l'accesso ai contenuti della documentazione. È possibile combinare diversi repository di documentazione nello stesso indice dell'archivio vettoriale. Il contenuto della documentazione è meno restrittivo dei repository di codice e un unico indice per tutti i repository di documentazione semplifica il processo di gestione dell'indice. L'autorizzazione ad accedere ai repository di documentazione è consentita solo agli utenti inseriti nello spazio di distribuzione.

Consentire agli utenti di un diverso sottogruppo di accedere ai repository della documentazione del progetto

In questo caso d'uso, diversi sottogruppi di un grande team gestiscono gli archivi della documentazione del progetto. L'accesso ai repository di documentazione è limitato ai diversi sottogruppi. Altri sottogruppi non hanno accesso a questi archivi di documentazione.

Per consentire a ciascun sottogruppo di accedere ai relativi archivi di documentazione del progetto:

Indicizzare i repository di documentazione separatamente nell'archivio vettoriale. Per ulteriori informazioni, vedere Indicizzazione del repository di codice con IBM watsonx.ai Studio.
Assicuratevi che lo spazio di distribuzione sia creato per ogni sottogruppo che include i suoi utenti.
Per ogni indice del repository di documentazione, creare una risorsa di connessione nel relativo spazio di distribuzione. Per ulteriori informazioni, vedere Creazione di una risorsa di connessione.
Usare il comando @docs in chat per generare una risposta che utilizzi il contesto dall'indice della documentazione.

Watsonx Code Assistant utilizza l'indice del repository della documentazione in base allo spazio di distribuzione assegnato agli utenti. La configurazione lato client non è necessaria.

Consentire agli utenti basati sui ruoli di accedere ai repository di documentazione del progetto

In questo caso d'uso, gli utenti di un team devono accedere a diversi set di documentazione in base al loro ruolo. L'ambito della documentazione utilizzata come contesto varia tra gli utenti senza restrizioni di accesso. Ad esempio, gli sviluppatori hanno bisogno solo di documentazione tecnica e API, mentre gli analisti aziendali si concentrano sui documenti dei processi aziendali.

Per personalizzare i repository di documentazione usati come contesto:

Indicizzare ogni repository di documentazione nell'archivio vettoriale separatamente. Per ulteriori informazioni, vedere Indicizzazione del repository di codice con IBM watsonx.ai Studio.
Creare una risorsa di connessione per ogni indice nello spazio di distribuzione del team. Per ulteriori informazioni, vedere Creazione di una risorsa di connessione.
Impostare la configurazione YAML per l'indice di documentazione richiesto, usato come contesto. Se si vogliono usare più indici di documentazione, impostare la configurazione YAML per ogni indice di documentazione.
Usare il comando @docs in chat per generare una risposta che utilizzi il contesto dall'indice della documentazione.