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,BOOLEANouLIST). Vous devez définir unRagDataSchemapour chaque clé de métadonnées que vous prévoyez d'utiliser pour le filtrage. RagFile : ressource enfant de
RagCorpusrepré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 ressourceRagMetadatadoit correspondre à une clé définie dans unRagDataSchemapour le corpus parent. Plusieurs ressourcesRagMetadatapeuvent être associées à un même fichier.
- RagMetadata : ressource enfant de
- RagDataSchema : ressource enfant de
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 queint_value.FLOAT: valeurs de métadonnées transmises sous forme defloat_value.STRING: valeurs de métadonnées transmises sous forme destr_value.DATETIME: valeurs de métadonnées transmises sous forme dedatetime_value(chaîne au format RFC 3339, par exemple "2024-01-01T00:00:00Z").BOOLEAN: valeurs de métadonnées transmises sous forme debool_value.LIST: valeurs de métadonnées transmises sous forme delist_value. L'exemple REST suivant montre comment créer par lot des schémas de métadonnées qui définissent les champsyearetmonthd'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
- 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.