根据文档生成答案

借助 Developer Knowledge API，您可以提出有关 Google 开发者产品的问题，并获得直接、自然的语言回答。对于每个查询，API 都会根据开发者知识库（在 API 参考文档中称为接地生成）撰写回答，并包含相关文档页面的引用。

准备工作

为首选工具设置环境：

gcloud

安装并配置 gcloud CLI，然后启用 Developer Knowledge API。

REST

启用 API 并生成 Developer Knowledge API 密钥。 然后，将密钥保存到环境变量中：

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

将 YOUR_API_KEY 替换为您的 Developer Knowledge API 密钥。

回答查询

使用 gcloud developer-knowledge answer-query 命令或 answerQuery REST 方法提问。

以下示例发送了一个查询，询问如何创建 BigQuery 数据集：

gcloud

gcloud developer-knowledge answer-query \
  --query="How do I create a BigQuery dataset?"

REST

curl -X POST "https://developerknowledge.googleapis.com/v1:answerQuery?key=$DEVELOPERKNOWLEDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I create a BigQuery dataset?"}'

响应在 answer.answerText 字段中包含文本答案，并在 answer 对象中包含 citations 和 references：

{
  "answer": {
    "answerText": "To create a BigQuery dataset, you can use the Google Cloud console, the bq command-line tool, or the BigQuery client libraries.",
    "citations": [
      {
        "startIndex": 0,
        "endIndex": 123,
        "sources": [
          {
            "referenceIndex": 0
          }
        ]
      }
    ],
    "references": [
      {
        "documentReference": {
          "documentChunk": {
            "parent": "documents/docs.cloud.google.com/bigquery/docs/datasets",
            "content": "This page explains how to create BigQuery datasets...",
            "document": {
              "name": "documents/docs.cloud.google.com/bigquery/docs/datasets",
              "title": "Introduction to datasets",
              "uri": "https://docs.cloud.google.com/bigquery/docs/datasets"
            }
          }
        }
      }
    ]
  }
}

过滤文档来源

如需限制用于生成答案的文档来源，请在 gcloud CLI 中使用 --query-filter 标志或在 REST 请求正文中使用 filter 字段传递过滤表达式。如需详细了解支持的过滤条件字段和运算符，请参阅过滤搜索结果。

以下示例将文档来源限制为 docs.cloud.google.com：

gcloud

gcloud developer-knowledge answer-query \
  --query="How do I create a BigQuery dataset?" \
  --query-filter='data_source = "docs.cloud.google.com"'

REST

curl -X POST "https://developerknowledge.googleapis.com/v1:answerQuery?key=$DEVELOPERKNOWLEDGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I create a BigQuery dataset?",
    "filter": "data_source = \"docs.cloud.google.com\""
  }'

请在 AnswerQuery 到 SearchDocumentChunks 之间选择

使用 API 或开发者知识 MCP 服务器时，请选择最符合您需求的方法：

  • AnswerQuery（或 answer_query MCP 工具）：最适合解答一般性的 HowTo 问题、比较产品，以及提供包含源文档链接的完整摘要的分步指南。
  • SearchDocumentChunks（或 search_documents MCP 工具）：最适合查一查确切的 CLI 标志、代码语法、参数名称或 IAM 权限（例如 service.resource.verb）。请使用两到五个具体关键字，而不是完整的问题。

解析引用和参考资料

调用 answerQuery 时，answer 对象会提供精细的归因，将生成的 answerText 的特定片段与 references 中的来源段落相关联。

references 中的单个源文档可以在不同的文本片段中多次引用，并且单个片段可以引用多个参考文档。

带引用的回答示例

以下 JSON 代码段展示了一个 answer 对象，其中包含指向不同文档参考信息的多个引用：

