Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Utilizza un database Weaviate con RAG Engine

Questa pagina mostra come connettere il corpus di RAG Engine al database Weaviate.

Puoi anche seguire la procedura utilizzando questo blocco note RAG Engine con Weaviate.

Puoi utilizzare l'istanza del database Weaviate, che è un database open source, con RAG Engine per indicizzare ed eseguire una ricerca di somiglianza basata su vettori. Una ricerca di somiglianze è un modo per trovare parti di testo simili al testo che stai cercando, il che richiede l'uso di un modello di embedding. Il modello di embedding produce dati vettoriali per ogni parte di testo confrontata. La ricerca per somiglianza viene utilizzata per recuperare i contesti semantici per il grounding, in modo da restituire i contenuti più accurati dall'LLM.

Con RAG Engine, puoi continuare a utilizzare l'istanza del database vettoriale completamente gestita, di cui sei responsabile del provisioning. RAG Engine utilizza il database vettoriale per l'archiviazione, la gestione degli indici e la ricerca.

Considerazioni

Prima di utilizzare il database Weaviate, considera i seguenti passaggi:

Devi creare, configurare ed eseguire il deployment dell'istanza e della raccolta del database Weaviate. Segui le istruzioni riportate in Crea la tua raccolta Weaviate per configurare una raccolta basata sul tuo schema.
Devi fornire una chiave API Weaviate, che consente a RAG Engine di interagire con il database Weaviate. Il motore RAG supporta AuthN e AuthZ basati su chiavi API, che si connettono al tuo database Weaviate e supportano una connessione HTTPS.
RAG Engine non archivia né gestisce la tua chiave API Weaviate. Devi invece:
1. Archivia la chiave in Google Cloud Secret Manager.
2. Concedi al account di servizio del tuo progetto le autorizzazioni per accedere al secret.
3. Fornisci a RAG Engine l'accesso al nome della risorsa del secret.
4. Quando interagisci con il tuo database Weaviate, RAG Engine accede alla tua risorsa secret utilizzando il tuo account di servizio.
Il corpus di RAG Engine e la raccolta Weaviate hanno una mappatura uno a uno. I file RAG sono archiviati in una raccolta di database Weaviate. Quando viene effettuata una chiamata all'API CreateRagCorpus o all'API UpdateRagCorpus, il corpus RAG viene associato alla raccolta del database.
Oltre alle ricerche semantiche basate su dense embedding, la ricerca ibrida è supportata anche con RAG Engine tramite un database Weaviate. Puoi anche regolare il peso tra la somiglianza vettoriale densa e sparsa in una ricerca ibrida.

Esegui il provisioning del database Weaviate

Prima di utilizzare il database Weaviate con RAG Engine, devi:

Configura ed esegui il deployment dell'istanza del database Weaviate.
Prepara l'endpoint HTTPS.
Crea la tua raccolta Weaviate.
Utilizza la tua chiave API per eseguire il provisioning di Weaviate utilizzando AuthN e AuthZ.
Esegui il provisioning del account di servizio RAG Engine.

Configura ed esegui il deployment dell'istanza del database Weaviate

Devi seguire la guida rapida ufficiale di Weaviate. Tuttavia, puoi utilizzare la guida diGoogle Cloud Marketplace, che è facoltativa.

Puoi configurare l'istanza Weaviate ovunque, purché l'endpoint Weaviate sia accessibile per la configurazione e il deployment nel tuo progetto. Puoi quindi gestire completamente l'istanza del database Weaviate.

Poiché RAG Engine non è coinvolto in nessuna fase del ciclo di vita dell'istanza del database Weaviate, è tua responsabilità concedere le autorizzazioni a RAG Engine in modo che possa archiviare e cercare dati nel tuo database Weaviate. È inoltre tua responsabilità assicurarti che i dati nel tuo database possano essere utilizzati dal motore RAG. Ad esempio, se modifichi i dati, il motore RAG non è responsabile di eventuali comportamenti imprevisti dovuti a queste modifiche.

Prepara l'endpoint HTTPS

Durante il provisioning di Weaviate, assicurati di creare un endpoint HTTPS. Sebbene le connessioni HTTP siano supportate, preferiamo che il traffico del database RAG Engine e Weaviate utilizzi una connessione HTTPS.

Crea la tua raccolta Weaviate

Poiché il corpus di RAG Engine e la raccolta Weaviate hanno una mappatura uno a uno, devi creare una raccolta nel tuo database Weaviate prima di associarla al corpus di RAG Engine. Questa associazione una tantum viene effettuata quando chiami l'API CreateRagCorpus o l'API UpdateRagCorpus.

Quando crei una raccolta in Weaviate, devi utilizzare il seguente schema:

Nome proprietà	Tipo di dati
`fileId`	`text`
`corpusId`	`text`
`chunkId`	`text`
`chunkDataType`	`text`
`chunkData`	`text`
`fileOriginalUri`	`text`

Utilizza la tua chiave API per eseguire il provisioning di Weaviate utilizzando `AuthN` e `AuthZ`

Il provisioning della chiave API Weaviate prevede i seguenti passaggi:

Crea la chiave API Weaviate.
Configura Weaviate utilizzando la tua chiave API Weaviate.
Archivia la chiave API Weaviate in Secret Manager.

Crea la chiave API

Il motore RAG può connettersi alle istanze del database Weaviate solo utilizzando la tua chiave API per l'autenticazione e l'autorizzazione. Devi seguire la guida ufficiale di Weaviate all'autenticazione per configurare l'autenticazione basata su chiave API nell'istanza del database Weaviate.

Se la creazione della chiave API Weaviate richiede informazioni sull'identità da associare provenienti da RAG Engine, devi creare il tuo primo corpus e utilizzare il tuo account di servizio RAG Engine come identità.

