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

Filtrare con la ricerca di metadati

Questa pagina mostra come utilizzare la funzionalità di ricerca dei metadati basata sullo schema nel motore RAG sulla piattaforma Gemini Enterprise Agent. Puoi definire uno schema di metadati per un corpus, allegare i metadati ai file all'interno di questo corpus e utilizzare questi metadati per filtrare i contesti durante il recupero.

Prima di iniziare

Per utilizzare la ricerca nei metadati, devi disporre di un corpus RAG e di file RAG esistenti. Per scoprire come creare un corpus e caricare file, consulta Gestire la knowledge base RAG.

Quando crei un corpus o carichi un file, l'API restituisce un RAG_CORPUS_ID e un RAG_FILE_ID numerici (ad esempio, 123456789). Devi avere a portata di mano questi ID per gestire le risorse di metadati.

Risorse sui metadati

La funzionalità di ricerca nei metadati utilizza la seguente gerarchia delle risorse:

RagCorpus: la risorsa di primo livello che contiene i file RAG e le relative configurazioni.
- RagDataSchema:una risorsa secondaria di RagCorpus. Definisce la struttura di un singolo campo di metadati utilizzato all'interno del corpus. Ogni schema specifica una chiave (ad esempio year) e un tipo di dati (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN o LIST). Devi definire un RagDataSchema per ogni chiave dei metadati che intendi utilizzare per il filtraggio.
- RagFile: una risorsa secondaria di RagCorpus che rappresenta un singolo documento importato.
  - RagMetadata:una risorsa secondaria di RagFile. Rappresenta una singola coppia di metadati chiave-valore allegata a quel file specifico (ad esempio year=2024). La chiave utilizzata in una risorsa RagMetadata deve corrispondere a una chiave definita in un RagDataSchema per il corpus principale. È possibile allegare più risorse RagMetadata a un singolo file.

Gestione schemi di metadati

Dopo aver creato un corpus RAG, definisci la struttura dei metadati utilizzando la risorsa RagDataSchema a livello di corpus. Puoi anche visualizzare ed eliminare gli schemi che definisci.

Definisci schemi di metadati

Quando definisci uno schema, specifichi una chiave e un tipo di dati. I tipi validi di una chiave sono:

INTEGER: Passato nei valori dei metadati come int_value.
FLOAT: Passato nei valori dei metadati come float_value.
STRING: Passato nei valori dei metadati come str_value.
DATETIME: passato nei valori dei metadati come datetime_value (stringa formattata RFC 3339, ad esempio "2024-01-01T00:00:00Z").
BOOLEAN: Passato nei valori dei metadati come bool_value.
LIST: valori dei metadati passati come list_value. Il seguente esempio REST mostra come creare in batch schemi di metadati che definiscono i campi year e month per un corpus.

REST

Sostituisci le seguenti variabili:

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

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "year",
        "schema_details": {"type": "INTEGER"}
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'",
      "rag_data_schema": {
        "key": "month",
        "schema_details": {"type": "STRING"}
      }
    }
  ]
}'

Elenca schemi di metadati

Il seguente esempio REST mostra come elencare gli schemi di metadati definiti per un corpus.

REST

Sostituisci le seguenti variabili:

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

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

Elimina schemi di metadati

Il seguente esempio REST mostra come eliminare in batch gli schemi dei metadati da un corpus.

REST

Sostituisci le seguenti variabili:

PROJECT_ID: il tuo ID progetto.
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID del corpus RAG.
RAG_DATA_SCHEMA_KEY_1: il nome della chiave del primo schema dei metadati da eliminare.
RAG_DATA_SCHEMA_KEY_2: il nome della chiave del secondo schema dei metadati da eliminare.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_DATA_SCHEMA_KEY_1=RAG_DATA_SCHEMA_KEY_1
RAG_DATA_SCHEMA_KEY_2=RAG_DATA_SCHEMA_KEY_2
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragDataSchemas:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragDataSchemas/'"${RAG_DATA_SCHEMA_KEY_2}"'"
  ]
}'

Gestire i metadati dei file

Dopo aver caricato o importato i file nel corpus, puoi allegare, aggiornare, visualizzare ed eliminare i metadati associati.

Allegare metadati a un file

I metadati allegati devono essere conformi allo schema definito per il corpus. Il seguente esempio REST mostra come allegare più valori di metadati a un file.

REST

