手头只有一份66页的工业库却把它做成了一条完整的知识库Agent主线。这件事做完以后我反而把知识库Agent这件事想明白了——它能不能跑起来跟文档数量多少没有决定关系而是看你能不能把每一个知识块都处理到位。这里说的工业库不是某种数据库产品而是工业现场最常见的文档集合设备参数手册、标准操作规程、报警响应预案、安全注意事项杂七杂八凑一起就66页。系统最终能稳定回答设备参数查询、异常处置步骤、标准依据核对这些高频问题每个答案还能给出文档页码出处。这篇文章就把这条主线的完整拆解过程写出来给想用小体量知识库起步做Agent的人一个参照。1. 项目解剖66页工业库为何能长成Agent主线1.1 这66页工业库到底是什么我先说清楚这份66页的底料长什么样因为它和网上常见的“通用知识库”差别很大。它不是一个单一的PDF文件而是好几类文档拼起来的一是核心设备的参数表和技术手册选页里面全是型号、额定电压、功率、压力范围这类数值二是一套标准操作流程也就是工业现场常说的SOP规定某个操作按什么顺序做、每步注意什么三是报警值和异常现象对照表比如哪个报警代码对应什么故障、该怎么处置四是安全注意事项和应急响应预案。这些内容在主题上高度强相关都在回答同一个车间里操作人员会遇到的日常问题但格式完全不统一有横版表格、有带层级编号的条款、有流程图截图。工业库的特点就是“数字化程度低但专业要求极高”大量缩写、中英混排、数值范围、版本号而且知识更新的节奏说变就变——设备一改型、标准一改版旧文档就得下线。更关键的是答错代价不同。通用知识库答错一句也就是用户觉得不准工业知识库要是答错一个报警阈值操作工照着回答去处理设备后果可能是设备损坏甚至安全事故。所以这个项目从一开始就定了底线每个回答必须有出处没有出处的回答宁可不说。这也决定了后面所有技术选型都围绕“可溯源、可验证、可更新”来展开。1.2 为什么用知识库Agent而不是“让大模型背下全本”有人会问66页内容这么少直接把全文塞给大模型让它回答不就行了我分别解释一下为什么三条路都没走。第一条路是微调。让大模型把这66页背下来听起来很诱人但工业文档的高频操作是“改版”今天参数表更新一页明天SOP修订一条每次改动都重新微调一轮时间和算力成本都不可接受。而且微调后的模型是黑盒回答没有出处运维人员根本不敢拿来做操作依据。66页的数据量对于微调来说也远远不够很容易学歪。第二条路是长上下文直读。把66页文本全部塞进上下文窗口模型确实能看到但有两个问题一是长篇文档中的具体数值会被上下文稀释提问“3号空压机排气压力上限是多少”模型很可能把4号设备的数据混进来二是没有检索定位能力每次回答都要重新处理全文延迟高也无法指出“依据在第34页”。第三条路就是知识库Agent也就是我这篇文章说的主线。它本质上是一个“检索增强生成”的框架但比普通的单次RAG多了一层Agent能力。普通RAG是“用户问一句、检索一次、生成一次”工业场景下的真实提问往往一句话里藏着好几个子问题。比如“空压机排气温度高报警到底怎么处置”这个问题实际上需要三步先确认空压机型号对应的正常温度范围和报警阈值再查对应型号的处置步骤最后补充安全注意事项。单次检索很可能只命中其中一段剩下的靠模型瞎猜。知识库Agent做的事情就是把“一次提问、多次检索、按需汇总”变成一套可控流程让问题拆解、检索调用、答案验证每个环节都透明可见。2. 工业文档的知识化加工从66页到可检索的知识块2.1 文档清洗有三件事必须亲自做知识库Agent的地基是文档本身。66页文档不多但这恰恰是优势——我有精力把每一页都人工过一遍。清洗阶段有三件事偷懒不得。第一件事是解析与转文本。PDF用pdfplumber或PyMuPDF转成文本横版表格直接用文本解析很容易错乱需要专门的表格抽取工具。我那份文档里有一页是设备参数总表直接用通用解析器抽出来列和行全错位单位也丢了最后是用表格识别工具加人工校对才恢复原样。工业文档里的数字和计量单位是生命线这里出错后面检索做得再好都是白搭。第二件事是清理噪音。页眉页脚、目录页码、水印、残留换行、制表符这些都会污染切块结果。尤其是OCR出来的文档错别字要逐页抽查我曾经遇到过“MPa”被识别成“M Pa”一个空格之差检索时关键词完全匹配不上。这种错误靠模型自动修是修不干净的必须人工盯一遍关键数值和单位。第三件事是结构还原。工业文档普遍有清晰的标题层级和编号体系比如“3.2.1 滤芯更换步骤”。要把这些层级关系提取出来构建成“文件—章节—小节—段落”的树状结构。这一步有两层价值一是后面检索时可以按章节做粗过滤把搜索范围大幅缩小二是每一段文本都带着章节路径回答时引用位置就能写到“第3.2.1节”这种级别而不是笼统说“某个文档里提到了”。清洗完成之后要给每个知识块设计元数据。我的做法是每个块固定挂六个字段来源文件名、版本号、章节路径、页码、内容类型正文/表格/步骤、创建时间。这些字段决定了后续检索过滤、版本隔离、引用格式能否落地越早定越好。等索引建完再回头补元数据等于重做一遍。2.2 切块策略三个参数如何定切块是知识库Agent里最容易被低估的环节。很多人以为随便按固定字数切就行实际上一旦切错后面所有环节都在错误的数据上做文章效果怎么调都上不去。先解释为什么要切块。Embedding模型对输入长度有限制当前常用的中文向量模型一般在8192个token以内但即使没超过上限太长的文本经过向量化后语义会被“平均”稀释——一段512字的文本里可能包含三个不同主题向量最终呈现的是三个主题混在一起的模糊语义检索时哪个都命不准。检索的目标是“返回和问题最相关的局部片段”不是“返回包含答案的整个章节”所以切块粒度直接决定召回质量。我用的切块策略可以总结为“结构优先、定长兜底”。具体分四步用文档的标题层级先把整份文档切成大块保证同一个大块内主题一致。大块内部如果超过阈值再按自然段落分割。段落仍然超长时用定长滑动窗口兜底。相邻块之间设置一定重叠防止上下文在切缝处断裂。三个核心参数里chunk_size和overlap是绕不开的。中文工业文档我建议以“字符数”而不是token数来衡量中文字符和token的比例大约是1:1.5直接按token切容易把一句话拦腰截断。我的参数范围供参考chunk_size取512到768字符overlap取64到128字符。块太大会混入无关信息块太小则语义不完整比如“禁止在未泄压状态下拆卸”本来是一个完整的安全警告切成“禁止在未泄压”和“状态下拆卸”两块语义就废了。另一个关键点是表格的切法。工业文档里的表格是“另一条主线”不能和普通文本混在一起切。一个表格应该作为一个整体块保留包括表头、单位和备注说明如果表格行数太多必须按行切每一行都要冗余携带表头信息。这个做法反直觉但非常有用否则“22.8”这个数字脱离列名和单位之后谁都不知道它是什么。2.3 向量索引与检索接口选型清洗和切块完成后下一步就是把知识块向量化并建立索引。向量模型我选了BGE-M3中文效果好而且是开源模型支持稠密向量和稀疏向量两种表示后面做混合检索时同一个模型就能输出两种索引省了不少事。如果环境受限、下载不了大模型退而求其次用text2vec-base-chinese也能跑起来只是准确率会打些折扣。66页文档切出来的知识块数量很小大概也就几百个块用FAISS内存索引完全够用连独立的向量数据库服务都不用部署。但我还是把检索接口封装成了一个独立服务。这么做的原因很朴素项目起步只有66页后面一定会扩展到更多设备手册如果一开始就把索引逻辑写死在业务代码里后面扩展时就得重构。把检索抽象成独立接口后续换成Milvus或者Qdrant只需要替换底层实现上层Agent的代码一行都不用动。索引建设的代码逻辑大致是这样的from pymupdf import open as pdf_open from bge_m3 import BGEM3EmbeddingModel doc pdf_open(industrial_lib_v2.pdf) blocks extract_structured_blocks(doc) # 返回带元数据的知识块列表 model BGEM3EmbeddingModel(model_nameBAAI/bge-m3) chunk_texts [b[text] for b in blocks] embeddings model.encode(chunk_texts)[dense_vecs] # 每个块保存文本和元数据 for idx, block in enumerate(blocks): block[embedding] embeddings[idx] block[id] fblock_{idx} # 写入FAISS索引 import faiss import numpy as np dim embeddings.shape[1] index faiss.IndexFlatIP(dim) faiss.normalize_L2(embeddings) index.add(embeddings) faiss.write_index(index, industrial_blocks.index)要强调的是Embedding模型选型不是一劳永逸的。换了模型后必须重建索引否则新旧向量不在同一个语义空间里检索结果会变得毫无意义。踩过一次坑之后我把索引重建做成了流水线上的固定步骤每次更新Embedding版本都跑一遍全量重建。3. 检索与生成的Agent闭环核心实现拆解3.1 混合检索向量不够BM25兜底工业库检索有个很实际的痛点纯向量检索对专有名词和缩写不友好。像“SOP”“PLC”“HVAC”这种缩写以及“A/B-3000”这种带特殊符号的型号Embedding模型经常把它们当成普通词组导致语义相近的段落凑上来精确匹配的段落反而排到后面去。解决办法是混合检索。向量检索负责捕捉语义相关性BM25这类稀疏检索负责精确匹配专有名词最后把两路结果融合排序。融合用的算法是RRFReciprocal Rank Fusion原理不复杂每个文档在两路结果里都有一个排名融合分数就是每个排名倒数之和排名越靠前贡献越大。这样语义和关键词两条线索都能发挥各自优势不会被某一方的偏差带偏。核心逻辑长这样from rank_bm25 import BM25Okapi # 用BGE-M3的sparse_vecs同时做BM25式匹配 bm25 BM25Okapi(tokenized_chunks) def hybrid_search(query, top_k5): query_vec embedding_model.encode([query])[dense_vecs] dense_scores, dense_indices faiss_index.search(query_vec, top_k) bm25_scores bm25.get_scores(tokenize(query)) top_bm25 sorted(range(len(bm25_scores)), keylambda i: bm25_scores[i], reverseTrue)[:top_k] # RRF融合 fused {} for rank, idx in enumerate(dense_indices[0]): fused[idx] fused.get(idx, 0) 1 / (60 rank) for rank, idx in enumerate(top_bm25): fused[idx] fused.get(idx, 0) 1 / (60 rank) return sorted(fused.items(), keylambda x: x[1], reverseTrue)[:top_k]实测下来加了BM25混合检索之后像“报警代码E-204”联合“处置建议”这种查询精准命中率提升非常明显。纯向量检索经常把“报警代码”相关的其他段落也排上来但精确带着“E-204”的那一段反而沉在下面。工业文档里大量存在“型号故障”这种组合查询BM25对这类模式就是天然的强项。3.2 Agent如何把“一个难题”拆成“几次查询”知识库Agent和普通RAG最核心的区别在于它把LLM从“直接答题的人”变成了“调度问题的人”。用户提一个复杂问题Agent先判断这个问题需要哪些信息再决定调用几次检索工具最后汇总成答案。我用一个实际例子说明。用户问“空压机排气温度高报警怎么处置”这个问题的正确回答需要三块知识空压机型号对应的排气温度正常范围、报警阈值、对应型号的处置步骤。如果只做一次检索返回的可能是报警处置步骤也可能是参数表里的温度范围反正很难一次拿全。Agent的做法是把一个问题改写成三个子查询子查询一空压机XX型号排气温度报警阈值是多少子查询二排气温度高报警的处置步骤子查询三空压机高温报警的安全注意事项每个子查询单独走一遍检索把三段结果拼接起来再让LLM组织成完整回答。这样每一步检索都是精准的最后给出的答案信息完整、逻辑连贯而不是大段堆砌无关内容。要想让Agent正确地做多步检索关键在于工具定义写得到位。LangChain或自建Agent框架里每个工具有一个descriptionLLM就是靠这个描述来决定何时调用工具的。描述写得太简略比如“知识库检索工具”模型就很容易在第一次检索拿到不相关内容后直接放弃或者反复调用同一个工具碰运气。我会写清楚这个工具能搜什么、什么时候用、返回什么格式。工具定义示意tools [ { name: search_kb, description: 在工业知识库中检索设备参数、操作流程、报警处置、安全注意事项。 当用户问题涉及具体设备型号、数值范围、操作步骤时必须调用此工具。 支持传入关键词组合例如空压机 排气温度 报警阈值。, parameters: {query: string} } ] def agent_loop(user_query, memory): # 1. 判断是否需要拆解子问题 sub_queries plan_subqueries(user_query, memory) # 2. 逐个子查询调用检索工具 contexts [] for sub_q in sub_queries: results search_kb(sub_q, top_k3) contexts.extend(results) # 3. 生成带引用的最终回答 answer generate_with_sources(user_query, contexts) return answer还需要处理多轮对话记忆。工业场景下用户不太会一句话把所有信息说全更常见的是“3号空压机排气温度高报警了怎么办”Agent回答完之后用户接着问“那压力上限呢”。如果不记忆上一轮的设备型号这个问题就失去了主语。我在会话状态里维护了两个变量——“当前设备型号”和“当前讨论故障”每当识别到新的设备型号就更新后续提问如果缺少主语自动从会话状态中补全。这个小功能看着不起眼但操作工用起来会明显觉得“这个机器人是懂上下文的”。3.3 回答纪律提示词里写死的三条底线知识库Agent的LLM生成环节提示词设计不能只考虑“答得准”更要考虑“答得安全”。工业场景下我直接写死了三条纪律。第一条是强制引用。回答中涉及的所有具体参数、步骤、报警代码必须附上引用来源格式为“依据文件名 第X页 第X节”。这不仅是可解释性问题更是合规问题。操作工需要一个可以翻纸质手册复核的答案而不是一个“看起来对但找不到依据”的结论。第二条是找不到就明说。如果检索到的上下文不足以支撑回答模型必须输出“该问题在当前知识库中没有找到明确依据请转人工确认后再执行操作”而不是基于通用知识自行推断。工业领域最大的风险不是“答不上来”而是“答错了还理直气壮”。我把这条写进提示词后无依据乱答的比例大幅下降。第三条是安全操作加现场确认。凡是涉及设备操作、安全阈值、应急处置的回答结尾自动追加一句“具体操作请结合现场设备状态和本地操作规程确认”。这句话不是废话它是在暗示用户系统给出的内容是知识库中的标准规定但现场可能有标准之外的特殊情况操作前必须二次确认。给出一段可以直接参考的回答提示词模板你是一个工业知识库问答助手。请严格遵循以下规则 1. 只依据上下文检索片段回答不得使用训练数据中的通用知识。 2. 回答中涉及参数、报警代码、操作步骤时必须标注引用来源格式为依据文件名 第X页。 3. 如果上下文不足以回答用户问题明确回复“该问题在当前知识库中没有找到明确依据请转人工确认后再执行操作。” 4. 涉及设备操作、安全阈值、应急处置的回答结尾必须追加“具体操作请结合现场设备和本地操作规程确认。” 5. 用简洁的中文回答不要重复问题不要展开与问题无关的内容。这套提示词实际跑下来回答风格变得非常“克制”甚至有时候显得啰嗦但用户接受度反而更高。工业场景的诉求是“我不需要你聪明我需要你靠谱”这三条纪律就是朝着靠谱去的。4. 实测评估与调优从“能用”到“敢用”4.1 三类测试问题与评估指标知识库Agent做出来能不能上线不能靠“感觉还行”必须有一套可量化的评估标准。我把测试问题分成三类每类准备30条。第一类是事实查询型问的是“XX设备额定功率是多少”“滤芯型号是多少”。这类问题答案是唯一的检索定位精准度就是核心指标。第二类是操作流程型问的是“更换滤芯的具体步骤是什么”“多久做一次保养”。这类问题答案跨度大往往分布在好几页考察的是检索结果覆盖是否完整。第三类是故障处置型问的是“排气温度高报警怎么处置”“油压过低会有什么后果”。这类问题还需要关联安全注意事项考察的是Agent多步检索和信息整合能力。这90条测试问题里有一半来自真实运维群里的历史提问记录另一半是我模拟新人操作工的口头问法。这个做法很关键——如果只靠自己顺着文档猜问题来测试很容易高估系统效果因为猜的问题往往正好落在文档的关键句上。真实问题则五花八门有问“怎么会这样的”、有问“要不要紧的”数据才能暴露系统的短板。评估指标我用四个检索命中率Top3结果里有没有包含关键答案段落、最终答案引用正确率、无依据回答比例越低越好、平均响应时间。检索命中率是基础指标引用正确率决定系统能不能“敢用”无依据回答比例体现安全底线。4.2 调优过程中的参数与结果调优过程有点像一个漏斗每一步都在修上一轮暴露的问题。我把每次改动和效果记录下来方便后面复盘。第一版是纯向量检索chunk_size取1024字符没有重叠没有混合检索。结果检索命中率只有50%出头而且经常出现“文档里明明有答案但系统答不对”的情况。原因很明确块太大一个块里信息太杂向量被稀释没有重叠关键句正好卡在切缝处时就整句丢失。第二版把chunk_size降到768overlap设为96同时把切块方式改成“结构优先、定长兜底”命中率提升到70%左右。这个提升主要靠数据质量和模型没什么关系。第三版最大的变化是表格独立切块、按行切时冗余表头命中率升到80%。到这里基本达到了“能用”的门槛但离“敢用”还差一口气。第四版加入BM25混合检索加RRF融合命中率到了90%左右尤其是故障处置型问题的表现改善明显。第五版加了BGE-Reranker做结果重排把检索出的Top20精排到Top5Top1准确率明显改善最终答案的引用正确率也随之提升。各阶段效果对比如下阶段主要改动检索命中率引用正确率无依据回答比例V1纯向量chunk_size102452%40%22%V2chunk_size768overlap96结构切块70%58%14%V3表格独立切块80%70%9%V4混合检索RRF89%81%6%V5加Rerank精排93%88%3%调优顺序给我的体会是先管数据质量再上重武器。前期最大的提升来自切块方式和表格处理而不是换更大的模型或更复杂的算法。等到数据质量稳定了Rerank这类重型手段才发挥出价值。如果顺序反了数据质量一团糟的时候上Rerank相当于在污水里做精过滤效果有限还浪费算力。5. 踩坑实录知识库Agent最常见的七个问题5.1 检索为空时按什么链路排查知识库Agent上线后最让人头疼的问题就是“检索返回为空”或“答非所问”表现形式五花八门但排查逻辑是有规律的按链路一步步走基本都能定位。排查顺序第一检查Embedding是否成功有没有特殊字符导致文本被截断第二检查切块是否存在过短或语义不完整的情况比如一个块只有十几个字符向量化后基本没有语义信息第三检查索引里有没有该文档的条目更新文档后漏了重建索引是最常见的原因第四检查混合检索的融合权重看是不是某一方分数过高压掉了另一方。一个实用技巧上线后在日志里把每次检索的“Top5命中片段文本相似度分数”全部打出来。肉眼扫一遍日志就能判断问题出在切块、向量还是融合环节。不要靠猜靠日志里的实际返回内容定位。5.2 表格被“切碎”后的修复方案我踩过最深的一个坑就是报警代码表被普通切块方式切碎。那张表有三列报警代码、含义、处置建议。用普通段落切法表头单独成块数据行单独成块嵌入检索时表头和数据行完全分离。用户搜“E-204报警怎么处置”时检索到报警代码“E-204”那个块但处置建议字段已经跑到下一个块里了导致答案缺一半。修复方案就是我前面说的表格独立通道一个表格作为一个整体块大表按行切分时每一行都冗余携带表头列名每个表格块的类型标记为“table”检索时优先匹配类型为“table”的块把表头行和命中行拼成完整句子后再交给LLM。这个方案对所有以数值、字段为核心的工业文档都适用。5.3 版本污染新旧文档打架怎么治理工业文档最频繁的变更就是版本更新。有一次我把新版设备手册索引进去之后发现同一个问题有时返回新参数、有时返回旧参数原因是旧版文档还留在索引里。向量检索按相似度排序新旧两块文本相似度都很高模型也不清楚该用哪个版本。治理方案有两个一是在元数据里加版本号检索时过滤条件只保留当前有效版本二是更新文档时对同一“来源文件章节路径”的旧块做标记下线不直接物理删除方便回溯历史。每次版本更新后我会人工抽查20个典型问题确保新旧文档切换后没有交叉污染。5.4 常见问题速查表最后整理一张速查表把我在这个项目里遇到频率最高的七类问题汇总在一起方便后面排查时快速对照。现象可能原因解法检索结果为空文档未重建索引、Embedding失败检查索引版本查看切块文本是否完整检索命中但答案不对切块太大导致语义混杂调低chunk_size增加overlap答案像是编的提示词未强制引用、上下文不足加引用约束无依据时明确拒绝回答表格数据残缺表格被当普通文本切碎表格独立切块按行切时冗余表头多轮对话丢失上下文会话状态未维护设备型号增加会话变量记录设备型号和故障主题新旧文档答案打架旧版本未下线元数据版本过滤更新后人工抽查专有名词检索不准Embedding不认识缩写/型号加BM25混合检索建立同义词扩展表最后说一点个人体会。做完这个项目我最深的感受是知识库Agent的主线并不取决于初始数据是66页还是66万页而是取决于你是否愿意把每一份文档当成知识资产来加工。66页的好处恰恰在于体量小你有能力逐页阅读、逐表校对把每个知识块都亲手处理到位——这种精细度在大型自动化流水线上反而不容易做到。如果你手头也有一堆不起眼的技术文档、操作手册、规范规程别等着数据攒齐了再动手。先拿这份小家底把闭环跑通后面每扩展一份文档都只是沿着这条主线再加一个分支而已。 66页工业文档打造知识库Agent主线：从切块到混合检索全拆解
手头只有一份66页的工业库却把它做成了一条完整的知识库Agent主线。这件事做完以后我反而把知识库Agent这件事想明白了——它能不能跑起来跟文档数量多少没有决定关系而是看你能不能把每一个知识块都处理到位。这里说的工业库不是某种数据库产品而是工业现场最常见的文档集合设备参数手册、标准操作规程、报警响应预案、安全注意事项杂七杂八凑一起就66页。系统最终能稳定回答设备参数查询、异常处置步骤、标准依据核对这些高频问题每个答案还能给出文档页码出处。这篇文章就把这条主线的完整拆解过程写出来给想用小体量知识库起步做Agent的人一个参照。1. 项目解剖66页工业库为何能长成Agent主线1.1 这66页工业库到底是什么我先说清楚这份66页的底料长什么样因为它和网上常见的“通用知识库”差别很大。它不是一个单一的PDF文件而是好几类文档拼起来的一是核心设备的参数表和技术手册选页里面全是型号、额定电压、功率、压力范围这类数值二是一套标准操作流程也就是工业现场常说的SOP规定某个操作按什么顺序做、每步注意什么三是报警值和异常现象对照表比如哪个报警代码对应什么故障、该怎么处置四是安全注意事项和应急响应预案。这些内容在主题上高度强相关都在回答同一个车间里操作人员会遇到的日常问题但格式完全不统一有横版表格、有带层级编号的条款、有流程图截图。工业库的特点就是“数字化程度低但专业要求极高”大量缩写、中英混排、数值范围、版本号而且知识更新的节奏说变就变——设备一改型、标准一改版旧文档就得下线。更关键的是答错代价不同。通用知识库答错一句也就是用户觉得不准工业知识库要是答错一个报警阈值操作工照着回答去处理设备后果可能是设备损坏甚至安全事故。所以这个项目从一开始就定了底线每个回答必须有出处没有出处的回答宁可不说。这也决定了后面所有技术选型都围绕“可溯源、可验证、可更新”来展开。1.2 为什么用知识库Agent而不是“让大模型背下全本”有人会问66页内容这么少直接把全文塞给大模型让它回答不就行了我分别解释一下为什么三条路都没走。第一条路是微调。让大模型把这66页背下来听起来很诱人但工业文档的高频操作是“改版”今天参数表更新一页明天SOP修订一条每次改动都重新微调一轮时间和算力成本都不可接受。而且微调后的模型是黑盒回答没有出处运维人员根本不敢拿来做操作依据。66页的数据量对于微调来说也远远不够很容易学歪。第二条路是长上下文直读。把66页文本全部塞进上下文窗口模型确实能看到但有两个问题一是长篇文档中的具体数值会被上下文稀释提问“3号空压机排气压力上限是多少”模型很可能把4号设备的数据混进来二是没有检索定位能力每次回答都要重新处理全文延迟高也无法指出“依据在第34页”。第三条路就是知识库Agent也就是我这篇文章说的主线。它本质上是一个“检索增强生成”的框架但比普通的单次RAG多了一层Agent能力。普通RAG是“用户问一句、检索一次、生成一次”工业场景下的真实提问往往一句话里藏着好几个子问题。比如“空压机排气温度高报警到底怎么处置”这个问题实际上需要三步先确认空压机型号对应的正常温度范围和报警阈值再查对应型号的处置步骤最后补充安全注意事项。单次检索很可能只命中其中一段剩下的靠模型瞎猜。知识库Agent做的事情就是把“一次提问、多次检索、按需汇总”变成一套可控流程让问题拆解、检索调用、答案验证每个环节都透明可见。2. 工业文档的知识化加工从66页到可检索的知识块2.1 文档清洗有三件事必须亲自做知识库Agent的地基是文档本身。66页文档不多但这恰恰是优势——我有精力把每一页都人工过一遍。清洗阶段有三件事偷懒不得。第一件事是解析与转文本。PDF用pdfplumber或PyMuPDF转成文本横版表格直接用文本解析很容易错乱需要专门的表格抽取工具。我那份文档里有一页是设备参数总表直接用通用解析器抽出来列和行全错位单位也丢了最后是用表格识别工具加人工校对才恢复原样。工业文档里的数字和计量单位是生命线这里出错后面检索做得再好都是白搭。第二件事是清理噪音。页眉页脚、目录页码、水印、残留换行、制表符这些都会污染切块结果。尤其是OCR出来的文档错别字要逐页抽查我曾经遇到过“MPa”被识别成“M Pa”一个空格之差检索时关键词完全匹配不上。这种错误靠模型自动修是修不干净的必须人工盯一遍关键数值和单位。第三件事是结构还原。工业文档普遍有清晰的标题层级和编号体系比如“3.2.1 滤芯更换步骤”。要把这些层级关系提取出来构建成“文件—章节—小节—段落”的树状结构。这一步有两层价值一是后面检索时可以按章节做粗过滤把搜索范围大幅缩小二是每一段文本都带着章节路径回答时引用位置就能写到“第3.2.1节”这种级别而不是笼统说“某个文档里提到了”。清洗完成之后要给每个知识块设计元数据。我的做法是每个块固定挂六个字段来源文件名、版本号、章节路径、页码、内容类型正文/表格/步骤、创建时间。这些字段决定了后续检索过滤、版本隔离、引用格式能否落地越早定越好。等索引建完再回头补元数据等于重做一遍。2.2 切块策略三个参数如何定切块是知识库Agent里最容易被低估的环节。很多人以为随便按固定字数切就行实际上一旦切错后面所有环节都在错误的数据上做文章效果怎么调都上不去。先解释为什么要切块。Embedding模型对输入长度有限制当前常用的中文向量模型一般在8192个token以内但即使没超过上限太长的文本经过向量化后语义会被“平均”稀释——一段512字的文本里可能包含三个不同主题向量最终呈现的是三个主题混在一起的模糊语义检索时哪个都命不准。检索的目标是“返回和问题最相关的局部片段”不是“返回包含答案的整个章节”所以切块粒度直接决定召回质量。我用的切块策略可以总结为“结构优先、定长兜底”。具体分四步用文档的标题层级先把整份文档切成大块保证同一个大块内主题一致。大块内部如果超过阈值再按自然段落分割。段落仍然超长时用定长滑动窗口兜底。相邻块之间设置一定重叠防止上下文在切缝处断裂。三个核心参数里chunk_size和overlap是绕不开的。中文工业文档我建议以“字符数”而不是token数来衡量中文字符和token的比例大约是1:1.5直接按token切容易把一句话拦腰截断。我的参数范围供参考chunk_size取512到768字符overlap取64到128字符。块太大会混入无关信息块太小则语义不完整比如“禁止在未泄压状态下拆卸”本来是一个完整的安全警告切成“禁止在未泄压”和“状态下拆卸”两块语义就废了。另一个关键点是表格的切法。工业文档里的表格是“另一条主线”不能和普通文本混在一起切。一个表格应该作为一个整体块保留包括表头、单位和备注说明如果表格行数太多必须按行切每一行都要冗余携带表头信息。这个做法反直觉但非常有用否则“22.8”这个数字脱离列名和单位之后谁都不知道它是什么。2.3 向量索引与检索接口选型清洗和切块完成后下一步就是把知识块向量化并建立索引。向量模型我选了BGE-M3中文效果好而且是开源模型支持稠密向量和稀疏向量两种表示后面做混合检索时同一个模型就能输出两种索引省了不少事。如果环境受限、下载不了大模型退而求其次用text2vec-base-chinese也能跑起来只是准确率会打些折扣。66页文档切出来的知识块数量很小大概也就几百个块用FAISS内存索引完全够用连独立的向量数据库服务都不用部署。但我还是把检索接口封装成了一个独立服务。这么做的原因很朴素项目起步只有66页后面一定会扩展到更多设备手册如果一开始就把索引逻辑写死在业务代码里后面扩展时就得重构。把检索抽象成独立接口后续换成Milvus或者Qdrant只需要替换底层实现上层Agent的代码一行都不用动。索引建设的代码逻辑大致是这样的from pymupdf import open as pdf_open from bge_m3 import BGEM3EmbeddingModel doc pdf_open(industrial_lib_v2.pdf) blocks extract_structured_blocks(doc) # 返回带元数据的知识块列表 model BGEM3EmbeddingModel(model_nameBAAI/bge-m3) chunk_texts [b[text] for b in blocks] embeddings model.encode(chunk_texts)[dense_vecs] # 每个块保存文本和元数据 for idx, block in enumerate(blocks): block[embedding] embeddings[idx] block[id] fblock_{idx} # 写入FAISS索引 import faiss import numpy as np dim embeddings.shape[1] index faiss.IndexFlatIP(dim) faiss.normalize_L2(embeddings) index.add(embeddings) faiss.write_index(index, industrial_blocks.index)要强调的是Embedding模型选型不是一劳永逸的。换了模型后必须重建索引否则新旧向量不在同一个语义空间里检索结果会变得毫无意义。踩过一次坑之后我把索引重建做成了流水线上的固定步骤每次更新Embedding版本都跑一遍全量重建。3. 检索与生成的Agent闭环核心实现拆解3.1 混合检索向量不够BM25兜底工业库检索有个很实际的痛点纯向量检索对专有名词和缩写不友好。像“SOP”“PLC”“HVAC”这种缩写以及“A/B-3000”这种带特殊符号的型号Embedding模型经常把它们当成普通词组导致语义相近的段落凑上来精确匹配的段落反而排到后面去。解决办法是混合检索。向量检索负责捕捉语义相关性BM25这类稀疏检索负责精确匹配专有名词最后把两路结果融合排序。融合用的算法是RRFReciprocal Rank Fusion原理不复杂每个文档在两路结果里都有一个排名融合分数就是每个排名倒数之和排名越靠前贡献越大。这样语义和关键词两条线索都能发挥各自优势不会被某一方的偏差带偏。核心逻辑长这样from rank_bm25 import BM25Okapi # 用BGE-M3的sparse_vecs同时做BM25式匹配 bm25 BM25Okapi(tokenized_chunks) def hybrid_search(query, top_k5): query_vec embedding_model.encode([query])[dense_vecs] dense_scores, dense_indices faiss_index.search(query_vec, top_k) bm25_scores bm25.get_scores(tokenize(query)) top_bm25 sorted(range(len(bm25_scores)), keylambda i: bm25_scores[i], reverseTrue)[:top_k] # RRF融合 fused {} for rank, idx in enumerate(dense_indices[0]): fused[idx] fused.get(idx, 0) 1 / (60 rank) for rank, idx in enumerate(top_bm25): fused[idx] fused.get(idx, 0) 1 / (60 rank) return sorted(fused.items(), keylambda x: x[1], reverseTrue)[:top_k]实测下来加了BM25混合检索之后像“报警代码E-204”联合“处置建议”这种查询精准命中率提升非常明显。纯向量检索经常把“报警代码”相关的其他段落也排上来但精确带着“E-204”的那一段反而沉在下面。工业文档里大量存在“型号故障”这种组合查询BM25对这类模式就是天然的强项。3.2 Agent如何把“一个难题”拆成“几次查询”知识库Agent和普通RAG最核心的区别在于它把LLM从“直接答题的人”变成了“调度问题的人”。用户提一个复杂问题Agent先判断这个问题需要哪些信息再决定调用几次检索工具最后汇总成答案。我用一个实际例子说明。用户问“空压机排气温度高报警怎么处置”这个问题的正确回答需要三块知识空压机型号对应的排气温度正常范围、报警阈值、对应型号的处置步骤。如果只做一次检索返回的可能是报警处置步骤也可能是参数表里的温度范围反正很难一次拿全。Agent的做法是把一个问题改写成三个子查询子查询一空压机XX型号排气温度报警阈值是多少子查询二排气温度高报警的处置步骤子查询三空压机高温报警的安全注意事项每个子查询单独走一遍检索把三段结果拼接起来再让LLM组织成完整回答。这样每一步检索都是精准的最后给出的答案信息完整、逻辑连贯而不是大段堆砌无关内容。要想让Agent正确地做多步检索关键在于工具定义写得到位。LangChain或自建Agent框架里每个工具有一个descriptionLLM就是靠这个描述来决定何时调用工具的。描述写得太简略比如“知识库检索工具”模型就很容易在第一次检索拿到不相关内容后直接放弃或者反复调用同一个工具碰运气。我会写清楚这个工具能搜什么、什么时候用、返回什么格式。工具定义示意tools [ { name: search_kb, description: 在工业知识库中检索设备参数、操作流程、报警处置、安全注意事项。 当用户问题涉及具体设备型号、数值范围、操作步骤时必须调用此工具。 支持传入关键词组合例如空压机 排气温度 报警阈值。, parameters: {query: string} } ] def agent_loop(user_query, memory): # 1. 判断是否需要拆解子问题 sub_queries plan_subqueries(user_query, memory) # 2. 逐个子查询调用检索工具 contexts [] for sub_q in sub_queries: results search_kb(sub_q, top_k3) contexts.extend(results) # 3. 生成带引用的最终回答 answer generate_with_sources(user_query, contexts) return answer还需要处理多轮对话记忆。工业场景下用户不太会一句话把所有信息说全更常见的是“3号空压机排气温度高报警了怎么办”Agent回答完之后用户接着问“那压力上限呢”。如果不记忆上一轮的设备型号这个问题就失去了主语。我在会话状态里维护了两个变量——“当前设备型号”和“当前讨论故障”每当识别到新的设备型号就更新后续提问如果缺少主语自动从会话状态中补全。这个小功能看着不起眼但操作工用起来会明显觉得“这个机器人是懂上下文的”。3.3 回答纪律提示词里写死的三条底线知识库Agent的LLM生成环节提示词设计不能只考虑“答得准”更要考虑“答得安全”。工业场景下我直接写死了三条纪律。第一条是强制引用。回答中涉及的所有具体参数、步骤、报警代码必须附上引用来源格式为“依据文件名 第X页 第X节”。这不仅是可解释性问题更是合规问题。操作工需要一个可以翻纸质手册复核的答案而不是一个“看起来对但找不到依据”的结论。第二条是找不到就明说。如果检索到的上下文不足以支撑回答模型必须输出“该问题在当前知识库中没有找到明确依据请转人工确认后再执行操作”而不是基于通用知识自行推断。工业领域最大的风险不是“答不上来”而是“答错了还理直气壮”。我把这条写进提示词后无依据乱答的比例大幅下降。第三条是安全操作加现场确认。凡是涉及设备操作、安全阈值、应急处置的回答结尾自动追加一句“具体操作请结合现场设备状态和本地操作规程确认”。这句话不是废话它是在暗示用户系统给出的内容是知识库中的标准规定但现场可能有标准之外的特殊情况操作前必须二次确认。给出一段可以直接参考的回答提示词模板你是一个工业知识库问答助手。请严格遵循以下规则 1. 只依据上下文检索片段回答不得使用训练数据中的通用知识。 2. 回答中涉及参数、报警代码、操作步骤时必须标注引用来源格式为依据文件名 第X页。 3. 如果上下文不足以回答用户问题明确回复“该问题在当前知识库中没有找到明确依据请转人工确认后再执行操作。” 4. 涉及设备操作、安全阈值、应急处置的回答结尾必须追加“具体操作请结合现场设备和本地操作规程确认。” 5. 用简洁的中文回答不要重复问题不要展开与问题无关的内容。这套提示词实际跑下来回答风格变得非常“克制”甚至有时候显得啰嗦但用户接受度反而更高。工业场景的诉求是“我不需要你聪明我需要你靠谱”这三条纪律就是朝着靠谱去的。4. 实测评估与调优从“能用”到“敢用”4.1 三类测试问题与评估指标知识库Agent做出来能不能上线不能靠“感觉还行”必须有一套可量化的评估标准。我把测试问题分成三类每类准备30条。第一类是事实查询型问的是“XX设备额定功率是多少”“滤芯型号是多少”。这类问题答案是唯一的检索定位精准度就是核心指标。第二类是操作流程型问的是“更换滤芯的具体步骤是什么”“多久做一次保养”。这类问题答案跨度大往往分布在好几页考察的是检索结果覆盖是否完整。第三类是故障处置型问的是“排气温度高报警怎么处置”“油压过低会有什么后果”。这类问题还需要关联安全注意事项考察的是Agent多步检索和信息整合能力。这90条测试问题里有一半来自真实运维群里的历史提问记录另一半是我模拟新人操作工的口头问法。这个做法很关键——如果只靠自己顺着文档猜问题来测试很容易高估系统效果因为猜的问题往往正好落在文档的关键句上。真实问题则五花八门有问“怎么会这样的”、有问“要不要紧的”数据才能暴露系统的短板。评估指标我用四个检索命中率Top3结果里有没有包含关键答案段落、最终答案引用正确率、无依据回答比例越低越好、平均响应时间。检索命中率是基础指标引用正确率决定系统能不能“敢用”无依据回答比例体现安全底线。4.2 调优过程中的参数与结果调优过程有点像一个漏斗每一步都在修上一轮暴露的问题。我把每次改动和效果记录下来方便后面复盘。第一版是纯向量检索chunk_size取1024字符没有重叠没有混合检索。结果检索命中率只有50%出头而且经常出现“文档里明明有答案但系统答不对”的情况。原因很明确块太大一个块里信息太杂向量被稀释没有重叠关键句正好卡在切缝处时就整句丢失。第二版把chunk_size降到768overlap设为96同时把切块方式改成“结构优先、定长兜底”命中率提升到70%左右。这个提升主要靠数据质量和模型没什么关系。第三版最大的变化是表格独立切块、按行切时冗余表头命中率升到80%。到这里基本达到了“能用”的门槛但离“敢用”还差一口气。第四版加入BM25混合检索加RRF融合命中率到了90%左右尤其是故障处置型问题的表现改善明显。第五版加了BGE-Reranker做结果重排把检索出的Top20精排到Top5Top1准确率明显改善最终答案的引用正确率也随之提升。各阶段效果对比如下阶段主要改动检索命中率引用正确率无依据回答比例V1纯向量chunk_size102452%40%22%V2chunk_size768overlap96结构切块70%58%14%V3表格独立切块80%70%9%V4混合检索RRF89%81%6%V5加Rerank精排93%88%3%调优顺序给我的体会是先管数据质量再上重武器。前期最大的提升来自切块方式和表格处理而不是换更大的模型或更复杂的算法。等到数据质量稳定了Rerank这类重型手段才发挥出价值。如果顺序反了数据质量一团糟的时候上Rerank相当于在污水里做精过滤效果有限还浪费算力。5. 踩坑实录知识库Agent最常见的七个问题5.1 检索为空时按什么链路排查知识库Agent上线后最让人头疼的问题就是“检索返回为空”或“答非所问”表现形式五花八门但排查逻辑是有规律的按链路一步步走基本都能定位。排查顺序第一检查Embedding是否成功有没有特殊字符导致文本被截断第二检查切块是否存在过短或语义不完整的情况比如一个块只有十几个字符向量化后基本没有语义信息第三检查索引里有没有该文档的条目更新文档后漏了重建索引是最常见的原因第四检查混合检索的融合权重看是不是某一方分数过高压掉了另一方。一个实用技巧上线后在日志里把每次检索的“Top5命中片段文本相似度分数”全部打出来。肉眼扫一遍日志就能判断问题出在切块、向量还是融合环节。不要靠猜靠日志里的实际返回内容定位。5.2 表格被“切碎”后的修复方案我踩过最深的一个坑就是报警代码表被普通切块方式切碎。那张表有三列报警代码、含义、处置建议。用普通段落切法表头单独成块数据行单独成块嵌入检索时表头和数据行完全分离。用户搜“E-204报警怎么处置”时检索到报警代码“E-204”那个块但处置建议字段已经跑到下一个块里了导致答案缺一半。修复方案就是我前面说的表格独立通道一个表格作为一个整体块大表按行切分时每一行都冗余携带表头列名每个表格块的类型标记为“table”检索时优先匹配类型为“table”的块把表头行和命中行拼成完整句子后再交给LLM。这个方案对所有以数值、字段为核心的工业文档都适用。5.3 版本污染新旧文档打架怎么治理工业文档最频繁的变更就是版本更新。有一次我把新版设备手册索引进去之后发现同一个问题有时返回新参数、有时返回旧参数原因是旧版文档还留在索引里。向量检索按相似度排序新旧两块文本相似度都很高模型也不清楚该用哪个版本。治理方案有两个一是在元数据里加版本号检索时过滤条件只保留当前有效版本二是更新文档时对同一“来源文件章节路径”的旧块做标记下线不直接物理删除方便回溯历史。每次版本更新后我会人工抽查20个典型问题确保新旧文档切换后没有交叉污染。5.4 常见问题速查表最后整理一张速查表把我在这个项目里遇到频率最高的七类问题汇总在一起方便后面排查时快速对照。现象可能原因解法检索结果为空文档未重建索引、Embedding失败检查索引版本查看切块文本是否完整检索命中但答案不对切块太大导致语义混杂调低chunk_size增加overlap答案像是编的提示词未强制引用、上下文不足加引用约束无依据时明确拒绝回答表格数据残缺表格被当普通文本切碎表格独立切块按行切时冗余表头多轮对话丢失上下文会话状态未维护设备型号增加会话变量记录设备型号和故障主题新旧文档答案打架旧版本未下线元数据版本过滤更新后人工抽查专有名词检索不准Embedding不认识缩写/型号加BM25混合检索建立同义词扩展表最后说一点个人体会。做完这个项目我最深的感受是知识库Agent的主线并不取决于初始数据是66页还是66万页而是取决于你是否愿意把每一份文档当成知识资产来加工。66页的好处恰恰在于体量小你有能力逐页阅读、逐表校对把每个知识块都亲手处理到位——这种精细度在大型自动化流水线上反而不容易做到。如果你手头也有一堆不起眼的技术文档、操作手册、规范规程别等着数据攒齐了再动手。先拿这份小家底把闭环跑通后面每扩展一份文档都只是沿着这条主线再加一个分支而已。