API RAG Engine

Vertex AI RAG Engine è un componente della piattaforma Vertex AI per la Retrieval-Augmented Generation (RAG). Con RAG Engine, i modelli linguistici di grandi dimensioni (LLM) possono accedere e utilizzare i dati di fonti di conoscenza esterne, come documenti e database, per generare risposte più accurate e informative.

Questo documento fornisce informazioni ed esempi per l'utilizzo dell'API RAG Engine e tratta i seguenti argomenti:

• Gestione del corpus: descrive i parametri API per la gestione dei corpus e fornisce esempi per creare, aggiornare, elencare, ottenere ed eliminare un corpus RAG.
• Gestione dei file: descrive i parametri API per la gestione dei file e fornisce esempi per il caricamento, l'importazione e la gestione dei file all'interno di un corpus RAG.
• Recupero e generazione: descrive i parametri dell'API per recuperare i contesti e generare risposte fondate, con esempi.
• Gestione dei progetti: spiega come configurare le impostazioni a livello di progetto per il motore RAG, con esempi.

Il seguente diagramma riassume il flusso di lavoro generale per l'utilizzo dell'API RAG Engine:

Parametri di gestione del corpus

Questa sezione descrive i parametri per la gestione di un corpus RAG. Per saperne di più, consulta Gestione del corpus.

Crea un corpus RAG

Le tabelle seguenti descrivono i parametri utilizzati per creare un corpus RAG.

Opzioni del database vettoriale

Puoi scegliere una delle seguenti opzioni di database vettoriale per il tuo corpus RAG.

Opzione di database vettoriale	Descrizione	Caso d'uso
rag_managed_db	Un database vettoriale serverless completamente gestito fornito da Vertex AI. Questa è l'opzione predefinita.	Consigliato se vuoi una soluzione semplice e integrata senza gestire la tua infrastruttura di database vettoriale.
pinecone	Integrazione con un database vettoriale Pinecone autogestito. Richiede di fornire il nome dell'indice Pinecone e la chiave API.	Utilizza questa opzione se hai già una configurazione Pinecone esistente o preferisci le sue funzionalità specifiche.
vertex_vector_search	Integrazione con la ricerca vettoriale. Richiede la fornitura dei nomi delle risorse dell'indice e dell'endpoint indice.	Utilizza questa opzione se hai bisogno di una soluzione di ricerca vettoriale scalabile e ad alte prestazioni all'interno dell'ecosistema Google Cloud.

Corpo della richiesta

Parametri
display_name	Obbligatorio: string Il nome visualizzato del corpus RAG.
description	(Facoltativo) string La descrizione del corpus RAG.
encryption_spec	(Facoltativo) Immutabile: string Il nome della chiave CMEK utilizzata per criptare i dati inattivi correlati al corpus RAG. Questa chiave è applicabile solo all'opzione RagManaged per il database vettoriale. Questo campo può essere impostato solo durante la creazione del corpus. Formato: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}
vector_db_config	(Facoltativo) Immutabile: vectorDbConfig La configurazione per il database vettoriale. Questo campo è un oggetto oneof. Scegli una delle opzioni seguenti: rag_managed_db: il database vettoriale predefinito completamente gestito. pinecone: specifica l'istanza Pinecone. index_name (string): il nome dell'indice Pinecone. Puoi impostarlo in un secondo momento con una chiamata all'UpdateRagCorpus. api_auth.api_key_config.api_key_secret_version (string): il nome completo della risorsa del secret in Secret Manager che contiene la chiave API Pinecone. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}. Puoi impostarlo in un secondo momento. vertex_vector_search: specifica l'istanza Vector Search. index (string): il nome della risorsa dell'indice di ricerca vettoriale. Formato: projects/{project}/locations/{location}/indexes/{index}. Puoi impostarlo in un secondo momento. index_endpoint (string): il nome della risorsa dell'endpoint di indice Vector Search. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}. Puoi impostarlo in un secondo momento.
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}
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 l'impostazione. Se lo lasci vuoto, viene utilizzato text-embedding-005 come modello di incorporamento predefinito.

