Filtrar com a pesquisa de metadados

Esta página mostra como usar o recurso de pesquisa de metadados com base em esquema no mecanismo RAG da Gemini Enterprise Agent Platform. É possível definir um esquema de metadados para um corpus, anexar metadados a arquivos nesse corpus e usar esses metadados para filtrar contextos durante a recuperação.

Antes de começar

Para usar a pesquisa de metadados, é necessário ter um corpus RAG e arquivos RAG. Para saber como criar um corpus e fazer upload de arquivos, consulte Gerenciar sua base de conhecimento RAG.

Ao criar um corpus ou fazer upload de um arquivo, a API retorna um RAG_CORPUS_ID e um RAG_FILE_ID numéricos (por exemplo, 123456789). É necessário ter esses IDs para gerenciar seus recursos de metadados.

Recursos de metadados

O recurso de pesquisa de metadados usa a seguinte hierarquia de recursos:

  • RagCorpus:o recurso de nível superior que contém seus arquivos RAG e as configurações deles.

    • RagDataSchema:um recurso filho de RagCorpus. Ele define a estrutura de um único campo de metadados usado no corpus. Cada esquema especifica uma chave (por exemplo, year) e um tipo de dados (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN ou LIST). É necessário definir um RagDataSchema para cada chave de metadados que você pretende usar para filtragem.

    • RagFile:um recurso filho de RagCorpus que representa um único documento ingerido.

      • RagMetadata:um recurso filho de RagFile. Ele representa um único par de metadados de chave-valor anexado a esse arquivo específico (por exemplo, year=2024). A chave usada em um recurso RagMetadata precisa corresponder a uma chave definida em um RagDataSchema para o corpus pai. Vários recursos RagMetadata podem ser anexados a um único arquivo.

Gerenciar esquemas de metadados

Depois de criar um corpus RAG, defina a estrutura de metadados usando o recurso RagDataSchema no nível do corpus. Também é possível visualizar e excluir os esquemas definidos.

Definir esquemas de metadados

Ao definir um esquema, você especifica uma chave e um tipo de dados. Os tipos válidos que uma chave pode ser são:

  • INTEGER: transmitido em valores de metadados como um int_value.
  • FLOAT: transmitido em valores de metadados como um float_value.
  • STRING: transmitido em valores de metadados como um str_value.
  • DATETIME: transmitido em valores de metadados como um datetime_value (string formatada RFC 3339, por exemplo, "2024-01-01T00:00:00Z").
  • BOOLEAN: transmitido em valores de metadados como um bool_value.
  • LIST: transmitido em valores de metadados como um list_value. O exemplo de REST a seguir mostra como criar esquemas de metadados em lote que definem os campos year e month para um corpus.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do 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"}
      }
    }
  ]
}'

Listar esquemas de metadados

O exemplo de REST a seguir mostra como listar os esquemas de metadados definidos para um corpus.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do 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

Excluir esquemas de metadados

O exemplo de REST a seguir mostra como excluir esquemas de metadados em lote de um corpus.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus RAG.
  • RAG_DATA_SCHEMA_KEY_1: o nome da chave do primeiro esquema de metadados a ser excluído.
  • RAG_DATA_SCHEMA_KEY_2: o nome da chave do segundo esquema de metadados a ser excluído.
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}"'"
  ]
}'

Gerenciar metadados de arquivos

Depois de fazer upload ou importar arquivos para o corpus, é possível anexar, atualizar, visualizar e excluir os metadados associados a esses arquivos.

Anexar metadados a um arquivo

Os metadados anexados precisam estar em conformidade com o esquema definido para o corpus. O exemplo de REST a seguir mostra como anexar vários valores de metadados a um arquivo.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus RAG.
  • RAG_FILE_ID: o ID do arquivo 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" } }
      }
    }
  ]
}'

Listar metadados de um arquivo

O exemplo de REST a seguir mostra como listar os metadados anexados a um arquivo específico.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus RAG.
  • RAG_FILE_ID: o ID do arquivo 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

Atualizar metadados

É possível atualizar os valores de metadados anexados a um arquivo. O exemplo de REST a seguir mostra como atualizar o valor de metadados associado à chave year. O RAG_METADATA_KEY é a string usada quando você criou os metadados.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus RAG.
  • RAG_FILE_ID: o ID do arquivo RAG.
  • RAG_METADATA_KEY: o nome da chave dos metadados a serem atualizados.
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 } }
}'

Excluir metadados de um arquivo

O exemplo de REST a seguir mostra como excluir valores de metadados em lote de um arquivo.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do corpus RAG.
  • RAG_FILE_ID: o ID do arquivo RAG.
  • RAG_METADATA_KEY_1: o nome da chave do primeiro valor de metadados a ser excluído.
  • RAG_METADATA_KEY_2: o nome da chave do segundo valor de metadados a ser excluído.
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}"'"
  ]
}'

Filtrar contextos com metadados

Para melhorar a relevância dos resultados, use metadados de arquivos para restringir o espaço de pesquisa durante a recuperação de contexto. Adicione uma expressão metadata_filter à solicitação RetrieveContexts usando a CEL (Common Expression Language), por exemplo, year == 2024 && month == "May". Somente arquivos com metadados que correspondam à expressão de filtro são considerados para recuperação.

O exemplo de REST a seguir mostra como recuperar contextos usando um filtro de metadados.

REST

Substitua as seguintes variáveis:

  • PROJECT_ID: seu ID do projeto.
  • LOCATION: a região para processar a solicitação.
  • RAG_CORPUS_ID: o ID do 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\""
         }
      }
    }
}'

A seguir