企业官网建设流程全解析

第一版跑通的那个晚上，我盯着终端卡了好一会儿：这个Agent从一份66页的工业手册里，翻出了一个我自己都已经忽略的参数，换算成对应的工况建议，还顺手标出了手册页码。那一刻我才真正理解“知识库Agent这条主线”是怎么回事——它从来不是临时接个大模型聊天框，而是从一份文档开始，一层层长出来的系统工程。这份66页的工业库，今天已经变成整个Agent主线的数据地基。这篇不聊宏大蓝图，只聊我自己从这份文档出发，把知识库Agent一步步搭起来的真实过程和踩过的坑。

1. 起点：一份66页的工业手册，和它逼我做的第一个决定

1.1 这份文档最让人头疼的部分不是厚，而是“结构”

我手里这份66页的工业库，是一份老设备的检修手册。它不像开发文档那样有清晰的API结构，也不像论文那样有摘要和结论。它是按维修工人的使用习惯写的：前面是设备总览，中间是各子系统的拆解步骤，后面是几十张参数表、报警代码表、扭力要求，甚至还有几页手写的加页记录。

最让我头疼的是它的结构“多头”：同样的故障，在第12页讲排查思路，第34页的表格里才有具体的报警代码，第58页又给出了对应的备件型号。你单独看任何一页，都觉得说清楚了，但当你想让一个模型基于整本手册回答问题时，它需要的不是某一页，而是把三处信息拼起来。

这个发现直接改变了我后续的所有选择。如果你只是把66页文档丢给模型做RAG，模型大概率会“选中”最相关的那一段，但工业类的连环问题——“这台设备报警E213，我该先查传感器还是先查线束”——往往涉及多个分散段落，不是一段检索就能解决的。我后来花了大量时间在结构解析上，根源就是这一天看明白了这份文档的特点。

1.2 从“能搜关键词”到“能回答问题”，差的是RAG那一层

一开始我走了一条所有新手都会走的路：把PDF转成文本，扔进一个本地向量库，接上大模型API，就以为知识库Agent完成了。结果第一次测试就问出问题——我问“油温超过85度应该怎么处理”，模型答得有模有样，但引用的页码根本不存在，那段内容其实来自另一个章节的例行保养说明。

问题不在于模型，而在于我跳过了知识库构建的过程，直接做了问答。检索增强生成（RAG）的核心并不只是“把文档切成块、做向量、召回Top K”，而是要让召回结果足够贴近提问者的真实意图。对一份工业检修手册来说，提问者问的是操作流程，是参数边界，是故障码背后的逻辑链。这比问“巴黎是哪个国家的首都”要复杂得多。

所以我把项目拆成了两条线：第一条线是把这份66页工业库整理成真正可被检索、可被理解的知识结构；第二条线才是围绕这个知识库做Agent的能力扩展。后来整个项目能长成一条主线，决定性动作其实发生在这第一步的拆解上，而不是后面选什么框架。

2. 把66页工业库喂给模型之前：清洗、切分与图片表格的处理

2.1 扫描件转出来的文本，离“可用”还差三步

说实话，拿到这份手册的第一步我就差点崩了。它是扫描件，OCR出来的文本里充满了断行、乱码、表格错位。直接拿去做RAG，效果可以用灾难形容。我试过用市面上常见的PDF解析工具直接把文本抽出来，结果是：正文段落勉强能读，但所有的表格数据全部挤成一团，页码也对不上。

在工业文档场景里，OCR后的清洗有三步我建议无论如何都不跳过。第一步是重组段落，把扫描件里因为换页、页眉页脚打断的句子重新拼接，这一步我用的是处理PDF布局的Python脚本，按坐标位置判断哪些文本属于同一段落块。第二步是识别表格结构，这一步尤其关键，因为66页手册里至少有十几页是参数表，我需要把表格行和列还原成结构化数据，而不是让模型去读一堆无规律的文本碎片。第三步是人工抽查，我会挑故障码表、扭力表这类关键表格逐行核对，确保数值没有在OCR过程中被认错。

我见过不少团队直接在OCR文本上跑RAG，结果用户问一个精确参数，模型回答的数值来自错误行。工业文档里一个数值错了，不是笑话，是事故。所以清洗环节，我宁可慢，也不愿意跳过。

2.2 切分策略：按报告结构切，而不是按固定字数切

RAG项目里最常见的默认做法是按固定token数切文档，比如每512个token切一块，块与块之间留一点重叠。这个方法在处理网页文章、新闻稿件时问题不大，但用在工业手册上会制造大量语义断裂。一份66页的检修手册，一个完整的检修流程可能跨了好几页，之间还穿插着图表。如果你硬按512 token切，一个故障排查流程会被切成七八段，检索时模型只能看到其中一段，自然答不好。

