快速入门：将 gcloud CLI 与 Developer Knowledge API 搭配使用

本快速入门介绍了如何使用 Google Cloud CLI 通过 Developer Knowledge API 回答查询、搜索和检索开发者文档。

准备工作

在开始使用 gcloud CLI 和 Developer Knowledge API 之前，请完成以下步骤。

安装并配置 gcloud CLI

如需安装和配置 gcloud CLI，请完成以下步骤：

  1. 如果您尚未安装 gcloud CLI，请安装 gcloud CLI。

  2. 运行 gcloud components update 命令，确保您拥有最新版本：

    gcloud components update

  3. 运行 gcloud auth login 命令，登录您的 Google Cloud 账号：

    gcloud auth login

  4. 运行 gcloud config set 命令，设置活跃的 Google Cloud 项目：

    gcloud config set project PROJECT_ID

    将 PROJECT_ID 替换为您的 Google Cloud 项目的 ID。

启用 API

如需启用 Developer Knowledge API，请完成以下步骤：

  1. 运行 gcloud services enable 命令，在 Google Cloud 项目中启用 Developer Knowledge API：

    gcloud services enable developerknowledge.googleapis.com

    您无需拥有特定的 Identity and Access Management (IAM) 角色即可启用或使用该 API。

  2. 运行 gcloud services list 命令，验证您的项目是否已启用该 API：

    gcloud services list --enabled \
    --filter="name:developerknowledge.googleapis.com"

    输出会列出 API 名称和标题：

    NAME                                     TITLE
developerknowledge.googleapis.com  Developer Knowledge API

根据文档生成答案

借助 gcloud developer-knowledge answer-query 命令，您可以询问有关 Google 产品的问题，并获得直接的自然语言回答。该命令会从官方文档来源中提取信息，并提供对所引用页面的引用。

如需提出问题并生成回答，请完成以下步骤：

  1. 运行以下命令，询问如何创建 Cloud Storage 存储桶：

    gcloud developer-knowledge answer-query \
    --query="How do I create a Cloud Storage bucket?"

  2. 确认该命令以 YAML 格式返回生成的答案和来源参考信息：

    answer:
  answerText: |-
    To create a Cloud Storage bucket, you can use the Google Cloud console,
    the gcloud CLI (`gcloud storage buckets create`), client libraries, or
    the REST API...
  citations:
  - endIndex: 158
    sources:
    - referenceIndex: 0
    startIndex: 0
  references:
  - documentReference:
      documentChunk:
        content: |-
          This document shows you how to create a Cloud Storage
          [bucket](https://docs.cloud.google.com/storage/docs/buckets)...
        document:
          dataSource: docs.cloud.google.com
          name: documents/docs.cloud.google.com/storage/docs/creating-buckets
          title: Create a bucket
          uri: https://docs.cloud.google.com/storage/docs/creating-buckets
        parent: documents/docs.cloud.google.com/storage/docs/creating-buckets

    输出中的 answer 对象包含以下字段：

    • answerText：针对您的查询生成的自然语言回答。
    • citations：answerText 中与 references 中的支持条目相对应的字节偏移范围（startIndex 和 endIndex），以 referenceIndex 为单位。
    • references：用于生成答案的源文档块和元数据，包括 document 和 parent。

搜索文档块

如需在 Google 的开发者文档中查找特定文本摘录，而不是生成式回答，请使用 gcloud developer-knowledge documents search-chunks 命令。 此命令会扫描文档语料库，并返回匹配的内容块以及其父文档的资源名称。

如需搜索文档块，请完成以下步骤：

  1. 运行以下命令，搜索有关创建 Cloud Storage 存储桶的文档：

    gcloud developer-knowledge documents search-chunks \
    --query="How do I create a Cloud Storage bucket?"

  2. 确认该命令以 YAML 格式返回匹配的文档块列表：

    ---
content: |-
  This document shows you how to create a Cloud Storage
  [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise
  specified in your request, buckets are created in the
  [US multi-region](https://docs.cloud.google.com/storage/docs/locations)...
document:
  contentLengthBytes: 31842
  dataSource: docs.cloud.google.com
  description: World-wide storage and retrieval of data in Google Cloud.
  name: documents/docs.cloud.google.com/storage/docs/creating-buckets
  title: Create a bucket
  updateTime: '2026-09-10T20:05:41Z'
  uri: https://docs.cloud.google.com/storage/docs/creating-buckets
  view: DOCUMENT_VIEW_BASIC
id: c1
parent: documents/docs.cloud.google.com/storage/docs/creating-buckets
relevanceScore: 0.856608

    输出中的每个块都包含以下字段：

    • content：文档中匹配的文本片段。
    • document：有关源文档的元数据，包括其 title、description、uri、dataSource 和 updateTime。
    • id：相应块在文档中的标识符。
    • parent：父文档的资源名称。您可以将此值传递给 describe 命令，以检索完整文档。
    • relevanceScore：块与搜索查询的相关性得分。

检索文档

找到相关的文档块后，使用这些搜索结果中的 parent 字段来提取文档的完整 Markdown 内容。

运行 gcloud developer-knowledge documents describe 命令，并提供文档的资源名称。例如，如需检索有关创建 Cloud Storage 存储桶的文档，请完成以下步骤：

  1. 运行以下命令：

    gcloud developer-knowledge documents describe \
  documents/docs.cloud.google.com/storage/docs/creating-buckets

  2. 确认该命令返回了文档的元数据和完整的 Markdown 内容：

    content: |
  This document shows you how to create a Cloud Storage [bucket](https://docs.cloud.google.com/storage/docs/buckets). If not otherwise specified in your request, buckets are
  created in the [`US` multi-region](https://docs.cloud.google.com/storage/docs/locations)
  with a default storage class of [Standard storage](https://docs.cloud.google.com/storage/docs/storage-classes)
  and have a seven-day [soft delete](https://docs.cloud.google.com/storage/docs/soft-delete)
  retention duration...
contentLengthBytes: 31842
dataSource: docs.cloud.google.com
description: World-wide storage and retrieval of data in Google Cloud.
name: documents/docs.cloud.google.com/storage/docs/creating-buckets
title: Create a bucket
updateTime: '2026-09-10T20:05:41Z'
uri: https://docs.cloud.google.com/storage/docs/creating-buckets
view: DOCUMENT_VIEW_CONTENT

    输出包含以下字段：

    • content：文档的完整 Markdown 文本。
    • contentLengthBytes：文档内容的总大小（以字节为单位）。
    • dataSource：托管文档的文档网域。
    • description：文档的简短摘要。
    • name：文档的唯一资源名称。
    • title：文档的标题。
    • updateTime：相应文档的上次更新时间。
    • uri：文档页面的公开网址。
    • view：返回的文档视图（DOCUMENT_VIEW_CONTENT、DOCUMENT_VIEW_BASIC 或 DOCUMENT_VIEW_FULL）。

后续步骤