API RAG Engine

Anteprima

Alcune funzionalità di RAG sono offerte in anteprima, soggette ai "Termini delle offerte pre-GA" dei Termini specifici dei servizi Google Cloud. I prodotti e le funzionalità pre-GA potrebbero avere supporto limitato e le modifiche ai prodotti e alle funzionalità pre-GA potrebbero non essere compatibili con altre versioni pre-GA. Per ulteriori informazioni, consulta le descrizioni della fase di lancio. Inoltre, utilizzando l'API Gemini su Vertex AI, accetti i termini e condizioni dell'anteprima dell'IA generativa(Termini di anteprima).

Il motore RAG di Vertex AI è un componente della piattaforma Vertex AI, che facilita la generazione con potenziamento del recupero (RAG). Il motore RAG consente ai modelli linguistici di grandi dimensioni (LLM) di accedere e incorporare i dati di fonti di conoscenza esterne, come documenti e database. Utilizzando la RAG, gli LLM possono generare risposte più accurate e informative.

Sintassi di esempio

Questa sezione fornisce la sintassi per creare un corpus RAG.

curl

PROJECT_ID: Your project ID.
LOCATION: The region to process the request.
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora\
  -d '{
  "display_name" : "...",
  "description": "..."
}'

Python

corpus = rag.create_corpus(display_name=..., description=...)
print(corpus)

Elenco dei parametri

Questa sezione elenca quanto segue:

Parametri	Esempi
Consulta Parametri di gestione del corpus.	Consulta Esempi di gestione del corpus.
Consulta Parametri di gestione dei file.	Consulta gli esempi di gestione dei file.

Parametri di gestione del corpus

Per informazioni su un corpus RAG, consulta Gestione dei corpora.

Crea un corpus RAG

Questa tabella elenca i parametri utilizzati per creare un corpus RAG.

Richiesta del corpo

Parametri
display_name	Obbligatorio: string Il nome visualizzato del corpus RAG.
description	(Facoltativo) string La descrizione del corpus RAG.
vector_db_config	(Facoltativo) Immutabile: RagVectorDbConfig La configurazione per i database Vector.
vertex_ai_search_config.serving_config	(Facoltativo) string La configurazione di Vertex AI Search. Formato: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/servingConfigs/{serving_config} o projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/servingConfigs/{serving_config}

RagVectorDbConfig

Parametri
rag_managed_db	oneof vector_db: RagVectorDbConfig.RagManagedDb Se non viene specificato alcun database vettoriale, rag_managed_db è il database vettoriale predefinito.
weaviate	oneof vector_db: RagVectorDbConfig.Weaviate Specifica l'istanza Weaviate.
weaviate.http_endpoint	string L'endpoint HTTP dell'istanza Weaviate. Questo valore non può essere modificato dopo l'impostazione. Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
weaviate.collection_name	string La raccolta Weaviate a cui viene mappato il corpus RAG. Questo valore non può essere modificato dopo l'impostazione. Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
pinecone	oneof vector_db: RagVectorDbConfig.Pinecone Specifica l'istanza Pinecone.
pinecone.index_name	string Questo è il nome utilizzato per creare l'indice Pinecone utilizzato con il corpus RAG. Questo valore non può essere modificato dopo l'impostazione. Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
vertex_feature_store	oneof vector_db: RagVectorDbConfig.VertexFeatureStore Specifica l'istanza Vertex AI Feature Store.
vertex_feature_store.feature_view_resource_name	string Il Vertex AI Feature Store FeatureView a cui viene mappato il corpus RAG. Formato: projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view} Questo valore non può essere modificato dopo l'impostazione. Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
vertex_vector_search	oneof vector_db: RagVectorDbConfig.VertexVectorSearch Specifica l'istanza Vertex Vector Search.
vertex_vector_search.index	string Si tratta del nome della risorsa dell'indice di ricerca vettoriale utilizzato con il corpus RAG. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint} Questo valore non può essere modificato dopo l'impostazione. Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
vertex_vector_search.index_endpoint	string Questo è il nome della risorsa dell'endpoint dell'indice di ricerca vettoriale utilizzato con il corpus RAG. Formato: projects/{project}/locations/{location}/indexes/{index} Questo valore non può essere modificato dopo l'impostazione. Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
api_auth.api_key_config.api_key_secret_version	string Si tratta del nome completo della risorsa del secret archiviato in Secret Manager, che contiene la chiave API Weaviate o Pinecone, a seconda della scelta del database di vettori. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID} Puoi lasciarlo vuoto nella chiamata API CreateRagCorpus e impostarlo con un valore non vuoto in una chiamata API UpdateRagCorpus successiva.
rag_embedding_model_config.vertex_prediction_endpoint.endpoint	(Facoltativo) Immutabile: string Il modello di embedding da utilizzare per il corpus RAG. Questo valore non può essere modificato dopo essere stato impostato. Se lasci vuoto questo campo, utilizzeremo text-embedding-004 come modello di embedding.

