Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

使用元数据搜索进行过滤

本页面介绍了如何在 Gemini Enterprise Agent Platform 上使用 RAG 引擎中基于架构的元数据搜索功能。您可以为语料库定义元数据架构，将元数据附加到该语料库中的文件，并在检索期间使用此元数据过滤上下文。

准备工作

如需使用元数据搜索，您必须拥有现有的 RAG 语料库和 RAG 文件。如需了解如何创建语料库和上传文件，请参阅管理 RAG 知识库。

创建语料库或上传文件时，API 会返回数字 RAG_CORPUS_ID 和 RAG_FILE_ID（例如 123456789）。您必须拥有这些 ID 才能管理元数据资源。

元数据资源

元数据搜索功能使用以下资源层次结构：

RagCorpus：包含 RAG 文件及其配置的顶级资源。
- RagDataSchema：RagCorpus 的子资源。它定义了语料库中使用的单个元数据字段的结构。每个架构都指定一个键（例如 year）和一个数据类型（INTEGER、FLOAT、STRING、DATETIME、BOOLEAN 或 LIST）。您必须为打算用于过滤的每个元数据键定义一个 RagDataSchema。
- RagFile：RagCorpus 的子资源，表示单个已提取的文档。
  - RagMetadata：RagFile 的子资源。它表示附加到特定文件（例如 year=2024）的单个键值元数据对。RagMetadata 资源中使用的键必须与父语料库的 RagDataSchema 中定义的键相对应。多个 RagMetadata 资源可以附加到单个文件。

管理元数据架构

创建 RAG 语料库后，请使用语料库级 RagDataSchema 资源定义元数据结构。您还可以查看和删除已定义的架构。

定义元数据架构

定义架构时，您需要指定键和数据类型。键的有效类型包括：

INTEGER：以 int_value 形式传入的元数据值。
FLOAT：以 float_value 形式传入的元数据值。
STRING：以 str_value 形式传入的元数据值。
DATETIME：以 datetime_value（RFC 3339 格式的字符串，例如“2024-01-01T00:00:00Z”）形式传入的元数据值。
BOOLEAN：以 bool_value 形式传入的元数据值。
LIST：以 list_value 形式传入的元数据值。以下 REST 示例展示了如何批量创建元数据架构，以定义语料库的 year 和 month 字段。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。

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"}
      }
    }
  ]
}'

列出元数据架构

以下 REST 示例展示了如何列出为语料库定义的元数据架构。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。

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

删除元数据架构

以下 REST 示例展示了如何从语料库中批量删除元数据架构。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。
RAG_DATA_SCHEMA_KEY_1：要删除的第一个元数据架构的键名称。
RAG_DATA_SCHEMA_KEY_2：要删除的第二个元数据架构的键名称。

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}"'"
  ]
}'

管理文件元数据

将文件上传或导入到语料库后，您可以附加、更新、查看和删除与这些文件关联的元数据。

将元数据附加到文件

附加的元数据必须符合为语料库定义的架构。以下 REST 示例展示了如何将多个元数据值附加到文件。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。
RAG_FILE_ID：RAG 文件的 ID。

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" } }
      }
    }
  ]
}'

列出文件的元数据

以下 REST 示例展示了如何列出附加到特定文件的元数据。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。
RAG_FILE_ID：RAG 文件的 ID。

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

更新元数据

您可以更新附加到文件的元数据值。以下 REST 示例展示了如何更新与 year 键相关联的元数据值。RAG_METADATA_KEY 是您创建元数据时使用的字符串。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。
RAG_FILE_ID：RAG 文件的 ID。
RAG_METADATA_KEY：要更新的元数据的键名称。

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 } }
}'

从文件中删除元数据

以下 REST 示例展示了如何批量删除文件中的元数据值。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。
RAG_FILE_ID：RAG 文件的 ID。
RAG_METADATA_KEY_1：要删除的第一个元数据值的键名称。
RAG_METADATA_KEY_2：要删除的第二个元数据值的键名称。

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}"'"
  ]
}'

使用元数据过滤上下文

为了提高结果的相关性，请使用文件元数据在检索上下文期间缩小搜索范围。使用 CEL（通用表达式语言）向 RetrieveContexts 请求添加 metadata_filter 表达式（例如 year == 2024 && month == "May"）。系统只会考虑检索元数据与过滤表达式匹配的文件。

以下 REST 示例展示了如何使用元数据过滤条件检索上下文。

REST

执行以下变量替换操作：

PROJECT_ID：您的项目 ID。
LOCATION：处理请求的区域。
RAG_CORPUS_ID：RAG 语料库的 ID。

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\""
         }
      }
    }
}'

后续步骤

如需详细了解如何上传和管理文件，请参阅管理 RAG 知识库。
如需详细了解 RAG 中的标准向量搜索，请参阅将 Vector Search 与 RAG 搭配使用。

使用元数据搜索进行过滤 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

准备工作

元数据资源

管理元数据架构

定义元数据架构

REST

列出元数据架构

REST

删除元数据架构

REST

管理文件元数据

将元数据附加到文件

REST

列出文件的元数据

REST

更新元数据

REST

从文件中删除元数据

REST

使用元数据过滤上下文

REST

后续步骤

使用元数据搜索进行过滤