我用的切分策略改为“结构优先”：先通过页眉、标题字体、章节编号把整本手册还原成一棵目录树，然后以最小的语义单元——比如一个检修步骤、一个故障码解释、一张参数表——作为切分单位。切分时保留章节路径作为元数据，例如“第3章-液压系统-3.2.1-油温异常排查”，这个章节路径在召回后非常有用，我可以在LangChain这类框架里直接把它当成filter条件，也可以拿它拼prompt，告诉模型“这段内容来自第三章液压系统”。

当然，这种切分方式比固定长度切分要复杂不少，它依赖文档本身的排版规律。好在这份66页手册的排版足够规范，有稳定的编号体系。我写了一个简单的规则脚本，先按标题层级切分，再对每个章节内部做段落合并，最后把表格转成Markdown格式单独存储。我这套脚本的产出物是带元数据的JSON，每条记录包含文本内容、章节路径、页码、表格标记。

2.3 图片和表格是工业文档RAG的重灾区

热搜里总有人问“RAG知识库能存储图片嘛”“知识库图片怎么处理”，我一开始也天真地以为把图片转成base64塞进向量库就行。实际测试下来完全不是那么回事。工业手册里的图片分为两类：一类是说明性的示意图，比如设备结构解剖图，这类图片模型看了也很难直接给出操作建议；另一类是有信息量的图表，比如压力曲线、接线图，这类图片如果单靠视觉问答模型去理解，准确率撑不住。

我最后的方案是“图转结构化描述”：对关键图表，我人工补充一段完整的文字说明，例如“图7是油路压力随温度变化曲线，85度时压力上限为12bar”，然后把这句描述和原图一起放进知识库。检索时优先命中这段结构化描述，图片作为参考附件展示给用户。这样既保住信息，又不依赖模型对图纸的直接理解能力。

表格的处理更直白：所有参数表我全部转成Markdown表格或CSV，单独存为结构化条目。工业场景里，表格是查询的高频区，你要回答“E213报警的触发条件”，就是在查表。表格不做结构化，RAG的召回质量永远上不去。

3. RAG、KG、结构化知识库：三条路线在工业知识场景里的边界

3.1 为什么我不反对“全文一股脑向量化”

现在圈子里聊知识库总绕不开RAG、KG、结构化知识库的区分。RAG是向量检索加生成，KG是知识图谱，结构化知识库说白了就是带Schema的数据库。这三个词被很多人当成三种互斥的技术选型，但我自己的体会是：它们只是解决不同问题的工具，应该组合使用。

先说RAG，它在工业手册里的优势是几乎没有门槛。66页文档经过清洗和切分后，用Embedding模型转成向量丢进向量库，就能跑一个基础的问答。它特别擅长处理那些“你知道内容确实在某处，但说不清关键词”的模糊问题。比如用户问“设备最近启动时总是抖动，可能是什么原因”，这种开放式问题没有固定答案模板，向量召回到位时，模型能综合多个段落给出合理的线索。

但RAG有一个我很在意的弱点：它对精确数值和强逻辑关系的处理不稳定。工业文档里大量存在A是B的前置条件、C必须在D之前操作这类逻辑，这些逻辑埋在不同段落里，靠向量相似度召回很容易丢上下文。所以我不否定RAG，但它不是唯一一条路。

3.2 什么时候值得把66页手册抽成KG知识图谱

KG知识图谱在工业场景里经常被提起，但说实话，66页的文档做知识图谱，收益和成本不一定成正比。知识图谱需要你定义实体、关系、属性，然后把文档里的信息全部抽取成三元组。对一份流程性很强的检修手册来说，“传感器A监测油压B并触发报警C”这种三元组确实能表达一部分逻辑，但维修流程的时序关系、条件分支用KG表达起来就很费劲。

我评估过把这份66页工业库抽成KG的成本：光实体关系定义就需要和业务专家碰三轮，抽取时还要人工校验关键节点，整体工作量至少是RAG路线的三倍。对一个只有66页的种子库来说，这个投入偏重。我的结论是：KG适合那些信息密度极高、实体关系非常明确且结构相对固定的领域，比如标准规范库、产品BOM表、法规库。像我这本检修手册，主体流程和故障排查逻辑更适合用RAG加结构化表格去解决，KG暂时作为辅助扩展路线放着。

3.3 结构化知识库负责“算”，RAG负责“找”