Aggiornare un corpus RAG

Questa tabella elenca i parametri utilizzati per aggiornare un corpus RAG.

Richiesta del corpo

Parametri
display_name	(Facoltativo) string Il nome visualizzato del corpus RAG.
description	(Facoltativo) string La descrizione del corpus RAG.
rag_vector_db.weaviate.http_endpoint	string L'endpoint HTTP dell'istanza Weaviate. Se RagCorpus è stato creato con una configurazione Weaviate e questo campo non è mai stato impostato, puoi aggiornare l'endpoint HTTP dell'istanza Weaviate.
rag_vector_db.weaviate.collection_name	string La raccolta Weaviate a cui viene mappato il corpus RAG. Se RagCorpus è stato creato con una configurazione Weaviate e questo campo non è mai stato impostato prima, puoi aggiornare il nome della raccolta dell'istanza Weaviate.
rag_vector_db.pinecone.index_name	string Questo è il nome utilizzato per creare l'indice Pinecone utilizzato con il corpus RAG. Se RagCorpus è stato creato con una configurazione Pinecone e questo campo non è mai stato impostato, puoi aggiornare il nome dell'indice dell'istanza Pinecone.
rag_vector_db.vertex_feature_store.feature_view_resource_name	string Il Vertex AI Feature Store FeatureView a cui viene mappato il corpus RAG. Formato: projects/{project}/locations/{location}/featureOnlineStores/{feature_online_store}/featureViews/{feature_view} Se il tuo RagCorpus è stato creato con una configurazione Vertex AI Feature Store e questo campo non è mai stato impostato, puoi aggiornarlo.
rag_vector_db.vertex_vector_search.index	string Si tratta del nome della risorsa dell'indice di ricerca vettoriale utilizzato con il corpus RAG. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint} Se il tuo RagCorpus è stato creato con una configurazione Vector Search e questo campo non è mai stato impostato, puoi aggiornarlo.
rag_vector_db.vertex_vector_search.index_endpoint	string Questo è il nome della risorsa dell'endpoint dell'indice di ricerca vettoriale utilizzato con il corpus RAG. Formato: projects/{project}/locations/{location}/indexes/{index} Se il tuo RagCorpus è stato creato con una configurazione Vector Search e questo campo non è mai stato impostato, puoi aggiornarlo.
rag_vector_db.api_auth.api_key_config.api_key_secret_version	string Il nome completo della risorsa del secret archiviato in Secret Manager, che contiene la chiave API Weaviate o Pinecone, dipende dalla scelta del database di vettori. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Elenca i corpora RAG

Questa tabella elenca i parametri utilizzati per elencare i corpora RAG.

Parametri
page_size	(Facoltativo) int Le dimensioni della pagina dell'elenco standard.
page_token	(Facoltativo) string Il token della pagina dell'elenco standard. In genere, viene ottenuto da [ListRagCorporaResponse.next_page_token][] della chiamata [VertexRagDataService.ListRagCorpora][] precedente.

Ottenere un corpus RAG

Questa tabella elenca i parametri utilizzati per ottenere un corpus RAG.

Parametri
name	string Il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

Eliminare un corpus RAG

Questa tabella elenca i parametri utilizzati per eliminare un corpus RAG.

Parametri
name	string Il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}

Parametri di gestione dei file

Per informazioni su un file RAG, consulta Gestione dei file.

Carica un file RAG

Questa tabella elenca i parametri utilizzati per caricare un file RAG.

Richiesta del corpo

Parametri
parent	string Il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}
rag_file	Obbligatorio: RagFile Il file da caricare.
upload_rag_file_config	Obbligatorio: UploadRagFileConfig La configurazione del RagFile da caricare in RagCorpus.

RagFile
display_name	Obbligatorio: string Il nome visualizzato del file RAG.
description	(Facoltativo) string La descrizione del file RAG.