Archivia la chiave API in Secret Manager

Una chiave API contiene informazioni sensibili che consentono l'identificazione personale (SPII), soggette a requisiti legali. Se i dati SPII vengono compromessi o utilizzati in modo improprio, un individuo potrebbe subire un rischio o un danno significativo. Per ridurre al minimo i rischi per un individuo durante l'utilizzo di RAG Engine, non archiviare e gestire la chiave API ed evita di condividere la chiave API non criptata.

Per proteggere le SPII, segui questi passaggi:

Archivia la chiave API in Secret Manager.
Concedi al tuo account di servizio RAG Engine le autorizzazioni per i tuoi secret e gestisci il controllo dell'accesso a livello di risorsa secret.
1. Vai alle autorizzazioni del progetto.
2. Attiva l'opzione Includi concessioni di ruoli fornite da Google.
3. Trova il account di servizio, che ha il formato
  service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
4. Modifica le entità del account di servizio.
5. Aggiungi il ruolo Secret Manager Secret Accessor al service account.
Durante la creazione o l'aggiornamento del corpus RAG, passa il nome della risorsa secret a RAG Engine e memorizzalo.

Quando effettui richieste API alle tue istanze di database Weaviate, RAG Engine utilizza ogni account di servizio per leggere la chiave API corrispondente alle tue risorse secret in Secret Manager dai tuoi progetti.

Esegui il provisioning del account di servizio RAG Engine

Quando crei la prima risorsa nel progetto, il motore RAG crea un account di servizio dedicato. Puoi trovare il tuo account di servizio nella pagina IAM del progetto. Il account di servizio ha il seguente formato:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Ad esempio, service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com.

Durante l'integrazione con il database Weaviate, il tuo account di servizio viene utilizzato nei seguenti scenari:

Puoi utilizzare il tuo account di servizio per generare la chiave API Weaviate per l'autenticazione. In alcuni casi, la generazione della chiave API non richiede informazioni sull'utente, il che significa che non è necessario un account di servizio per generare la chiave API.
Puoi associare il account di servizio alla chiave API nel database Weaviate per configurare l'autenticazione (AuthN) e l'autorizzazione (AuthZ). Tuttavia, il account di servizio non è obbligatorio.
Puoi archiviare la chiave API in Secret Manager nel tuo progetto e concedere al tuo account di servizio le autorizzazioni per queste risorse secret.
RAG Engine utilizza i service account per accedere alla chiave API da Secret Manager nei tuoi progetti.

Configura l'ambiente della console Google Cloud

Fai clic per scoprire come configurare l'ambiente

Scopri come configurare l'ambiente selezionando una delle seguenti schede:

Python

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment di workload.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Nota: se hai familiarità con l'API Gemini in Google AI Studio, tieni presente che l'API Gemini per Agent Platform utilizza Identity and Access Management anziché le chiavi API per gestire l'accesso.
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
```
gcloud auth application-default login
```
Non è necessario farlo se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.
Installa o aggiorna l'SDK Agent Platform per Python eseguendo questo comando:
```
pip3 install --upgrade "google-cloud-aiplatform>=1.38"
    
```

Node.js

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Nota: se hai familiarità con l'API Gemini in Google AI Studio, tieni presente che l'API Gemini per Agent Platform utilizza Identity and Access Management anziché le chiavi API per gestire l'accesso.
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
```
gcloud auth application-default login
```
Non è necessario farlo se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.
Installa o aggiorna l'SDK Agent Platform per Node.js eseguendo questo comando:
```
npm install @google-cloud/vertexai
    
```

Java

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Nota: se hai familiarità con l'API Gemini in Google AI Studio, tieni presente che l'API Gemini per Agent Platform utilizza Identity and Access Management anziché le chiavi API per gestire l'accesso.
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
```
gcloud auth application-default login
```
Non è necessario farlo se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

Per aggiungere google-cloud-vertexai come dipendenza, aggiungi il codice appropriato per il tuo ambiente:

Maven con BOM

Aggiungi il seguente codice HTML al tuo pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>
<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-vertexai</artifactId>
  </dependency>
</dependencies>

Maven senza BOM

Aggiungi il seguente codice HTML al tuo pom.xml:

<dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>google-cloud-vertexai</artifactId>
  <version>0.4.0</version>
</dependency>

Gradle senza BOM

Aggiungi quanto segue al tuo file build.gradle:

implementation 'com.google.cloud:google-cloud-vertexai:0.4.0'

Go

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Nota: se hai familiarità con l'API Gemini in Google AI Studio, tieni presente che l'API Gemini per Agent Platform utilizza Identity and Access Management anziché le chiavi API per gestire l'accesso.
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
```
gcloud auth application-default login
```
Non è necessario farlo se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.
Esamina i pacchetti Go dell'API Agent Platform disponibili per determinare quale pacchetto soddisfa meglio le esigenze del tuo progetto:
- Pacchetto cloud.google.com/go/vertexai (consigliato)
  
  vertexai è un pacchetto creato da un essere umano che fornisce l'accesso a funzionalità e caratteristiche comuni.
  
  Questo pacchetto è consigliato come punto di partenza per la maggior parte degli sviluppatori che creano con l'API Agent Platform. Per accedere a funzionalità e caratteristiche non ancora coperte da questo pacchetto, utilizza invece il aiplatform generato automaticamente.
- Pacchetto cloud.google.com/go/aiplatform
  
  aiplatform è un pacchetto generato automaticamente.
  
  Questo pacchetto è destinato ai progetti che richiedono l'accesso alle funzionalità dell'API Agent Platform non ancora fornite dal pacchetto vertexai creato da persone.

Installa il pacchetto Go desiderato in base alle esigenze del tuo progetto eseguendo uno dei seguenti comandi:

