Filtrer avec la recherche de métadonnées

Preview

Certaines fonctionnalités RAG sont des versions Preview, soumises aux "Conditions des Offres de pré-DG" des Conditions spécifiques aux services Google Cloud. Les fonctionnalités et produits pré-DG sont disponibles "en l'état" et sont susceptibles de présenter une compatibilité limitée. De plus, il est possible que les modifications apportées à ces fonctionnalités ou produits ne soient pas compatibles avec d'autres versions pré-DG. Pour en savoir plus, consultez les descriptions des étapes de lancement. En utilisant l'API Gemini sur Gemini Enterprise Agent Platform, vous acceptez les Conditions d'utilisation de l'IA générative(Conditions bêta).

Les contrôles de sécurité VPC-SC et les CMEK sont compatibles avec le moteur RAG d'Agent Platform. Les contrôles de sécurité pour la résidence des données et Access Transparency ne sont pas compatibles.

VPC Service Controls : la fonctionnalité de recherche de métadonnées n'est pas disponible pour les projets pour lesquels VPC Service Controls était activé avant la sortie de la version bêta de la recherche de métadonnées. Si vous activez VPC Service Controls après la version Preview, la recherche de métadonnées est disponible.

Cette page explique comment utiliser la fonctionnalité de recherche de métadonnées basée sur le 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 à des fichiers de ce corpus et utiliser ces métadonnées pour filtrer les contextes lors de la récupération.

Remarque : La recherche de métadonnées n'est disponible que dans l'API v1beta1. Il n'est pas compatible avec le mode sans serveur.

Avant de commencer

Pour utiliser la recherche de métadonnées, vous devez disposer d'un corpus et de fichiers RAG existants. 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 qui contient vos fichiers RAG et leurs configurations.

  • RagDataSchema : ressource enfant de RagCorpus. Il définit la structure d'un champ de métadonnées unique 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 souhaitez 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 de clés valides sont les suivants :

• INTEGER : valeurs de métadonnées transmises en tant que int_value.
• FLOAT : valeurs de métadonnées transmises en tant que float_value.
• STRING : valeurs de métadonnées transmises en tant que str_value.
• DATETIME : valeurs de métadonnées transmises sous la forme d'un datetime_value (chaîne au format RFC 3339, par exemple "2024-01-01T00:00:00Z").
• BOOLEAN : valeurs de métadonnées transmises en tant que bool_value.
• LIST : valeurs de métadonnées transmises en tant que 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 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 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 de fichier

Une fois que vous avez importé des fichiers dans votre corpus, vous pouvez associer, modifier, afficher et supprimer les métadonnées qui leur sont associées.

Associer des métadonnées à un fichier

Les métadonnées jointes 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 modifier 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 correspond à 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 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 clé de la première valeur de métadonnées à supprimer.
• RAG_METADATA_KEY_2 : nom de 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

• Pour en savoir plus sur l'importation et la gestion des fichiers, consultez Gérer votre base de connaissances RAG.
• Pour en savoir plus sur la recherche vectorielle standard dans RAG, consultez Utiliser Vector Search avec RAG.