{
  "answer": {
    "answerText": "You can create a BigQuery dataset using the Google Cloud console, the bq command-line tool, or the client libraries. Each dataset is assigned a region or multi-region location when created.",
    "citations": [
      {
        "startIndex": 0,
        "endIndex": 116,
        "sources": [
          {
            "referenceIndex": 0
          }
        ]
      },
      {
        "startIndex": 117,
        "endIndex": 189,
        "sources": [
          {
            "referenceIndex": 1
          }
        ]
      }
    ],
    "references": [
      {
        "documentReference": {
          "documentChunk": {
            "parent": "documents/docs.cloud.google.com/bigquery/docs/datasets",
            "content": "You can create a dataset in BigQuery using the Google Cloud console, the bq command-line tool, or client libraries...",
            "document": {
              "name": "documents/docs.cloud.google.com/bigquery/docs/datasets",
              "title": "Creating and managing datasets",
              "uri": "https://docs.cloud.google.com/bigquery/docs/datasets"
            }
          }
        }
      },
      {
        "documentReference": {
          "documentChunk": {
            "parent": "documents/docs.cloud.google.com/bigquery/docs/locations",
            "content": "When you create a dataset, you specify the location where your BigQuery data is stored...",
            "document": {
              "name": "documents/docs.cloud.google.com/bigquery/docs/locations",
              "title": "Dataset locations",
              "uri": "https://docs.cloud.google.com/bigquery/docs/locations"
            }
          }
        }
      }
    ]
  }
}

引用映射和字段

如需将引用映射到其文档来源，请使用以下字段：

  • answerText：生成的完整自然语言回答字符串。
  • citations：一个由引用的片段归因构成的数组：
    • startIndex：所引用片段的起始偏移量（含），以 UTF-8 字节为单位。
    • endIndex：引用片段的结束偏移量（不包含该位置本身），以 UTF-8 字节为单位。
    • sources：引用来源数组。每个条目都包含一个从 0 开始的 referenceIndex，对应于 references 数组中的一项（例如，referenceIndex: 0 映射到 references[0]）。
  • references：用于生成答案的源文档段落数组。每个条目都包含一个具有以下元数据的 documentReference.documentChunk：
    • document.title：文档页面的标题。
    • document.uri：文档页面的公开网址。
    • document.name：文档的规范资源名称。
    • content：从用于合成答案的文档块中提取的文本片段。
    • parent：父级文档的资源名称（例如 documents/docs.cloud.google.com/bigquery/docs/datasets），您可以将其传递给 documents.get 或 documents.batchGet 以检索完整文档。

在应用中实现引用

如需在客户端应用或 AI 智能体流水线中呈现带有引用的回答，请执行以下操作：

  1. 提取引用的片段：如需从 answerText 中切分相关片段，请使用 startIndex 和 endIndex 字节偏移量。
  2. 解析来源详细信息：如需检索页面 document.title 和目标 document.uri，请使用 sources[].referenceIndex 在 references 中查找相应项。
  3. 呈现内嵌链接或脚注：直接链接到来源页面，插入脚注编号（例如 [1] 或 [2]）、预览卡片或指向 document.uri 的可点击超链接。
  4. 根据需要提取完整上下文：如果 content 中的摘录不足，要提取完整的文档页面，请将 parent 传递给 documents.get。
  • UTF-16 语言（JavaScript 或 TypeScript）：在切片之前将字符串转换为 UTF-8 字节。例如，在 Node.js 中使用 Buffer.from(answerText, 'utf-8').subarray(start, end)，或在浏览器环境中使用 TextEncoder 和 TextDecoder。
  • Python：在切片之前将字符串编码为 UTF-8 字节，然后解码：answer_text.encode('utf-8')[start:end].decode('utf-8')。
  • 其他语言：对于原生按 UTF-8 字节为字符串编制索引的语言（例如 Go 或 Rust），请直接使用 startIndex 和 endIndex 对 answerText 进行切片。否则，请在切片之前将字符串转换为 UTF-8 字节。

后续步骤