# Human authored package. Recommended for most developers.
go get cloud.google.com/go/vertexai
    

# Auto-generated package.
go get cloud.google.com/go/aiplatform

C#

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Nota: se hai familiarità con l'API Gemini in Google AI Studio, tieni presente che l'API Gemini per Agent Platform utilizza Identity and Access Management anziché le chiavi API per gestire l'accesso.
Se utilizzi una shell locale, crea credenziali di autenticazione locali per il tuo account utente:
```
gcloud auth application-default login
```
Non è necessario farlo se utilizzi Cloud Shell.

Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver eseguito l'accesso a gcloud CLI con la tua identità federata.

REST

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.

Roles required to enable APIs

Enable the API

Nella console Google Cloud , attiva Cloud Shell.

Attiva Cloud Shell

Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

Nota: se hai familiarità con l'API Gemini in Google AI Studio, tieni presente che l'API Gemini per Agent Platform utilizza Identity and Access Management anziché le chiavi API per gestire l'accesso.
Configura le variabili di ambiente inserendo quanto segue. Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud .
```
MODEL_ID="gemini-3.5-flash"
PROJECT_ID="PROJECT_ID"
    
```

Esegui il provisioning dell'endpoint:

gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}

(Facoltativo) Se utilizzi Cloud Shell e ti viene chiesto di autorizzarlo, fai clic su Autorizza.

Prepara il corpus RAG

Per accedere ai dati del tuo database Weaviate, RAG Engine deve avere accesso a un corpus RAG. Questa sezione fornisce i passaggi per creare un singolo corpus RAG e altri corpora RAG.

Utilizza le API `CreateRagCorpus` e `UpdateRagCorpus`

Quando chiami le API CreateRagCorpus e UpdateRagCorpus, devi specificare i seguenti campi:

rag_vector_db_config.weaviate: dopo aver chiamato l'API CreateRagCorpus, viene scelta la configurazione del database vettoriale. La configurazione del database vettoriale contiene tutti i campi di configurazione. Se il campo rag_vector_db_config.weaviate non è impostato, per impostazione predefinita viene utilizzato rag_vector_db_config.rag_managed_db.
weaviate.http_endpoint: l'endpoint Weaviate HTTPS o HTTP viene creato durante il provisioning dell'istanza del database Weaviate.
weaviate.collection_name: il nome della raccolta creata durante il provisioning dell'istanza Weaviate. Il nome deve iniziare con una lettera maiuscola.
api_auth.api_key_config: la configurazione specifica di utilizzare una chiave API per autorizzare l'accesso al database vettoriale.
api_key_config.api_key_secret_version: il nome della risorsa del secret archiviato in Secret Manager, che contiene la tua chiave API Weaviate.

Puoi creare e associare il corpus RAG alla raccolta Weaviate nell'istanza del database. Tuttavia, potresti aver bisogno del account di servizio per generare la chiave API e configurare l'istanza del database Weaviate. Quando crei il tuo primo corpus RAG, viene generato il account di servizio. Dopo aver creato il tuo primo corpus RAG, l'associazione tra il database Weaviate e la chiave API potrebbe non essere pronta per l'uso nella creazione di un altro corpus RAG.

Nel caso in cui il database e la chiave non siano pronti per essere associati al corpus RAG, segui questi passaggi per il corpus RAG:

Imposta il campo weaviate su rag_vector_db_config.
- Non puoi modificare il database vettoriale associato.
- Lascia vuoti i campi http_endpoint e collection_name. Entrambi i campi possono essere aggiornati in un secondo momento.
Se non hai archiviato la chiave API in Secret Manager, puoi lasciare vuoto il campo api_auth. Quando chiami l'API UpdateRagCorpus, puoi aggiornare il campo api_auth. Weaviate richiede che venga eseguito quanto segue:
1. Imposta api_key_config nel campo api_auth.
2. Imposta il api_key_secret_version della chiave API Weaviate in Secret Manager. Il campo api_key_secret_version utilizza il seguente formato:
  
  projects/{project}/secrets/{secret}/versions/{version}
Se specifichi campi che possono essere impostati una sola volta, come http_endpoint o collection_name, non puoi modificarli a meno che non elimini il corpus RAG e lo crei di nuovo. Altri campi, come il campo della chiave API, api_key_secret_version, possono essere aggiornati.
Quando chiami UpdateRagCorpus, puoi impostare il campo vector_db. vector_db deve essere impostato su weaviate dalla chiamata API CreateRagCorpus. In caso contrario, il sistema sceglie l'opzione Database gestito RAG, che è l'impostazione predefinita. Questa opzione non può essere modificata quando chiami l'API UpdateRagCorpus. Quando chiami UpdateRagCorpus e il campo vector_db è parzialmente impostato, puoi aggiornare i campi contrassegnati come Modificabile (indicati anche come mutabili).

Questa tabella elenca i campi modificabili e immutabili di WeaviateConfig utilizzati nel codice.

Nome campo	Modificabile o immutabile
`http_endpoint`	Immutabile una volta impostato
`collection_name`	Immutabile una volta impostato
`api_key_authentication`	Modificabile

Crea il primo corpus RAG

Se il account di servizio del motore RAG non esiste, segui questi passaggi:

Crea un corpus RAG in RAG Engine con una configurazione Weaviate vuota, che avvia il provisioning di RAG Engine per creare un account di servizio.
Scegli un nome per il account di servizio del motore RAG che segua questo formato:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com

