Filtra con la búsqueda de metadatos

En esta página, se muestra cómo usar la función de búsqueda de metadatos basada en esquemas en el motor RAG en Gemini Enterprise Agent Platform. Puedes definir un esquema de metadatos para un corpus, adjuntar metadatos a los archivos dentro de ese corpus y usar estos metadatos para filtrar contextos durante la recuperación.

Antes de comenzar

Para usar la búsqueda de metadatos, debes tener un corpus de RAG y archivos de RAG existentes. Para obtener información sobre cómo crear un corpus y subir archivos, consulta Administra tu base de conocimiento de RAG.

Cuando creas un corpus o subes un archivo, la API muestra un RAG_CORPUS_ID y un RAG_FILE_ID numéricos (por ejemplo, 123456789). Debes tener estos IDs a mano para administrar tus recursos de metadatos.

Recursos de metadatos

La función de búsqueda de metadatos usa la siguiente jerarquía de recursos:

  • RagCorpus: Es el recurso de nivel superior que contiene tus archivos de RAG y sus configuraciones.

    • RagDataSchema: Es un recurso secundario de RagCorpus. Define la estructura de un solo campo de metadatos que se usa dentro del corpus. Cada esquema especifica una clave (por ejemplo, year) y un tipo de datos (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN o LIST). Debes definir un RagDataSchema para cada clave de metadatos que deseas usar para el filtrado.

    • RagFile: Es un recurso secundario de RagCorpus que representa un solo documento ingerido.

      • RagMetadata: Es un recurso secundario de RagFile. Representa un solo par clave-valor de metadatos adjunto a ese archivo específico (por ejemplo, year=2024). La clave que se usa en un recurso RagMetadata debe corresponder a una clave definida en un RagDataSchema para el corpus superior. Se pueden adjuntar varios recursos RagMetadata a un solo archivo.

Administra esquemas de metadatos

Después de crear un corpus de RAG, define la estructura de metadatos con el recurso RagDataSchema a nivel del corpus. También puedes ver y borrar los esquemas que definas.

Define esquemas de metadatos

Cuando defines un esquema, especificas una clave y un tipo de datos. Los tipos válidos que puede tener una clave son los siguientes:

  • INTEGER: Se pasa en valores de metadatos como un int_value.
  • FLOAT: Se pasa en valores de metadatos como un float_value.
  • STRING: Se pasa en valores de metadatos como un str_value.
  • DATETIME: Se pasa en valores de metadatos como un datetime_value (cadena con formato RFC 3339, por ejemplo, "2024-01-01T00:00:00Z").
  • BOOLEAN: Se pasa en valores de metadatos como un bool_value.
  • LIST: Se pasa en valores de metadatos como un list_value. En el siguiente ejemplo de REST, se muestra cómo crear por lotes esquemas de metadatos que definen los campos year y month para un corpus.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de 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"}
      }
    }
  ]
}'

Enumera esquemas de metadatos

En el siguiente ejemplo de REST, se muestra cómo enumerar los esquemas de metadatos definidos para un corpus.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de 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

Borra esquemas de metadatos

En el siguiente ejemplo de REST, se muestra cómo borrar por lotes esquemas de metadatos de un corpus.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de RAG.
  • RAG_DATA_SCHEMA_KEY_1: Es el nombre de clave del primer esquema de metadatos que se borrará.
  • RAG_DATA_SCHEMA_KEY_2: Es el nombre de clave del segundo esquema de metadatos que se borrará.
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}"'"
  ]
}'

Administra metadatos de archivos

Después de subir o importar archivos a tu corpus, puedes adjuntar, actualizar, ver y borrar los metadatos asociados con esos archivos.

Adjunta metadatos a un archivo

Los metadatos adjuntos deben cumplir con el esquema definido para el corpus. En el siguiente ejemplo de REST, se muestra cómo adjuntar varios valores de metadatos a un archivo.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de RAG.
  • RAG_FILE_ID: Es el ID del archivo de 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" } }
      }
    }
  ]
}'

Enumera los metadatos de un archivo

En el siguiente ejemplo de REST, se muestra cómo enumerar los metadatos adjuntos a un archivo específico.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de RAG.
  • RAG_FILE_ID: Es el ID del archivo de 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

Actualiza metadatos

Puedes actualizar los valores de metadatos adjuntos a un archivo. En el siguiente ejemplo de REST, se muestra cómo actualizar el valor de metadatos asociado con la clave year. RAG_METADATA_KEY es la cadena que se usó cuando creaste los metadatos.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de RAG.
  • RAG_FILE_ID: Es el ID del archivo de RAG.
  • RAG_METADATA_KEY: Es el nombre de clave de los metadatos que se actualizarán.
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 } }
}'

Borra metadatos de un archivo

En el siguiente ejemplo de REST, se muestra cómo borrar por lotes valores de metadatos de un archivo.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de RAG.
  • RAG_FILE_ID: Es el ID del archivo de RAG.
  • RAG_METADATA_KEY_1: Es el nombre de clave del primer valor de metadatos que se borrará.
  • RAG_METADATA_KEY_2: Es el nombre de clave del segundo valor de metadatos que se borrará.
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 contextos con metadatos

Para mejorar la relevancia de los resultados, usa metadatos de archivos para limitar el espacio de búsqueda durante la recuperación de contexto. Agrega una expresión metadata_filter a tu solicitud RetrieveContexts con CEL (Common Expression Language) (por ejemplo, year == 2024 && month == "May"). Solo se consideran para la recuperación los archivos con metadatos que coincidan con la expresión de filtro.

En el siguiente ejemplo de REST, se muestra cómo recuperar contextos con un filtro de metadatos.

REST

Reemplaza las siguientes variables:

  • PROJECT_ID: Es tu ID del proyecto.
  • LOCATION: Es la región para procesar la solicitud.
  • RAG_CORPUS_ID: Es el ID del corpus de 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\""
         }
      }
    }
}'

¿Qué sigue?