检索数据资产的上下文

此产品或功能受服务专用条款的“通用服务条款”部分中的“正式发布前产品条款”的约束。 正式发布前产品和功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

数据周围的上下文可让 AI 应用深入了解数据资产，从而提高 LLM 生成的回答的准确性和相关性。

lookupContext 方法通过单个 API 请求检索预格式化的一组数据资产元数据（针对交互式智能体工作流进行了优化），从而弥合上下文差距。您可以使用此紧凑的、可供 LLM 使用的上下文来指导智能体评估和使用数据资产。

您可以对存储在 Knowledge Catalog 中的任何数据资产（例如 BigQuery 表、数据集或任何其他条目）使用 lookupContext 方法。

如何使用 lookupContext 方法检索素材资源的上下文

1. 智能体检索可能与上下文检索相关的数据资产，例如使用 Knowledge Catalog 语义搜索。
2. 代理使用 lookupContext 方法进行单个 API 调用或 MCP 工具请求，以检索特定资产的上下文。

3. 该方法会返回包含预格式化文本块的响应。根据您在请求中指定的 format 参数，文档可以采用 YAML、XML 或 JSON 格式。

   响应包含以下上下文元素：

   上下文元素	说明
   技术元数据	资源架构和物理配置，例如 BigQuery 分区和聚簇策略。
   运营元数据	联接和其他关系，基于历史查询日志和数据洞见。如需了解详情，请参阅查看数据关系。
   商家说明	相关业务术语、概览、目录注释、在源系统中捕获并在 Knowledge Catalog 中自动生成的说明，以及指南。 注意：您可以使用数据资产的“指南”方面来捕获对客服人员发现、检查或使用数据资产有用的其他背景信息。
   数据分析	分布统计信息、不同值数量、Null 比率和样本值。
   数据质量	根据预定义的规则自动检查数据质量并输出结果。
   相关数据资产的背景信息	相关数据资产的背景信息，例如术语表中的术语或其他相关资产，如经常联接的表。为相关媒体资源返回的上下文包含的元素范围与主要媒体资源或媒体资源相同。

4. 代理会使用此响应来指导相关素材资源的选取或使用。

准备工作

在使用 lookupContext 方法之前，请确保您拥有必要的角色并启用所需的 API。

所需的角色

如需获得调用 lookupContext 方法所需的权限，请让您的管理员为您授予 Google Cloud 项目 iam.gserviceaccount.com的以下 IAM 角色：

• 对目录资源（包括条目、条目组和术语库）的读取权限：Dataplex Catalog Viewer (roles/dataplex.catalogViewer)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

启用 API

如需使用 lookupContext 方法，请在项目中启用以下 API：

• Knowledge Catalog API

启用 API 所需的角色

如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

启用 API

检索数据资产的上下文

如需检索数据资产的上下文，请使用 Dataplex API 直接访问 lookupContext 方法，或使用 Knowledge Catalog 远程 Model Context Protocol (MCP) 服务器或 MCP Toolbox For Databases。

lookupContext 方法会根据您的权限过滤资源。响应仅包含您的身份拥有必要的 Identity and Access Management (IAM) 权限才能访问的资源的数据。如果您对所请求的资源没有任何权限，该方法会返回空响应。

REST

如需检索数据资产的情境，请发送以下请求：

curl --request POST \
   'https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupContext' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
  "resources": RESOURCES
  "options": OPTIONS
  }' \
--compressed

替换以下内容：

• PROJECT_ID：您的 Google Cloud 项目的 ID
• LOCATION：资源所在的区域（例如 us-central1）
• RESOURCES：最多可包含 10 个要检索上下文的条目名称，格式为 projects/{project}/locations/{location}/entryGroups/{entryGroup}/entries/{entry}。对于多个资源，API 会建立所请求资源之间的关系（例如频繁的架构联接），并在上下文中返回关系信息。
• OPTIONS：用于定义上下文的选项：
  • format 是上下文的描述文件的格式。例如 yaml。
  • context_budget 是回答的字符数上限。如果您将 all_schema_fields 参数设置为 true，则无论 context_budget 值如何，API 都会返回所有架构字段。

以下示例请求用于检索 BigQuery 表的上下文：

curl --request POST \
'https://dataplex.googleapis.com/v1/projects/test-project/locations/us:lookupContext?key=[YOUR_API_KEY]' \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
    "resources":
    ["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
    "options":
    {
      "format":"yaml",
      "context_budget":"4000"
    }
  }' \
--compressed

响应是一个预先设置格式的文本块，类似于以下内容：

{
"context": "resource: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/orders\"\ntechnical_metadata:\n  schema:\n    - name: order_id\n      type: STRING\n      description: \"Primary key for the order.\"\n    - name: customer_id\n      type: STRING\n    - name: total_amount\n      type: NUMERIC\n  partitioning:\n    type: TIMESTAMP\n    field: order_date\nbusiness_descriptions:\n  overview: \"Historical record of all customer transactions.\"\n  related_terms:\n    - \"Revenue\"\n    - \"Sales Transactions\"\n  guidelines: \"Always filter by 'order_date' to optimize query costs due to partitioning.\"\ndata_profile:\n  columns:\n    - name: total_amount\n      null_ratio: 0.001\n      distinct_values: 52340\n      sample_values: [45.99, 120.00, 15.50]\ndata_quality:\n  summary:\n    - rule: \"positive_amounts\"\n      status: PASSED\n      description: \"Ensures total_amount is greater than zero.\"\noperational_metadata:\n  frequent_joins:\n    - table: \"projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/sales_data/tables/customers\"\n      join_key: \"customer_id\"\n"
}

Python

Python

试用此示例之前，请按照《Knowledge Catalog 快速入门：使用客户端库》中的 Python 设置说明进行操作。 如需了解详情，请参阅 Knowledge Catalog Python API 参考文档。

如需向 Knowledge Catalog 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_lookup_context():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.LookupContextRequest(
        name="name_value",
        resources=["resources_value1", "resources_value2"],
    )

    # Make the request
    response = client.lookup_context(request=request)

    # Handle the response
    print(response)

以下示例展示了如何检索 BigQuery 表的上下文：

 from google.cloud import dataplex_v1

 # Initialize the client
 client = dataplex_v1.CatalogServiceClient()

 # Define the request with a seed resource
 request = dataplex_v1.LookupContextRequest(
     name="projects/test-project/locations/us",
     resources=["projects/test-project/locations/us/entryGroups/@bigquery/entries/bigquery.googleapis.com/projects/test-project/datasets/test-dataset/tables/test-table"],
     options={"format": "yaml", "budget": "4000"}
 )

 # Retrieve the LLM-ready context
 response = client.lookup_context(request=request)
 context_yaml = response.context

 print(f"Retrieved Context: \n{context_yaml}")

lookupContext 方法的最佳实践

如需在使用 lookupContext 方法时优化结果，请考虑采用以下最佳实践：

• 使用 context_budget 参数请求所选长度的输出上下文。lookupContext 方法会尽可能在参数规定的限制范围内将最相关的上下文纳入输出中。
• 您可以在 resources 列表中列出最多 10 项数据资产。例如，在 resources 列表中包含多个表可让 API 不仅提供这些表的上下文，还提供它们之间可能的联接路径，从而为如何一起使用这些表提供必要的指导。
• 使用与 LLM 或代理的解析逻辑最契合的 format 选项（例如 yaml 或 json），以避免进行代价高昂的转换。

后续步骤

• 了解如何构建代理来发现数据。
• 了解如何构建代理来丰富元数据。
• 了解 Knowledge Catalog 的搜索语法。
• 详细了解如何查看数据关系。