Ad esempio, service-123456789@gcp-sa-vertex-rag.iam.gserviceaccount.com.
Utilizzando il tuo account di servizio, accedi al secret archiviato in Secret Manager del tuo progetto, che contiene la tua chiave API Weaviate.
Dopo aver completato il provisioning di Weaviate, ottieni le seguenti informazioni:
- Il tuo endpoint HTTPS o HTTP Weaviate.
- Il nome della tua raccolta Weaviate.
Chiama l'API CreateRagCorpus per creare un corpus RAG con una configurazione Weaviate vuota e chiama l'API UpdateRagCorpus per aggiornare il corpus RAG con le seguenti informazioni:
- Il tuo endpoint HTTPS o HTTP Weaviate.
- Il nome della tua raccolta Weaviate.
- Il nome della risorsa della chiave API.

Crea un altro corpus RAG

Quando il account di servizio RAG Engine esiste, segui questi passaggi:

Recupera il account di servizio RAG Engine dalle autorizzazioni del progetto.
Attiva l'opzione "Includi concessioni di ruoli fornite da Google"
Scegli un nome per il account di servizio del motore RAG che segua questo formato:

service-{project number}@gcp-sa-vertex-rag.iam.gserviceaccount.com
Utilizzando il tuo account di servizio, accedi al secret archiviato in Secret Manager del tuo progetto, che contiene la tua chiave API Weaviate.
Durante il provisioning di Weaviate, ottieni le seguenti informazioni:
- L'endpoint HTTPS o HTTP di Weaviate.
- Il nome della tua raccolta Weaviate.
Crea un corpus RAG in RAG Engine e connettiti alla tua raccolta Weaviate eseguendo una delle seguenti operazioni:
1. Effettua una chiamata API CreateRagCorpus per creare un corpus RAG con una configurazione Weaviate compilata, che è l'opzione preferita.
2. Effettua una chiamata API CreateRagCorpus per creare un corpus RAG con una configurazione Weaviate vuota ed effettua una chiamata API UpdateRagCorpus per aggiornare il corpus RAG con le seguenti informazioni:
  - Endpoint HTTP del database Weaviate
  - Nome della raccolta Weaviate
  - Chiave API

Esempi

Questa sezione presenta un codice campione che mostra come configurare il database Weaviate, Secret Manager, il corpus RAG e il file RAG. Viene fornito anche un codice campione per mostrare come importare i file, recuperare il contesto, generare contenuti ed eliminare il corpus RAG e i file RAG.

Per utilizzare il blocco note dell'API RAG di Model Garden, consulta Utilizza Weaviate con Llama 3.

Configura il database Weaviate

Questo esempio di codice mostra come configurare i dati di Weaviate e Secret Manager.

REST

# TODO(developer): Update the variables.
# The HTTPS/HTTP Weaviate endpoint you created during provisioning.
HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"

# Select your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
# For example, "MyCollectionName"
# Note that the first letter needs to be capitalized.
# Otherwise, Weavaite will capitalize it for you.
WEAVIATE_COLLECTION_NAME="MyCollectionName"

# Create a collection in Weaviate which includes the required schema fields shown below.
echo '{
  "class": "'${WEAVIATE_COLLECTION_NAME}'",
  "properties": [
    { "name": "fileId", "dataType": [ "string" ] },
    { "name": "corpusId", "dataType": [ "string" ] },
    { "name": "chunkId", "dataType": [ "string" ] },
    { "name": "chunkDataType", "dataType": [ "string" ] },
    { "name": "chunkData", "dataType": [ "string" ] },
    { "name": "fileOriginalUri", "dataType": [ "string" ] }
  ]
}' | curl \
    -X POST \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer "${WEAVIATE_API_KEY} \
    -d @- \
    ${HTTP_ENDPOINT_NAME}/v1/schema

Configura Secret Manager

Per configurare Secret Manager, devi abilitarlo e impostare le autorizzazioni.

Crea secret

Per attivare Secret Manager:

Console

Vai alla pagina Secret Manager.
Vai a Secret Manager
Fai clic su + Crea secret.
Inserisci il nome del secret. I nomi dei secret possono contenere solo lettere latine (A-Z), numeri (0-9), trattini (-) e trattini bassi (_).
La specifica dei seguenti campi è facoltativa:
1. Per caricare il file con il secret, fai clic su Sfoglia.
2. Leggi la policy di replica.
3. Se vuoi gestire manualmente le località per il secret, seleziona Gestisci manualmente le località per questo secret. Devi selezionare almeno una regione.
4. Seleziona l'opzione di crittografia.
5. Se vuoi impostare manualmente il periodo di rotazione, seleziona Imposta periodo di rotazione.
6. Se vuoi specificare gli argomenti di pubblicazione o sottoscrizione per ricevere le notifiche degli eventi, fai clic su Aggiungi argomenti.
7. Per impostazione predefinita, il secret non ha scadenza. Se vuoi impostare una data di scadenza, seleziona Imposta data di scadenza.
8. Per impostazione predefinita, le versioni del secret vengono eliminate al momento della richiesta. Per ritardare l'eliminazione delle versioni dei secret, seleziona Imposta la durata per l'eliminazione ritardata.
9. Se vuoi utilizzare le etichette per organizzare e categorizzare i secret, fai clic su + Aggiungi etichetta.
10. Se vuoi utilizzare le annotazioni per collegare ai tuoi secret metadati non identificativi, fai clic su + Aggiungi annotazione.
Fai clic su Crea secret.

REST

# Create a secret in SecretManager.
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets?secretId=${SECRET_NAME}" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"replication\": {\"automatic\": {}}}"

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

# Import the Secret Manager client library.
from google.cloud import secretmanager