Aggiorna un corpus RAG

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

Corpo della richiesta

Parametri
display_name	(Facoltativo) string Il nuovo nome visualizzato del corpus RAG.
description	(Facoltativo) string La nuova descrizione del corpus RAG.
rag_vector_db.pinecone.index_name	string Il nome dell'indice Pinecone. Puoi impostare questo campo se il tuo RagCorpus è stato creato con una configurazione Pinecone e il nome dell'indice non è stato impostato in precedenza.
rag_vector_db.vertex_vector_search.index	string Il nome della risorsa dell'indice Vector Search. Puoi impostare questo campo se il tuo RagCorpus è stato creato con una configurazione Vector Search e l'indice non è stato impostato in precedenza. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}
rag_vector_db.vertex_vector_search.index_endpoint	string Il nome della risorsa dell'endpoint di indice Vector Search. Puoi impostare questo campo se il tuo RagCorpus è stato creato con una configurazione Vector Search e l'endpoint dell'indice non è stato impostato in precedenza. Formato: projects/{project}/locations/{location}/indexes/{index}
rag_vector_db.api_auth.api_key_config.api_key_secret_version	string Il nome risorsa completo del secret in Secret Manager che contiene la chiave API Pinecone. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

Elenca i corpora RAG

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

Parametri
page_size	(Facoltativo) int Il numero massimo di corpora da restituire per pagina.
page_token	(Facoltativo) string Il token della pagina dell'elenco standard. In genere, viene ottenuto da [ListRagCorporaResponse.next_page_token][] della precedente chiamata [VertexRagDataService.ListRagCorpora][].

Recuperare un corpus RAG

Questa tabella elenca il parametro utilizzato per ottenere un corpus RAG.

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

Elimina un corpus RAG

Questa tabella elenca il parametro utilizzato per eliminare un corpus RAG.

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

Parametri di gestione dei file

Questa sezione descrive i parametri per la gestione dei file in un corpus RAG. Per saperne di più, consulta Gestione dei file.

Caricare un file RAG

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

Corpo della richiesta

Parametri
parent	Obbligatorio: string Il nome della risorsa RagCorpus in cui caricare il file. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus_id}
rag_file	Obbligatorio: RagFile Il file da caricare. Contiene i seguenti campi: display_name (obbligatorio, string): il nome visualizzato del file RAG. description (facoltativo, string): la descrizione del file RAG.
upload_rag_file_config	Obbligatorio: UploadRagFileConfig La configurazione per RagFile. Contiene i seguenti campi: rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_size (int32): il numero di token in ogni chunk. rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap (int32): la sovrapposizione di token tra i chunk.

Importare 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 Percorso di Cloud Storage. Supporta l'importazione di singoli file e di intere directory 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 blocco.
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 dell'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 viene 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 Google Drive.

SlackSource
channels.channels	Ripetuto: SlackSource.SlackChannels.SlackChannel Informazioni sul canale Slack, inclusi ID e intervallo di tempo da importare.
channels.channels.channel_id	Obbligatorio: string L'ID del 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 per i messaggi da importare.
channels.api_key_config.api_key_secret_version	Obbligatorio: string Il nome risorsa completo del secret archiviato in Secret Manager, che contiene un token di accesso al canale Slack che ha accesso agli ID canale Slack. Vedi: https://api.slack.com/tutorials/tracks/getting-a-token. Formato: projects/{PROJECT_NUMBER}/secrets/{SECRET_ID}/versions/{VERSION_ID}

JiraSource
jira_queries.projects	Ripetuto: string Un elenco di progetti Jira da importare nella loro interezza.
jira_queries.custom_queries	Ripetuto: 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 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 risorsa completo del secret archiviato in Secret Manager, che contiene la chiave API Jira con accesso agli ID dei canali Slack. Vedi: 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 i file.
share_point_sources.sharepoint_folder_id	oneof in folder_source: string L'ID della cartella SharePoint da cui scaricare.
share_point_sources.drive_name	oneof in drive_source: string Il nome dell'unità da cui scaricare.
share_point_sources.drive_id	oneof in drive_source: string L'ID dell'unità da cui scaricare.
share_point_sources.client_id	string L'ID applicazione per l'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 eseguire il download. Può trattarsi del nome o dell'ID del sito.

