从零开始搭建知识库 · EP03 · 数据准备篇
数据准备在能力栈里的位置
"从零开始搭建知识库"系列第三期。EP01 论证了为什么需要知识库，EP02 跑通了检索闭环。本期补上工程上最容易被跳过的一段：文档入库前的数据准备。
先说百炼这块能力栈的通道分工，这个社区里问得最多：
| 需求 | 正确通道 | 说明 |
|---|---|---|
| 知识库建库、导入文档、切片修正 | 百炼控制台（网页） | knowledge 组 CLI 只有 retrieve，导入无命令 |
给 bl omni / bl app call 传文件 |
bl file upload --file <path> --model <model> |
DashScope 48 小时临时存储，文件绑定模型 |
| 知识库检索 | bl knowledge retrieve --index-id <id> --query <text> |
输出结构化 JSON |
file upload 经常被误当成知识库导入命令，注意它的 --model 是必填参数：上传的文件要绑定到具体模型上供多模态调用，48 小时过期，与知识库的长期索引是两条完全独立的通道。
三类主流翻车实测（现象→原因→解法）
环境：沿用 EP02 知识库（index-id zj0knmrbye），追加 5 份文档，共 8 文档 27 切片，切片方式为默认的智能切分。
翻车一：版本混喂。两版差旅报销制度同库（2023 版与 2026 版，六处数字冲突）。问"报销发票怎么提交"，2023 旧版 0.7226 排第一，现行版 0.7055 排第二：旧版要求纸质发票装订提交，现行版要求电子发票拍照上传。三条 query 实测，两版分差全部在 0.017-0.05（噪声级），Top1 随措辞漂移，文件名中的"旧版/现行版"标注不参与检索。检索层无版本意识，这是版本治理必须发生在入库前的实证。
翻车二：Excel 格式。同一份运费信息，分节 Markdown 对照合并表头 Excel（备注塞角落、双 sheet）。三种实测行为：一，烂版碎片高分但残缺，问"新疆买沙发能发货吗"，碎片 0.7982 排第一，"差价15""6-8天"失去上下文，好版 0.6894 返回完整规则；二，碎片膨胀，6KB 表拆成 11 片（控制台切片视图实数）占全库四成，其过时备注"以上如有变动以客服最新答复为准（2024.6 更新）"凭高频词十条检索六次混入 Top5；三，结构蒸发，sheet 名与行列结构不进 content。官方 RAG 优化文档的建议在此得到验证：优先 Markdown，避免合并单元格表格。
翻车三：长文切分行为。五千字客服手册按小节语义聚簇，每片 2-4 节，title 字段携带小节标题链并参与匹配（问"沙发的尺寸怎么推荐"，0.9108 命中 title 为"2.2 尺寸推荐|2.3 比价与砍价|2.4 催券与活动咨询"的切片）。跨章切片存在（第四章末节与第五章开头同片）但语义完整；Markdown 表格进切片后语法降级为竖线拼接。文档首行的"版本：v3.2 ｜ 更新日期：2026 年 6 月"进切片，检索排序不读它，下游生成模型可读，是版本冲突场景下模型唯一的判断依据。
另撞见跨文档口径冲突一例：问"满多少钱包邮"，"满 99"（新表）与"满 59/偏远满 129"（EP02 旧政策）同时返回，检索不做仲裁。
入库前检查清单
- 过期版本删除（实测旧版 0.7226 反超现行版 0.7055）
- 同一事实口径唯一（满 59 与满 99 同返）
- Excel 拆弹或转 Markdown（6KB 表膨胀为 17/27 切片）
- 长文标题分层（title 标题链参与匹配）
- 版本与日期写入正文首行（版本头进切片）
这套清单零代码，执行者是文档的业务归属方（财务、运营、客服主管），管库和 CLI 的同学负责验收：问一条改过版的规则的操作流程（"报销发票怎么提交"），Top2 新旧两版同时上榜即打回。
与生态其他组件的衔接
- 检索参数调优（EP04）：本次实测暴露的碎片污染和口径冲突，正好作为多路检索（
--dense-similarity-top-k、--sparse-similarity-top-k、--rerank系列）的测试集：脏库上调参，比干净库上更能暴露机制差异 - 应用挂载（EP05）：客服 agent 计划挂载
zj0knmrbye，届时需先裁决实验文档（旧版制度、烂 Excel）去留，本期实测结论直接支撑该决策 - 控制台切片修正：智能切分边界不理想时，切片详情支持人工编辑，本文未展开
复现路径
npm install -g bailian-cli
bl auth login --api-key sk-xxxxx
bl knowledge retrieve --index-id 你的库id --query "报销发票怎么提交"
文档结构照本文三类翻车构造，控制台导入后跑对照验证。
十条检索均基于百炼 CLI 与百炼控制台实测，request_id 留痕于项目仓库。CLI 安装：官方文档，API Key：免费领取（新用户有免费额度）。