真正让整个知识库Agent变好用的是我把结构化数据和RAG结合起来：参数表、报警代码表、备件清单这类精确查找内容全部进结构化知识库，查询时我用确定性代码去查；而检修步骤、原理说明、经验描述这类开放性内容走RAG向量检索。两条路的指令路由由Agent决定，用户问“E213报警怎么处理”，Agent先识别出“E213”是个报警代码，优先去结构化表里查定义和触发条件，再结合RAG召回的检修上下文，生成完整的处理建议。

这套组合下来，最直观的变化是模型的“胡编率”大幅下降。以前问报警代码相关问题，模型经常自信地给出一个看起来合理但手册里根本不存在的定义。现在只要代码能查表，答案就是确定性的。至于那些表里没有的模糊问题，再回到RAG的语境中去解决。三类知识库的边界我用一张表整理过：

4. Agent主线的骨架：从一轮问答到多步任务的编排

4.1 先谈边界：Agent不是把问题直接转发给大模型

知识库做到能准确回答常规问题之后，我开始做Agent这条主线。这里有个常见的认知误区：Agent不是把用户问题原样丢给大模型，让它自由发挥。那样的话，前面辛辛苦苦做的知识库清洗和结构化都没有意义，模型还是会拿通用知识来编答案。Agent首先要解决的问题是：让大模型学会在特定场景下调用正确的能力，而不是代替能力本身。

我搭Agent的时候，把能力边界画得很清楚。第一层是入口路由，判断用户问题属于安全咨询、故障排查、参数查询还是操作指导。第二层是工具层，每个能力都封装成一个可被调用的函数，比如query_structured_table、search_rag_context、calculate_oil_pressure_limit。第三层是执行层，Agent根据用户的连续意图决定先调用哪个工具、调用多少次、什么时候生成最终答案。

做这个骨架的时候，我刻意没一开始就上复杂的Agent框架。先自己手写了一个简单的工具调用循环，用大模型做意图解析，按JSON结构返回工具名和参数，再由本地的调度器执行工具。这样跑通一条完整链路之后，再搬到开源框架里做升级，思路会清晰很多。

4.2 工具调用与工作流：检索、计算、写查询、给依据

工具层里我做了四个最常用的工具。第一个是“语义检索”，底层走向量库召回Top K相关段落，返回带章节路径的markdown内容。第二个是“结构化查询”，专门查表格数据，支持按报警代码、设备型号、参数名称精确匹配。第三个是“参数计算”，这个工具不是查表，而是根据手册里的公式动态计算，例如根据油温和环境温度推算当前工况下的压力上限。第四个是“答案溯源”，在最终回复里自动附上引用页码和章节位置。

这四类工具接进Agent后，工作流的编排就灵活了很多。用户问一个问题，Agent可以先查结构化表确认数值边界，再用语义检索找排查流程，最后如果需要，调用计算工具给出一组动态推荐值。整个流程里，每一步的工具调用结果都会留痕，方便后续审计。

工作流的编排我建议用显式的图结构而不是写死在代码里。现代Agent框架里，流程节点的跳转条件、工具失败后的重试策略，都可以配置化。尤其是工具调用失败时，别让Agent自作主张编一个结果，宁可让它明确说“该参数手册中没有记录”，也比骗人强。

4.3 链路可观测：一条完整问答要能复盘

Agent一旦进入多工具协同状态，最大的麻烦是不透明。用户看到的是最终答案，但如果你无法回答“它为什么给出这个结论”，那这个系统就不敢用在严肃的工业决策场景里。我要求每条问答链路必须输出一份可读的决策日志：用户问题、意图路由结果、每一步调用的工具、工具返回的内容摘要、最终使用哪些上下文片段生成了回答。分析日志时，能清晰看出知识库哪里漏了，检索里哪里错排了，Agent路线哪里误判了。

有一次用户问“这台设备能不能在零下十度启动”，日志显示Agent先调了语义检索，但召回了“工作温度范围”和“低温启动注意事项”两段内容，结果模型给出了自相矛盾的答复。事后我修正了切分策略，把低温相关的几个段落合并成同一块，并增加了一层规则判断：当问题中检测到温度数值时，优先从结构化的环境参数表里取值，而不是依赖语义检索的模糊匹配。

5. 跑通之后的现实问题：记忆、安全与知识库的持续维护

5.1 Agent的记忆：别把对话历史当作知识库