RagFileParsingConfig
layout_parser	oneof parser: RagFileParsingConfig.LayoutParser Il parser del layout da utilizzare per RagFile.
layout_parser.processor_name	string Il nome completo della risorsa di un processore o di una versione del processore Document AI. 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ò effettuare al processore Document AI al minuto. Consulta la pagina https://cloud.google.com/document-ai/quotas e la pagina Quote per il tuo progetto per impostare un valore appropriato qui. Se non specificato, viene utilizzato un valore predefinito di 120 QPM.
llm_parser	oneof parser: RagFileParsingConfig.LlmParser Il parser LLM da utilizzare per RagFile.
llm_parser.model_name	string Il nome della risorsa di un modello LLM. Formato: projects/{project_id}/locations/{location}/publishers/{publisher}/models/{model}
llm_parser.max_parsing_requests_per_min	string Il numero massimo di richieste che il job può eseguire al modello LLM al minuto. Per impostare un valore appropriato per il tuo progetto, consulta la sezione relativa alle quote del modello e la pagina Quote per il tuo progetto per impostare un valore appropriato. Se non specificato, viene utilizzato un valore predefinito di 5000 QPM.

Recuperare un file RAG

Questa tabella elenca il parametro utilizzato per ottenere un file RAG.

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

Eliminare un file RAG

Questa tabella elenca il parametro utilizzato per eliminare un file RAG.

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

Parametri di 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 risorsa della località da 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 Singola query di recupero RAG.

VertexRagStore

VertexRagStore
rag_resources	elenco: RagResource La rappresentazione dell'origine RAG. Può essere utilizzato per specificare solo il corpus o RagFile. Supporta solo un corpus o più file di un corpus.
rag_resources.rag_corpus	(Facoltativo) string Nome della risorsa 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 del recupero per la query.

RagRetrievalConfig
top_k	(Facoltativo) int32 Il numero di contesti da recuperare.
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 del vettore superiore alla soglia.
ranking.rank_service.model_name	(Facoltativo) string Il nome del modello del servizio di classificazione. Esempio: semantic-ranker-512@latest
ranking.llm_ranker.model_name	(Facoltativo) string Il nome del modello utilizzato per il ranking. Esempio: gemini-2.5-flash

Parametri di previsione

Questa tabella elenca i parametri di previsione.

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

Per maggiori dettagli, consulta VertexRagStore.

Parametri di gestione dei progetti

Questa tabella elenca le configurazioni del livello a livello di progetto per il database gestito del motore RAG.

Livello	Descrizione	Caso d'uso
RagManagedDbConfig.scaled	Un livello su scala di produzione che offre prestazioni elevate e funzionalità di scalabilità automatica per il tuo database vettoriale gestito.	Consigliato per le applicazioni di produzione con carichi di query elevati o grandi volumi di dati.
RagManagedDbConfig.basic	Un livello di computing basso ed economico per il database vettoriale gestito.	Utilizza per lo sviluppo, i test o le applicazioni su piccola scala con traffico ridotto.
RagManagedDbConfig.unprovisioned	Elimina il database vettoriale gestito e le relative risorse sottostanti. In questo modo il database gestito viene disattivato per il progetto.	Utilizzalo per eliminare l'infrastruttura del database gestito quando non è più necessaria per gestire i costi.

Esempi di gestione del corpus

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

Crea un esempio di corpus RAG

Questi esempi di codice mostrano come creare un corpus RAG.

REST

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• CORPUS_DISPLAY_NAME: il nome visualizzato del corpus RAG.
• CORPUS_DESCRIPTION: la descrizione del corpus RAG.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso a Google Cloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login oppure utilizzando Cloud Shell, che esegue automaticamente l'accesso a gcloud CLI . Puoi controllare l'account attivo eseguendo gcloud CLI auth list.

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora"

