立即同步知识库

可立即触发知识库的有源知识的增量同步，当前仅支持 Google Drive 来源。

注意：

接口在完成校验与规划后立即返回，因此返回的是“已受理”，而非“已更新”。

频率限制：每个 Agent / Workflow 每分钟最多 1 次。

请求方式

POST

调用地址

按 API Key 所属的资源类型选择对应路径。两个接口的请求参数、响应结构、限流规则完全一致。

• 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"
}

                    

使用说明

返回的是“已受理”，不是“已完成”

接口在完成校验与规划后立即返回，真正的拉取、解析、向量化在后台异步执行。因此 matched_doc_count 是“本次将检查多少个文档”，而非“更新了多少个文档”。想确认最终结果，请轮询获取知识文档列表接口查看文档状态，文档状态变为 AVAILABLE 即表示该文档已同步完成。

只做增量，不会重复消耗额度

对每个文档，系统会先比对 Google Drive 上的最后修改时间：

• 源文档未改动：跳过，不重新下载、不重新解析、不消耗额度。
• 源文档已改动：重新拉取并重新解析、向量化。
• 绑定的文件夹中有新文件：自动新增为知识文档。

因此重复调用本接口是安全的，未变更的内容不会产生额外费用。

本接口不能重试解析失败的文档

增量判断只看 Google Drive 上的源文档有没有变化，不看文档当前处于什么状态。

因此，一个此前解析失败（状态为 FAIL）的文档，只要它在 Google Drive 上的源文件没有被修改过，调用本接口不会重新处理它——它会被当作“源文档未改动”直接跳过，状态保持不变，也不会出现在 skipped 中。

要重试解析失败的文档，请使用重新嵌入文档接口。或者在 Google Drive 上对源文件做一次修改，使其最后修改时间更新，本接口即可重新拉取。

同步会删除知识文档

本接口不只做新增和更新，也会按 Google Drive 的当前状态删除知识文档。

当绑定的 Google Drive 文件夹变空时，该文件夹下已导入的知识文档会被全部删除。 触发条件是文件夹在 Google Drive 上仍可访问、但列举不到任何文件。系统会先校验文件夹可访问性，拿不到文件夹元信息时（文件夹被移走、权限变更、临时不可达等）会跳过删除，以避免误删。

删除范围限定在“该文件夹 + 该知识库”之内。同一个 Google Drive 文件夹被多个知识库引用时，各知识库互不影响。

该行为与系统定时同步一致，本接口只是让它提前发生。但由于本接口还覆盖了导入时没有配置定时同步计划的文档（这部分原本不会被任何自动流程删除），调用前请确认 Google Drive 侧的文件夹内容符合预期。

覆盖范围

同步范围覆盖知识库中所有来自 Google Drive 的文档，包括导入时没有配置定时同步计划的那部分——这部分文档不会被系统的定时轮次处理，只能通过本接口更新。

限流

• 每个 Agent / Workflow 每分钟最多 1 次。两条路径共用同一个计数器，换路径不会绕过限流。
• 同时受组织套餐的知识库类 API 每分钟请求数（RPM）限制，与其它知识库接口共享该额度。
• 同一 Agent / Workflow 的上一次同步尚未执行完时，再次调用会返回 accepted=false 且 reason=SYNC_IN_PROGRESS。

与定时同步的关系

本接口与系统定时同步相互独立、互不阻塞。scheduled_round_running 为 true 时本次请求仍会被受理，不会因为定时轮次正在执行而被拒绝。

两者同时处理同一个文档时不会产生重复内容：系统按源文档的最后修改时间做增量判断，且已导入的文件不会被重复创建。

定时同步按知识库自身配置的频率自动执行，本接口则忽略该频率立即触发。二者互为补充：定时同步负责常态更新，本接口负责“现在就要同步”的场景。