def create_secret(
    project_id: str, secret_id: str, ttl: Optional[str] = None
) -> secretmanager.Secret:
    """
    Create a new secret with the given name. A secret is a logical wrapper
    around a collection of secret versions. Secret versions hold the actual
    secret material.

     Args:
        project_id (str): The project ID where the secret is to be created.
        secret_id (str): The ID to assign to the new secret. This ID must be unique within the project.
        ttl (Optional[str]): An optional string that specifies the secret's time-to-live in seconds with
                             format (e.g., "900s" for 15 minutes). If specified, the secret
                             versions will be automatically deleted upon reaching the end of the TTL period.

    Returns:
        secretmanager.Secret: An object representing the newly created secret, containing details like the
                              secret's name, replication settings, and optionally its TTL.

    Example:
        # Create a secret with automatic replication and no TTL
        new_secret = create_secret("my-project", "my-new-secret")

        # Create a secret with a TTL of 30 days
        new_secret_with_ttl = create_secret("my-project", "my-timed-secret", "7776000s")
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent project.
    parent = f"projects/{project_id}"

    # Create the secret.
    response = client.create_secret(
        request={
            "parent": parent,
            "secret_id": secret_id,
            "secret": {"replication": {"automatic": {}}, "ttl": ttl},
        }
    )

    # Print the new secret name.
    print(f"Created secret: {response.name}")

Imposta le autorizzazioni

Devi concedere le autorizzazioni di Secret Manager al tuo account di servizio.

Console

Nella sezione IAM e amministrazione della console Google Cloud , individua il tuo service account e fai clic sull'icona a forma di matita per modificarlo.
Nel campo Ruolo, seleziona Secret Manager Secret Accessor.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

def iam_grant_access(
    project_id: str, secret_id: str, member: str
) -> iam_policy_pb2.SetIamPolicyRequest:
    """
    Grant the given member access to a secret.
    """

    # Import the Secret Manager client library.
    from google.cloud import secretmanager

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the secret.
    name = client.secret_path(project_id, secret_id)

    # Get the current IAM policy.
    policy = client.get_iam_policy(request={"resource": name})

    # Add the given member with access permissions.
    policy.bindings.add(role="roles/secretmanager.secretAccessor", members=[member])

    # Update the IAM Policy.
    new_policy = client.set_iam_policy(request={"resource": name, "policy": policy})

    # Print data about the secret.
    print(f"Updated IAM policy on {secret_id}")

Aggiungi versione secret

REST

# TODO(developer): Update the variables.
# Select a resource name for your Secret, which contains your API Key.
SECRET_NAME="MyWeaviateApiKeySecret"

# Your Weaviate API Key.
WEAVIATE_API_KEY="example-api-key"
# Encode your WEAVIATE_API_KEY using base 64.
SECRET_DATA=$(echo ${WEAVIATE_API_KEY} | base64)

# Create a new version of your secret which uses SECRET_DATA as payload
curl "https://secretmanager.googleapis.com/v1/projects/${PROJECT_ID}/secrets/${SECRET_NAME}:addVersion" \
    --request "POST" \
    --header "authorization: Bearer $(gcloud auth print-access-token)" \
    --header "content-type: application/json" \
    --data "{\"payload\": {\"data\": \"${SECRET_DATA}\"}}"

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

from google.cloud import secretmanager
import google_crc32c  # type: ignore


def add_secret_version(
    project_id: str, secret_id: str, payload: str
) -> secretmanager.SecretVersion:
    """
    Add a new secret version to the given secret with the provided payload.
    """

    # Create the Secret Manager client.
    client = secretmanager.SecretManagerServiceClient()

    # Build the resource name of the parent secret.
    parent = client.secret_path(project_id, secret_id)

    # Convert the string payload into a bytes. This step can be omitted if you
    # pass in bytes instead of a str for the payload argument.
    payload_bytes = payload.encode("UTF-8")

    # Calculate payload checksum. Passing a checksum in add-version request
    # is optional.
    crc32c = google_crc32c.Checksum()
    crc32c.update(payload_bytes)

    # Add the secret version.
    response = client.add_secret_version(
        request={
            "parent": parent,
            "payload": {
                "data": payload_bytes,
                "data_crc32c": int(crc32c.hexdigest(), 16),
            },
        }
    )

    # Print the new secret version name.
    print(f"Added secret version: {response.name}")

Utilizza Weaviate con Llama 3

Il notebook dell'API RAG di Model Garden mostra come utilizzare l'SDK Agent Platform per Python con un corpus Weaviate e un modello Llama 3. Per utilizzare il notebook, devi:

Configura il database Weaviate.
Configura Secret Manager.
Utilizza il blocco note dell'API RAG di Model Garden.

Per altri esempi, consulta Esempi.

Crea un corpus RAG

Questo esempio di codice mostra come creare un corpus RAG e imposta l'istanza Weaviate come database vettoriale.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di Agent Platform per l'utilizzo delle librerie client.

Per eseguire l'autenticazione in Agent Platform, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.


import agentplatform
from agentplatform import types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# weaviate_http_endpoint = "weaviate-http-endpoint"
# weaviate_collection_name = "weaviate-collection-name"
# weaviate_api_key_secret_manager_version = "projects/{PROJECT_ID}/secrets/{SECRET_NAME}/versions/latest"
# display_name = "test_corpus"
# description = "Corpus Description"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

# Configure embedding model (Optional)
embedding_model_config = types.RagEmbeddingModelConfig(
    vertex_prediction_endpoint=types.RagEmbeddingModelConfigVertexPredictionEndpoint(
        endpoint="publishers/google/models/text-embedding-005"
    )
)

# Configure Vector DB
vector_db = types.RagVectorDbConfigWeaviate(
    http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
)

corpus = client.rag.create_corpus(
    rag_corpus=types.RagCorpus(
        display_name=display_name,
        description=description,
        rag_vector_db_config=types.RagVectorDbConfig(
            weaviate=vector_db,
            api_auth=types.ApiAuth(
                api_key_config=types.ApiAuthApiKeyConfig(
                    api_key_secret_version=weaviate_api_key_secret_manager_version
                )
            ),
            rag_embedding_model_config=embedding_model_config,
        ),
    )
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

Utilizza il file RAG

L'API RAG gestisce il caricamento, l'importazione, l'elenco e l'eliminazione dei file.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: .
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
INPUT_FILE: il percorso di un file locale.
FILE_DISPLAY_NAME: il nome visualizzato di RagFile.
RAG_FILE_DESCRIPTION: la descrizione di RagFile.

Metodo HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/media:upload

Corpo JSON della richiesta:

{
 "rag_file": {
  "display_name": "FILE_DISPLAY_NAME",
  "description": "RAG_FILE_DESCRIPTION"
 }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato INPUT_FILE, quindi esegui il comando seguente:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @INPUT_FILE \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/media:upload"

PowerShell

Salva il corpo della richiesta in un file denominato INPUT_FILE, quindi esegui il comando seguente:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile INPUT_FILE `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/media:upload" | Select-Object -Expand Content

Una risposta positiva restituisce la risorsa RagFile. L'ultimo componente del campo RagFile.name è il valore rag_file_id generato dal server.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"
# path = "path/to/local/file.txt"
# display_name = "file_display_name"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

rag_file = client.rag.upload_file(
    corpus_name=corpus_name,
    path=path,
    display_name=display_name,
)
print(rag_file)
# RagFile(name='projects/[PROJECT_ID]/locations/us-east5/ragCorpora/1234567890/ragFiles/09876543',
#  display_name='file_display_name')

Importa file RAG

File e cartelle possono essere importati da Drive o Cloud Storage.

REST

Utilizza response.metadata per visualizzare gli errori parziali, l'ora della richiesta e l'ora della risposta nell'oggetto response dell'SDK.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: .
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
GCS_URIS: un elenco di località Cloud Storage. Esempio: gs://my-bucket1, gs://my-bucket2.
DRIVE_RESOURCE_ID: l'ID della risorsa di Drive. Esempi:

https://drive.google.com/file/d/ABCDE
https://drive.google.com/corp/drive/u/0/folders/ABCDEFG

DRIVE_RESOURCE_TYPE: il tipo di risorsa di Drive. Opzioni:

RESOURCE_TYPE_FILE - File
RESOURCE_TYPE_FOLDER - Cartella

CHUNK_SIZE: (Facoltativo) Numero di token che deve avere ogni chunk.
CHUNK_OVERLAP: (Facoltativo) Numero di token sovrapposti tra i chunk.

Metodo HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import

Corpo JSON della richiesta:

{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": GCS_URIS
    },
    "google_drive_source": {
      "resource_ids": {
        "resource_id": DRIVE_RESOURCE_ID,
        "resource_type": DRIVE_RESOURCE_TYPE
      },
    }
  }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content

Una risposta positiva restituisce la risorsa ImportRagFilesOperationMetadata.

L'esempio seguente mostra come importare un file da Cloud Storage. Utilizza il campo di controllo max_embedding_requests_per_min per limitare la frequenza con cui il motore RAG chiama il modello di embedding durante il processo di indicizzazione ImportRagFiles. Il valore predefinito del campo è 1000 chiamate al minuto.

// Cloud Storage bucket/file location.
// Such as "gs://rag-e2e-test/"
GCS_URIS=YOUR_GCS_LOCATION

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, GCS_URIS
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "gcs_source": {
      "uris": '\""${GCS_URIS}"\"'
    },
    "rag_file_chunking_config": {
      "chunk_size": 512
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

L'esempio seguente mostra come importare un file da Drive. Utilizza il campo di controllo max_embedding_requests_per_min per limitare la frequenza con cui il motore RAG chiama il modello di embedding durante il processo di indicizzazione ImportRagFiles. Il valore predefinito del campo è 1000 chiamate al minuto.

// Google Drive folder location.
FOLDER_RESOURCE_ID=YOUR_GOOGLE_DRIVE_FOLDER_RESOURCE_ID

// Enter the QPM rate to limit RAG's access to your embedding model
// Example: 1000
EMBEDDING_MODEL_QPM_RATE=MAX_EMBEDDING_REQUESTS_PER_MIN_LIMIT

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: ENDPOINT, PROJECT_ID, RAG_CORPUS_ID, FOLDER_RESOURCE_ID
// Output: ImportRagFilesOperationMetadataNumber
// Use ListRagFiles to find the server-generated rag_file_id.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${ENDPOINT}/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles:import \
-d '{
  "import_rag_files_config": {
    "google_drive_source": {
      "resource_ids": {
        "resource_id": '\""${FOLDER_RESOURCE_ID}"\"',
        "resource_type": "RESOURCE_TYPE_FOLDER"
      }
    },
    "max_embedding_requests_per_min": '"${EMBEDDING_MODEL_QPM_RATE}"'
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID=OPERATION_ID
poll_op_wait ${OPERATION_ID}

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform
from agentplatform import types

from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"
# paths = ["gs://my_bucket/my_files_dir/*"]

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.import_files(
    name=corpus_name,
    import_config=types.ImportRagFilesConfig(
        gcs_source=genai_types.GcsSource(uris=paths),
        rag_file_transformation_config=types.RagFileTransformationConfig(
            rag_file_chunking_config=types.RagFileChunkingConfig(
                chunk_size=512,
                chunk_overlap=100,
            )
        ),  # optional
        max_embedding_requests_per_min=900,  # optional
    ),
)

print(f"Imported {response.imported_rag_files_count} files.")
# Example response:
# Imported 2 files.

Ottieni un file RAG

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: .
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
RAG_FILE_ID: l'ID della risorsa RagFile.

Metodo HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando:

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Esegui questo comando:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Una risposta positiva restituisce la risorsa RagFile.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

rag_file = client.rag.get_file(name=file_name)
print(rag_file)
# Example response:
# RagFile(name='projects/1234567890/locations/us-east5/ragCorpora/11111111111/ragFiles/22222222222',
# display_name='file_display_name', description='file description')

Elenca i file RAG

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: .
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
PAGE_SIZE: la dimensione della pagina dell'elenco standard. Puoi modificare il numero di RagFiles da restituire per pagina aggiornando il parametro page_size.
PAGE_TOKEN: il token della pagina dell'elenco standard. In genere si ottiene utilizzando ListRagFilesResponse.next_page_token della chiamata VertexRagDataService.ListRagFiles precedente.

Metodo HTTP e URL:

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando:

curl -X GET \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

Esegui questo comando:

$headers = @{  }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Dovresti ricevere un codice di stato riuscito (2xx) insieme a un elenco di RagFiles sotto il RAG_CORPUS_ID specificato.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

files_response = client.rag.list_files(name=corpus_name)
for file in files_response.rag_files:
    print(file.display_name)
    print(file.name)
# Example response:
# g-drive_file.txt
# projects/1234567890/locations/us-east5/ragCorpora/111111111111/ragFiles/222222222222
# g_cloud_file.txt
# projects/1234567890/locations/us-east5/ragCorpora/111111111111/ragFiles/333333333333

Elimina un file RAG

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: .
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
RAG_FILE_ID: l'ID della risorsa RagFile. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file_id}.

Metodo HTTP e URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

Esegui questo comando:

curl -X DELETE \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Esegui questo comando:

$headers = @{  }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Una risposta positiva restituisce la risorsa DeleteOperationMetadata.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# file_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}/ragFiles/{rag_file_id}"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

client.rag.delete_file(name=file_name)
print(f"File {file_name} deleted.")
# Example response:
# Successfully deleted the RagFile.
# File projects/1234567890/locations/us-east5/ragCorpora/1111111111/ragFiles/2222222222 deleted.

Recupera contesto

Quando un utente pone una domanda o fornisce un prompt, il componente di recupero in RAG cerca nella sua knowledge base per trovare informazioni pertinenti alla query.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

LOCATION: la regione in cui elaborare la richiesta.
PROJECT_ID: .
RAG_CORPUS_RESOURCE: il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
VECTOR_DISTANCE_THRESHOLD: vengono restituiti solo i contesti con una distanza del vettore inferiore alla soglia.
TEXT: il testo della query per ottenere i contesti pertinenti.
SIMILARITY_TOP_K: il numero di contesti principali da recuperare.

Metodo HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts

Corpo JSON della richiesta:

{
 "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "vector_distance_threshold": 0.8
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
 }

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content

Dovresti ricevere un codice di stato riuscito (2xx) e un elenco di RagFiles correlati.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform

from agentplatform import types
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-east5/ragCorpora/[rag_corpus_id]"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Genera contenuti

Una previsione controlla il metodo LLM che genera i contenuti.

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

PROJECT_ID: .
LOCATION: la regione in cui elaborare la richiesta.
MODEL_ID: modello LLM per la generazione di contenuti. Esempio: gemini-3.5-flash
GENERATION_METHOD: metodo LLM per la generazione di contenuti. Opzioni: generateContent, streamGenerateContent
INPUT_PROMPT: il testo inviato all'LLM per la generazione di contenuti. Prova a utilizzare un prompt pertinente ai file RAG caricati.
RAG_CORPUS_RESOURCE: il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
SIMILARITY_TOP_K: (facoltativo) il numero di contesti principali da recuperare.
VECTOR_DISTANCE_THRESHOLD: (facoltativo) vengono restituiti i contesti con una distanza del vettore inferiore alla soglia.

Metodo HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD

Corpo JSON della richiesta:

{
 "contents": {
  "role": "user",
  "parts": {
    "text": "INPUT_PROMPT"
  }
 },
 "tools": {
  "retrieval": {
   "disable_attribution": false,
   "vertex_rag_store": {
    "rag_resources": {
      "rag_corpus": "RAG_CORPUS_RESOURCE",
    },
    "similarity_top_k": SIMILARITY_TOP_K,
    "vector_distance_threshold": VECTOR_DISTANCE_THRESHOLD
   }
  }
 }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

curl -X POST \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

PowerShell

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente:

$headers = @{  }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD" | Select-Object -Expand Content

Una risposta positiva restituisce i contenuti generati con le citazioni.

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


from google import genai
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Ricerca ibrida

La ricerca ibrida è supportata con il database Weaviate, che combina ricerche semantiche e per parole chiave per migliorare la pertinenza dei risultati di ricerca. Durante il recupero dei risultati di ricerca, una combinazione di punteggi di somiglianza della corrispondenza semantica (un vettore denso) e della corrispondenza delle parole chiave (un vettore sparso) produce i risultati finali classificati.

Ricerca ibrida utilizzando l'API di recupero di RAG Engine

Questo è un esempio di come abilitare una ricerca ibrida utilizzando l'API di recupero del motore RAG.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


import agentplatform

from agentplatform import types
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/[PROJECT_ID]/locations/us-east5/ragCorpora/[rag_corpus_id]"

# Initialize Agent Platform client once per session.
# See https://docs.cloud.google.com/gemini-enterprise-agent-platform/build/rag-engine/rag-overview#supported-regions
client = agentplatform.Client(project=PROJECT_ID, location="us-east5")

response = client.rag.retrieve_contexts(
    vertex_rag_store=genai_types.VertexRagStore(
        rag_resources=[
            genai_types.VertexRagStoreRagResource(
                rag_corpus=corpus_name,
                # Optional: supply IDs from `rag.list_files()`.
                # rag_file_ids=["rag-file-1", "rag-file-2", ...],
            )
        ],
    ),
    query=types.RagQuery(
        text="Hello World!",
        rag_retrieval_config=genai_types.RagRetrievalConfig(
            top_k=10,
            filter=genai_types.RagRetrievalConfigFilter(
                vector_distance_threshold=0.5
            ),
        ),
    )
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Utilizza la ricerca ibrida e RAG Engine per la generazione con grounding

Questo è un esempio di come utilizzare la ricerca ibrida e il motore RAG per la generazione con grounding.

REST

  # TODO(developer): Update the variables.
  PROJECT_ID = "YOUR_PROJECT_ID"
  # The HTTPS/HTTP Weaviate endpoint you created during provisioning.
  HTTP_ENDPOINT_NAME="https://your.weaviate.endpoint.com"

  # Your Weaviate collection name, which roughly corresponds to a Agent Platform Knowledge Engine Corpus.
  # For example, "MyCollectionName"
  # Note that the first letter needs to be capitalized.
  # Otherwise, Weaviate will capitalize it for you.
  WEAVIATE_COLLECTION_NAME="MyCollectionName"

  # The resource name of your Weaviate API Key your Secret.
  SECRET_NAME="MyWeaviateApiKeySecret"
  # The Secret Manager resource name containing the API Key for your Weaviate endpoint.
  # For example, projects/{project}/secrets/{secret}/versions/latest
  APIKEY_SECRET_VERSION="projects/${PROJECT_ID}/secrets/${SECRET_NAME}/versions/latest"

  # Select a Corpus display name.
  CORPUS_DISPLAY_NAME="SpecialCorpus"

  # Call CreateRagCorpus API and set all Vector DB Config parameters for Weaviate to create a new corpus associated to your selected Weaviate collection.
  curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora \
  -d '{
        "display_name" : '\""${CORPUS_DISPLAY_NAME}"\"',
        "rag_vector_db_config" : {
                "weaviate": {
                      "http_endpoint": '\""${HTTP_ENDPOINT_NAME}"\"',
                      "collection_name": '\""${WEAVIATE_COLLECTION_NAME}"\"'
                },
          "api_auth" : {
                  "api_key_config": {
                        "api_key_secret_version": '\""${APIKEY_SECRET_VERSION}"\"'
                  }
          }
        }
    }'

  # TODO(developer): Update the variables.
  # Get operation_id returned in CreateRagCorpus.
  OPERATION_ID="your-operation-id"

  # Poll Operation status until done = true in the response.
  curl -X GET \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
  https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/operations/${OPERATION_ID}

  # Call ListRagCorpora API to verify the RAG corpus is created successfully.
  curl -sS -X GET \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://us-central1-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/us-central1/ragCorpora"

Python

Per scoprire come installare o aggiornare l'SDK Vertex AI Python, consulta Installa l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.


from google import genai
from google.genai import types as genai_types

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-east5/ragCorpora/{rag_corpus_id}"

rag_retrieval_tool = genai_types.Tool(
    retrieval=genai_types.Retrieval(
        vertex_rag_store=genai_types.VertexRagStore(
            rag_resources=[
                genai_types.VertexRagStoreRagResource(
                    rag_corpus=corpus_name
                )
            ],
            rag_retrieval_config=genai_types.RagRetrievalConfig(
                top_k=10,
                filter=genai_types.RagRetrievalConfigFilter(
                    vector_distance_threshold=0.5
                ),
            ),
        ),
    )
)

# Create a GenAI SDK client to make a generate_content request
genai_client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")

response = genai_client.models.generate_content(
    model="gemini-3.8-flash",
    contents="Why is the sky blue?",
    config=genai_types.GenerateContentConfig(
        tools=[rag_retrieval_tool]
    ),
)
print(response.text)
# Example response:
#   The sky appears blue due to a phenomenon called Rayleigh scattering.
#   Sunlight, which contains all colors of the rainbow, is scattered
#   by the tiny particles in the Earth's atmosphere....
#   ...

Passaggi successivi

Utilizza Pinecone con RAG Engine su Gemini Enterprise Agent Platform

Utilizza un database Weaviate con RAG Engine Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Considerazioni

Esegui il provisioning del database Weaviate

Configura ed esegui il deployment dell'istanza del database Weaviate

Prepara l'endpoint HTTPS

Crea la tua raccolta Weaviate

Utilizza la tua chiave API per eseguire il provisioning di Weaviate utilizzando AuthN e AuthZ

Crea la chiave API

Archivia la chiave API in Secret Manager

Esegui il provisioning del account di servizio RAG Engine

Configura l'ambiente della console Google Cloud

Fai clic per scoprire come configurare l'ambiente

Python

Node.js

Java

Maven con BOM

Maven senza BOM

Gradle senza BOM

Go

C#

REST

Prepara il corpus RAG

Utilizza le API CreateRagCorpus e UpdateRagCorpus

Crea il primo corpus RAG

Crea un altro corpus RAG

Esempi

Configura il database Weaviate

REST

Configura Secret Manager

Crea secret

Console

REST

Python

Imposta le autorizzazioni

Console

Python

Aggiungi versione secret

REST

Python

Utilizza Weaviate con Llama 3

Crea un corpus RAG

REST

Python

Utilizza il file RAG

REST

curl

PowerShell

Python

Importa file RAG

REST

curl

PowerShell

Python

Ottieni un file RAG

REST

curl

PowerShell

Python

Elenca i file RAG

REST

curl

PowerShell

Python

Elimina un file RAG

REST

curl

PowerShell

Python

Recupera contesto

REST

curl

PowerShell

Python

Genera contenuti

REST

curl

PowerShell

Python

Ricerca ibrida

Ricerca ibrida utilizzando l'API di recupero di RAG Engine

Utilizza un database Weaviate con RAG Engine

Utilizza la tua chiave API per eseguire il provisioning di Weaviate utilizzando `AuthN` e `AuthZ`

Utilizza le API `CreateRagCorpus` e `UpdateRagCorpus`