Google Developer Knowledge API 介紹：以 Markdown 回傳文件、批次上限與價格現況

重點先看： Google 於 2026 年 10 月 7 日公布 Developer Knowledge API，可透過 gcloud、代理技能與用戶端程式庫，以 Markdown 格式回傳開發者文件。BatchGetDocuments 每次最多 20 份文件，公告中沒有列出價格。

會把整頁文件一次拉下來的那個呼叫，才是貴的。Google 自己的安裝說明叫你不要從那裡開始。Christina Gonzalez 在 10 月 7 日的 Google Developers Blog 把 Developer Knowledge API 寫成 Cloud、Firebase、Android 等文件的程式化來源。她指向的 agent skill 把順序寫死了。先用 searchDocumentChunks 看片段，真的需要整頁 Markdown 再用 documents.get，或者乾脆走 answerQuery 拿有依據的回答。你若讓代理把搜尋碰到的每一頁都下載，等於用官方客戶端把她說要取代的爬蟲習慣裝回去。

本站寫過另一種本機執行環境。Antigravity 在你的 GPU 上跑 Gemma 4，那不是文件庫。寫過安裝說明裡第二步並不是你以為的那一步。OpenShell 的安裝，Sentry 不是第二步。也寫過一個端點從預覽變成測試版的過程。Decisions API。這篇是文件 API，命令印在公告裡。

Developer Knowledge API 說它回什麼

Gonzalez 稱它是那些文件的官方來源，對象是代理、IDE 擴充、自動流程。要換掉的是容易碎的網頁抓取，和訓練截止日期之後就過時的模型記憶。內容是結構化的，她點名的格式是 Markdown。搜尋可以是語意，也可以是關鍵字。文件會切成片段。另外有一條有依據的問答路徑。索引經常更新，讓取回可預期，上游改了文件之後，代理拿到新版的延遲要小。她沒有印出延遲是幾分鐘。

公告沒有價格，沒有配額，也沒有列出哪些 Android 頁面在索引裡、哪些不在。「Google Cloud、Firebase、Android，以及其他」是範圍句。「以及其他」不是目錄。你的代理若要一份不在這三個名字裡的產品文件，先拿一個你知道存在的頁面去搜片段，再承諾索引涵蓋它。搜尋失敗是一個事實。Firestore 搜得到，不能證明另一個產品的頁面也在裡面。

同一次公告有四個入口。gcloud CLI、官方 agent skill、API Explorer、各語言客戶端程式庫。Gonzalez 說你可以在終端機、對代理下提示、互動試請求，或在正式程式裡用。那是四扇門，不是四套索引。gcloud 拿到的片段和 Python 客戶端拿到的片段，依這篇的說法，應該是同一份文件。公告沒有並排測試。

gcloud 命令就按公告印的順序

CLI 在 Cloud Shell 裡是預先裝好的。一般的 Google Cloud SDK，在 Linux、macOS、Windows 上不用額外外掛。這是設定聲明。公告接著指向 gcloud 的快速入門。10 月 7 日正文裡真正印出來的命令，足夠看出形狀。

終端機裡要一個有依據的回答：

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

搜片段：

gcloud developer-knowledge documents search-chunks --query="Firestore transactions"

用公告範例裡的資源名稱取一份文件：

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

把錯誤檔當成查詢：

gcloud developer-knowledge answer-query --query="$(cat error.txt)"

最後一行先讀再放進腳本。shell 會先把 $(cat error.txt) 展開，gcloud 才看得到。堆疊追蹤裡若有引號、反引號，或一份好幾 MB 的傾印，都會變成查詢字串。公告把這個寫成除錯手法，沒有寫長度上限。

describe 那一行最有用，也最容易被當成網址略過。參數不是瀏覽器上複製的 URL。它是資源名稱：documents/ 加上主機和文件路徑。範例是 documents/docs.cloud.google.com/storage/docs/creating-buckets。片段搜尋若回了一個 parent 名稱，那個名稱才是你交給 get 或 describe 的東西。不要自己把 https:// 黏回去。公告範例沒有協定，也沒有查詢字串。

印出來的 answer-query 和 documents search-chunks 用 --query。印出來的 documents describe 把資源名稱放在位置參數。以後的參考頁若有專案旗標或格式旗標，讓那一頁去加。這篇教學停在公告停的地方。

Cloud Shell 是安裝工作最少的路，因為元件已經在。筆電上的 SDK 是公告也聲稱可用、且不用額外外掛的路。如果你的機器上沒有 gcloud developer-knowledge 這個命令，就用公告自己的分法：有 CLI 就用 CLI；沒有，就把 agent skill 交給助理，而不是卡住猜元件名稱。

先搜片段，再決定要不要整頁

技能的安裝命令，公告印了一行：

npx skills add google/skills --skill retrieving-developer-knowledge

它從 google/skills 拉技能，路徑寫的是 GitHub 上的 skills/developers/retrieving-developer-knowledge。Gonzalez 說這個技能會告訴助理怎麼用 Developer Knowledge MCP 伺服器，或退回用 curl 打 REST。她點名的相容對象：Google Antigravity、Claude Code、Cursor、GitHub Copilot，以及自訂代理框架。點名一個客戶端，不等於附了帶版本號的測試矩陣。

即使你不安裝技能，取回順序也值得自己守。先 searchDocumentChunks。需要整頁 Markdown 再 documents.get。想要有依據的回答、不要整頁，就走 answerQuery。理由是 token。片段比整頁小。代理若為每個片段都去抓父文件，上下文會被導覽列和重複的頁首填滿。公告把這叫做較省的 token 與上下文用法。它也說，這樣能減少模型死抱過期訓練資料而產生的幻覺。兩句都是 Google 的說法。片段本身若錯了，還是錯的。官方 Markdown 比模型對 2024 年文件的記憶好。它不是回答端點忠實摘要了片段的證明。決定要緊的時候，讀片段，不要只讀回答。