Powershell

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora" | Select-Object -Expand Content

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

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

  // 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora \
  -d '{
        "display_name" : "CORPUS_DISPLAY_NAME"
    }'

Python

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

from vertexai 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 backend_config
backend_config = rag.RagVectorDbConfig(
    rag_embedding_model_config=rag.RagEmbeddingModelConfig(
        vertex_prediction_endpoint=rag.VertexPredictionEndpoint(
            publisher_model="publishers/google/models/text-embedding-005"
        )
    )
)

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

Aggiorna un esempio di corpus RAG

Puoi aggiornare il nome visualizzato, la descrizione e la configurazione del database vettoriale di un corpus RAG. Tuttavia, non puoi modificare i seguenti parametri immutabili nel corpus RAG:

• Il tipo di database vettoriale. Ad esempio, non puoi modificare il database vettoriale da Pinecone a Vector Search.
• Se utilizzi l'opzione di 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, effettua le seguenti sostituzioni:

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• CORPUS_ID: l'ID corpus del tuo corpus RAG.
• CORPUS_DISPLAY_NAME: il nome visualizzato del corpus RAG.
• CORPUS_DESCRIPTION: la descrizione del corpus RAG.
• INDEX_NAME: il nome della risorsa dell'indice di ricerca vettoriale. Formato: projects/{project}/locations/{location}/indexes/{index}.
• INDEX_ENDPOINT_NAME: il nome della risorsa dell'endpoint di indice Vector Search. Formato: projects/{project}/locations/{location}/indexEndpoints/{index_endpoint}.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso a Google Cloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login oppure utilizzando Cloud Shell, che esegue automaticamente l'accesso a gcloud CLI . Puoi controllare l'account attivo eseguendo gcloud CLI auth list.

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID"

Powershell

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/CORPUS_ID" | Select-Object -Expand Content

Una richiesta riuscita restituisce un codice di stato 2xx.

Esempio di elenco di corpora RAG

Questi esempi di codice mostrano come elencare tutti i tuoi corpus RAG.

REST

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• PAGE_SIZE: il numero massimo di corpora RAG da restituire per pagina.
• PAGE_TOKEN: un token di pagina di una risposta ListRagCorpora precedente per recuperare la pagina successiva dei risultati.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Esegui questo comando:

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

Powershell

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Una richiesta riuscita restituisce un codice di stato 2xx e un elenco di corpus RAG per il progetto specificato.

Python

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

