昇腾部署第 G3 课：知识库搭建——从装 RAG SDK 到把公司文档变成可检索的库
系列定位：G2 讲了 RAG 的两条主线与八个步骤，但主线一的三步只讲了"是什么"。 G3 把主线一拆开讲透：从装 RAG SDK开始，到一份公司文档真正进库、能被检索出来为止。
⚠️ 本课与 G1/G2 的写法不同：按用户要求，这一课给足可照抄的命令与接口。 所有命令、包名、路径、函数名、参数均来自官方文档（出处见附录 A）， 版本基准：MindSDK 26.1.0（RAG SDK）。版本会更新，引用前请对照你手上的版本文档。
第一段 章前定位
这课不教你什么：
- 不教检索调优（查询改写 / reranker）—— 那是 G4，本课只保证东西能进去、能查出来。
- 不教线上问答怎么串（Chain / 缓存）—— 那是 G2 讲过的结构 + G6 讲的容量问题。
- 不贴完整业务代码。给的是官方示例的关键片段，够你跑通一条最小链路。
这课要教你什么：
知识库搭建 = 四个零件装到一起： 解析器（把文件读成文本）、切分器（把文本切成块）、 embedding 模型（把块变成向量）、两个库（存块 + 存向量）。
四样东西缺一样，库就是空的或者查不出东西。 本课按这个顺序装。
第二段 学习目标
学完这课，你应该能独立完成下面六件事：
- 把 RAG SDK 装到机器上，并验证装成功了（有命令有期望输出）
- 看懂官方的运行环境变量，知道每一行在干什么、哪几个必须改
- 注册文档解析器和切分器，让
.docx/.pdf/.xlsx能进库 - 初始化两个库（chunk 关系库 + 向量库），理解它们各自存什么
- 用
upload_files/upload_dir把文件真正灌进库 - 验证"库真的有东西"，而不是"命令没报错"
第三段 全景：知识库构建的四个零件
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ ① 解析器 │ → │ ② 切分器 │ → │ ③ embedding │ → │ ④ 两个库 │
│ Loader │ │ Splitter │ │ 模型 │ │ Docstore │
│ 把文件读成 │ │ 把文本切成 │ │ 把块变成 │ │ + VectorStore│
│ 文本 │ │ chunk │ │ 向量 │ │ 存起来 │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
↑ ↑ ↑ ↑
按扩展名注册 按扩展名指定 要单独加载模型 官方给了具体选型
⭐ 官方的依赖关系图（这是理解四个零件关系的官方原文）：
KnowledgeDB 依赖了 KnowledgeStore、Docstore、VectorStore 实现对知识库文档片段及向量化入库。 - KnowledgeStore 负责对知识库增删查操作 - Docstore 负责对文档片段增删改查操作，具体配置实例为（OpenGaussDocstore、MilvusDocstore、SQLiteDocstore） - VectorStore 负责对向量增删改查操作，具体配置实例为（OpenGaussDB、MilvusDB、MindFAISS）
把这张图翻译成一句话：
KnowledgeDB = KnowledgeStore（管有哪些知识库）
+ Docstore （管知识库里的文档片段）
+ VectorStore （管片段的向量）
⭐⭐ 官方给出了具体的库选型 —— 这是搭库时第一个要做的决定：
| 用途 | 官方给的实例 | 本课用哪个 | 为什么 |
|---|---|---|---|
| 文档片段（Docstore） | OpenGaussDocstore / MilvusDocstore / SQLiteDocstore | SQLiteDocstore | 单机、零依赖、适合先跑通 |
| 向量（VectorStore） | OpenGaussDB / MilvusDB / MindFAISS | MindFAISS | 昇腾自研，和 NPU 亲和 |
⚠️ 这两个选型是"最小可用组合"：SQLite + MindFAISS，一台机器就能跑。 要上生产、要多用户并发，再按官方给的其他实例替换 —— 接口不变，换的就是这两个类。
第四段 【如果我来做】装起来：先摸环境，再按依赖顺序装
本节全部命令来自官方《安装部署》，路径占位符按你的实际环境替换。
4.0 我会按这个顺序做（顺序错了会返工）
① 摸环境（不装任何东西，先查三件事）
· 有没有 NPU 卡、驱动挂上没有 → npu-smi info
· Python 是不是 3.11 → python3 -V
· 机器能不能上外网 → 决定后面是"在线装"还是"离线搬"
⚠️ 这一步不做，第 ③ 步会返工
② 选装法（容器 / 物理机）
官方建议容器 → 拉镜像起容器，跳过下面全部步骤
物理机 → 按 ③ 走（本课讲这条，因为你要知道里面装了什么）
③ 备料（按依赖顺序，不能乱）
NPU 驱动固件 + CANN（含 Toolkit 和 ops 包）
→ Index SDK（Ascend-mindxsdk-mxindex）
→ RAG SDK 本体
→ Python 依赖包（requirements.txt）
⭐ 顺序的依据：后者依赖前者。装反了会报"找不到 libascendcl"这类错，
而且报错位置会误导你以为包坏了。
④ 装 RAG SDK（十步，见 4.3）
每步都有【期望输出】，看到才算过 —— 不攒着一起验
⑤ 配环境变量（4.4）
十个 export + 三个 source；配完必须 source ~/.bashrc
⑥ 验安装（4.5）
npu-smi info 看 Health=OK；python3 -c "import mxRag..."
⚠️ 这一验只证明"能 import"，不证明"能跑" —— 真正的验证在第五段
⑦ 搭知识库（第五段：注册解析器 → 加载模型 → 建两个库 → 灌文档）
⑧ 出证据（第六段八条判据，尤其"换个说法也查得出来"）
⭐ 这个顺序里最容易被跳过的是 ① 和 ⑧：
- ①：不摸环境直接开装，装到一半发现 Python 版本不对 / 卡没挂上，前面白装；
- ⑧：用"命令没报错"当验收 —— 而 upload_files 不报错 ≠ 上传成功（它返回的是失败列表）。
① 的三条摸底命令：
命令 npu-smi info
含义：查看 NPU 设备信息（A1 讲过，这里当作"环境摸底的第一条"） 拆解：
npu-smi（昇腾设备管理工具）＋info（子命令：查信息） 用法：npu-smi info期望：打印一张表，列出每张卡的型号、温度、显存、进程；Health为OK不过会怎样：命令不存在 → 驱动没装（"驱动包 = 驱动 & npu-smi 工具包"）；有输出但列不出卡 → 权限或硬件问题
命令 python3 -V
含义：查 Python 版本。RAG SDK 官方要求 Python 3.11 拆解：
-V（version，大写；小写-v是啰嗦模式，别搞混） 用法：python3 -V期望：Python 3.11.x不过会怎样：版本不是 3.11 → 先解决 Python，再动 RAG SDK（否则 pip 装依赖会莫名其妙失败）
命令 curl -s --max-time 5 -o /dev/null -w "%{http_code}" https://www.hiascend.com
含义：测本机能不能上外网 —— 决定走"在线装"还是"离线搬" 拆解：
-s（静默，不显示进度）--max-time 5（最多等 5 秒）-o /dev/null（丢弃正文，只看状态码）-w "%{http_code}"（输出 HTTP 状态码） 用法：直接执行 期望：打印200（能上外网）；超时/000（上不了，走离线） 不过会怎样：超时不要急着报错 —— 如果目标是私有化环境，"连不上"本来就是预期结果
4.1 先决定：容器装还是物理机装
4.1 先决定：容器装还是物理机装
官方原文：
RAG SDK 支持物理机部署和容器部署两种方式，本文档介绍在物理机内部署的方式。 建议在容器内部署 RAG SDK，在容器中进行部署则不需要执行本文档后续操作， 部署指导请参考 RAG SDK 镜像启动。
⭐ 结论：官方建议容器部署，直接拉官方镜像起容器，跳过本课 4.2–4.4 全部步骤。 本课讲物理机部署 —— 因为你得先知道里面装了什么，出问题才查得动。
4.2 依赖装什么（三类）
官方《安装依赖说明》：
① NPU 驱动 + CANN：按《CANN 安装指南》装（包含 Toolkit 和 ops 包），并配置环境变量。
（这部分在 A1 / B1–B4 已完整讲过，本课不重复。）
② Index SDK 检索软件包：
| 项 | 官方值 |
|---|---|
| 安装包全名 | Ascend-mindxsdk-mxindex_<version>_linux-<arch>.run |
| 配套版本 | 26.1.0 |
| 获取 | 昇腾社区下载页（module=sdk+cann） |
③ Python：3.11（官方指定版本）
⚠️ 官方特别提示（非 root 用户必看）：
为了让非 root 用户能够使用驱动，安装 npu-driver 要添加
--install-for-all选项。
为什么这条重要：不加这个选项，非 root 用户用不了驱动 ——
而 RAG SDK 又不建议用 root 跑服务（见 4.5 的分寸说明）——
两头一夹，--install-for-all 就成了必选项。
4.3 装 RAG SDK 本体（离线 run 包，官方十步）
官方给的安装须知里有两条要记住：
- 使用同一普通用户完成 CANN、NPU 驱动固件及 RAG SDK 的安装与运行。
- 软件包的安装、升级、卸载及版本查询相关的日志会保存至
~/log/mxRag/deployment.log； 完整性校验、提取文件、tar 命令访问相关的日志会保存至~/log/makeself/makeself.log。
「同一普通用户」这条很关键：装的时候用谁，跑的时候就得用谁 —— 换了用户，环境变量和权限都对不上。
日志路径要记住：装不上、装错了，先看这两个文件，比瞎猜快。
安装准备（官方第 1 步）：
source /usr/local/Ascend/ascend-toolkit/set_env.sh # 默认路径，请按实际安装路径修改
安装步骤（官方第 3–10 步，逐条对应官方编号）：
第 3 步 · 加可执行权限
chmod u+x Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run
第 4 步 · 校验软件包完整性和一致性
./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --check
官方给的期望输出：
Verifying archive integrity... 100% SHA256 checksums are OK. All good.
第 5 步 · 创建安装路径（可选）
官方注意事项（值得单独拎出来）：
不建议在
/tmp路径下安装：系统重启后/tmp内容可能被清除， 且该目录权限与空间不稳定，不适合持久化部署。
- 不指定路径 → 默认装到
/usr/local/Ascend/mxRag - 指定路径 → 先创建，例如：
mkdir -p /home/work/RAG_SDK
官方给的 install 可选参数（表 1）：
| 参数名 | 官方说明 |
|---|---|
--install-path |
（可选）自定义软件包安装根目录。如未设置，默认为当前命令执行所在目录。路径必须是 / 或 ~ 开头，合法字符为 a-zA-Z0-9_/- |
--quiet |
表示静默操作 |
--whitelist |
可选参数，表示安装白名单特性，取值可以是 operator 或者 whl，安装多个特性时可用逗号分隔 |
第 6 步 · 执行安装
# 指定安装路径
./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install --install-path=/home/work/RAG_SDK
# 不指定安装路径（装在当前路径）
./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install
官方提示：安装时会弹出确认下载许可协议的说明，若要在安装时直接跳过，
可在安装命令前增加 echo y |：
echo y | ./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --install --install-path=/home/work/RAG_SDK
第 7 步 · 许可提示
安装过程中提示 Do you accept the LICENSE to install RAG SDK? [Y/N] 时，
输入 Y 或 y 继续安装；输入其他字符会停止安装并退出程序。
第 8 步 · 成功标志
Install package successfully
第 9 步 · 装 RAG SDK 的依赖包
pip3 install -r <安装路径>/mxRag/requirements.txt
第 10 步 · 验证依赖安装成功
pip3 list | grep mxRag
能检索到 mxRag 相关包，说明安装成功。
⚠️ 第 9 步可能报的错（官方给了处置方法）：
``` ERROR: Cannot uninstall 'xxx'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would lead to only a partial uninstall.
> 说明 `xxx` 模块是操作系统自带的组件，无法直接升级，可以尝试重新下发指令安装：
> ```bash
pip3 install -r <安装路径>/mxRag/requirements.txt --ignore-installed
4.4 配运行环境变量（官方示例，照抄后改路径）
官方做法：用 vim 打开 ~/.bashrc，在文件最后添加：
export MX_INDEX_FINALIZE=0
export PY_VERSION=python3.11
export LOGURU_FORMAT='<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message!r}</level>'
export MX_INDEX_MODELPATH=<模型路径>
# 设置 index SDK 安装路径，请根据实际安装路径修改
export MX_INDEX_INSTALL_PATH=<index SDK安装路径>
export MX_INDEX_MULTITHREAD=1
export ASCEND_HOME=<Ascend安装路径>
export ASCEND_VERSION=<Ascend安装路径>/ascend-toolkit/latest
export LD_LIBRARY_PATH=<index SDK安装路径>/lib:<faiss安装路径>/lib:<Ascend安装路径>/OpenBLAS/lib:$LD_LIBRARY_PATH
export LD_PRELOAD=$(find $(python3 -c "import sklearn; print(sklearn.__path__[0])")/../scikit_learn.libs -name "libgomp-*" | head -1):$LD_PRELOAD
export PATH=/usr/local/bin:$PATH
source <Ascend安装路径>/ascend-toolkit/set_env.sh
source <Ascend安装路径>/nnal/atb/set_env.sh
source <安装路径>/mxRag/script/set_env.sh
官方对四个路径占位符的说明：
| 占位符 | 官方说明 |
|---|---|
<Ascend安装路径> |
CANN 和驱动的安装根目录，默认为 /usr/local/Ascend |
<index SDK安装路径> |
Index SDK 的安装路径，默认为 <Ascend安装路径>/mxIndex |
<faiss安装路径> |
faiss 的安装路径 |
<模型路径> |
模型存放路径 |
保存退出后让它生效：
source ~/.bashrc
⭐ 这一段的读法（别整段照抄不看来路）：
| 变量 | 在干什么 |
|---|---|
三个 source |
依次加载 CANN（ascend-toolkit）、NNAL/ATB 加速库、RAG SDK 自己的环境 |
ASCEND_HOME / ASCEND_VERSION |
告诉 RAG SDK CANN 装在哪（报"找不到 libascendcl"就查这两行） |
MX_INDEX_INSTALL_PATH |
告诉它 Index SDK（检索）装在哪 |
MX_INDEX_MODELPATH |
模型放哪 —— embedding 模型、reranker 模型都从这里找 |
LD_LIBRARY_PATH |
动态库搜索路径 —— 把 Index SDK、faiss、OpenBLAS 的 lib 目录加进去 |
LD_PRELOAD |
预加载一个 OpenMP 运行库（libgomp），解决多线程库冲突 |
MX_INDEX_MULTITHREAD=1 |
开多线程检索 |
⚠️ 这是官方给的示例配置，官方原话就是「以下为示例配置，请根据实际安装路径替换所有路径占位符」。 别把示例里的
/usr/local/Ascend当成硬规定 —— 你如果装在别处，要全部替换。
4.5 安装验证（两条命令，官方给的）
① 查驱动是否挂载正常
npu-smi info
官方判据：当 Health 参数的值为 OK 时，即表示当前芯片的健康状态为正常。
② 验证 RAG SDK 是否装成功
python3 -c "import mxRag; print('RAG SDK import: OK')"
⚠️ 这条命令看着简单，但它验的是"Python 能不能 import" —— import 成功 ≠ 库能跑。真正的验证在第六段（把文件灌进去再查出来）。
⚠️ 关于 root 的分寸（G2 埋的坑，这里说清）
官方《开发流程》里有一句：「运行阶段请使用 root 用户执行相关用例。」
但这不是"生产环境该用 root"的意思 —— 它是跑官方自带用例的要求。 理由很直接：官方的用例脚本里路径是固定的，非 root 用户读不到。
实际部署要反过来看：RAG SDK 自己给的 KnowledgeStore 参数约束里，
明确把 /etc、/usr/bin、/sys/、/dev/、/sbin 列为禁止存放路径 ——
这个设计本身就是在防越权。所以：
跑官方用例按官方说的用 root；部署自己的服务，按最小权限来。
4.6 另一种装法：Wheel 包（官方给了完整办法）
官方说明 Wheel 包的两个前提：
- Wheel 包不包含 CANN（
libascendcl.so等）及 Python 第三方依赖，使用前须按安装依赖说明完成安装。- 每次启动 Python 前，须加载 CANN 环境变量：
bash source /usr/local/Ascend/ascend-toolkit/set_env.sh # 或 source /usr/local/Ascend/cann/set_env.sh
怎么拿到 wheel（两种，官方给了第二种的命令）：
# 从 run 包里提取
./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --noexec --extract=/tmp/ragsdk_extract
find /tmp/ragsdk_extract -name 'ragsdk-*.whl'
安装：
pip3 install /path/to/ragsdk-1.0.0-py3-none-any.whl
已存在旧版本时强制重装：
pip3 install --force-reinstall --no-deps /path/to/ragsdk-1.0.0-py3-none-any.whl
⚠️ 官方提示（这条很实用）：
建议使用
--no-deps，避免 pip 自动升级或降级成固定的依赖版本。
为什么：不加 --no-deps，pip 会按 wheel 里声明的版本号去重新装一遍依赖 ——
你环境里已经调好的版本可能被改掉，"装个 RAG SDK 把 CANN 相关依赖弄坏了"就是这么来的。
第五段 【搭起来】把文档变成可检索的知识库
本段代码来自官方《知识管理 · 接口参考》的调用示例，是官方给的最小完整链路。 按官方示例的形状给你，再逐段解释。
5.1 官方完整示例（先看全貌）
from mx_rag.embedding.local import TextEmbedding
from mx_rag.knowledge import KnowledgeStore, KnowledgeDB, upload_files, delete_files, FilesLoadInfo
from mx_rag.document import LoaderMng
from mx_rag.storage.document_store import SQLiteDocstore
from mx_rag.storage.vectorstore import MindFAISS
from langchain.text_splitter import RecursiveCharacterTextSplitter
from mx_rag.knowledge import upload_dir
from mx_rag.document.loader import DocxLoader, PdfLoader, ExcelLoader
# ① 解析器与切分器：按扩展名注册
loader_mng = LoaderMng()
loader_mng.register_loader(DocxLoader, [".docx"])
loader_mng.register_loader(PdfLoader, [".pdf"])
loader_mng.register_loader(ExcelLoader, [".xlsx"])
# loader_mng.register_loader(ImageLoader, [".png"])
loader_mng.register_splitter(RecursiveCharacterTextSplitter, [".docx", ".pdf", ".xlsx"])
# ② embedding：设置向量检索使用的 NPU 卡，加载模型
dev = 0
emb = TextEmbedding("/path/to/model", dev_id=dev)
# ③ 向量库
vector_store = MindFAISS(x_dim=1024, devs=[dev],
load_local_index="/path/to/index", auto_save=True)
# ④ 两个关系库（chunk 片段库 + 知识管理库）
chunk_store = SQLiteDocstore(db_path="./sql.db")
knowledge_store = KnowledgeStore(db_path="./sql.db")
# ⑤ 添加知识库及管理员
knowledge_store.add_knowledge(knowledge_name="test", user_id='Default', role='admin')
# ⑥ 初始化知识管理
knowledge_db = KnowledgeDB(knowledge_store=knowledge_store, chunk_store=chunk_store,
vector_store=vector_store,
knowledge_name="test", user_id='Default', white_paths=["/home/"])
# ⑦ 上传单个文件
upload_files(knowledge=knowledge_db, files=["/path/data/test.docx"], loader_mng=loader_mng,
embed_func=emb.embed_documents, force=True)
# ⑧ 上传整个目录
params = FilesLoadInfo(knowledge=knowledge_db, dir_path="/path/data/files", loader_mng=loader_mng,
embed_func=emb.embed_documents, force=True, load_image=False)
upload_dir(params=params)
# ⑨ 删除文件
delete_files(knowledge_db, ["test.docx"])
⭐ 这九段就是"知识库搭建"的全部 —— 下面逐段说关键点。
5.2 ① 解析器与切分器：按扩展名注册
loader_mng = LoaderMng()
loader_mng.register_loader(DocxLoader, [".docx"])
loader_mng.register_loader(PdfLoader, [".pdf"])
loader_mng.register_loader(ExcelLoader, [".xlsx"])
loader_mng.register_splitter(RecursiveCharacterTextSplitter, [".docx", ".pdf", ".xlsx"])
这两种注册是分开的，别混：
| 方法 | 注册什么 | 决定 |
|---|---|---|
register_loader |
怎么把文件读成文本 | 支持哪些格式（.docx / .pdf / .xlsx） |
register_splitter |
怎么把文本切成块 | 用哪个切分策略、对哪些格式生效 |
⭐ 官方还给了扩展空间（G2 引用过，这里落到实处）：
用户可以根据上传的文件类型注册相应的文档解析器（参见文档解析、langchain 文档解析 API 或基于 langchain 自定义） 和文档切分器（参见 langchain 文档切分 API 或基于 langchain 自定义）。
意思是：官方内置的解析器不够用时，可以接 langchain 的生态，也可以自己写一个 ——
因为这里的 RecursiveCharacterTextSplitter 本身就是 langchain 的类。
⚠️ 切分器要全部登记一遍：示例里 register_splitter 传的是列表 [".docx", ".pdf", ".xlsx"] ✓ ——
只注册 loader 不注册 splitter，文件读进来了也切不成 chunk。
5.3 ② embedding：要单独加载，还要指定用哪张卡
dev = 0
emb = TextEmbedding("/path/to/model", dev_id=dev)
三个要点：
| 要点 | 说明 |
|---|---|
| 模型路径 | /path/to/model 要换成你的实际路径；对应环境变量 MX_INDEX_MODELPATH |
dev_id |
指定用第几张 NPU 卡 —— 0 就是第 0 张。多卡机器上这一步决定了跑在哪张卡上 |
embed_documents |
后面 upload_files 的 embed_func 传的就是这个对象的方法 |
⚠️ 官方对 embed_func 有一条进阶说明（在 upload_files 的参数表里）：
嵌入函数，把文件信息转换为向量。直接传入回调方法默认按稠密处理，即
{'dense': Callable, 'sparse': None}；传入字典格式为{'dense': x, 'sparse': y}， x 和 y 分别为稠密和稀疏向量的回调函数，xy 不能同时为 None。支持同时入库稠密和稀疏向量。
翻译：默认只用稠密向量（最常见、够用）； 要稀疏向量（关键词权重那类）就传字典，可以两种一起入库。
5.4 ③ 向量库：x_dim 是最容易填错的一个参数
vector_store = MindFAISS(x_dim=1024, devs=[dev],
load_local_index="/path/to/index", auto_save=True)
| 参数 | 填什么 | 为什么容易错 |
|---|---|---|
x_dim |
向量维度，示例是 1024 | 必须和 embedding 模型输出的维度一致 —— 换了模型忘了改这里，检索就会出错或查不准 |
devs |
用哪些卡，列表 | 示例传 [dev]，也可以传多张 |
load_local_index |
索引加载路径 | 已有索引就加载，没有则新建 |
auto_save |
自动保存索引 | 开了省事，不开要自己存 |
⭐
x_dim这一条是本课最该记住的操作细节： 换 embedding 模型时，x_dim必须跟着换。 这是"换了模型检索就变差"的头号原因。
5.5 ④⑤⑥ 两个关系库 + 知识库对象
chunk_store = SQLiteDocstore(db_path="./sql.db")
knowledge_store = KnowledgeStore(db_path="./sql.db")
knowledge_store.add_knowledge(knowledge_name="test", user_id='Default', role='admin')
knowledge_db = KnowledgeDB(knowledge_store=knowledge_store, chunk_store=chunk_store,
vector_store=vector_store,
knowledge_name="test", user_id='Default', white_paths=["/home/"])
三个对象、各管一摊（对应第三段的官方依赖关系图）：
| 对象 | 管什么 |
|---|---|
knowledge_store（KnowledgeStore） |
有哪些知识库、谁能用 |
chunk_store（SQLiteDocstore） |
知识库里的文档片段 |
vector_store（MindFAISS） |
片段的向量 |
knowledge_db（KnowledgeDB） |
把上面三个捆在一起，之后上传/删除都操作它 |
KnowledgeStore(db_path) 的官方参数约束（这条要看清，很容易踩）：
db_path：数据库路径，长度 [1, 1024]；路径不能为软链接且不允许存在..； 文件名长度不能超过 200。存放路径不能在路径列表中：["/etc", "/usr/bin", "/usr/lib", "/usr/lib64", "/sys/", "/dev/", "/sbin", "/tmp"]。
⭐ 这份禁用清单本身就是一个安全设计 —— 它把系统目录全排除了。
/tmp 也在里面，和 4.3 那条"不建议在 /tmp 安装"是同一个道理。
add_knowledge 的官方说明：
| 参数 | 类型 | 必选 | 官方说明 |
|---|---|---|---|
knowledge_name |
str | 必选 | 知识库名称，长度 [1, 1024] |
user_id |
str | 必选 | 用户 ID，区分不同知识库，需满足正则 ^[a-zA-Z0-9_-]{6,64}$ |
role |
str | 可选 | 用户角色，默认为 'admin'。添加后该 user_id 默认可以操作该知识库 |
返回值：int —— 返回添加的知识库对应的 knowledge_id。
⚠️
user_id有正则要求：^[a-zA-Z0-9_-]{6,64}$—— 只能字母数字下划线连字符，长度 6–64，不能用中文。 示例里用'Default'是 7 位，刚好够 —— 你如果写"张三"，这里会直接报错。
white_paths=["/home/"] 是什么：路径白名单 ——
告诉知识库只允许从这些路径下读文件。
⭐ 这是个安全开关：不设白名单等于允许从任意路径读。 配合 G1 的私有化要求，这里应该是"公司文档目录"，不要图省事写
/。
5.6 ⑦⑧⑨ 上传、批量上传、删除
上传单个文件：
upload_files(knowledge=knowledge_db, files=["/path/data/test.docx"], loader_mng=loader_mng,
embed_func=emb.embed_documents, force=True)
官方参数说明：
| 参数 | 必选 | 官方说明 |
|---|---|---|
knowledge |
必选 | KnowledgeDB 对象 |
files |
必选 | 要上传的文件列表 |
loader_mng |
必选 | 提供文档解析函数的管理类对象 |
embed_func |
必选 | 嵌入函数（见 5.3 的稠密/稀疏说明） |
force |
可选 | 是否强制覆盖旧数据；如果选择否，文档重复会抛出异常。默认为 False |
返回值：List[str] —— 添加到知识库中失败的文件列表。
⭐ 这个返回值要用起来： 它返回的是"失败的文件"，不是"成功的文件" —— 空列表才是全成功。 上传 100 个文件时，别只看"没报错"，要打印这个列表看有没有漏的。
上传整个目录：
params = FilesLoadInfo(knowledge=knowledge_db, dir_path="/path/data/files", loader_mng=loader_mng,
embed_func=emb.embed_documents, force=True, load_image=False)
upload_dir(params=params)
load_image 的官方说明（这里有个容易搞混的规则）：
是否支持图片类型文件，默认为
False。 如果选择False，表示只支持文档类型如.docx、.txt、.md等， 具体支持类型为 loader_mng 注册器中 loader 和 splitter 方法支持类型的交集。 如果选择True表示只支持图片类型，支持的范围仅限于 loader_mng 注册器中 loader 方法支持的类型与[".jpg", ".png"]的交集。
⚠️ 两个关键点：
load_image=False时，实际支持的格式是「loader 和 splitter 的"交集"」 —— 两个注册器都要有，格式才生效（这就是 5.2 那句"切分器要全部登记一遍"的官方依据）；load_image是"二选一"不是"叠加" ——True表示只支持图片，不是"文档+图片"。
⚠️ 官方还有一条配套提醒：
当支持文档类型的解析时，对应的
embed_func嵌入函数应该支持对应文档类型； 当支持图片类型的解析时，对应的embed_func也应该支持图片类型，否则会出现错误。
意思是：你要能读图片，得先有一个"能理解图片"的 embedding 模型 ——
不是把 load_image 改成 True 就能读图了。
删除文件：
delete_files(knowledge_db, ["test.docx"])
5.7 ⭐ 关于"用户和权限"，本课要澄清 G2 的一句话
G2 里我引用了官方《简介》的一句：
RAG SDK……不包含用户、权限等和业务强相关的功能接口。
但本课在《知识管理》接口里，看到了明确的用户与角色参数：
add_knowledge(..., user_id, role)、add_usr_id_to_knowledge(...)（角色可为 'admin' 或 'member'）。
这两句话看起来矛盾，其实说的是两个层次：
| 层次 | 官方给不给 | 依据 |
|---|---|---|
| 知识库归属与查询权限（这个库归谁、谁能查） | ✅ 给 | user_id / role（admin / member）/ add_usr_id_to_knowledge |
| 业务级权限体系（认证、组织架构、细粒度管控、审计） | ❌ 不给 | 官方《简介》原话：「不包含用户、权限等和业务强相关的功能接口」 |
⭐ 所以正确的理解是：
RAG SDK 有一套"够区分知识库归属和查询权限"的轻量机制， 但它不是一套企业级的权限系统 —— 认证、组织、审计那些要自己接。
⚠️ 这个区分对项目很实际：如果你看到 user_id 就以为权限这块不用做了 ✗ ——
上线时会被安全审查挡下来 ✓（G7 展开）。
第六段 判据 / 验收
⭐ 本段的原则：验收要"看内容"，不能"看有没有报错"。
| # | 判据 | 怎么验（可操作） | 不过说明 |
|---|---|---|---|
| ① | 装上了 | pip3 list \| grep mxRag 能搜到 |
4.3 第 9 步没做完 |
| ② | 能 import | python3 -c "import mxRag; print('RAG SDK import: OK')" |
环境变量没生效（重开终端或 source ~/.bashrc） |
| ③ | 卡是好的 | npu-smi info 里 Health 为 OK |
驱动/固件问题（回 A1） |
| ④ | 文件进去了 | upload_files 的返回列表为空（返回的是失败列表） |
解析器/切分器没注册齐全 |
| ⑤ | chunk 数不为 0 | 用 get_all_documents("<知识库名>", user_id) 看文档列表 |
切分器没生效（格式不在交集里） |
| ⑥ | 向量库有东西 | 看 load_local_index 那个索引路径有没有生成内容 |
x_dim 与模型不匹配，或 embedding 模型路径错 |
| ⑦ | 查得出来 | 用知识库里原句做检索，返回里含那段原文 | 检索环节问题（G4） |
| ⑧ | 换个说法也查得出来 | 换一种表述问同一个问题 | 该上"查询改写检索"了（G4） |
⚠️ 第 ④ 条最容易被忽略：
upload_files不报错 ≠ 上传成功 —— 它的返回值就是失败列表。空列表才是全成功。
第七段 出问题怎么查
排查顺序：先看"装的时候对不对"，再看"注册得全不全"，最后才怀疑检索。
| 你看到的现象 | 先查哪一步 | 具体动作 |
|---|---|---|
import mxRag 失败 |
4.4 环境变量 | 确认三个 source 都执行了；echo $ASCEND_HOME 看有没有值 |
报找不到 libascendcl.so |
4.4 | 查 ASCEND_HOME / ASCEND_VERSION 两行路径对不对 |
| 报找不到检索相关库 | 4.4 | 查 MX_INDEX_INSTALL_PATH；查 LD_LIBRARY_PATH 里有没有 Index SDK 的 lib |
| 报多线程/OpenMP 冲突 | 4.4 | 查 LD_PRELOAD 那行（libgomp 预加载） |
pip3 install 卡在 uninstall 报错 |
4.3 | 用官方给的 --ignore-installed 重跑 |
| 装完 RAG SDK,别的依赖坏了 | 4.6 | 下次装 wheel 加 --no-deps（官方建议） |
KnowledgeStore 报路径非法 |
5.5 | 对照禁用清单：/etc、/usr/bin、/sys/、/dev/、/sbin、/tmp 都不行；也不能是软链接或含 .. |
user_id 报格式错 |
5.5 | 对照正则 ^[a-zA-Z0-9_-]{6,64}$ —— 不能有中文，长度 6–64 |
| 上传返回失败列表非空 | 5.6 | 看文件格式在不在"loader ∩ splitter"的交集里 |
| 上传报"文档重复" | 5.6 | force=False 是默认值 —— 重复上传同名文件会抛异常，要覆盖就传 force=True |
| chunk 数是 0 | 5.2 | 切分器没注册（只注册了 loader） |
| 换了 embedding 模型后检索变差 | 5.4 | x_dim 忘了跟着改 |
| 读图片报错 | 5.6 | load_image=True 时，embedding 模型也要支持图片 |
第八段 常见报错清单
本课出现了官方正文里给出的两条真实报错（下表前两条是官方原文，其余是流程性排查方向）。 查其他报错用官方案例库：
https://www.hiascend.com/document/caselibrary—— 按报错原文的稳定特征词检索。
| 报错 / 现象 | 官方给的处置 |
|---|---|
ERROR: Cannot uninstall 'xxx'. It is a distutils installed project and thus we cannot accurately determine which files belong to it which would lead to only a partial uninstall. |
官方原文：说明 xxx 是操作系统自带组件，无法直接升级 → pip3 install -r <安装路径>/mxRag/requirements.txt --ignore-installed |
Do you accept the LICENSE to install RAG SDK? [Y/N] 后输入非 Y 字符 |
官方原文：输入其他字符时停止安装，退出程序 → 重跑，输入 Y/y，或在命令前加 echo y \| |
Install package successfully 没出现 |
4.3 |
校验不通过（不是 SHA256 checksums are OK） |
4.3 第 4 步 |
装到了 /tmp 下 |
4.3 第 5 步 |
⭐ 日志位置（官方给的，存下来）：
| 日志 | 记什么 |
|---|---|
~/log/mxRag/deployment.log |
安装、升级、卸载及版本查询相关 |
~/log/makeself/makeself.log |
完整性校验、提取文件、tar 命令访问相关 |
第九段 小结 + 钩子 + 自测
三句话记住本课
- 知识库搭建 = 四个零件：解析器 → 切分器 → embedding 模型 → 两个库。 注册要成对（loader 和 splitter 都要登记，实际支持格式是两者的交集）。
- 官方给了具体的库选型：文档片段用 SQLiteDocstore / Milvus / OpenGauss； 向量用 MindFAISS / Milvus / OpenGauss。最小可用组合 = SQLite + MindFAISS。
- 三个最容易踩的坑：
upload_files返回的是失败列表（不是成功列表）；x_dim必须跟着 embedding 模型变；重复上传同名文件默认抛异常（要覆盖得传force=True）。
自测（不看上文）
- RAG SDK 官方建议容器部署还是物理机部署？为什么本课还讲物理机？
- 装 RAG SDK 要用哪三个环境变量脚本？（提示：一个是 CANN，一个是加速库，一个是它自己）
register_loader和register_splitter分别决定什么？两个里少一个会怎样？upload_files返回的是什么？怎么判断"全成功"？x_dim填错会有什么后果？什么时候必须改它？- 官方说 RAG SDK「不包含用户、权限」，但接口里又有
user_id和role—— 这两者怎么统一？
钩子：下一课
东西进库了，也能查出来了 —— 但你可能发现：
用文档里的话问，查得到；用自己的话说，查不到。 同一份文档里的两个相似段落，总是那一片被查出来，另一片从来不露面。
这就是检索质量问题，也是 RAG 落地效果差异最大的地方。
G4 会把官方给的三条路（查询改写检索 / 近似检索 / reranker 精排）拆开讲 —— 那时候我们再回到这套代码，把三个调点一个一个加上去。
附录 A 官方出处
| # | 内容 | 官方出处 |
|---|---|---|
| 1 | 部署方式与建议：支持物理机部署和容器部署；建议在容器内部署 RAG SDK，容器部署参考 RAG SDK 镜像启动 | MindSDK 26.1.0《RAG SDK · 安装部署》→ zh/mindsdk/2610/rag/ragug/docs/zh/installation_guide.md |
| 2 | 依赖三类：① NPU 驱动固件与 CANN（含 Toolkit 和 ops 包）② Index SDK 检索软件包 Ascend-mindxsdk-mxindex_<version>_linux-<arch>.run（配套版本 26.1.0） ③ Python 3.11 |
同上 |
| 3 | --install-for-all：为了让非 root 用户能够使用驱动，安装 npu-driver 要添加该选项 |
同上 |
| 4 | 安装须知：使用同一普通用户完成安装与运行；安装/升级/卸载/版本查询日志 → ~/log/mxRag/deployment.log；完整性校验/提取文件/tar → ~/log/makeself/makeself.log |
同上 |
| 5 | 离线安装十步：chmod u+x → --check（期望 Verifying archive integrity... 100% SHA256 checksums are OK. All good.）→ 创建安装路径（默认 /usr/local/Ascend/mxRag；不建议在 /tmp 安装）→ --install [--install-path=] → 许可提示输入 Y → Install package successfully → pip3 install -r <安装路径>/mxRag/requirements.txt → pip3 list \| grep mxRag |
同上 |
| 6 | install 可选参数：--install-path（须 / 或 ~ 开头，合法字符 a-zA-Z0-9_/-）／--quiet／--whitelist（取值 operator 或 whl，逗号分隔） |
同上 |
| 7 | pip 报错处置：Cannot uninstall 'xxx'. It is a distutils installed project… → 加 --ignore-installed 重跑 |
同上 |
| 8 | 运行环境变量官方示例（含 MX_INDEX_FINALIZE、PY_VERSION、MX_INDEX_MODELPATH、MX_INDEX_INSTALL_PATH、MX_INDEX_MULTITHREAD、ASCEND_HOME、ASCEND_VERSION、LD_LIBRARY_PATH、LD_PRELOAD、三个 source） |
同上 |
| 9 | 安装验证：npu-smi info（Health 为 OK 即正常）；python3 -c "import mxRag; print('RAG SDK import: OK')" |
同上 |
| 10 | Wheel 包安装：不含 CANN 与第三方依赖；每次启动 Python 前须加载 CANN 环境变量；run 包提取 --noexec --extract= + find -name 'ragsdk-*.whl'；pip3 install [--force-reinstall --no-deps]；建议使用 --no-deps |
同上 |
| 11 | KnowledgeDB 依赖关系：依赖 KnowledgeStore（知识库增删查）、Docstore（文档片段增删改查，实例 OpenGaussDocstore / MilvusDocstore / SQLiteDocstore）、VectorStore（向量增删改查，实例 OpenGaussDB / MilvusDB / MindFAISS） | MindSDK 26.1.0《RAG SDK · 知识管理 · 接口参考》→ …/docs/zh/api/knowledge_management.md |
| 12 | KnowledgeStore 类与调用示例（完整九段示例代码） | 同上 |
| 13 | KnowledgeStore(db_path) 路径约束：长度 [1,1024]；不能为软链接、不允许 ..；文件名 ≤200；禁用路径列表 ["/etc","/usr/bin","/usr/lib","/usr/lib64","/sys/","/dev/","/sbin","/tmp"] |
同上 |
| 14 | add_knowledge(knowledge_name, user_id, role)：role 默认为 'admin'；user_id 需满足正则 ^[a-zA-Z0-9_-]{6,64}$；返回 knowledge_id(int) |
同上 |
| 15 | check_knowledge_exist(knowledge_name, user_id) → bool；add_usr_id_to_knowledge（角色可为 'admin' 或仅有查询权限的 'member'） |
同上 |
| 16 | upload_files 参数：loader_mng（必选）、embed_func（必选，默认稠密 {'dense': Callable, 'sparse': None}，传字典可同时入库稠密与稀疏）、force（可选，默认 False，为否时文档重复抛异常）；返回 List[str] = 添加到知识库中失败的文件列表 |
同上 |
| 17 | upload_dir 参数：load_image（可选，默认 False；False 时支持类型为 loader 与 splitter 支持类型的交集；True 时仅支持图片，范围为 loader 支持类型与 [".jpg",".png"] 的交集）；嵌入函数应支持对应文档/图片类型，否则出错 |
同上 |
| 18 | 文档解析可扩展：文档解析器与切分器均可使用 langchain 的 API 或基于 langchain 自定义 | MindSDK 26.1.0《RAG SDK · 开发流程》→ …/docs/zh/user_guide.md |
| 19 | 「运行阶段请使用 root 用户执行相关用例」 | 同上 |
| 20 | RAG SDK「不包含用户、权限等和业务强相关的功能接口」 | MindSDK 26.1.0《RAG SDK · 简介》→ …/docs/zh/introduction.md |
⚠️ 本体系中属于「讲解/归纳」而非官方原文的部分，已明确标注： - 第三段「四个零件」的框架与那幅流程图，是我对官方依赖关系图的讲法，非官方术语； - 4.4 那张"每个变量在干什么"的解读表，是对官方示例配置的解释； - 「三个最容易踩的坑」「验收要看内容不看报错」等属实践方法； - 第 5.7 节对「用户/权限」两句官方表述的统一，是我的分析（两句官方原文都已原样列出）。
附录 B 命令详解（本课新增部分）
A1–G2 已解释过的命令（
npu-smi info、source、cat、export等）此处不重复。 本课命令很多，按"装的时候用 / 验的时候用"分两组。
B.1 安装相关
命令 chmod u+x <文件>
含义：给这个文件加上"可执行"权限。u 表示文件属主（user），+x 表示增加执行权限 拆解：chmod（change mode，改权限）＋ u（属主）＋ +x（加执行） 用法：chmod u+x Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run 期望：没有任何输出（Linux 的惯例：成功就是沉默） 不过会怎样：不加这一步直接 ./ 执行，会报 Permission denied
命令 ./<安装包>.run --check
含义：只校验不安装 —— 检查安装包的完整性和一致性（SHA256 校验） 拆解：./（执行当前目录下的这个文件）＋ --check（校验模式） 用法：./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --check 期望（官方给的原话）： Verifying archive integrity... 100% SHA256 checksums are OK. All good. 不过会怎样：校验不过 → 包在下载或搬运中损坏，重新获取，不要硬装
命令 mkdir -p <路径>
含义：创建目录。-p 表示"需要的父目录一起建，已存在也不报错" 拆解：mkdir（make directory）＋ -p（parents） 用法：mkdir -p /home/work/RAG_SDK 期望：无输出 不过会怎样：不加 -p，路径的上级目录不存在时会报 "No such file or directory"
命令 ./<安装包>.run --install [--install-path=<路径>]
含义：执行安装。--install 是安装模式；--install-path 指定装到哪 拆解：--install（安装）＋ --install-path（可选，安装根目录） 不指定 → 默认装到 /usr/local/Ascend/mxRag 指定 → 路径必须是 / 或 ~ 开头，只能用 a-zA-Z0-9_/- 这些字符 用法：./Ascend-mindxsdk-mxrag_{version}linux-{arch}.run --install --install-path=/home/work/RAG_SDK echo y | ./Ascend-mindxsdk-mxrag{version}_linux-{arch}.run --install --install-path=/home/work/RAG_SDK （前加 echo y | 表示预先回答 Y，跳过许可协议交互） --quiet 静默操作（不打印过程） --whitelist=operator,whl 安装白名单特性 期望：出现 Do you accept the LICENSE...? [Y/N] → 输入 Y → 最后出现 Install package successfully 不过会怎样：输入非 Y → 停止安装并退出；报路径非法 → 对照上面的字符和开头要求
命令 ./<安装包>.run --noexec --extract=<目录>
含义：只解压，不安装。用来从 run 包里把内容（比如 wheel 文件）掏出来 拆解：--noexec（不执行安装脚本）＋ --extract=<目录>（解压到哪） 用法：./Ascend-mindxsdk-mxrag_{version}_linux-{arch}.run --noexec --extract=/tmp/ragsdk_extract 期望：指定目录里出现解压后的文件 不过会怎样：目标目录已存在同名文件时可能失败 —— 换一个空目录
命令 find <目录> -name '模式'
含义：在目录里按文件名找文件（支持通配符） 拆解：find（查找）＋ 目录（在哪儿找）＋ -name（按名字匹配）＋ 模式（支持 * 通配） 用法：find /tmp/ragsdk_extract -name 'ragsdk-.whl' 期望：打印出找到的 wheel 文件的完整路径 不过会怎样*：什么都没输出 → 该目录下没有匹配的文件（解压步骤没成功？）
命令 pip3 install -r <文件>
含义：按 requirements 文件里列的清单，一次装齐所有 Python 依赖 拆解：pip3（Python 包管理器）＋ install（安装）＋ -r（requirements，按文件里的清单） 用法：pip3 install -r <安装路径>/mxRag/requirements.txt pip3 install -r <安装路径>/mxRag/requirements.txt --ignore-installed # 遇到 distutils 报错时 期望：逐条安装，最后 Successfully installed ... 不过会怎样：报 Cannot uninstall 'xxx'. It is a distutils installed project... → 这是官方正文收录过的报错，处置方式就是加 --ignore-installed
命令 pip3 install [--force-reinstall] [--no-deps] <wheel路径>
含义：安装单个 wheel 包 拆解：--force-reinstall（已装过也强制重装） --no-deps（只装这一个，不动它的依赖） 用法：pip3 install /path/to/ragsdk-1.0.0-py3-none-any.whl pip3 install --force-reinstall --no-deps /path/to/ragsdk-1.0.0-py3-none-any.whl 期望：Successfully installed ... 不过会怎样：不加 --no-deps 时，pip 会按 wheel 声明的版本重装依赖 —— 可能把你环境里已调好的版本换掉（官方建议加 --no-deps 的原因）
命令 pip3 list | grep mxRag
含义：列出已装的 Python 包，并筛出名字里含 mxRag 的 拆解：pip3 list（列包）＋ | （管道：把左边输出交给右边）＋ grep（筛选含关键词的行） 用法：pip3 list | grep mxRag 期望：出现 mxRag 相关的包名和版本 不过会怎样：没有输出 → 依赖包没装上（回到第 9 步）
命令 source ~/.bashrc
含义：在当前终端重新执行 ~/.bashrc，让刚加进去的环境变量立刻生效 拆解：source（在当前 shell 里执行，不是新开进程）＋ ~/.bashrc（用户级配置文件） 用法：source ~/.bashrc 期望：无输出 不过会怎样：不执行 → 刚加的 export 在当前终端不生效（新开终端才会读） ⭐ 这是"我明明配了环境变量为什么还说找不到"的头号原因
B.2 验证相关
命令 python3 -c "<代码>"
含义：不写文件，直接在命令行里跑一小段 Python 代码 拆解：python3（解释器）＋ -c（command，把后面字符串当代码执行） 用法：python3 -c "import mxRag; print('RAG SDK import: OK')" 期望：打印 RAG SDK import: OK 不过会怎样：报 ModuleNotFoundError → 没装上或环境变量没生效 ⚠️ 注意：这条只验"能不能 import"，不等于库能正常跑
命令 python3 -c "import sklearn; print(sklearn.__path__[0])"
含义：打印 sklearn 这个包被装在哪个目录（这行是环境变量里的用法，单独也能跑） 拆解：path[0] 是这个包的第一个搜索路径 —— 也就是它实际所在目录 用法：见 4.4 环境变量的 LD_PRELOAD 那行（官方示例里嵌在 find 命令里用） 期望：打印出路径，如 /usr/local/lib/python3.11/site-packages/sklearn 不过会怎样：报 ModuleNotFoundError → sklearn 没装（它属于 RAG SDK 的依赖）
B.3 本课涉及的 Python 类（不是命令，一并解释）
| 类 / 函数 | 干什么 |
|---|---|
LoaderMng |
解析器管理器。往里注册 loader 和 splitter，后面上传文件时由它负责读和切 |
DocxLoader / PdfLoader / ExcelLoader |
官方内置的文档解析器，分别对应 .docx / .pdf / .xlsx |
RecursiveCharacterTextSplitter |
切分器（来自 langchain）：按字符递归地把长文本切成块 |
TextEmbedding(模型路径, dev_id=卡号) |
embedding 模型的封装。dev_id 指定用哪张 NPU 卡 |
MindFAISS(x_dim=维度, devs=[卡], ...) |
昇腾自研的向量库。x_dim 必须匹配 embedding 模型的输出维度 |
SQLiteDocstore(db_path=...) |
文档片段库，用 SQLite 存 chunk 原文 |
KnowledgeStore(db_path=...) |
知识库管理库：有哪些知识库、谁能查 |
KnowledgeDB(knowledge_store=, chunk_store=, vector_store=, ...) |
把上面三个捆在一起的总对象，上传/删除都操作它 |
upload_files / upload_dir / delete_files |
上传单个文件 / 上传整个目录 / 删除文件 |
FilesLoadInfo(...) |
批量上传时的参数打包对象 |