Utilizzare un database Weaviate con il motore RAG di Vertex AI

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

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

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

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

Considerazioni

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

  1. Devi creare, configurare ed eseguire il deployment dell'istanza e della raccolta del database Weaviate. Segui le istruzioni riportate in Creare la raccolta Weaviate per configurare una raccolta in base al tuo schema.
  2. 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 database Weaviate e supportano una connessione HTTPS.
  3. RAG Engine non memorizza e gestisce la chiave API Weaviate. Devi invece svolgere i seguenti passaggi:
    1. Memorizza la chiave in Secret Manager di Google Cloud .
    2. Concedi all'account di servizio del progetto le autorizzazioni per accedere al tuo secret.
    3. Fornisci a RAG Engine l'accesso al nome della risorsa del tuo secret.
    4. Quando interagisci con il database Weaviate, RAG Engine accede alla risorsa segreta utilizzando il tuo account di servizio.
  4. Il corpus di RAG Engine e la raccolta Weaviate hanno una mappatura uno a uno. I file RAG vengono archiviati in una raccolta del database Weaviate. Quando viene eseguita una chiamata all'API CreateRagCorpus o all'API UpdateRagCorpus, il corpus RAG viene associato alla raccolta del database.
  5. Oltre alle ricerche semantiche basate su embedding densi, anche la ricerca ibrida è supportata dal motore RAG tramite un database Weaviate. Puoi anche regolare il peso tra la somiglianza di vettori densi e sparsi in una ricerca ibrida.

Esegui il provisioning del database Weaviate

Prima di utilizzare il database Weaviate con il motore RAG, devi svolgere quanto segue:

  1. Configura ed esegui il deployment dell'istanza del database Weaviate.
  2. Prepara l'endpoint HTTPS.
  3. Crea la tua raccolta Weaviate.
  4. Utilizza la tua chiave API per eseguire il provisioning di Weaviate utilizzando AuthN e AuthZ.
  5. Esegui il provisioning dell'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 del marketplace di Google Cloud , che è facoltativa.

Puoi configurare l'istanza Weaviate ovunque, purché l'endpoint Weaviate sia accessibile per la configurazione e il deployment nel tuo progetto. A questo punto puoi gestire completamente la tua istanza di 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 i dati nel database Weaviate. È inoltre tua responsabilità assicurarti che i dati nel database possano essere utilizzati da RAG Engine. Ad esempio, se modifichi i dati, RAG Engine 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.

Creare la tua raccolta Weaviate

Poiché il corpus del motore RAG e la raccolta Weaviate hanno una mappatura uno a uno, devi creare una raccolta nel database Weaviate prima di associarla al corpus del motore RAG. 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 chiave API per eseguire il provisioning di Weaviate utilizzando AuthN e AuthZ

Il provisioning della chiave API Weaviate prevede i seguenti passaggi:

  1. Crea la chiave API Weaviate.
  2. Configura Weaviate utilizzando la chiave API di Weaviate.
  3. Memorizza la chiave API Weaviate in Secret Manager.

Crea la chiave API

RAG Engine 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 a quelle provenienti da RAG Engine, devi creare il tuo primo corpus e utilizzare il tuo account di servizio RAG Engine come identità.

Memorizza la chiave API in Secret Manager

Una chiave API contiene informazioni sensibili che consentono l'identificazione personale (informazioni personali sensibili), che sono soggette a requisiti legali. Se i dati relativi alle informazioni personali sensibili vengono compromessi o utilizzati in modo improprio, un privato potrebbe essere esposto a un rischio o a un danno significativo. Per ridurre al minimo i rischi per un singolo utente durante l'utilizzo di RAG Engine, non memorizzare e gestire la chiave API ed evita di condividerla non criptata.

Per proteggere le informazioni sensibili relative alla privacy:

  1. Memorizza la chiave API in Secret Manager.
  2. Concedi all'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 l'account di servizio, che ha il formato

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

    4. Modifica gli entità dell'account di servizio.
    5. Aggiungi il ruolo Funzione di accesso ai secret di Secret Manager all'account di servizio.
  3. Durante la creazione o l'aggiornamento del corpus RAG, passa il nome della risorsa secret a RAG Engine e memorizzalo.

Quando invii 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 dell'account di servizio RAG Engine