from vertexai 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 {
# ...

Ottenere un esempio di corpus RAG

Questi esempi di codice mostrano come ottenere un corpus RAG.

REST

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• RAG_CORPUS_ID: l'ID della risorsa del corpus RAG.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Esegui questo comando:

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

Powershell

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID" | Select-Object -Expand Content

Una risposta corretta 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 all'interno di vector_db_config, che punta al modello di incorporamento 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.
  ```

```sh
  // 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/v1/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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/
  ```

Python

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

from vertexai 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',
# ...

Elimina un esempio di corpus RAG

Questi esempi di codice mostrano come eliminare un corpus RAG.

REST

Prima di utilizzare i dati della richiesta, effettua 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Esegui questo comando:

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

Powershell

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID" | Select-Object -Expand Content

Una risposta corretta restituisce DeleteOperationMetadata.

Python

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

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

Questi esempi di codice mostrano come caricare un file RAG.

REST

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• RAG_CORPUS_ID: l'ID corpus del tuo corpus RAG.
• LOCAL_FILE_PATH: il percorso locale del file da caricare.
• DISPLAY_NAME: il nome visualizzato del file RAG.
• DESCRIPTION: la descrizione del file RAG.

Per inviare la richiesta, utilizza il comando seguente:

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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:upload"

Python

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

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

Puoi importare file e cartelle da Drive o Cloud Storage. Puoi utilizzare response.metadata per visualizzare errori parziali, tempo di richiesta e tempo di risposta nell'oggetto response dell'SDK.

Il campo response.skipped_rag_files_count contiene il numero di file ignorati durante l'importazione. Il servizio ignora un file se sono soddisfatte le seguenti condizioni:

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

Python

from vertexai 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 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,
    transformation_config=rag.TransformationConfig(
        rag.ChunkingConfig(chunk_size=1024, chunk_overlap=256)
    ),
    import_result_sink="gs://sample-existing-folder/sample_import_result_unique.ndjson",  # Optional: This must be an existing Cloud Storage bucket folder, and the filename must be unique (non-existent).
    llm_parser=rag.LlmParserConfig(
      model_name="gemini-2.5-pro-preview-05-06",
      max_parsing_requests_per_min=100,
    ),  # Optional
    max_embedding_requests_per_min=900,  # Optional
)
print(f"Imported {response.imported_rag_files_count} files.")

REST

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• RAG_CORPUS_ID: l'ID corpus del tuo corpus RAG.
• FOLDER_RESOURCE_ID: l'ID risorsa della tua cartella Drive.
• GCS_URIS: un elenco di località Cloud Storage. Esempio: gs://my-bucket1.
• CHUNK_SIZE: numero di token che ogni blocco deve avere.
• CHUNK_OVERLAP: numero di token sovrapposti tra i chunk.
• EMBEDDING_MODEL_QPM_RATE: la frequenza di query al minuto per limitare l'accesso di RAG al tuo modello di incorporamento. Esempio: 1000.

Metodo HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/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 di queste opzioni:

curl

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import"

Powershell

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles:import" | Select-Object -Expand Content

Una risposta corretta restituisce la risorsa ImportRagFilesOperationMetadata.

Il seguente esempio mostra come importare un file da Cloud Storage. Utilizza il campo di controllo max_embedding_requests_per_min per limitare la velocità con cui RAG Engine chiama il modello di incorporamento durante il processo di indicizzazione ImportRagFiles. Il campo ha un valore predefinito di 1000 chiamate al minuto.

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• RAG_CORPUS_ID: l'ID corpus del tuo corpus RAG.
• GCS_URIS: un elenco di località Cloud Storage. Esempio: gs://my-bucket1.
• CHUNK_SIZE: numero di token che ogni blocco deve avere.
• CHUNK_OVERLAP: numero di token sovrapposti tra i chunk.
• EMBEDDING_MODEL_QPM_RATE: la frequenza di QPM per limitare l'accesso di RAG al tuo modello di incorporamento. Esempio: 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/v1/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
  }
}'

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 velocità con cui RAG Engine chiama il modello di incorporamento durante la procedura di indicizzazione ImportRagFiles. Il campo ha un valore predefinito di 1000 chiamate al minuto.

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• RAG_CORPUS_ID: l'ID corpus del tuo corpus RAG.
• FOLDER_RESOURCE_ID: l'ID risorsa della tua cartella Drive.
• CHUNK_SIZE: numero di token che ogni blocco deve avere.
• CHUNK_OVERLAP: numero di token sovrapposti tra i chunk.
• EMBEDDING_MODEL_QPM_RATE: la frequenza di query al minuto per limitare l'accesso di RAG al tuo modello di incorporamento. Esempio: 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/v1/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
  }
}'

Esempio di elenco di file RAG

Questi esempi di codice mostrano come elencare i file RAG.

REST

Prima di utilizzare i dati della richiesta, effettua 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: il numero massimo di RagFiles da restituire per pagina.
• PAGE_TOKEN: un token di pagina di una risposta ListRagFiles precedente per recuperare la pagina successiva dei risultati.

Metodo HTTP e URL:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Esegui questo comando:

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

Powershell

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles?page_size=PAGE_SIZE&page_token=PAGE_TOKEN" | Select-Object -Expand Content

Una richiesta riuscita restituisce un codice di stato 2xx e un elenco di RagFiles per il RAG_CORPUS_ID specificato.

Python

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

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

Ottenere un esempio di file RAG

Questi esempi di codice mostrano come ottenere un file RAG.

REST

Prima di utilizzare i dati della richiesta, effettua 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Esegui questo comando:

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

Powershell

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Una risposta corretta restituisce la risorsa RagFile.

Python

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

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

Elimina un esempio di file RAG

Questi esempi di codice mostrano come eliminare un file RAG.

REST

Prima di utilizzare i dati della richiesta, effettua 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Esegui questo comando:

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

Powershell

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso a gcloud CLI con il tuo account utente eseguendo gcloud CLI init o gcloud CLI auth login. Puoi controllare l'account attivo eseguendo gcloud CLI 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/v1/projects/PROJECT_ID/locations/LOCATION/ragCorpora/RAG_CORPUS_ID/ragFiles/RAG_FILE_ID" | Select-Object -Expand Content

Una risposta corretta restituisce DeleteOperationMetadata.

Python

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

from vertexai 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.

Esempio di query di recupero

Quando fornisci una query, il componente di recupero nella RAG esegue una ricerca nella knowledge base per trovare informazioni pertinenti.

Python

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

from vertexai 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!",
    rag_retrieval_config=rag.RagRetrievalConfig(
        top_k=10,
        filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
    ),
)
print(response)
# Example response:
# contexts {
#   contexts {
#     source_uri: "gs://your-bucket-name/file.txt"
#     text: "....
#   ....

REST

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

• PROJECT_ID: il tuo ID progetto.
• LOCATION: la regione in cui elaborare la richiesta.
• 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/v1/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
  }
}

curl

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts"

Powershell

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION:retrieveContexts" | Select-Object -Expand Content

Una richiesta riuscita restituisce un codice di stato 2xx e un elenco di contesti correlati.

Esempio di generazione

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

REST

Prima di utilizzare i dati della richiesta, effettua 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-2.5-flash.
• GENERATION_METHOD: metodo LLM per la generazione di contenuti. Opzioni: generateContent, streamGenerateContent.
• INPUT_PROMPT: il testo inviato all'LLM per la generazione di contenuti. Prova a utilizzare un prompt pertinente ai file RAG caricati.
• RAG_CORPUS_RESOURCE: il nome della risorsa RagCorpus. Formato: projects/{project}/locations/{location}/ragCorpora/{rag_corpus}.
• SIMILARITY_TOP_K: (facoltativo) il numero di contesti principali da recuperare.
• VECTOR_DISTANCE_THRESHOLD: facoltativo: vengono restituiti i contesti con una distanza del vettore inferiore alla soglia.
• USER: il tuo nome utente.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATION_METHOD"

Powershell

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

Salva il corpo della richiesta in un file denominato request.json ed 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/v1/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 Python, consulta Installare l'SDK Vertex AI Python. Per saperne di più, consulta la documentazione di riferimento dell'API Python.

from vertexai import rag
from vertexai.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", ...],
                )
            ],
            rag_retrieval_config=rag.RagRetrievalConfig(
                top_k=10,
                filter=rag.utils.resources.Filter(vector_distance_threshold=0.5),
            ),
        ),
    )
)

rag_model = GenerativeModel(
    model_name="gemini-2.0-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....
#   ...

Esempi di gestione dei progetti

Il livello è un'impostazione a livello di progetto nella risorsa RagEngineConfig che influisce sui corpus RAG che utilizzano RagManagedDb. Per ottenere la configurazione del livello, utilizza GetRagEngineConfig. Per aggiornare la configurazione del livello, utilizza UpdateRagEngineConfig.

Per ulteriori informazioni sulla gestione della configurazione dei livelli, consulta Gestire i livelli.

Recupera la configurazione del progetto

I seguenti esempi di codice mostrano come leggere il tuo RagEngineConfig:

Console

1. Nella console Google Cloud , vai alla pagina Motore RAG.

   Vai a RAG Engine

2. Seleziona la regione in cui è in esecuzione RAG Engine. L'elenco dei corpora RAG è aggiornato.
3. Fai clic su Configura RAG Engine. Viene visualizzato il riquadro Configura RAG Engine. Puoi vedere il livello selezionato per il motore RAG.
4. Fai clic su Annulla.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config = rag.rag_data.get_rag_engine_config(
    name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"
)

print(rag_engine_config)

REST

curl -X GET \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig

Aggiorna la configurazione del progetto

Questa sezione fornisce esempi di codice per dimostrare come modificare la configurazione in un livello scalabile, Basic o non sottoposto a provisioning.

Aggiorna il tuo RagEngineConfig al livello Scaled

I seguenti esempi di codice mostrano come impostare RagEngineConfig sul livello scalato:

Console

1. Nella console Google Cloud , vai alla pagina Motore RAG.

   Vai a RAG Engine

2. Seleziona la regione in cui è in esecuzione RAG Engine. L'elenco dei corpora RAG è aggiornato.
3. Fai clic su Configura RAG Engine. Viene visualizzato il riquadro Configura RAG Engine.
4. Seleziona il livello su cui vuoi eseguire RAG Engine.
5. Fai clic su Salva.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"

new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Scaled()),
)

updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)

print(updated_rag_engine_config)

REST

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'scaled': {}}}"

Aggiorna il tuo RagEngineConfig al livello Basic

I seguenti esempi di codice mostrano come impostare RagEngineConfig sul livello Basic:

Nota: se il tuo RagManagedDb contiene una grande quantità di dati nei tuoi corpora RAG, il downgrade al livello Basic potrebbe non riuscire a causa di capacità di calcolo e archiviazione insufficienti.

Console

1. Nella console Google Cloud , vai alla pagina Motore RAG.

   Vai a RAG Engine

2. Seleziona la regione in cui è in esecuzione RAG Engine. L'elenco dei corpora RAG è aggiornato.
3. Fai clic su Configura RAG Engine. Viene visualizzato il riquadro Configura RAG Engine.
4. Seleziona il livello su cui vuoi eseguire RAG Engine.
5. Fai clic su Salva.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"

new_rag_engine_config = rag.RagEngineConfig(
name=rag_engine_config_name,
rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Basic()),
)

updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
rag_engine_config=new_rag_engine_config
)

print(updated_rag_engine_config)

REST

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'basic': {}}}"

Aggiorna il tuo RagEngineConfig al livello Non sottoposto a provisioning

I seguenti esempi di codice mostrano come impostare RagEngineConfig sul livello Non sottoposto a provisioning:

Console

1. Nella console Google Cloud , vai alla pagina Motore RAG.

   Vai a RAG Engine

2. Seleziona la regione in cui è in esecuzione RAG Engine. L'elenco dei corpora RAG è aggiornato.
3. Fai clic su Configura RAG Engine. Viene visualizzato il riquadro Configura RAG Engine.
4. Fai clic su Elimina RAG Engine. Viene visualizzata una finestra di dialogo di conferma.
5. Verifica di voler eliminare i dati in RAG Engine digitando delete, quindi fai clic su Conferma.
6. Fai clic su Salva.

Python

from vertexai import rag
import vertexai

PROJECT_ID = YOUR_PROJECT_ID
LOCATION = YOUR_RAG_ENGINE_LOCATION

# Initialize Vertex AI API once per session
vertexai.init(project=PROJECT_ID, location=LOCATION)

rag_engine_config_name=f"projects/{PROJECT_ID}/locations/{LOCATION}/ragEngineConfig"

new_rag_engine_config = rag.RagEngineConfig(
  name=rag_engine_config_name,
  rag_managed_db_config=rag.RagManagedDbConfig(tier=rag.Unprovisioned()),
)

updated_rag_engine_config = rag.rag_data.update_rag_engine_config(
  rag_engine_config=new_rag_engine_config
)

print(updated_rag_engine_config)

REST

curl -X PATCH \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/ragEngineConfig -d "{'ragManagedDbConfig': {'unprovisioned': {}}}"

Passaggi successivi

• Per scoprire di più sui modelli di generazione supportati, consulta la pagina Modelli di AI generativa che supportano RAG.
• Per scoprire di più sui modelli di embedding supportati, consulta Modelli di embedding.
• Per scoprire di più sui modelli aperti, consulta Modelli aperti.
• Per saperne di più su RAG Engine, consulta la panoramica di RAG Engine.