UploadRagFileConfig
rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size	int32 Numero di token di ogni chunk.
rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap	int32 La sovrapposizione tra i chunk.

Importa file RAG

Questa tabella elenca i parametri utilizzati per importare un file RAG.

Parametri
parent	Obbligatorio: string Il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}
gcs_source	oneof import_source: GcsSource Località Cloud Storage. Supporta l'importazione di singoli file e di intere directory di Cloud Storage.
gcs_source.uris	list di string URI Cloud Storage contenente il file di caricamento.
google_drive_source	oneof import_source: GoogleDriveSource Posizione di Google Drive. Supporta l'importazione di singoli file e cartelle di Google Drive.
slack_source	oneof import_source: SlackSource Il canale Slack in cui viene caricato il file.
jira_source	oneof import_source: JiraSource La query Jira in cui viene caricato il file.
share_point_sources	oneof import_source: SharePointSources Le origini SharePoint in cui viene caricato il file.
rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size	int32 Numero di token di ogni chunk.
rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap	int32 La sovrapposizione tra i chunk.
rag_file_parsing_config	(Facoltativo) RagFileParsingConfig Specifica la configurazione di analisi per RagFiles. Se questo campo non è impostato, RAG utilizza il parser predefinito.
max_embedding_requests_per_min	(Facoltativo) int32 Il numero massimo di query al minuto che questo job può eseguire sul modello di embedding specificato nel corpus. Questo valore è specifico per questo job e non è condiviso con altri job di importazione. Consulta la pagina Quote del progetto per impostare un valore appropriato. Se non specificato, viene utilizzato un valore predefinito di 1000 QPM.

GoogleDriveSource
resource_ids.resource_id	Obbligatorio: string L'ID della risorsa Google Drive.
resource_ids.resource_type	Obbligatorio: string Il tipo di risorsa di Google Drive.

SlackSource
channels.channels	Ripetuta: SlackSource.SlackChannels.SlackChannel Informazioni sul canale Slack, inclusi ID e intervallo di tempo da importare.
channels.channels.channel_id	Obbligatorio: string L'ID canale Slack.
channels.channels.start_time	(Facoltativo) google.protobuf.Timestamp Il timestamp iniziale dei messaggi da importare.
channels.channels.end_time	(Facoltativo) google.protobuf.Timestamp Il timestamp finale dei messaggi da importare.
channels.api_key_config.api_key_secret_version	Obbligatorio: string Il nome completo della risorsa del secret archiviato in Secret Manager, che contiene un token di accesso al canale Slack che ha accesso agli ID canale Slack. Visita la pagina https://api.slack.com/tutorials/tracks/getting-a-token. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

JiraSource
jira_queries.projects	Ripetuta: string Un elenco di progetti Jira da importare nella loro interezza.
jira_queries.custom_queries	Ripetuta: string Un elenco di query Jira personalizzate da importare. Per informazioni su JQL (Jira Query Language), consulta Assistenza Jira
jira_queries.email	Obbligatorio: string L'indirizzo email di Jira.
jira_queries.server_uri	Obbligatorio: string L'URI del server Jira.
jira_queries.api_key_config.api_key_secret_version	Obbligatorio: string Il nome completo della risorsa del secret archiviato in Secret Manager, che contiene la chiave API di Jira che ha accesso agli ID canale Slack. Consulta: https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/ Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

SharePointSources
share_point_sources.sharepoint_folder_path	oneof in folder_source: string Il percorso della cartella di SharePoint da cui scaricare.
share_point_sources.sharepoint_folder_id	oneof in folder_source: string L'ID della cartella di SharePoint da cui scaricare.
share_point_sources.drive_name	oneof in drive_source: string Il nome del drive da cui scaricare.
share_point_sources.drive_id	oneof in drive_source: string L'ID del dispositivo da cui scaricare.
share_point_sources.client_id	string L'ID applicazione dell'app registrata nel portale Microsoft Azure. L'applicazione deve essere configurata anche con le autorizzazioni MS Graph "Files.ReadAll", "Sites.ReadAll" e BrowserSiteLists.Read.All.
share_point_sources.client_secret.api_key_secret_version	Obbligatorio: string Il nome completo della risorsa del secret archiviato in Secret Manager, che contiene il secret dell'applicazione per l'app registrata in Azure. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}
share_point_sources.tenant_id	string Identificatore univoco dell'istanza di Azure Active Directory.
share_point_sources.sharepoint_site_name	string Il nome del sito SharePoint da cui scaricare. Può essere il nome o l'ID del sito.