Quando crei la prima risorsa nel progetto, RAG Engine crea un account di servizio dedicato. Puoi trovare il tuo account di servizio nella pagina IAM del progetto. L'account di servizio segue questo 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 tuo account di servizio alla chiave API nel database Weaviate per configurare l'autenticazione (AuthN) e l'autorizzazione (AuthZ). Tuttavia, il tuo account di servizio non è obbligatorio.
  • Puoi archiviare la chiave API Secret Manager nel tuo progetto e concedere le autorizzazioni del tuo account di servizio a queste risorse con segreto.
  • RAG Engine utilizza gli account di servizio per accedere alla chiave API da Secret Manager nei tuoi progetti.

Configurare l'ambiente della console Google Cloud

Fai clic per scoprire come configurare il tuo ambiente

Scopri come configurare il tuo ambiente selezionando una delle seguenti schede:

Python

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Installa o aggiorna l'SDK Vertex AI per Python eseguendo il seguente comando:

    pip3 install --upgrade "google-cloud-aiplatform>=1.38"

Node.js

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Installa o aggiorna l'SDK Vertex AI per Node.js eseguendo il seguente comando:

    npm install @google-cloud/vertexai

Java

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

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

    Maven con BOM

    Aggiungi il seguente codice HTML a 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 a pom.xml:

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

    Gradle without BOM

    Add the following to your build.gradle

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

Go

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

  8. Esamina i pacchetti Go dell'API Vertex AI disponibili per determinare quale soddisfa al meglio le esigenze del tuo progetto:

    • Pacchetto cloud.google.com/go/vertexai (consigliato)

      vertexai è un pacchetto creato da persone che fornisce accesso a funzionalità e capacità comuni.

      Questo pacchetto è consigliato come punto di partenza per la maggior parte degli sviluppatori che creano con l'API Vertex AI. Per accedere a funzionalità e scettri non ancora coperti da questo pacchetto, utilizza 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à e alle funzionalità dell'API Vertex AI non ancora fornite dal pacchetto vertexai creato da persone.

  9. 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#

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

REST

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Enable the Vertex AI API.

    Enable the API

    4.

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

    Go to project selector

  5. Enable the Vertex AI API.

    Enable the API

    6.

  6. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  7. Configura le variabili di ambiente inserendo quanto segue. Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud. 
    MODEL_ID="gemini-1.5-flash-002"
PROJECT_ID="PROJECT_ID"
  8. Esegui il provisioning dell'endpoint: 
    gcloud beta services identity create --service=aiplatform.googleapis.com --project=${PROJECT_ID}

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

Prepara il corpus RAG

Per accedere ai dati del database Weaviate, RAG Engine deve avere accesso a un corpus RAG. Questa sezione illustra 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 di vettori. La configurazione del database di vettori contiene tutti i campi di configurazione. Se il campo rag_vector_db_config.weaviate non è impostato, per impostazione predefinita viene impostato 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 il tuo accesso al database di vettori.
  • api_key_config.api_key_secret_version: il nome della risorsa del secret memorizzato in Secret Manager, che contiene la chiave dell'API Weaviate.

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

Se il database e la chiave non sono pronti per essere associati al corpus RAG, procedi nel seguente modo:

  1. Imposta il campo weaviate in rag_vector_db_config.

    • Non puoi modificare il database di vettori associato.
    • Lascia vuoti i campi http_endpoint e collection_name. Entrambi i campi possono essere aggiornati in un secondo momento.

  2. Se non hai la chiave API memorizzata in Secret Manager, puoi lasciare vuoto il campo api_auth. Quando chiami l'API UpdateRagCorpus, puoi aggiornare il campo api_auth. Weaviate richiede 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}

  3. 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.

  4. 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 è predefinita. Questa opzione non può essere modificata quando chiami l'API UpdateRagCorpus. Quando chiami UpdateRagCorpus e il campo vector_db è impostato parzialmente, puoi aggiornare i campi contrassegnati come Modificabili (chiamati anche mutabili).

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

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

Creare il primo corpus RAG

Se l'account di servizio RAG Engine non esiste:

  1. 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.
  2. Scegli un nome per l'account di servizio RAG Engine che rispetti questo formato:

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

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

  3. Utilizza il tuo account di servizio per accedere al tuo secret archiviato in Secret Manager del progetto, che contiene la chiave API Weaviate.
  4. Dopo il completamento del provisioning di Weaviate, ottieni le seguenti informazioni:
    • L'endpoint HTTPS o HTTP di Weaviate.
    • Il nome della tua raccolta Weaviate.
  5. 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:
    • L'endpoint HTTPS o HTTP di Weaviate.
    • Il nome della tua raccolta Weaviate.
    • Il nome della risorsa della chiave API.