驗證是公告點了名、卻沒有帶你走完的步驟。Application Default Credentials，或一把 API 金鑰，並指向快速入門的一個錨點，以及連接 MCP 伺服器的那一頁。公告說得清楚的部分是：技能和 MCP 這條路要你設定那個憑證；CLI 這條路則被寫成 gcloud 在場就能用。這兩套憑證不一定是同一套。筆電上的 ADC 不會自動變成 CI 上 curl 要的那把金鑰。你混用的時候，跟公告連結裡、你真正在呼叫的那一面走。不要假設 Cloud Shell 的登入涵蓋了 CI runner 上的 curl。

Antigravity 在相容名單上。這不表示這個 API 是本機模型主機。本站上一篇是用另一個 SDK 在 GPU 上跑 Gemma 4。這個技能是 Google 文件的取回策略。依公告，你可以讓 Antigravity 的工作階段指向它。不要期待技能會下載模型，也不要期待本機的 Gemma 行程會自動擁有這份索引，除非你自己接上工具。公告沒有展示那條接線。它展示的是 npx skills add。

Python 範例沒有做的那些呼叫

Gonzalez 列出的客戶端語言是 C#、Go、Java、Node.js 與 TypeScript、PHP、Python、Ruby。她點名的方法是 AnswerQuery、SearchDocumentChunks、GetDocument、BatchGetDocuments。批次方法一次最多取 20 份文件。20 是公告裡唯一的數字上限。她還說程式庫支援 Application Default Credentials、自動重試、結構化的引用追蹤。「支援」不是重試策略的範例。

公告裡的 Python 範例是一個函式，用片段搜尋某產品的發行說明。

from google.cloud import developer_knowledge_v1

def FetchMyProductReleaseNotes(my_product_name: str) -> str:
    my_api_client = developer_knowledge_v1.DeveloperKnowledgeClient()
    my_search_query = f"{my_product_name} latest release notes"
    my_request = developer_knowledge_v1.SearchDocumentChunksRequest(
        query=my_search_query,
    )
    my_response = my_api_client.search_document_chunks(request=my_request)
    my_release_notes = [my_chunk.text for my_chunk in my_response.chunks]
    return "\n".join(my_release_notes)

用戶端建構時沒有專案、沒有金鑰、沒有端點。範例依賴程式庫的預設行為，周圍文字把它接到 Application Default Credentials。公告沒有展示那個失敗。

函式把片段文字用換行接起來。它沒有呼叫 GetDocument，沒有呼叫 answerQuery，也沒有讀 parent。你若需要整頁，這個函式是錯的那一個。它只是技能描述的第一步。發行說明的查詢可以從好幾個頁面回好幾個片段。只留 .text 會丟掉後續 get 需要的父名稱。公告正文說，片段搜尋是用來決定要抓哪一頁。範例印出來的樣子卻把那個決定丟了，只留文字。真的要寫代理，文字和 parent 一起留。

BatchGetDocuments 是你已經有最多 20 個文件名稱、想一次拿回來時用的。它不是搜尋。範例根本沒走到那裡。對每個片段的 parent 各打一次 GetDocument 也能動，但會無視公告特地點名的批次方法。你若有 21 個 parent，20 的上限表示要打兩次，不是一次。公告沒說送 21 個時 API 回什麼。把清單切開。

API Explorer 是不用寫程式的那扇門。Gonzalez 說你可以在那裡試核心端點，公告還附了一張草稿示意圖。想在選定客戶端之前看回應形狀，就用 Explorer。不要憑記憶把示意圖寫成正式 URL。

第一次接的時候不要假設的事

不要假設價格、免費額度或配額。10 月 7 日的公告裡沒有。教學若編出「一天 1000 次查詢」，審查時就會爆。呼叫你需要的方法，看客戶端實際丟出的錯誤，在你打開的定價頁說話之前，把那個錯誤當成上限。

不要假設回答端點可以不帶片段就當成引用出貨。技能存在，是因為 Google 希望模型站在新的 Markdown 上。依公告的用詞，回答是依據那些 Markdown 生成的。有依據，不等於逐字引用。你在填運行手冊，就把片段和 parent 名稱存下來。你在終端機回答一個開發者，answer-query 是公告帶頭的命令，那個桌子上用它是對的。

不要把 $(cat error.txt) 指向你沒看過的輸入。查詢仍是你送給 Google 的字串。客戶日誌裡可能有密鑰。公告把這個模式寫成除錯，沒有把它寫成日誌管線。那是兩種信任邊界。

不要把這個索引和 EmbeddingGemma 2 混在一起。同一個部落格在 10 月 6 日發了那份開發者指南。那是可以往邊緣跑的模型。這個 API 是遠端的文件索引。同一週，同一個部落格，兩種東西。代理可以兩個都用。不該拿 Gemma 的指南當 gcloud developer-knowledge 的手冊。

Gonzalez 自己的收尾很小。機器上已經有 gcloud，就用公告裡的 BigQuery 例子跑一次 answer-query，看回答是否對得上你記得的那份文件。機器上沒有 gcloud，就安裝技能，向助理要同一頁。片段的 parent 若以 documents/... 回來，你就有了 describe 範例用的那種把手。若回來的是別的形狀，相信回應，不要相信範例字串。範例是一份儲存服務的文件。它不是索引裡每一個 parent 名稱的綱要。

對讀者的意義

第一次整合時，建議先搜尋相關片段再抓取完整文件，批次請求每次控制在 20 份以內；由於公告沒有公布價格，請到 Google Cloud 主控台確認配額與計費。安裝設定可參考 Google 的 gcloud CLI 文件。