从零开始搭建知识库 · EP02 · 基础篇
知识库能力栈的分工
"从零开始搭建知识库"系列第二期。上期（EP01）用三组实验说明了为什么需要知识库：答案散落多文件时，直接传文件问 AI 会得到"给什么信什么"的不可验证回答。本期把百炼知识库能力栈的最小闭环跑通。
先看分工，这是百炼这块能力栈比较特殊的设计：
| 环节 | 入口 | 说明 |
|---|---|---|
| 建库 + 导入文档 | 百炼控制台（网页） | 零代码，非技术角色可操作 |
| 检索 | bl knowledge retrieve（CLI） |
可自动化、可编排、输出结构化 JSON |
| 生成（组织成答案） | bl text chat 等 |
本期不展开，进阶篇接上 |
建库侧没有 CLI 命令，knowledge 组目前只有 retrieve 一条。这个分工实际是个分层设计：低频、需要人判断的操作（建库、导入、纠错）留在控制台；高频、值得脚本化的操作（检索）开放命令行。对做集成的同学来说，检索恰恰是最需要进 pipeline 的那一环。
实测环境
虚构网店"暖屋家居"的客服 FAQ，三份 Markdown：发货与物流政策（运费规则、货到付款地区）、退换货与售后政策（7 天无理由、电器保修）、支付与发票说明（支付方式、优惠券）。单份 1-2KB，官方建议的 Markdown 源文件格式。
一个设计细节：货到付款的信息故意拆在两份文档里：地区限制在物流文档，3 元代收服务费在支付文档。这是为了验证知识库的核心卖点：跨文件自动检索。
五组检索的行为验证
命令签名：
bl knowledge retrieve --index-id zj0knmrbye --query "新疆可以货到付款吗"
--index-id 与 --query 必填；无 --model（检索模型内置于知识库）。默认输出 JSON，核心字段：score（相关度排序分）、metadata.doc_name（来源文档）、metadata.content（命中切片原文）、request_id（调用凭证）。
| # | query | 返回 | 行为 |
|---|---|---|---|
| Q1 | 新疆可以货到付款吗 | 物流 0.83 + 支付 0.49 | 跨文件召回 |
| Q2 | 满多少钱包邮 | 物流 0.68 | 事实型命中 |
| Q3 | 收到的加湿器坏了怎么办 | 退换货 0.75 | 语义匹配（query 与文档标题零重叠） |
| Q4 | 优惠券能和满减一起用吗 | 支付 0.54（唯一一条） | 低相关自动过滤 |
| Q5 | 货到付款要额外收费吗 | 物流 0.82 + 支付 0.77 | 双文档高分聚合 |
Q5 是核心证据：物流返回"货到付款仅支持华东、华南主要城市（上海、杭州、南京、广州、深圳、厦门等）"，支付返回"需额外支付 3 元代收服务费"，一条命令同时召回，拼合才是完整答案。对集成视角更有价值的是 Q3：query 说"加湿器坏了"，命中的原文是"电器类商品（如加湿器、小夜灯）提供 1 年保修，非人为损坏免费维修或换新"，口语与文档措辞完全不同仍能命中，说明语义检索可用性过了基本门槛，不需要先做同义词工程。
三个工程细节：小文档（KB 级）整篇成一个切片，不切块；nodes 数组长度不恒定（Q4 只返回 1 条），下游集成别假设固定长度；输出天生结构化，接工单系统或 pipeline 零解析成本。
与生态其他组件的衔接
这个检索结果怎么继续往下走，百炼生态里有现成的下游：
- 应用（app）：EP05 计划把客服 agent 直接挂载这个知识库，同一个 index-id（
zj0knmrbye）贯穿系列，建库一次复用到 agent 场景 - pipeline：检索是典型可编排节点，多路检索参数（
--dense-similarity-top-k、--sparse-similarity-top-k、--rerank系列）在 EP04 展开 - 任意脚本：JSON 输出即取即用，
jq一行取 Top1 内容
复现路径
npm install -g bailian-cli
bl auth login --api-key sk-xxxxx
控制台建库（标准版 + 文件连接器，10 分钟）拿 index-id，写三份自己业务的 Markdown 文档导入，然后一条命令检索。完整命令与五组 JSON 返回见文末链接的项目仓库。
五组检索均基于百炼 CLI 与百炼控制台实测，request_id 留痕于项目仓库。CLI 安装：官方文档，API Key：免费领取（新用户有免费额度）。
