立即同步知識庫

可立即觸發知識庫的有源知識的增量同步，目前僅支援 Google Drive 來源。

注意：

API 在完成校驗與規劃後立即返回，因此返回的是「已受理」，而非「已更新」。

頻率限制：每個 Agent / Workflow 每分鐘最多 1 次。

請求方式

POST

調用地址

按 API Key 所屬的資源類型選擇對應路徑。兩個 API 的請求參數、回應結構、限流規則完全一致。

• Agent：

https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync

• Workflow：

https://api-${endpoint}.gptbots.ai/v1/workflow/knowledge-base/sync

下文的請求 / 回應說明對兩個路徑同時適用，範例以 Agent 路徑書寫。

調用驗證

詳情請參閱 API 概述的驗證方式說明。

請求

請求範例

• 同步指定知識庫：

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive",
    "knowledge_base_ids": ["6a44c3512ceb43775567391c", "6a44c3512ceb43775567391d"]
}'

                    

• 同步該 Agent 下全部知識庫：

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/agent/knowledge-base/sync' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json' \
-d '{
    "source": "google-drive"
}'

                    

請求標頭

請求參數

回應

回應範例

                      
                      {
    "code": 0,
    "message": "OK",
    "data": {
        "accepted": true,
        "source": "google-drive",
        "matched_knowledge_base_count": 2,
        "matched_doc_count": 37,
        "matched_folder_count": 3,
        "skipped": [
            {
                "reason": "DRIVE_NOT_AUTHORIZED",
                "message": "The document owner has not authorized Google Drive, or the authorization has expired.",
                "knowledge_base_id": "6a44c3512ceb43775567391e",
                "doc_count": 8
            },
            {
                "reason": "KNOWLEDGE_BASE_NOT_FOUND",
                "message": "Knowledge base does not exist or does not belong to this agent.",
                "knowledge_base_id": "deadbeefdeadbeefdeadbeef"
            }
        ],
        "scheduled_round_running": false
    }
}

                    

成功回應

skipped[].reason 取值

失敗回應

常見錯誤碼：

source 非法時的回應範例：

                      
                      {
    "code": 40000,
    "message": "Unsupported source: sharepoint. Supported: google-drive"
}

                    

使用說明

返回的是「已受理」，不是「已完成」

API 在完成校驗與規劃後立即返回，真正的拉取、解析、向量化在後台非同步執行。因此 matched_doc_count 是「本次將檢查多少個文件」，而非「更新了多少個文件」。想確認最終結果，請輪詢取得知識文件清單 API 查看文件狀態，文件狀態變為 AVAILABLE 即表示該文件已同步完成。

只做增量，不會重複消耗額度

對每個文件，系統會先比對 Google Drive 上的最後修改時間：

• 源文件未改動：跳過，不重新下載、不重新解析、不消耗額度。
• 源文件已改動：重新拉取並重新解析、向量化。
• 綁定的資料夾中有新檔案：自動新增為知識文件。

因此重複調用本 API 是安全的，未變更的內容不會產生額外費用。

本 API 不能重試解析失敗的文件

增量判斷只看 Google Drive 上的源文件有沒有變化，不看文件目前處於什麼狀態。

因此，一個此前解析失敗（狀態為 FAIL）的文件，只要它在 Google Drive 上的源檔案沒有被修改過，調用本 API 不會重新處理它——它會被當作「源文件未改動」直接跳過，狀態保持不變，也不會出現在 skipped 中。

要重試解析失敗的文件，請使用重新嵌入文件 API。或者在 Google Drive 上對源檔案做一次修改，使其最後修改時間更新，本 API 即可重新拉取。

同步會刪除知識文件

本 API 不只做新增和更新，也會按 Google Drive 的目前狀態刪除知識文件。

當綁定的 Google Drive 資料夾變空時，該資料夾下已匯入的知識文件會被全部刪除。 觸發條件是資料夾在 Google Drive 上仍可存取、但列舉不到任何檔案。系統會先校驗資料夾可存取性，拿不到資料夾元資訊時（資料夾被移走、權限變更、暫時不可達等）會跳過刪除，以避免誤刪。

刪除範圍限定在「該資料夾 + 該知識庫」之內。同一個 Google Drive 資料夾被多個知識庫引用時，各知識庫互不影響。

該行為與系統定時同步一致，本 API 只是讓它提前發生。但由於本 API 還涵蓋了匯入時沒有配置定時同步計劃的文件（這部分原本不會被任何自動流程刪除），調用前請確認 Google Drive 側的資料夾內容符合預期。

涵蓋範圍

同步範圍涵蓋知識庫中所有來自 Google Drive 的文件，包括匯入時沒有配置定時同步計劃的那部分——這部分文件不會被系統的定時輪次處理，只能透過本 API 更新。

限流

• 每個 Agent / Workflow 每分鐘最多 1 次。兩條路徑共用同一個計數器，換路徑不會繞過限流。
• 同時受組織套餐的知識庫類 API 每分鐘請求數（RPM）限制，與其它知識庫 API 共享該額度。
• 同一 Agent / Workflow 的上一次同步尚未執行完時，再次調用會返回 accepted=false 且 reason=SYNC_IN_PROGRESS。

與定時同步的關係

本 API 與系統定時同步相互獨立、互不阻塞。scheduled_round_running 為 true 時本次請求仍會被受理，不會因為定時輪次正在執行而被拒絕。

兩者同時處理同一個文件時不會產生重複內容：系統按源文件的最後修改時間做增量判斷，且已匯入的檔案不會被重複建立。

定時同步按知識庫自身配置的頻率自動執行，本 API 則忽略該頻率立即觸發。二者互為補充：定時同步負責常態更新，本 API 負責「現在就要同步」的場景。