RagFileParsingConfig
layout_parser	oneof parser: RagFileParsingConfig.LayoutParser Il parser del layout da utilizzare per i RagFile.
layout_parser.processor_name	string Il nome completo di un processore Document AI o di una versione del processore. Formato: projects/{project_id}/locations/{location}/processors/{processor_id} projects/{project_id}/locations/{location}/processors/{processor_id}/processorVersions/{processor_version_id}
layout_parser.max_parsing_requests_per_min	string Il numero massimo di richieste che il job può inviare al processore Document AI al minuto. Consulta la pagina https://cloud.google.com/document-ai/quotas e la pagina Quota per il tuo progetto per impostare un valore appropriato qui. Se non specificato, viene utilizzato un valore predefinito di 120 QPM.

Recuperare un file RAG

Questa tabella elenca i parametri utilizzati per ottenere un file RAG.

Parametri
name	string Il nome della risorsa RagFile. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

Eliminare un file RAG

Questa tabella elenca i parametri utilizzati per eliminare un file RAG.

Parametri
name	string Il nome della risorsa RagFile. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_file_id}

Recupero e previsione

Questa sezione elenca i parametri di recupero e previsione.

Parametri di recupero

Questa tabella elenca i parametri per l'API RetrieveContexts.

Parametri
parent	Obbligatorio: string Il nome della risorsa della località da cui recuperare RagContexts. Gli utenti devono disporre dell'autorizzazione per effettuare una chiamata nel progetto. Formato: projects/{project}/locations/{location}
vertex_rag_store	VertexRagStore L'origine dati per Vertex RagStore.
query	Obbligatorio: RagQuery Query di recupero RAG singola.

VertexRagStore

VertexRagStore
rag_resources	elenco: RagResource La rappresentazione dell'origine RAG. Può essere utilizzato per specificare solo il corpus o i RagFile. Supporta solo un corpus o più file di un corpus.
rag_resources.rag_corpus	(Facoltativo) string RagCorpora. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}
rag_resources.rag_file_ids	elenco: string Un elenco di risorse RagFile. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}/ragFiles/{rag_file}

RagQuery
text	string La query in formato di testo per ottenere contesti pertinenti.
rag_retrieval_config	(Facoltativo) RagRetrievalConfig La configurazione di recupero per la query.

RagRetrievalConfig
top_k	(Facoltativo) int32 Il numero di contesti da recuperare.
hybrid_search.alpha	(Facoltativo) float Il valore alpha controlla il peso tra i risultati della ricerca di vettori densi e sparsi. L'intervallo è [0, 1], dove 0 indica solo la ricerca vettoriale sparsa e 1 indica solo la ricerca vettoriale densa. Il valore predefinito è 0,5, che bilancia uniformemente la ricerca di vettori sparsi e densi. La ricerca ibrida è disponibile solo per Weaviate.
filter.vector_distance_threshold	oneof vector_db_threshold: double Restituisce solo i contesti con una distanza del vettore inferiore alla soglia.
filter.vector_similarity_threshold	oneof vector_db_threshold: double Restituisce solo i contesti con una somiglianza di vettori superiore alla soglia.
ranking.rank_service.model_name	(Facoltativo) string Il nome del modello del servizio di ranking. Esempio: semantic-ranker-512@latest
ranking.llm_ranker.model_name	(Facoltativo) string Il nome del modello utilizzato per il ranking. Esempio: gemini-1.5-pro

Parametri di previsione

Questa tabella elenca i parametri di previsione.

GenerateContentRequest
tools.retrieval.vertex_rag_store	VertexRagStore Impostato per utilizzare un'origine dati basata sul RAG store di Vertex AI.

Per informazioni dettagliate, visita la pagina VertexRagStore.

Esempi di gestione del corpus

Questa sezione fornisce esempi di come utilizzare l'API per gestire il corpus RAG.

Creare un esempio di corpus RAG

Questo esempio di codice mostra come creare un corpus 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.
• CORPUS_DISPLAY_NAME: il nome visualizzato del RagCorpus.
• CORPUS_DESCRIPTION: la descrizione del RagCorpus.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "display_name" : "CORPUS_DISPLAY_NAME",
  "description": "CORPUS_DESCRIPTION",
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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/ragCorpora" | Select-Object -Expand Content

