把本地文档目录挂到百炼知识库上同步，四轮实操记与三个坑

组里那个问答机器人的资料库是我在管的，源文档放在一个 git 仓库里。上礼拜有人反馈答案里的退货政策是旧的，我一查，仓库里的文档半个月前就改过了，库里那份还是改之前的。原因没什么好说的，改完没人去后台重传。

这礼拜抽时间解决了，用的是阿里云百炼命令行里的 bl knowledge doc sync，专门做本地目录到知识库的增量同步。过程记一下，包括三个卡住我的地方。

没敢直接上手

我们工作区里已经有一堆在用的知识库，这条命令的帮助里写着风险级别高、可能替换或删除库里受管的文档，所以我先新建了一个专门试的库。

习惯是先带 dry-run 看一眼。它什么都没建，把要做的六步列出来，然后很直白地说：库一建出来就会一直按时间算下去，哪怕一次都不查，而且它没核实账号上还剩多少额度。看着没问题再正式跑，16 秒建好，给了库编号、检索服务编号、样例文件编号，每个资源旁边还附了删除命令。

目录与哨兵值

7 个文件，含 faq 与 notes 两层子目录、中文文件名、md 与 txt 与 png 三种格式，其中 notes 里那篇是我故意写的内部草稿。

有个小技巧值得说：在文档里埋一个哨兵值，我埋的是退货窗口 15 天。后面判断同步生效没有全靠问这个值，

预览别省

bl knowledge doc sync --dir ./petdocs --index-id 你的库编号 --dry-run

4 秒回来，不落盘，可以反复看。它给的是七个数字：新增、跳过、替换、保留、删除、待恢复、冲突，每个文件还带一条理由。首跑是新增 7、其余全 0。

两个归类挺细心：它自己存台账的隐藏目录判已排除、不会跟着进库；子目录判目录、只当路径用。图片也不拦，那张纯色 png 判的是新增。

正式同步 7 个文件用了 1 分 47 秒，库里 8 条状态全部完成（多的那条是建库样例）。问退货窗口多少天，命中退换货政策那篇，0.9152，正文写着 15 天，基线有了。

第二轮一次改了四件事

我想搞清楚它拿什么判断文件变没变，所以一次动了四个地方：把 15 天改成 30 天、加一篇保修与延保、把内部草稿删掉，再把产品总览原样重写一遍，内容一个字没动，只让修改时间往前跳一秒多。

预览回来是新增 1、跳过 5、替换 1、保留 1，四个文件正好落在四个桶里。被原样重写的那份判跳过，理由 same-sha256。这条我印象最深，它认内容不认时间戳：切分支、换机器、整目录拷一遍导致时间戳全变，都不会触发全量重传。放 CI 里这点很要紧。

正式同步 48 秒跑完，和预览逐项一致。再问一次退货窗口，命中同一篇，0.8994，正文已经是 30 天。新加那篇也立刻搜得到，0.8498。

坑一：本地删了，线上还在

那个被我删掉的内部草稿，在库里活得好好的。拿草稿里那个没发布的型号去检索，它 0.9557 排第一；问退货政策这种不相干的问题时，它也以 0.2476 出现在结果里。

这篇草稿是我故意写的，正文里明写着不应进入对外客服知识库，它照样入库照样被召回。同步不判断内容该不该进库，目录里有什么就进什么。

原因写在理由里：remote-deletion-disabled，远端删除默认关着，要下架得自己加 delete 参数。让我放心的是删除的作用域：我拿一个空目录对同一个库预览，七个数字全是 0，但库里 9 个远端文档编号全被列进了不受管清单。它只删自己管着的路径，同一个库里从别处来的文档不受影响。

坑二：带删除参数那一轮，四次 429

加 delete 的正式同步我试了四次，全挂在 HTTP 429，间隔留了 80 秒、180 秒、240 秒，最后一次前还专门空了 4 分钟什么都不干，照样 429。

开详细日志才看清：一次带删除的同步总共发 16 个请求，列文件那个接口占 9 次，429 落在第 9 次上；同一个时间窗里把 delete 去掉再预览，5 秒正常返回。所以限流卡在删除路径要用的那段文件枚举上，不是同步整体不能用。想提前预判也不行，查限流的命令管的是模型侧的请求数和 token 限额，管不到这个接口。

删除真正生效是什么样子，我改用按文档编号直删补上：2 秒成功，再检索那个型号，草稿彻底消失，库里文档数从 9 回到 8。

坑三：检索报应用未发布

建库时顺手建出来的检索服务是草稿态，没发布过。我第一次直接检索就报应用未发布、错误码是检索服务不存在。翻帮助才明白，检索命令的版本参数默认取最新已发布版本，而这个服务从来没有已发布版本，加上参数指定 beta 就好了。

台账别丢

同步会在文档目录下建一个隐藏目录，台账在里面，文件名是按库编号算出来的一串哈希，权限 600，我这份从 3219 字节涨到 3636 字节。

我手欠试了一下：把台账挪走再预览，七个数字变成新增 7、跳过 0，所有文件理由退回本地新路径。它不记得这些文件传过了，因为记忆就是那份台账，这时候正式跑一次就是重复入库。所以仓库里这个隐藏目录要么提交、要么在 CI 上固定住；帮助里还写了每个同步集只允许一个写入者。

收尾与感受

库建出来就一直按时间算，删掉库才停，只删库里的文档不停；导入文档另外产生解析和向量化这类模型调用，两笔账分开。我这次跑完就删了库、删了检索服务、又删了 10 个数据中心文件，按库名查返回 0 条，测试库一共存在 23 分 41 秒。

不必用的情况也有：文档只在在线协作平台上的走平台侧编排更省事；内容一次写好不再改的直接上传就够了；一库多目录并发同步又没划分同步集的，先别上。

它替我解决的是「改完得有人记得去后台点一下」这件事，把记性换成了哈希。没解决的是哪些文档本来就不该进库，那还是目录结构的活儿；还有 429 之后的自动退避，挂流水线得自己在外面包一层。

命令行从CLI 安装页装，Key 在控制台密钥管理页领。先建个专用库，拿三五个文件的小目录跑一次预览，试完记得删库。