“Agent记忆”是热门话题，我也踩过坑。最初我天真地以为只要把整个对话历史全量传给模型，Agent就能记住用户偏好。结果对话轮次一长，Token开销爆炸，而且模型容易把用户随口一提的假设当成事实，在后续回答里复用。工业场景里这个问题尤其危险：用户说“我怀疑是传感器漂移”，模型如果把它当成既定事实，后面所有回复都会被带偏。

正确的做法是区分短期记忆和长期记忆。短期记忆只保留当前对话轮次的关键上下文，每次新会话重新开始；长期记忆则沉淀有价值的事实性信息，比如用户负责的设备型号、经常查询的对象、历史处理过的问题，这部分用结构化的KV存储，写出独立的记忆条目，再由Agent在合适时机调用。我把记忆设计成一个显式工具，模型需要时才会写入或读取，不让它隐式影响每一步推理。

5.2 权限分级与内容安全：工业文档比通用文档更敏感

网络上聊Agent安全，多数关注“提示注入”“越狱”，但在工业知识库场景里，我更在意的是权限边界。手册里的内容不全是应该对所有人开放的，比如维修参数表和紧急操作流程可以向一线维护人员开放，但涉及设备采购验收入的信息、内部改造记录就不能随便查。

我把知识库的权限拉到了文档条目级别。每个切分出来的模块都带一层可见性标签，Agent在试图调用工具前先过一遍权限校验，当前用户无权访问的内容直接不进上下文。这一条比什么安全提示都要硬核，它是从源头阻断信息泄漏，而不是依赖模型判断。做这个设计时明显感觉到，把知识库Agent当成“企业级应用”而不是“玩具聊天”来看待，能挡住很多后来的麻烦。

5.3 让知识库“自己长”：从问答日志回补给工业库

我特别想强调一件事：知识库Agent这个标题里的“知识库”不是静态的。66页手册只是种子，真正的工业知识库会长大的。怎么长大？我认为最靠谱的方法就是从Agent的问答日志里回补。每当有用户问出一个现有知识库答不好的问题，这条问答记录就是新增知识的候选。在这个项目里，我把这样的候选沉淀成“未覆盖问题清单”，定期人工判断，决定是为现有文档补充说明、调整切分逻辑，还是新增一条结构化记录。

运行了几个月后，原始66页手册之外已经长出了不少高价值内容：现场反馈的故障处理记录、维修人员总结的小经验、以及针对特定机型的补充参数。这些内容经过整理后，以追加页的形式并入知识库结构，Agent的长线价值也是这样逐渐体现出来的。说句实话，当知识库自己开始“长”的时候，才是这条主线真正值钱的时候。

6. 复盘一条完整链路，总结五条比技术更重要的体会

6.1 从头到尾，这份66页工业库带来的一条明确技术链路

把整个项目串联起来，其实链路并不复杂：源文档清洗 → 结构解析 → 切分与元数据标注 → 向量化检索（RAG）＋结构化表格＋少量计算工具 → 工具层封装 → Agent路由编排 → 日志回补知识库。每一步做扎实，知识库Agent的质量就会往上抬一截。如果哪一环节偷懒，比如切分随意、表格没结构化、链路不可观测，后期一定加倍还债。

基于这几步，我做几个自测过的小建议：

• 先花时间把文档结构吃透，再动手写切分代码。你对手册的理解程度直接决定知识库质量。
• 结构化表格优先级永远排在向量检索前面，能查表就不靠模型猜。
• Agent的第一个版本越简单越好，手写一个工具调用循环能让你真正理解编排逻辑。
• 每次问答都留日志，没有日志的Agent我不会让它对用户输出结论。
• 权限校验走代码层，别把希望寄托在模型自觉上。

6.2 个人体会：主线项目里，慢就是快

我自己在这个项目上最大的体会是，知识库Agent的主线做的是“数据工程”而不是“模型工程”。大模型的能力已经足够好，瓶颈都在数据侧：文档清没清洗干净、表格有没有结构化、切分边界有没有切在语义节点上、检索日志有没有反哺知识库更新。把精力重点投在这些地方，Agent的“聪明”才会真正有根。

还有一个很现实的心态问题：这类项目短期内看不到爆发性成果，它更像是在持续经营一块自留地。最开始那份66页工业库看起来很窄，但随着一层层积累和回补，它能覆盖的问题会慢慢变宽。我在推进的过程中放弃过好几次接新框架的冲动，因为保持主线清晰比追热词重要得多。如果你手里也有一份这样的“种子文档”，想把知识库Agent这条线做长，我的实际建议是：从一页一页清洗开始，先别急着接Agent，等知识库自己长出结构感，后面的一切都会自然顺起来。