API RAG Engine

Vertex AI RAG Engine è un componente della piattaforma Vertex AI, che facilita la Retrieval-Augmented Generation (RAG). RAG Engine consente ai modelli linguistici di grandi dimensioni (LLM) di accedere e incorporare dati da fonti di conoscenza esterne, come documenti e database. Utilizzando la RAG, gli LLM possono generare risposte più accurate e informative.

Elenco dei parametri

Questa sezione elenca:

Parametri	Esempi
Consulta Parametri di gestione del corpus.	Vedi Esempi di gestione del corpus.
Vedi Parametri di gestione dei file.	Vedi Esempi di gestione dei file.
Vedi Parametri di gestione del progetto.	Vedi Esempi di gestione dei progetti.

Parametri di gestione del corpus

Per informazioni su un corpus RAG, vedi Gestione del corpus.

Crea un corpus RAG

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

Body Request

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 viene utilizzato per criptare i dati at-rest correlati al corpus RAG. Il nome della chiave è applicabile solo all'opzione RagManaged per il database vettoriale. Una volta creato il corpus, questo campo può essere impostato e non può essere aggiornato o eliminato. Formato: projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{key_name}
vector_db_config	(Facoltativo) Immutabile: vectorDbConfig La configurazione per i database vettoriali.
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}

vectorDbConfig

Parametri
rag_managed_db	oneof vector_db: vectorDbConfig.RagManagedDb Se non viene specificato alcun database vettoriale, rag_managed_db è il database vettoriale predefinito.
pinecone	oneof vector_db: vectorDbConfig.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_vector_search	oneof vector_db: vectorDbConfig.VertexVectorSearch Specifica l'istanza di Vertex Vector Search.
vertex_vector_search.index	string Questo è il nome risorsa dell'indice Vector Search 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 di indice Vector Search 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 Questo è il nome completo della risorsa del secret archiviato in Secret Manager, che contiene la chiave API Pinecone. 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 l'impostazione. Se lo lasci vuoto, utilizziamo text-embedding-005 come modello di incorporamento.

Aggiorna un corpus RAG

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

Body Request

Parametri
display_name	(Facoltativo) string Il nome visualizzato del corpus RAG.
description	(Facoltativo) string La descrizione del corpus RAG.
rag_vector_db.pinecone.index_name	string Questo è il nome utilizzato per creare l'indice Pinecone utilizzato con il corpus RAG. Se il tuo RagCorpus è stato creato con una configurazione Pinecone e questo campo non è mai stato impostato prima, puoi aggiornare il nome dell'indice dell'istanza Pinecone.
rag_vector_db.vertex_vector_search.index	string Questo è il nome risorsa dell'indice Vector Search 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 prima, puoi aggiornarlo.
rag_vector_db.vertex_vector_search.index_endpoint	string Questo è il nome della risorsa dell'endpoint di indice Vector Search 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 prima, 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 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 Le dimensioni standard della pagina dell'elenco.
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 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}

Elimina 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, vedi Gestione dei file.

Caricare un file RAG

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

Body Request

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 di 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 blocco.
rag_file_transformation_config.rag_file_chunking_config.fixed_length_chunking.chunk_overlap	int32 La sovrapposizione 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 canale Slack.
channels.channels.start_time	(Facoltativo) google.protobuf.Timestamp Il timestamp iniziale per i 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 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. 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 canale 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. 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 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}

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 i parametri a livello di progetto.

RagEngineConfig

Parametri
RagManagedDbConfig.scaled	Questo livello offre prestazioni su scala di produzione insieme alla funzionalità di scalabilità automatica.
RagManagedDbConfig.basic	Questo livello offre un livello di computing economico e basso.
RagManagedDbConfig.unprovisioned	Questo livello elimina RagManagedDb e la relativa istanza Spanner sottostante.

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 all'interfaccia a riga di comando 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 corpus RAG con un nuovo nome visualizzato, una nuova descrizione e una nuova configurazione del database vettoriale. Tuttavia, non puoi modificare i seguenti parametri nel corpus RAG:

• Il tipo di database vettoriale. Ad esempio, non puoi modificare il database vettoriale da Weaviate a Vertex AI Feature Store.
• 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 all'interfaccia a riga di comando 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

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

Esempio di elenco di corpora RAG

Questi esempi di codice mostrano come elencare tutti i 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: la dimensione standard della pagina dell'elenco. Puoi modificare il numero di corpus RAG da restituire per pagina aggiornando il parametro page_size.
• PAGE_TOKEN: il token della pagina di elenco standard. Ottenuto in genere utilizzando ListRagCorporaResponse.next_page_token della precedente chiamata VertexRagDataService.ListRagCorpora.

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 di 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 di 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 all'interfaccia a riga di comando 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

Dovresti ricevere un codice di stato di operazione riuscita (2xx) e un elenco di corpus RAG nel PROJECT_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"

# 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 di 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 di 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 all'interfaccia a riga di comando 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 di 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 di 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 all'interfaccia a riga di comando 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

File e cartelle possono essere importati 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.

response.skipped_rag_files_count indica il numero di file ignorati durante l'importazione. Un file viene ignorato quando si verificano 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 di 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 di 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 all'interfaccia a riga di comando 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: la dimensione 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 di elenco standard. Ottenuto utilizzando ListRagFilesResponse.next_page_token della chiamata VertexRagDataService.ListRagFiles precedente.

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 di 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 di 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 all'interfaccia a riga di comando 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

Dovresti ricevere un codice di stato riuscito (2xx) insieme a un elenco di RagFiles nel 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

Visualizzare 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 di 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 di 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 all'interfaccia a riga di comando 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 di 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 di 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 all'interfaccia a riga di comando 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

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 un utente pone una domanda o fornisce un prompt, il componente di recupero in RAG cerca nella sua knowledge base le informazioni pertinenti alla query.

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 di 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 di 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 all'interfaccia a riga di comando 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

Dovresti ricevere un codice di stato riuscito (2xx) e un elenco di RagFiles 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 di 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 di 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 all'interfaccia a riga di comando 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 disponibile nella risorsa RagEngineConfig e 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 Scaled, Basic o Unprovisioned.

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 hai una grande quantità di dati in RagManagedDb nei tuoi corpora RAG, il downgrade a un 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 sezione 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.