Filtrer avec la recherche de métadonnées

Cette page explique comment utiliser la fonctionnalité de recherche de métadonnées basée sur un schéma dans le moteur RAG sur Gemini Enterprise Agent Platform. Vous pouvez définir un schéma de métadonnées pour un corpus, associer des métadonnées aux fichiers de ce corpus et utiliser ces métadonnées pour filtrer les contextes lors de la récupération.

Avant de commencer

Pour utiliser la recherche de métadonnées, vous devez disposer d'un corpus RAG et de fichiers RAG. Pour savoir comment créer un corpus et importer des fichiers, consultez Gérer votre base de connaissances RAG.

Lorsque vous créez un corpus ou importez un fichier, l'API renvoie un RAG_CORPUS_ID et un RAG_FILE_ID numériques (par exemple, 123456789). Vous devez disposer de ces ID pour gérer vos ressources de métadonnées.

Ressources de métadonnées

La fonctionnalité de recherche de métadonnées utilise la hiérarchie de ressources suivante :

  • RagCorpus : ressource de premier niveau contenant vos fichiers RAG et leurs configurations.

    • RagDataSchema : ressource enfant de RagCorpus. Il définit la structure d'un seul champ de métadonnées utilisé dans le corpus. Chaque schéma spécifie une clé (par exemple, year) et un type de données (INTEGER, FLOAT, STRING, DATETIME, BOOLEAN ou LIST). Vous devez définir un RagDataSchema pour chaque clé de métadonnées que vous prévoyez d'utiliser pour le filtrage.
    • RagFile : ressource enfant de RagCorpus représentant un seul document ingéré.

      • RagMetadata : ressource enfant de RagFile. Elle représente une seule paire clé-valeur de métadonnées associée à ce fichier spécifique (par exemple, year=2024). La clé utilisée dans une ressource RagMetadata doit correspondre à une clé définie dans un RagDataSchema pour le corpus parent. Plusieurs ressources RagMetadata peuvent être associées à un même fichier.

Gérer les schémas de métadonnées

Après avoir créé un corpus RAG, définissez la structure des métadonnées à l'aide de la ressource RagDataSchema au niveau du corpus. Vous pouvez également afficher et supprimer les schémas que vous définissez.

Définir des schémas de métadonnées

Lorsque vous définissez un schéma, vous spécifiez une clé et un type de données. Les types valides pour une clé sont les suivants :

  • INTEGER : valeurs de métadonnées transmises en tant que int_value.
  • FLOAT : valeurs de métadonnées transmises sous forme de float_value.
  • STRING : valeurs de métadonnées transmises sous forme de str_value.
  • DATETIME : valeurs de métadonnées transmises sous forme de datetime_value (chaîne au format RFC 3339, par exemple "2024-01-01T00:00:00Z").
  • BOOLEAN : valeurs de métadonnées transmises sous forme de bool_value.
  • LIST : valeurs de métadonnées transmises sous forme de list_value. L'exemple REST suivant montre comment créer par lot des schémas de métadonnées qui définissent les champs year et month d'un corpus.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du 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"}
      }
    }
  ]
}'

Lister les schémas de métadonnées

L'exemple REST suivant montre comment lister les schémas de métadonnées définis pour un corpus.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du 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

Supprimer des schémas de métadonnées

L'exemple REST suivant montre comment supprimer par lot des schémas de métadonnées d'un corpus.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du corpus RAG.
  • RAG_DATA_SCHEMA_KEY_1 : nom de clé du premier schéma de métadonnées à supprimer.
  • RAG_DATA_SCHEMA_KEY_2 : nom de clé du deuxième schéma de métadonnées à supprimer.
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}"'"
  ]
}'

Gérer les métadonnées des fichiers

Une fois que vous avez importé des fichiers dans votre corpus, vous pouvez joindre, mettre à jour, afficher et supprimer les métadonnées associées à ces fichiers.

Associer des métadonnées à un fichier

Les métadonnées associées doivent être conformes au schéma défini pour le corpus. L'exemple REST suivant montre comment associer plusieurs valeurs de métadonnées à un fichier.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du corpus RAG.
  • RAG_FILE_ID : ID du fichier 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" } }
      }
    }
  ]
}'

Lister les métadonnées d'un fichier

L'exemple REST suivant montre comment lister les métadonnées associées à un fichier spécifique.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du corpus RAG.
  • RAG_FILE_ID : ID du fichier 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

Mettre à jour les métadonnées

Vous pouvez mettre à jour les valeurs de métadonnées associées à un fichier. L'exemple REST suivant montre comment mettre à jour la valeur de métadonnées associée à la clé year. RAG_METADATA_KEY est la chaîne utilisée lors de la création des métadonnées.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du corpus RAG.
  • RAG_FILE_ID : ID du fichier RAG.
  • RAG_METADATA_KEY : nom de la clé des métadonnées à mettre à jour.
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 } }
}'

Supprimer les métadonnées d'un fichier

L'exemple REST suivant montre comment supprimer par lot des valeurs de métadonnées d'un fichier.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du corpus RAG.
  • RAG_FILE_ID : ID du fichier RAG.
  • RAG_METADATA_KEY_1 : nom de la clé de la première valeur de métadonnées à supprimer.
  • RAG_METADATA_KEY_2 : nom de la clé de la deuxième valeur de métadonnées à supprimer.
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}"'"
  ]
}'

Filtrer les contextes avec des métadonnées

Pour améliorer la pertinence de vos résultats, utilisez les métadonnées des fichiers pour affiner l'espace de recherche lors de la récupération du contexte. Ajoutez une expression metadata_filter à votre requête RetrieveContexts à l'aide du CEL (Common Expression Language) (par exemple, year == 2024 && month == "May"). Seuls les fichiers dont les métadonnées correspondent à l'expression de filtre sont pris en compte pour la récupération.

L'exemple REST suivant montre comment récupérer des contextes à l'aide d'un filtre de métadonnées.

REST

Remplacez les variables suivantes :

  • PROJECT_ID : ID de votre projet.
  • LOCATION : région dans laquelle traiter la requête.
  • RAG_CORPUS_ID : ID du 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\""
         }
      }
    }
}'

Étapes suivantes