摘要
把 Notion 接入 AI 知识库，看起来只是 OAuth 授权和页面读取，真正困难的却是同步语义：如何增量更新、如何保留上一次成功版本、部分失败时能不能避免误删、断开授权后知识是否继续生效。本文用一套“远端来源—本地文档—索引版本”的架构解释这些问题。
正文
将 Notion 页面接入 RAG 系统，常见做法有两种：
- 用户每次提问时，临时调用 Notion API；
- 先把 Notion 内容同步到本地知识库，再走统一的处理、检索和回答链路。
对生产环境来说，第二种方式通常更稳定。
云答智能客服公开的 Notion 知识流程采用本地同步模式：系统先将授权范围内的页面同步到本地知识库，之后再经过既有的知识处理和检索链路；AI 回答客户时不会临时访问 Notion。
一、为什么不在问答时实时访问 Notion？
实时读取看起来更新更快，却会把第三方系统的不确定性带进每一次回答：
- Notion API 限流会直接影响响应时间；
- OAuth 凭据失效会让知识瞬间不可用；
- 页面树较大时，无法在单次问答中完整遍历；
- 同一个问题在不同时间可能读取到不同版本；
- 内容还没有完成分块和索引，检索质量不可控。
本地同步可以把外部系统与在线回答解耦：
Notion 页面 ↓ OAuth 只读授权 同步任务 ↓ 本地来源文档 ↓ 清洗 / 分块 / 摘要 / 索引 ↓ 可检索版本 ↓ AI 调试与正式回答这条链路中，“同步成功”和“已经能被 AI 检索”是两个不同状态。页面刚刚拉取到本地，不代表分块与索引已经完成。
二、连接、来源和文档要分成三层
一个可维护的数据模型至少需要区分：
CREATE TABLE knowledge_connections ( id UUID PRIMARY KEY, provider VARCHAR(30) NOT NULL, remote_scope_id VARCHAR(255) NOT NULL, credential_ref VARCHAR(255) NOT NULL, status VARCHAR(30) NOT NULL, last_success_at TIMESTAMP, next_sync_at TIMESTAMP, last_error TEXT ); CREATE TABLE knowledge_source_items ( connection_id UUID NOT NULL, remote_item_id VARCHAR(255) NOT NULL, remote_version VARCHAR(255), title TEXT NOT NULL, content_hash VARCHAR(64), active BOOLEAN NOT NULL, last_seen_run_id UUID, PRIMARY KEY (connection_id, remote_item_id) ); CREATE TABLE knowledge_index_versions ( source_item_id VARCHAR(255) NOT NULL, index_version BIGINT NOT NULL, process_status VARCHAR(30) NOT NULL, activated_at TIMESTAMP, PRIMARY KEY (source_item_id, index_version) );三层分别回答不同问题：
- 连接层：授权是否有效、下次什么时候同步；
- 来源层：远端页面是否存在、正文是否变化；
- 索引层：当前哪一版已经处理完成并可供检索。
如果把它们合成一张表，部分失败和回滚会很难处理。
三、增量同步不能只看更新时间
远端的updated_at可以用于初筛，但不适合作为唯一依据。更稳妥的方式是：
- 读取远端 ID 和版本信息；
- 对规范化正文计算内容哈希；
- 正文哈希变化时重新处理；
- 只有标题变化时，只更新展示元数据；
- 没有变化时跳过分块和向量化。
示意代码：
async function syncItem(remote: RemotePage, local: LocalItem | null) { const normalized = normalize(remote.content); const contentHash = sha256(normalized); if (!local) { return createAndScheduleIndex(remote, normalized, contentHash); } if (local.contentHash !== contentHash) { return updateAndScheduleNewIndex(remote, normalized, contentHash); } if (local.title !== remote.title) { return updateTitleOnly(local.id, remote.title); } return { action: "unchanged" }; }云答公开流程也区分正文和标题变化：正文未变化时不重复处理，标题变化可以单独更新。
四、部分失败时，最重要的是“不要误删”
同步大目录时，第三方限流、分页失败和单个页面权限变化都可能出现。如果本轮没有读到某个页面，就立刻把本地文档删除，会产生严重后果：一次临时故障就可能让大量知识从线上回答中消失。
更合理的是使用同步运行标记：
开始 run-20260730 ↓ 每成功读取一个远端页面，写入 last_seen_run_id ↓ 整轮完整成功？ ├─ 是：将未在本轮出现的页面标记为删除候选 └─ 否：保留上一轮 active 状态，不执行缺失删除只有完整遍历授权范围后，“本轮未出现”才有资格解释为远端删除。
云答帮助中心公开说明中，“部分失败”会保留旧的可用知识，不会因为一次不完整同步而误删；第三方限流或暂时不可用时，也会保留上一次成功同步的 active 文档。
五、新索引完成前，不要替换旧版本
正文变化后，可以创建一个新索引版本：
v12（active） → 当前继续回答 v13（building）→ 分块、向量化、摘要 v13（ready） → 原子切换为 active v12（retired） → 保留一段时间用于排查或回滚这样，即使新版本处理中途失败，在线检索仍能使用上一版，不会出现“文档已经更新，但索引只完成一半”的中间状态。
六、授权失效、断开连接和删除知识不是一回事
这三个动作应该拥有不同语义：
- 授权失效：停止后续同步，保留当前可用数据，并提示重新授权；
- 断开连接：删除连接凭据，停止计划任务；
- 删除本地知识：明确停止 AI 使用相应文档。
云答公开规则中，断开 Notion 会删除连接凭据并停止同步，但已经导入的本地文档不会自动删除。若不希望 AI 继续使用，需要在知识库中单独删除。
这种设计避免管理员在处理授权问题时误删已经加工完成的知识。
七、同步完成后还要做回答验证
数据进入本地并不代表接入完成。至少要检查：
- 连接状态是否为正常；
- 目标文档是否已经出现；
- 文档处理和索引是否完成；
- 用关键问题在调试台测试；
- 查看回答是否命中预期来源和版本；
- 用边界问题检查是否错误引用相邻页面。
把第三方知识接入 AI 系统，真正需要设计的不是一次导入，而是一个能解释增量、失败、版本和删除语义的长期同步协议。
YundaDesk云答智能客服: 出海品牌的全渠道 AI 客服，越用越懂你 | YundaDesk