Sostituisci le seguenti variabili:

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

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchCreate \
-d '{
  "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
  "requests": [
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "year", "value": { "int_value": 2024 } }
      }
    },
    {
      "parent": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'",
      "rag_metadata": {
        "user_specified_metadata": { "key": "month", "value": { "str_value": "May" } }
      }
    }
  ]
}'

Elencare i metadati di un file

Il seguente esempio REST mostra come elencare i metadati allegati a un file specifico.

REST

Sostituisci le seguenti variabili:

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

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

Aggiorna metadati

Puoi aggiornare i valori dei metadati allegati a un file. Il seguente esempio REST mostra come aggiornare il valore dei metadati associato alla chiave year. RAG_METADATA_KEY è la stringa utilizzata al momento della creazione dei metadati.

REST

Sostituisci le seguenti variabili:

PROJECT_ID: il tuo ID progetto.
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID del corpus RAG.
RAG_FILE_ID: l'ID del file RAG.
RAG_METADATA_KEY: il nome della chiave dei metadati da aggiornare.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY=RAG_METADATA_KEY
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata/${RAG_METADATA_KEY} \
-d '{
  "user_specified_metadata": { "key": "'"${RAG_METADATA_KEY}"'", "value": { "int_value": 2025 } }
}'

Eliminare i metadati da un file

Il seguente esempio REST mostra come eliminare in batch i valori dei metadati da un file.

REST

Sostituisci le seguenti variabili:

PROJECT_ID: il tuo ID progetto.
LOCATION: la regione in cui elaborare la richiesta.
RAG_CORPUS_ID: l'ID del corpus RAG.
RAG_FILE_ID: l'ID del file RAG.
RAG_METADATA_KEY_1: il nome della chiave del primo valore dei metadati da eliminare.
RAG_METADATA_KEY_2: il nome della chiave del secondo valore dei metadati da eliminare.

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
RAG_FILE_ID=RAG_FILE_ID
RAG_METADATA_KEY_1=RAG_METADATA_KEY_1
RAG_METADATA_KEY_2=RAG_METADATA_KEY_2
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/ragCorpora/${RAG_CORPUS_ID}/ragFiles/${RAG_FILE_ID}/ragMetadata:batchDelete \
-d '{
  "names": [
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_1}"'",
    "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'/ragFiles/'"${RAG_FILE_ID}"'/ragMetadata/'"${RAG_METADATA_KEY_2}"'"
  ]
}'

Filtrare i contesti con i metadati

Per migliorare la pertinenza dei risultati, utilizza i metadati dei file per restringere lo spazio di ricerca durante il recupero del contesto. Aggiungi un'espressione metadata_filter alla richiesta RetrieveContexts utilizzando CEL (Common Expression Language) (ad esempio, year == 2024 && month == "May"). Vengono presi in considerazione per il recupero solo i file con metadati che corrispondono all'espressione di filtro.

Il seguente esempio REST mostra come recuperare i contesti utilizzando un filtro dei metadati.

REST

Sostituisci le seguenti variabili:

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

PROJECT_ID=PROJECT_ID
LOCATION=LOCATION
RAG_CORPUS_ID=RAG_CORPUS_ID
QUERY="except share amounts"
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}:retrieveContexts -d '{
    "vertex_rag_store": {
       "rag_resources": [
         {
           "rag_corpus": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/ragCorpora/'"${RAG_CORPUS_ID}"'"
         }
       ]
    },    
    "query": {
      "text": "'"${QUERY}"'", 
      "rag_retrieval_config": {
         "top_k": 10,
         "filter": {
            "vector_distance_threshold": 0.5,
            "metadata_filter": "year == 2024 && month == \"May\""
         }
      }
    }
}'

Passaggi successivi

Per saperne di più sul caricamento e sulla gestione dei file, consulta Gestire la knowledge base RAG.
Per saperne di più sulla ricerca vettoriale standard in RAG, consulta Utilizzare la ricerca vettoriale con RAG.

Filtrare con la ricerca di metadati Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Risorse sui metadati

Gestione schemi di metadati

Definisci schemi di metadati

REST

Elenca schemi di metadati

REST

Elimina schemi di metadati

REST

Gestire i metadati dei file

Allegare metadati a un file

REST

Elencare i metadati di un file

REST

Aggiorna metadati

REST

Eliminare i metadati da un file

REST

Filtrare i contesti con i metadati

REST

Passaggi successivi

Filtrare con la ricerca di metadati