Creare un altro corpus RAG

Se l'account di servizio RAG Engine esiste, procedi nel seguente modo:

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

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

  4. Utilizza il tuo account di servizio per accedere al tuo secret archiviato in Secret Manager del progetto, che contiene la chiave API Weaviate.
  5. Durante il provisioning di Weaviate, ottieni le seguenti informazioni:
    • L'endpoint HTTPS o HTTP di Weaviate.
    • Il nome della tua raccolta Weaviate.
  6. Crea un corpus RAG in RAG Engine e connettiti alla tua raccolta Weaviate in uno dei seguenti modi:
    1. Esegui una chiamata all'API CreateRagCorpus per creare un corpus RAG con una configurazione Weaviate compilata, che è l'opzione preferita.
    2. Esegui una chiamata all'API CreateRagCorpus per creare un corpus RAG con una configurazione Weaviate vuota ed esegui una chiamata all'API UpdateRagCorpus per aggiornare il corpus RAG con le seguenti informazioni:
      • Endpoint HTTP del database Weaviate
      • Nome della collezione Weaviate
      • Chiave API

Esempi

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

Per utilizzare il notebook dell'API Model Garden RAG, consulta Utilizzare 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 Vertex AI 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

Configurare Secret Manager

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

Crea secret

Per attivare Secret Manager:

Console

  1. Vai alla pagina Secret Manager.

    Vai a Secret Manager

  2. Fai clic su + Crea secret.

  3. Inserisci il nome del segreto. I nomi dei secret possono contenere solo lettere latine (A-Z), numeri (0-9), trattini (-) e trattini bassi (_).

  4. La specifica dei seguenti campi è facoltativa:

    1. Per caricare il file con il segreto, fai clic su Sfoglia.
    2. Leggi le norme sulla replica.
    3. Se vuoi gestire manualmente le posizioni per il tuo secret, seleziona Gestisci manualmente le località per questo secret. Deve essere selezionata 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 uno o più argomenti di pubblicazione o di iscrizione per ricevere notifiche sugli 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 su richiesta. Per ritardare l'eliminazione delle versioni dei secret, seleziona Imposta 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.

  5. 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 Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 

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")
    """

    # 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 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 autorizzazioni

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

Console

  1. Nella sezione IAM e amministrazione della console Google Cloud, individua il tuo account di servizio e fai clic sull'icona a forma di matita per apportare modifiche.

  2. Nel campo Ruolo, seleziona Accesso ai secret di Secret Manager.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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 del 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 Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare 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}")

Utilizzare Weaviate con Llama 3

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

  1. Configura il database Weaviate.

  2. Configura Secret Manager.

  3. Utilizza il notebook dell'API RAG di Model Garden.

Per altri esempi, consulta la sezione Esempi.

Crea un corpus RAG

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

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 Vertex AI 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 Python riportate nella guida rapida all'utilizzo delle librerie client di Vertex AI. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API Python di Vertex AI.

Per autenticarti a Vertex AI, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configurare l'autenticazione per un ambiente di sviluppo locale. 


from vertexai.preview import rag
import vertexai

# 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 Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

# Configure embedding model (Optional)
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

# Configure Vector DB
vector_db = rag.Weaviate(
    weaviate_http_endpoint=weaviate_http_endpoint,
    collection_name=weaviate_collection_name,
    api_key=weaviate_api_key_secret_manager_version,
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    embedding_model_config=embedding_model_config,
    vector_db=vector_db,
)
print(corpus)
# Example response:
# RagCorpus(name='projects/1234567890/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description', embedding_model_config=...
# ...

Utilizzare il file RAG

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

REST

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

  • PROJECT_ID: il tuo ID progetto.
  • 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 del RagFile.
  • RAG_FILE_DESCRIPTION: la descrizione del RagFile.

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una delle seguenti 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/ragFiles: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/ragFiles: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 per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


from vertexai.preview import rag
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

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

Importa file RAG

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

REST

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

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

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui elaborare la richiesta.
  • RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
  • GCS_URIS: un elenco di località di Cloud Storage. Esempio: gs://my-bucket1, gs://my-bucket2.
  • DRIVE_RESOURCE_ID: l'ID della risorsa Drive. Esempi:
    • https://drive.google.com/file/d/ABCDE
    • https://drive.google.com/corp/drive/u/0/folders/ABCDEFG
  • DRIVE_RESOURCE_TYPE: 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 delle seguenti 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 RAG Engine chiama il modello di embedding durante il processo di indicizzazione ImportRagFiles. Il campo ha un valore predefinito di 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 riportato di seguito mostra come importare un file da Drive. Utilizza il campo di controllo max_embedding_requests_per_min per limitare la frequenza con cui RAG Engine chiama il modello di embedding durante il processo di indicizzazione ImportRagFiles. Il campo ha un valore predefinito di 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 per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


from vertexai.preview import rag
import vertexai

# TODO(developer): Update and un-comment below lines
# PROJECT_ID = "your-project-id"
# corpus_name = "projects/{PROJECT_ID}/locations/us-central1/ragCorpora/{rag_corpus_id}"
# paths = ["https://drive.google.com/file/123", "gs://my_bucket/my_files_dir"]  # Supports Google Cloud Storage and Google Drive Links

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.import_files(
    corpus_name=corpus_name,
    paths=paths,
    chunk_size=512,  # Optional
    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.

Recuperare un file RAG

REST

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

  • PROJECT_ID: il tuo ID progetto.
  • 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 delle seguenti 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 per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


from vertexai.preview import rag
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

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

Elenco file RAG

REST

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

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui elaborare la richiesta.
  • RAG_CORPUS_ID: l'ID della risorsa RagCorpus.
  • PAGE_SIZE: le dimensioni standard della pagina dell'elenco. Puoi modificare il numero di RagFiles da restituire per pagina aggiornando il parametro page_size.
  • PAGE_TOKEN: il token della pagina dell'elenco standard. Ottenuto in genere 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 delle seguenti 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 di operazione riuscita (2xx) insieme a un elenco di RagFiles in base al RAG_CORPUS_ID specificato.

Python

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


from vertexai.preview import rag
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

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

Eliminare un file RAG

REST

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

  • PROJECT_ID: il tuo ID progetto.
  • 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 delle seguenti 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 per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


from vertexai.preview import rag
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

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

Recuperare il contesto

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

REST

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

  • LOCATION: la regione in cui elaborare la richiesta.
  • PROJECT_ID: il tuo ID progetto.
  • 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 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 delle seguenti 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 positivo (2xx) e un elenco di RagFiles correlati.

Python

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


from vertexai.preview import rag
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    similarity_top_k=10,  # Optional
    vector_distance_threshold=0.5,  # Optional
    # vector_search_alpha=0.5, # Optional - Only supported for Weaviate
)
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 seguenti sostituzioni:

  • PROJECT_ID: il tuo ID progetto.
  • LOCATION: la regione in cui elaborare la richiesta.
  • MODEL_ID: modello LLM per la generazione di contenuti. Esempio: gemini-1.5-pro-002
  • 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 delle seguenti 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 corretta restituisce i contenuti generati con le citazioni.

Python

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


from vertexai.preview import rag
from vertexai.preview.generative_models import GenerativeModel, Tool
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            similarity_top_k=3,  # Optional
            vector_distance_threshold=0.5,  # Optional
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-1.5-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
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....
#   ...

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

Ricerca ibrida che utilizza l'API di recupero del motore RAG

Questo è un esempio di come attivare 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 Vertex AI 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 per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


from vertexai.preview import rag
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

response = rag.retrieval_query(
    rag_resources=[
        rag.RagResource(
            rag_corpus=corpus_name,
            # Optional: supply IDs from `rag.list_files()`.
            # rag_file_ids=["rag-file-1", "rag-file-2", ...],
        )
    ],
    text="Hello World!",
    similarity_top_k=10,  # Optional
    vector_distance_threshold=0.5,  # Optional
    # vector_search_alpha=0.5, # Optional - Only supported for Weaviate
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Utilizzare la ricerca ibrida e RAG Engine per la generazione basata su dati

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 Vertex AI 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 per Python, consulta Installare l'SDK Vertex AI per Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python. 


from vertexai.preview import rag
from vertexai.preview.generative_models import GenerativeModel, Tool
import vertexai

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

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location="us-central1")

rag_retrieval_tool = Tool.from_retrieval(
    retrieval=rag.Retrieval(
        source=rag.VertexRagStore(
            rag_resources=[
                rag.RagResource(
                    rag_corpus=corpus_name,
                    # Optional: supply IDs from `rag.list_files()`.
                    # rag_file_ids=["rag-file-1", "rag-file-2", ...],
                )
            ],
            similarity_top_k=3,  # Optional
            vector_distance_threshold=0.5,  # Optional
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-1.5-flash-001", tools=[rag_retrieval_tool]
)
response = rag_model.generate_content("Why is the sky blue?")
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