Dovresti ricevere un codice di stato di esito positivo (2xx).

Il seguente esempio mostra come creare un corpus RAG utilizzando l'API REST.

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  CORPUS_DISPLAY_NAME: The display name of the <code>RagCorpus</code>.

    // CreateRagCorpus
    // Input: LOCATION, PROJECT_ID, CORPUS_DISPLAY_NAME
    // Output: CreateRagCorpusOperationMetadata
    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora \
    -d '{
          "display_name" : "CORPUS_DISPLAY_NAME"
      }'

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"
# 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
embedding_model_config = rag.EmbeddingModelConfig(
    publisher_model="publishers/google/models/text-embedding-004"
)

corpus = rag.create_corpus(
    display_name=display_name,
    description=description,
    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=...
# ...

Aggiornare un esempio di corpus RAG

Puoi aggiornare il corpus RAG con un nuovo nome visualizzato, una descrizione e una configurazione del database di vettori. Tuttavia, non puoi modificare i seguenti parametri nel corpus RAG:

• Il tipo di database vettoriale. Ad esempio, non puoi cambiare il database di vettori da Weaviate a Vertex AI Feature Store.
• Se utilizzi l'opzione del database gestito, non puoi aggiornare la configurazione del database vettoriale.

Questi esempi mostrano come aggiornare un corpus 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.
• CORPUS_ID: l'ID del tuo corpus RAG.
• CORPUS_DISPLAY_NAME: il nome visualizzato del RagCorpus.
• CORPUS_DESCRIPTION: la descrizione del RagCorpus.
• INDEX_NAME: il nome della risorsa del Vector Search Index. Formato: projects/{project}/locations/{location}/indexes/{index}
• INDEX_ENDPOINT_NAME: il nome della risorsa del Vector Search Index Endpoint. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}

Metodo HTTP e URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID

Corpo JSON della richiesta:

{
  "display_name" : "CORPUS_DISPLAY_NAME",
  "description": "CORPUS_DESCRIPTION",
  "rag_vector_db_config": {
     "vertex_vector_search": {
         "index": "INDEX_NAME",
         "index_endpoint": "INDEX_ENDPOINT_NAME",
     }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Dovresti ricevere un codice di stato di esito positivo (2xx).

Esempio di elenco di corpora RAG

Questo esempio di codice mostra come elencare tutti i corpora 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.
• PAGE_SIZE: le dimensioni standard della pagina dell'elenco. Puoi modificare il numero di RagCorpora da restituire per pagina aggiornando il parametro page_size.
• PAGE_TOKEN: il token della pagina dell'elenco standard. Ottenuto in genere utilizzando ListRagCorporaResponse.next_page_token della chiamata VertexRagDataService.ListRagCorpora precedente.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Dovresti ricevere un codice di stato di operazione riuscita ("2xx") e un elenco di RagCorpora in base al PROJECT_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"

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

corpora = rag.list_corpora()
print(corpora)
# Example response:
# ListRagCorporaPager<rag_corpora {
#   name: "projects/[PROJECT_ID]/locations/us-central1/ragCorpora/2305843009213693952"
#   display_name: "test_corpus"
#   create_time {
# ...

Esempio di corpus 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.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Una risposta positiva restituisce la risorsa RagCorpus.

I comandi get e list vengono utilizzati in un esempio per dimostrare come RagCorpus utilizza il campo rag_embedding_model_config in vector_db_config, che rimanda al modello di embedding che hai scelto.

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.

// GetRagCorpus
// Input: LOCATION, PROJECT_ID, RAG_CORPUS_ID
// Output: RagCorpus
curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID

// ListRagCorpora
curl -sS -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/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")

corpus = rag.get_corpus(name=corpus_name)
print(corpus)
# Example response:
# RagCorpus(name='projects/[PROJECT_ID]/locations/us-central1/ragCorpora/1234567890',
# display_name='test_corpus', description='Corpus Description',
# ...

Eliminare un esempio di corpus 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.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Una risposta positiva restituisce 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"
# 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.delete_corpus(name=corpus_name)
print(f"Corpus {corpus_name} deleted.")
# Example response:
# Successfully deleted the RagCorpus.
# Corpus projects/[PROJECT_ID]/locations/us-central1/ragCorpora/123456789012345 deleted.

Esempi di gestione dei file

Questa sezione fornisce esempi di come utilizzare l'API per gestire i file RAG.

Carica un esempio di file RAG

REST

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

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  LOCAL_FILE_PATH: The local path to the file to be uploaded.
  DISPLAY_NAME: The display name of the RAG file.
  DESCRIPTION: The description of the RAG file.

Per inviare la richiesta, utilizza il seguente comando:

  curl -X POST \
    -H "X-Goog-Upload-Protocol: multipart" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -F metadata="{'rag_file': {'display_name':' DISPLAY_NAME', 'description':'DESCRIPTION'}}" \
    -F file=@LOCAL_FILE_PATH \
    "https://LOCATION-aiplatform.googleapis.com/upload/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

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

Esempio di importazione di file RAG

File e cartelle possono essere importati da Drive o Cloud Storage. Puoi utilizzare response.metadata per visualizzare errori parziali, ora della richiesta e tempo di risposta nell'oggetto response dell'SDK.

response.skipped_rag_files_count si riferisce al numero di file che sono stati ignorati durante l'importazione. Un file viene ignorato quando si verificano le seguenti condizioni:

1. Il file è già stato importato.
2. Il file non è cambiato.
3. La configurazione del chunking per il file non è cambiata.

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.
• GCS_URIS: un elenco di località di Cloud Storage. Esempio: gs://my-bucket1, gs://my-bucket2.
• 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/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"
    },
    "rag_file_chunking_config": {
      "chunk_size": CHUNK_SIZE,
      "chunk_overlap": CHUNK_OVERLAP
    }
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  GCS_URIS: A list of Cloud Storage locations. Example: gs://my-bucket1.
  CHUNK_SIZE: Number of tokens each chunk should have.
  CHUNK_OVERLAP: Number of tokens overlap between chunks.
  EMBEDDING_MODEL_QPM_RATE: The QPM rate to limit RAGs access to your embedding model. Example: 1000.

// ImportRagFiles
// Import a single Cloud Storage file or all files in a Cloud Storage bucket.
// Input: LOCATION, 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://LOCATION-aiplatform.googleapis.com/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": CHUNK_SIZE,
      "chunk_overlap": CHUNK_OVERLAP
    },
    "max_embedding_requests_per_min": EMBEDDING_MODEL_QPM_RATE
  }
}'

