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 su schema in RAG Engine su Gemini Enterprise Agent Platform. Puoi definire uno schema dei metadati per un corpus, allegare i metadati ai file all'interno del corpus e utilizzarli per filtrare i contesti durante il recupero.

Prima di iniziare

Per utilizzare la ricerca dei metadati, devi disporre di un corpus RAG e di file RAG esistenti. Per scoprire come creare un corpus e caricare file, consulta Gestisci 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 questi ID a portata di mano per gestire le risorse dei metadati.

Risorse dei metadati

La funzionalità di ricerca dei 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 dei 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 i filtri.
- RagFile: una risorsa secondaria di RagCorpus che rappresenta un singolo documento importato.
  - RagMetadata: una risorsa secondaria di RagFile. Rappresenta una singola coppia chiave-valore di metadati associata 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. A un singolo file possono essere allegate più risorse RagMetadata.

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 gli schemi dei metadati

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

INTEGER: Valori dei metadati passati come int_value.
FLOAT: valori dei metadati passati come float_value.
STRING: i valori dei metadati passati come str_value.
DATETIME: valori dei metadati trasmessi come datetime_value (stringa formattata RFC 3339, ad esempio "2024-01-01T00:00:00Z").
BOOLEAN: i valori dei metadati passati come bool_value.
LIST: i 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: l'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 gli schemi dei metadati

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

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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 gli schemi dei metadati

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

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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 di metadati da eliminare.
RAG_DATA_SCHEMA_KEY_2: il nome della chiave del secondo schema di 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}"'"
  ]
}'

Gestisci i metadati dei file

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

Allega i metadati a un file

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

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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" } }
      }
    }
  ]
}'

Elenca i metadati di un file

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

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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 associati a un file. L'esempio REST seguente mostra come aggiornare il valore dei metadati associato alla chiave year. RAG_METADATA_KEY è la stringa utilizzata durante la creazione dei metadati.

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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 } }
}'

Elimina i metadati da un file

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

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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}"'"
  ]
}'

Filtra 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"). Solo i file con metadati che corrispondono all'espressione di filtro vengono presi in considerazione per il recupero.

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

REST

Sostituisci le seguenti variabili:

PROJECT_ID: l'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 scoprire di più sul caricamento e sulla gestione dei file, consulta Gestisci la knowledge base RAG.
Per scoprire di più sulla ricerca vettoriale standard in RAG, consulta Utilizza Vector Search 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 dei metadati

Gestione schemi di metadati

Definisci gli schemi dei metadati

REST

Elenca gli schemi dei metadati

REST

Elimina gli schemi dei metadati

REST

Gestisci i metadati dei file

Allega i metadati a un file

REST

Elenca i metadati di un file

REST

Aggiorna metadati

REST

Elimina i metadati da un file

REST

Filtra i contesti con i metadati

REST

Passaggi successivi

Filtrare con la ricerca di metadati