Gerar respostas com base na documentação

A API Developer Knowledge permite fazer perguntas sobre os produtos para desenvolvedores do Google e receber respostas diretas em linguagem natural. Para cada consulta, a API compõe uma resposta extraída do corpus do Developer Knowledge (referido na referência da API como geração fundamentada) e inclui citações das páginas de documentação relevantes.

Antes de começar

Configure seu ambiente para a ferramenta preferida:

gcloud

Instale e configure a CLI gcloud e ative a API Developer Knowledge.

REST

Ative a API e gere uma chave de API Developer Knowledge. Em seguida, salve a chave em uma variável de ambiente:

export DEVELOPERKNOWLEDGE_API_KEY="YOUR_API_KEY"

Substitua YOUR_API_KEY pela sua chave de API Developer Knowledge.

Responder a uma consulta

Use o gcloud developer-knowledge answer-query comando ou o answerQuery método REST para fazer uma pergunta.

O exemplo a seguir envia uma consulta perguntando como criar um conjunto de dados do 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?"}'

A resposta contém o texto no campo answer.answerText, além de citations e references no answer objeto:

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

Filtrar fontes de documentação

Para restringir as fontes de documentação usadas para gerar a resposta, transmita uma expressão de filtro usando a flag --query-filter na CLI gcloud ou o filter campo no corpo da solicitação REST. Para mais detalhes sobre os campos de filtro compatíveis e operadores, consulte Filtrar resultados da pesquisa.

O exemplo a seguir restringe as fontes de documentação a 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\""
  }'

Escolher entre AnswerQuery e SearchDocumentChunks

Ao usar a API ou o servidor MCP do Developer Knowledge, escolha o método que melhor se adapta ao que você está procurando:

  • AnswerQuery (ou a ferramenta MCP answer_query): melhor para perguntas gerais de "Instruções", comparação de produtos e guias explicativos em que você quer um resumo completo com links para os documentos de origem.
  • SearchDocumentChunks (ou a ferramenta MCP search_documents): melhor para procurar flags exatas da CLI, sintaxe de código, nomes de parâmetros ou permissões do IAM (como service.resource.verb). Use de duas a cinco palavras-chave específicas em vez de uma pergunta completa.

A seguir