昇腾部署第 G4 课：文档解析与切分——决定检索质量的第一道关
系列定位：G3 讲了「怎么把文件灌进库」，但没讲「怎么灌才对」。 G4 把主线一的第一步（加载与切分）拆开讲透： 一份 200 页的 PDF，切成多少块、每块多大、按什么切、怎么知道切对了。 版本基准：MindSDK 26.1.0（RAG SDK）
第一段 章前定位
这课不教你什么：
- 不教检索调优（查询改写 / reranker）—— 那是 G5，本课只保证「切出来的东西值得被检索」。
- 不教知识库管理（增删文档、多知识库）—— 那是 G3 讲过的。
- 不给"最优切分参数" —— ⚠️ 官方给的是示例值，不是最优值；本课给的是怎么试出你这个场景的值。
这课要教你什么：
切分是 RAG 里"一次做完、后面全受影响"的一步。 切得太碎 → 检索到的上下文不完整，模型答不全； 切得太大 → 检索到的上下文掺了无关内容，模型答不准。 而这两件事，在检索阶段怎么调都救不回来。
第二段 学习目标
- 支持的文档格式有哪些？为什么实际生效的是两个注册器的交集？
chunk_size与chunk_overlap各控制什么？调大调小分别会发生什么？- 拿到一份新领域的文档，怎么定初始切分参数？
- 怎么判断"切得对不对"？（不是看代码跑没跑通）
- 文档总结（
Summary） 解决什么问题？它的not_summarize_threshold参数为什么要设？ - 对接大模型时的证书与协议要配什么？（
ClientParam）
第三段 全景：为什么切分是第一道关
3.1 切分在整条链路里的位置
原始文件 ──①解析──→ 纯文本 ──②切分──→ chunks ──③向量化──→ 向量库
│
┌───────────────────┘
↓
检索时：找到的是 chunk，给模型看的也是 chunk
⭐ 关键：chunk 是 RAG 里的最小单位 —— 检索找到的是它，喂给模型看的也是它。 所以 chunk 的质量 = 检索的上限。
3.2 两个典型失败（都是切分造成的，而且是反向的）
| 失败 | 现象 | 根因 |
|---|---|---|
| 切太碎 | 检索到的片段话说到一半，模型答不全 | chunk 太小，上下文被切断 |
| 切太大 | 检索到的片段里大部分内容不相关，模型答偏 | chunk 太大，噪声太多 |
⭐ 这两件事最坑的地方是：在检索阶段（G5）无论怎么调都调不回来 —— 因为检索的输入就只有这些 chunk，源头不好，后面全是补救。
3.3 官方的切分是怎么做的
官方在《开发流程》里给的说法是「加载和切分」：
初始化文档处理器，用户可以根据上传的文件类型注册相应的文档解析器 和文档切分器……输出为文档切分后的文本 chunks。
两层，各管一段：
| 层 | 管什么 | 决定 |
|---|---|---|
| 文档解析器（Loader） | 把文件读成纯文本 | 支持哪些格式 |
| 文档切分器（Splitter） | 把纯文本切成块 | 每块多大、怎么切 |
⭐ 而且官方还给了一条组合规则（这条最容易踩）：
如果选择
load_image=False，表示只支持文档类型如.docx、.txt、.md等， 具体支持类型为 loader_mng 注册器中 loader 和 splitter 方法支持类型的交集。
「交集」两个字是关键 —— 两个都注册了，格式才生效。
第四段 【如果我来做】从拿到文档到切分定版
4.0 我会按这个顺序做（顺序错了会返工）
① 先摸清文档长什么样（不写代码）
格式是什么 · 多大 · 有没有表格/图片/多级标题 · 是不是扫描件
⚠️ 这一步"以为"最贵：以为都是 docx，结果一堆扫描 PDF
② 定切分策略（按什么切）
按段落？按标题？按固定长度？—— 取决于文档结构
③ 用官方示例值起步（chunk_size=750, chunk_overlap=150）
⚠️ 别一上来自己拍脑袋定参数 —— 先用官方给的那组做基线
④ 灌一小批进去（一个部门、一份文档、10 个问题）
不做全量！全量灌完再发现问题，改一次要重灌一遍
⑤ 用同一组问题测前后效果（这才是"切得对不对"的唯一判据）
⚠️ 不是看"代码跑通没有"，是看"该找到的找到了没有"
⑥ 调参数（按失败现象调，不是瞎调）
答不全 → 调大 chunk_size 或 overlap；答偏 → 调小 chunk_size
⑦ 定版并记录（参数 + 文档类型 + 测试结果）
换文档类型要重新试，不要以为是通用参数
⑧ 诚实（官方给的是示例值，不是最优值；你的最优值只能试出来）
⭐ 这个顺序里最容易被跳过的是 ① 和 ⑤： - ①：不摸文档结构就定策略，切出来一堆断句； - ⑤：用"代码没报错"当验收 —— 而 chunk 数不为 0 只说明切了，不说明切对了。
4.1 第 ① 步：先摸清文档长什么样
先看格式和数量（不用写代码）：
命令 find <文档目录> -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
含义：统计目录下各类扩展名各有多少个文件 —— 一眼看出"都是 docx 还是有混杂格式" 拆解：
find（找文件）＋-type f（只要普通文件）＋|（管道）sed 's/.*\.//'（把路径替换成只剩扩展名）＋sort（排序）＋uniq -c（去重计数）＋sort -rn（按数量倒序） 用法：直接执行（把<文档目录>换成实际路径） 期望：输出形如128 docx/43 pdf/12 xlsx不过会怎样：输出为空 → 路径不对或真没文件； ⚠️ 出现png/jpg→ 说明有图片，后面要走load_image那条路（见 5.3）
命令 du -sh <文档目录>
含义：看文档总体积（决定灌库要不要分批） 拆解：
du（disk usage，统计占用）＋-s（summary，只给总计）＋-h（人类可读单位） 用法：du -sh /path/to/docs期望：打印总大小，如1.2G不过会怎样：报路径不存在 → 先确认挂载盘在不在（服务器配置那步查过df -h） ⭐ 为什么要看：灌库是有时间的，体积大就要规划"分几批、每批多少"
然后人工抽看三份文档（这一步没有命令能替代）：
| 看什么 | 为什么重要 |
|---|---|
| 有没有多级标题 | 决定能不能按标题切（按标题切最符合语义） |
| 有没有表格 | 表格被当纯文本读会丢失行列关系 |
| 是不是扫描件 | 扫描件里的文字是图片，必须走 OCR，不能直接当文本读 |
| 有没有长长的代码/日志块 | 这类内容按固定长度切会把一条命令切成两半 |
4.2 第 ③ 步：用官方示例值起步
官方给的真实参数（来自《文档总结》的调用示例）：
RecursiveCharacterTextSplitter(chunk_size=750, chunk_overlap=150)
这两个参数分别控制什么：
| 参数 | 控制 | 调大的后果 | 调小的后果 |
|---|---|---|---|
chunk_size |
每块最多多长 | 上下文全，但噪声多、向量化慢 | 精准，但话容易被切断 |
chunk_overlap |
相邻两块重叠多长 | 减少"话被切断"，但存储和检索都会重复 | 省空间，但跨块信息会丢 |
⭐ 官方的 750/150 是什么定位： 它是一组"能跑通的示例值"，不是"官方推荐最优值"。 具体怎么定，要用你自己的文档试（第 ⑤ 步）。
⚠️ 但有一条经验值得先记住：
chunk_overlap 通常设成 chunk_size 的 10%–25% ——
官方示例里 150/750 正好是 20%，这个比例可以作为起点。
4.3 第 ⑤ 步：用同一组问题测前后效果（这是唯一的判据）
⭐ 测法：准备 10 个"答案一定能在这份文档里找到"的问题，然后看：
| 现象 | 说明什么 | 往哪调 |
|---|---|---|
| 问题 A 的答案查不到 | 那段内容可能被切碎了 | 调大 chunk_size 或 chunk_overlap |
| 查到了，但答案不完整 | 话被切断 | 调大 chunk_overlap |
| 查到了，但答偏 | chunk 里无关内容太多 | 调小 chunk_size |
| 10 个问题只对 3 个 | 整体策略不对（不该按长度切） | 回第 ② 步，改按标题/段落切 |
| 10 个问题都对 | 这组参数可用 | 定版，记录下来 |
⚠️ 一个必做的对照：同一组问题，用不同参数各跑一遍 —— 只跑一次得到的"看起来还行"，证明不了什么。
4.4 第 ⑦ 步：定版并记录
切分是要"定版"的 —— 因为换了参数等于换了整个库 ✗（chunk 变了，向量也要重算）。
定版记录表（我会留这份）：
| 项 | 内容 |
|---|---|
| 文档类型 | 制度文件 / 技术手册 / 会议纪要 … |
| 切分策略 | 按长度 / 按标题 / 按段落 |
chunk_size |
定版值 |
chunk_overlap |
定版值 |
| 测试问题数 | 如 10 个 |
| 命中数 | 如 9/10 |
| 未命中的那个 | 是什么问题、为什么（这一栏最值钱） |
⭐ "未命中的那个"最值钱：它告诉你这套参数的边界在哪 —— 下次遇到同类问题，你就知道该往哪调。
第五段 逐件拆开：解析器、切分器、文档总结
5.1 文档解析器（Loader）：按扩展名注册
from mx_rag.document import LoaderMng
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"])
官方说明支持的类型：
支持的文档类型包括 Docx、Excel、Pdf、PowerPoint 等。
⭐ 一个很实用的写法：单个 Loader 可以直接实例化（官方《文档总结》示例里的用法）：
from mx_rag.document.loader import DocxLoader
loader = DocxLoader("/workspace/MindIE.docx")
docs = loader.load_and_split(RecursiveCharacterTextSplitter(chunk_size=750, chunk_overlap=150))
两种用法的区别：
| 用法 | 什么时候用 |
|---|---|
LoaderMng 注册 |
批量灌库时（按扩展名自动选解析器） |
| 单个 Loader 直接实例化 | 调参/试效果时（拿一份文档反复试切分） |
⭐ 调切分参数时用第二种 —— 不要每次都建整个库，拿一份文档反复试快得多。
5.2 文档切分器（Splitter）：也要按扩展名注册
from langchain.text_splitter import RecursiveCharacterTextSplitter
loader_mng.register_splitter(RecursiveCharacterTextSplitter, [".docx", ".pdf", ".xlsx"])
⭐ 两个注册是分开的，别混：
| 方法 | 注册什么 | 决定 |
|---|---|---|
register_loader |
怎么把文件读成文本 | 支持哪些格式 |
register_splitter |
怎么把文本切成块 | 用哪个切分策略、对哪些格式生效 |
⚠️ 官方那条"交集"规则再引一次：
如果选择
load_image=False……具体支持类型为 loader_mng 注册器中 loader 和 splitter 方法支持类型的交集。
翻译：只注册 loader 不注册 splitter，文件读进来了也切不成 chunk。
注册时两个列表要对齐（示例里 [".docx", ".pdf", ".xlsx"] 两边是一样的）。
5.3 图片与多模态：load_image 是"二选一"不是"叠加"
官方说明（全文）：
load_image：是否支持图片类型文件，默认为False。 如果选择False，表示只支持文档类型如.docx、.txt、.md等， 具体支持类型为 loader_mng 注册器中 loader 和 splitter 方法支持类型的交集。 如果选择True表示只支持图片类型，支持的范围仅限于 loader_mng 注册器中 loader 方法支持的类型与[".jpg", ".png"]的交集。
⚠️ 两个容易搞混的点：
True表示"只支持图片"，不是"文档 + 图片" —— 它是二选一；- 官方配套提醒：
当支持文档类型的解析时，对应的
embed_func嵌入函数应该支持对应文档类型； 当支持图片类型的解析时，对应的embed_func也应该支持图片类型，否则会出现错误。
翻译：要能读图，得先有一个"能理解图片"的 embedding 模型 ——
不是把 load_image 改成 True 就能读图了。
5.4 文档总结（Summary）：为超长文档准备的一层
官方功能描述：
该类实现了对文档提取总结内容。
函数原型：
from mx_rag.summary import Summary
Summary(llm, llm_config)
| 参数 | 类型 | 必选 | 官方说明 |
|---|---|---|---|
llm |
Text2TextLLM | 必选 | 大模型对象实例 |
llm_config |
LLMParameterConfig | 可选 | 调用大模型参数，默认 temperature 为 0.5，top_p 为 0.95 |
官方调用示例（完整）：
from langchain_text_splitters import RecursiveCharacterTextSplitter
from mx_rag.document.loader import DocxLoader
from mx_rag.llm import Text2TextLLM
from mx_rag.summary import Summary
from mx_rag.utils import ClientParam
client_param = ClientParam(ca_file="/path/to/ca.crt")
llm = Text2TextLLM(base_url="https://ip:port/v1/chat/completions",
model_name="qianwen-7b", client_param=client_param)
loader = DocxLoader("/workspace/MindIE.docx")
docs = loader.load_and_split(RecursiveCharacterTextSplitter(chunk_size=750, chunk_overlap=150))
summary = Summary(llm=llm)
# 调用 summarize 方法
sub_summaries = summary.summarize([doc.page_content for doc in docs])
# 调用 merge_text_summarize 方法
res = summary.merge_text_summarize(sub_summaries)
print(res)
⭐ 这里能看出一个完整流程：
DocxLoader 读文件 → load_and_split(切分器) 切成 docs → 取每个 doc 的 page_content →
summarize 分别总结 → merge_text_summarize 把分段总结合并成一份完整总结。
它解决什么问题：文档太长，一次塞不进模型 —— 所以先分段总结，再合并总结（两段式），这是处理超长文档的通用做法。
5.5 not_summarize_threshold：一个很实用但要设对的参数
官方说明（原文）：
not_summarize_threshold：int，可选。单次总结时由于给定的文本太短， 大模型无法进行总结或总结错误，此值设定需要大模型进行总结的文本长度阈值， 如果给定的文本内容小于等于not_summarize_threshold，不调用大模型进行总结操作， 总结内容为文本原始内容，默认值为 30，取值范围 (0, 1024*1024]。
翻译成人话：
太短的文本别让模型总结了 —— 模型对短文本总结往往"总结出不存在的东西"， 所以短于阈值就直接用原文。
⭐ 为什么这是个好设计：它承认了模型的弱点 —— 不是所有东西都该交给模型，该直出原文的时候就直出。
summarize 的其他参数（官方）：
| 参数 | 类型 | 官方约束 |
|---|---|---|
texts |
List[str] |
所有文本长度和 (0, 1024×1024]；列表长度 (0, 1024] |
not_summarize_threshold |
int | 默认 30，取值 (0, 1024×1024] |
prompt |
— | 提示词 |
⚠️ 那两条取值范围要记住 —— 一次塞太多文本会被拒（长度和上限约 100 万字符，列表最多 1024 条）。 长文档要分批总结，再 merge。
5.6 对接大模型的两个基础类（ClientParam / Lang）
ClientParam：对接服务端的配置参数
from mx_rag.utils import ClientParam
ClientParam(use_http, ca_file, crl_file, timeout, response_limit_size)
| 参数 | 类型 | 官方说明 |
|---|---|---|
use_http |
bool | 默认 False（即使用 HTTPS 协议）。官方提示：HTTP 协议存在安全风险，建议使用 HTTPS 安全协议 |
ca_file |
str | 对接服务端根证书。路径长度 ≤1024，不能为软链接且不允许存在 ..，文件大小 ≤1M |
crl_file |
str | 对接服务端吊销列表。约束同上 |
timeout |
int | 响应超时，取值 (0, 600]，默认 60 秒 |
response_limit_size |
int | 客户端接受响应的最大字节，取值 (0, 10MB]，默认 1M |
⭐ 官方的一条 NOTE（很关键）：
创建客户端时，判断
use_http，如果启用 HTTPS 时，ca_file是必传参数； 如果只传入了ca_file参数，创建单向认证的 TLS/SSL context。
⚠️ 这条对私有化项目很重要：内网部署也不是"就不用证书了" ——
HTTPS 是默认项，ca_file 在 HTTPS 下是必传的。
Lang：语言枚举
语言枚举类。当前支持两种语言，包括英文（EN）和中文（CH）。
⭐ 处理中文文档时记得设成 CH —— 这是中文知识库的一个基础开关。
完整调用示例（官方）：
from mx_rag.llm import Text2TextLLM, LLMParameterConfig
from mx_rag.utils import ClientParam
llm = Text2TextLLM(base_url="https://{ip}:{port}/v1/chat/completions",
model_name="qianwen-7b",
llm_config=LLMParameterConfig(max_tokens=512),
client_param=ClientParam(ca_file="/path/to/ca.crt"))
res = llm.chat("请介绍下北京")
print(res)
for res in llm.chat_streamly("请介绍下北京"):
print(res)
注意两个方法：chat（一次性返回）与 chat_streamly（流式返回 —— 用于逐字显示的场景）。
第六段 判据 / 验收
本段的硬要求：看内容，不看报错。
| # | 判据 | 怎么验 | 不过说明 |
|---|---|---|---|
| ① | 格式都认 | 摸底的每种格式各拿一份试灌，看失败列表 | loader/splitter 注册不齐（交集规则） |
| ② | chunk 数合理 | 看 chunk 总数 | 为 0 → 切分器没生效；异常多 → chunk_size 太小 |
| ③ | chunk 内容完整 | 抽 5 块人工读一遍 | 话说到一半 → chunk_size/chunk_overlap 太小 |
| ④ | 该找到的找得到 | 10 个"答案在文档里"的问题 | 命中率低 → 回第 ② 步改策略 |
| ⑤ | 答案完整 | 命中的问题里，答案有没有缺 | 缺 → 调大 chunk_overlap |
| ⑥ | 答案不跑偏 | 返回的 chunk 里相关内容占比 | 偏低 → 调小 chunk_size |
| ⑦ | 参数定版并记录 | 有定版记录表 | 不定版 = 下次换人做要重来 |
⭐ 判据 ③ 是最容易被跳过、也最有效的： 不用任何工具，打开几十块 chunk 人工读一遍 —— 切碎了、切断了、表格变乱了，肉眼一看就知道。
第七段 出问题怎么查
排查顺序：先确认"文档能不能读"，再看"切得对不对"，最后才怪检索。
| 你看到的现象 | 先归到哪一步 | 具体动作 |
|---|---|---|
| 某格式全部灌失败 | 解析器注册 | 查该格式的 loader 和 splitter 是否都注册了（交集规则） |
.docx 能进、.pdf 不能 |
解析器注册 | .pdf 漏注册了某一边 |
| chunk 数是 0 | 切分 | 切分器没注册，或文件是空的/加密的 |
| chunk 特别多且都很短 | 参数 | chunk_size 太小 |
| chunk 里话说到一半 | 参数 | chunk_overlap 太小 |
| 表格内容乱掉 | 解析 | 表格被当纯文本读了（行列关系丢失） |
| 扫描件里一个字都读不到 | 解析 | 扫描件是图片，要走 OCR/图片那条路（load_image） |
加了 load_image=True 还是读不了图 |
模型 | embedding 模型不支持图片（官方明说两者要配套） |
| 中文检索效果明显差 | 语言 | Lang 没设成 CH |
| 调大模型时报连接/证书错 | 对接 | HTTPS 下 ca_file 是必传的（官方 NOTE） |
| 总结报长度超限 | 总结 | texts 的长度和/列表长度超了官方范围 → 分批总结再 merge |
| 短文本总结结果很怪 | 总结 | not_summarize_threshold 设小了 → 调大，让短文本直接返回原文 |
第八段 常见报错清单
⚠️ 官方的 RAG SDK 文档没有单独的"报错码表" —— 本表按现象组织，查其他报错用官方案例库按稳定特征词检索：
https://www.hiascend.com/document/caselibrary
| 现象 | 先查什么 |
|---|---|
| 文件加载失败 | 格式在不在支持列表（Docx、Excel、Pdf、PowerPoint 等）；两类注册是否齐全 |
| 切分结果异常（一块巨大 / 全是碎片） | chunk_size / chunk_overlap 取值；这一步决定后面所有效果 |
| 图片文件解析报错 | load_image 是二选一；且 embed_func 要支持图片类型，否则会出错 |
| 大模型调用报证书相关错误 | HTTPS 下 ca_file 必传；路径不能是软链接、不能含 ..、≤1M |
| 大模型调用超时 | timeout 默认 60 秒，取值 (0,600] |
| 响应被截断 | response_limit_size 默认 1M，取值 (0,10MB] |
summarize 报文本过长 |
texts 长度和上限 1024×1024、列表长度上限 1024 → 分批 |
| 短文本总结结果失真 | not_summarize_threshold 默认 30 → 调大 |
第九段 小结 + 钩子 + 自测
三句话记住本课
- 切分是"一次做完、后面全受影响"的一步 —— 切太碎答不全，切太大答偏，而且检索阶段救不回来。
- 两个注册器各管一段，实际生效的是交集 ——
register_loader管读，register_splitter管切，少一个格式就不生效。 - 官方给的
chunk_size=750, chunk_overlap=150是示例值不是最优值 —— 必须用你自己的文档、自己的问题试出来，并定版记录。
自测（不看上文）
chunk_size和chunk_overlap分别控制什么？调大调小各会怎样？- 为什么只注册 loader 不注册 splitter，文件还是进不去库？
load_image=True是"文档+图片都支持"吗？not_summarize_threshold为什么要存在？设小了会怎样？- 内网部署还需要配
ca_file吗？为什么？ - 怎么判断"切分切对了"？（提示：不是看代码跑没跑通）
钩子：下一课
文档进了库、切分也定版了 —— 但你可能发现：
用文档里的原句问，查得到；用自己的话说，查不到。 同一份文档里的两个相似段落，总是那一片被查出来，另一片从来不露面。
这就是检索阶段的问题了，也是 RAG 效果差异最大的地方。
G5 会把官方给的三条路拆开讲： 查询改写检索（检索前）／ 近似检索（检索时）／ reranker 精排（检索后） —— 那时候我们再回到这套代码，把三个调点一个一个加上去。
附录 A 官方出处
| # | 内容 | 官方出处 |
|---|---|---|
| 1 | 加载和切分：初始化文档处理器，按文件类型注册相应的文档解析器和文档切分器，支持类型包括 Docx、Excel、Pdf、PowerPoint 等，输出为文档切分后的文本 chunks | MindSDK 26.1.0《RAG SDK · 开发流程》→ zh/mindsdk/2610/rag/ragug/docs/zh/user_guide.md |
| 2 | 交集规则：load_image=False 时，具体支持类型为 loader_mng 注册器中 loader 和 splitter 方法支持类型的交集 |
MindSDK 26.1.0《RAG SDK · 知识管理 · 接口参考》→ …/docs/zh/api/knowledge_management.md |
| 3 | load_image 全文说明：默认 False；False 时支持文档类型；True 时仅支持图片，范围为 loader 支持类型与 [".jpg",".png"] 的交集 |
同上 |
| 4 | 配套提醒：文档解析时 embed_func 应支持该文档类型；图片解析时应支持图片类型，否则会出错 |
同上 |
| 5 | 文档解析可扩展：可使用 langchain 的文档解析/切分 API，或基于 langchain 自定义 | MindSDK 26.1.0《RAG SDK · 开发流程》 |
| 6 | Summary(llm, llm_config)：实现对文档提取总结内容；llm 必选（Text2TextLLM 对象）；llm_config 可选，默认 temperature=0.5、top_p=0.95 |
MindSDK 26.1.0《RAG SDK · 文档总结 · 接口参考》→ …/docs/zh/api/document_summary.md |
| 7 | 官方调用示例（含 DocxLoader("/workspace/MindIE.docx")、load_and_split(RecursiveCharacterTextSplitter(chunk_size=750, chunk_overlap=150))、summarize、merge_text_summarize） |
同上 |
| 8 | summarize(texts, not_summarize_threshold, prompt)：texts 为 List[str]，所有文本长度和 (0, 1024×1024]、列表长度 (0,1024]；not_summarize_threshold 默认 30，给定文本长度 ≤ 该阈值时不调用大模型总结，总结内容为文本原始内容 |
同上 |
| 9 | ClientParam(use_http, ca_file, crl_file, timeout, response_limit_size)：use_http 默认 False（即 HTTPS），官方提示 HTTP 有安全风险建议用 HTTPS；ca_file/crl_file 路径长度 ≤1024、不能软链接、不许 ..、≤1M；timeout 默认 60 秒取值 (0,600]；response_limit_size 默认 1M 取值 (0,10MB] |
MindSDK 26.1.0《RAG SDK · 通用 · 接口参考》→ …/docs/zh/api/universal_api.md |
| 10 | NOTE：启用 HTTPS 时 ca_file 是必传参数；只传 ca_file 创建单向认证的 TLS/SSL context |
同上 |
| 11 | Lang 语言枚举：支持 EN（英文）/ CH（中文） |
同上 |
| 12 | Text2TextLLM 调用示例：llm.chat(...) 与 llm.chat_streamly(...)（流式） |
同上 |
| 13 | 检索的三个调点（查询改写检索／近似检索／reranker 精排） | 见 G5（《检索》《排序》接口参考） |
⚠️ 属于本文「归纳/实践」而非官方原文的部分，已明确标注：
- 4.1 的三份抽看法、4.2 的「chunk_overlap 取 chunk_size 的 10%–25%」经验比例、
4.3 的测试方法与 4.4 的定版记录表 —— 官方未给成文规范，
官方只给了 chunk_size=750, chunk_overlap=150 这一组示例值；
- 第六段判据表与第八段报错表属实践归纳；
- 5.1 表格里「批量灌库用 LoaderMng / 调参用单个 Loader」的分工，是用法归纳。
附录 B 命令详解
G3 已解释过的命令（
chmod、pip3 install -r、source、python3 -c、ls等）此处不重复。
命令 find <目录> -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn
含义：统计目录下各类扩展名各有多少个文件 —— 一眼看出文档格式分布 拆解：
find <目录> -type f（找出所有普通文件）|（管道：把左边输出交给右边）sed 's/.*\.//'（把每行的路径替换成只剩扩展名）sort（排序）→uniq -c（去重并计数）→sort -rn（按数量倒序） 用法：find /path/to/docs -type f | sed 's/.*\.//' | sort | uniq -c | sort -rn期望：输出形如128 docx／43 pdf／12 xlsx不过会怎样：输出为空 → 路径不对或真没文件； 出现png/jpg→ 后面要走load_image那条路
命令 du -sh <目录>
含义：看文档总体积（决定灌库要不要分批） 拆解：
du（disk usage，统计占用）＋-s（summary，只给总计）＋-h（人类可读单位） 用法：du -sh /path/to/docs期望：打印总大小，如1.2G不过会怎样：报路径不存在 → 先确认挂载盘在不在（df -h） ⭐ 灌库是有时间的，体积大就要规划分批
命令 head -c 2000 <文件>
含义：看文件开头 2000 字节 —— 快速判断"是不是扫描件/乱码" 拆解：
head（取开头）＋-c 2000（2000 字节） 用法：head -c 2000 /path/to/doc.txt期望：能看到可读的文字 不过会怎样：一片乱码 → 可能是二进制/压缩/加密文件；head看到的是乱码，这属正常 —— 要判断扫描件得用 PDF 工具看 ⚠️ 这条只适用于txt/md这类纯文本，二进制格式别用它下结论