// Poll the operation status.
// The response contains the number of files imported.
OPERATION_ID: The operation ID you get from the response of the previous command.
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.

  PROJECT_ID: Your project ID.
  LOCATION: The region to process the request.
  RAG_CORPUS_ID: The corpus ID of your RAG corpus.
  FOLDER_RESOURCE_ID: The resource ID of your Google Drive folder.
  CHUNK_SIZE: Number of tokens each chunk should have.
  CHUNK_OVERLAP: Number of tokens overlap between chunks.
  EMBEDDING_MODEL_QPM_RATE: The QPM rate to limit RAGs access to your embedding model. Example: 1000.

// ImportRagFiles
// Import all files in a Google Drive folder.
// Input: LOCATION, 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://LOCATION-aiplatform.googleapis.com/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: The operation ID you get from the response of the previous command.
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.

Esempio di elenco di file RAG

Questo esempio di codice mostra come elencare i 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

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Visualizza un esempio di file RAG

Questo esempio di codice mostra come ottenere 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

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Eliminare un esempio di file RAG

Questo esempio di codice mostra come 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

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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.

Query di recupero

Quando un utente pone una domanda o fornisce un prompt, il componente di recupero in RAG esegue una ricerca nella 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 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": VECTOR_DISTANCE_THRESHOLD
  },
  "query": {
   "text": "TEXT",
   "similarity_top_k": SIMILARITY_TOP_K
  }
}

Per inviare la richiesta, scegli una delle seguenti opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

PowerShell

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

Generazione

L'LLM genera una risposta fondata utilizzando i contesti recuperati.

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

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che ti consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso alla CLI gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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

Passaggi successivi

• Per scoprire di più sui modelli di generazione supportati, consulta Modelli di IA generativa che supportano RAG.
• Per scoprire di più sui modelli di incorporamento supportati, consulta Modelli di incorporamento.
• Per scoprire di più sui modelli aperti, consulta Modelli aperti.
• Per scoprire di più su RAG Engine, consulta la panoramica di RAG Engine.