企业官网建设流程全解析

手上这份内部设备的《用户运维手册》一共 100 多页，PDF、Word、老版扫描件混在一起，光目录就有三层。过去员工遇到问题都是先翻目录再跳章节，翻不到就直接找人问。现在我要做的是把这 100 页手册变成一套“会回答问题的 AI”——输入“报错 E203 怎么处理”，它能把手册第 6 章的操作步骤、故障码含义和注意事项全部找出来，组织成一段清晰可读的回答，甚至还能说出“这段话出自手册第 6.3 节”。

这个需求最合适的落地方案就是 RAG（检索增强生成），而我用来落地这套 RAG 的工具，选的是开源的 Dify 平台。它是目前为数不多能把“模型管理、知识库、应用编排、日志观测”全部串起来的一站式 LLM 应用平台，不需要我自己写向量检索代码，也不用操心前后端。下面我把整个项目从环境部署、文档处理、分段策略到最终上线实测的过程完整记录下来，包括那些文档里不会写、官网没解释清楚的坑。

1. 先把场景盘清楚：这套知识库到底要解决什么问题

1.1 100 页手册这类资料的天然痛点

100 页手册本身信息量不小，但它的问题恰好出在“组织形式”上。比如手册里讲“设备自检流程”时，会引用“附录 A 错误代码表”，而错误代码表里又反复提到“第 4 章 维护操作”。这种交叉引用非常常见，但在传统阅读里是很重的认知负担。

另一个痛点在于内容形态高度混合：有用 Word 排版的文字段落、有扫描成图片的硬件连接图、有 PowerShell 命令示例，还有覆盖旧型号的批注说明。这些内容混杂在一份“手册”里，用普通关键词搜索很难找到答案，因为用户往往不知道准确术语。

手册知识还有一个特点：时效性变化。版本 V2.1 新增了几条故障码，但旧章节里还可能残留着已废弃的流程。因此知识库构建不只是“把文本倒进去”，还需要考虑内容版本、优先级、引用溯源。

RAG 的思路就是不改变原手册的任何内容，而是把它切块、向量化、建立索引。用户在提问时，系统先从向量库召回最相关的若干片段，再把片段连同问题一起交给大模型生成回答。整个流程相当于给大模型配了一个“考场里能翻书”的能力。

1.2 为什么不是微调模型，也不是裸奔提示词

很多人一听“把手册变成 AI”，第一反应是微调模型，把它们全部塞进权重里。对这个需求来说，微调是杀鸡用牛刀，而且效果并不好。手册有新增修订，微调一次模型需要准备高质量指令对、做训练、评估、灰度发布，一套流程走完，手册可能又更新了一版。

也有人提出“直接写提示词，把整本手册贴在系统提示词里”。这种做法在 token 限制下完全不现实，100 页全文远超上下文窗口，而且手册里还存在大量代码块、表格和附录，混在提示词里会严重干扰模型对当前问题的注意力。

RAG 的好处是它把“记忆”从“推理”中剥离出来。记忆放在可动态更新的向量库里，推理由大模型完成，更新手册时只需重新处理变化的段落，不需要动模型。这个特性在企业知识场景里非常关键，因为内容的迭代频率远高于模型技术的迭代。

1.3 Dify 在这个体系里的定位

如果完全从零开始构建 RAG，需要自己搞定以下环节：文档解析、分段、向量化、向量数据库选型、检索逻辑、重排策略、大模型接入、应用前端、用户权限管理。这个工程量怎么说呢，光是把文档解析和分段调明白就得一周，而且每一环都是独立的坑。

Dify 恰好把这些环节都封装成了可视化组件：创建“知识库”，上传文档，设置分段模式和索引方式；创建“应用”，选择模型，挂上知识库，编排提示词；再配置检索模式和重排策略。平台自带 API 接口，后续要集成到内部系统也有现成方案。

我选择的版本是自部署的社区版。原因很现实：手册内容属于企业内部资料，不能送出内网依赖云端 SaaS；另外 Dify 社区版功能已经覆盖知识库 RAG 的全部核心场景，没有必要为这个需求上商业版。

2. 环境准备与部署：Dify 跑起来最容易栽的四个坑

2.1 官方脚本和镜像源的取舍

Dify 官方提供 docker compose 方式部署，项目目录里有一个docker文件夹，里面是编排文件和 .env 配置模板。理论上执行docker compose up -d就能把 API 服务、Worker、Web 前端、PostgreSQL、Redis、Weaviate 全部拉起来。

但国内网络环境下直接拉取 Docker Hub 镜像经常失败。我的建议是先把 Docker 的镜像源配置成可用的加速地址，再执行编排。另一个隐藏问题是：Dify 的镜像版本更新比较频繁，不同版本之间数据结构和 API 不保证完全兼容，所以部署时最好固定一个具体版本，不要直接latest。

我在部署时把 compose 文件里的镜像版本 tag 从默认值改成了当时的最新稳定版，例如langgenius/dify-api:1.x.x。这样做的好处是后续排查问题时能明确镜像内容和本地代码的对应关系。等全部服务起来后，还要花时间看一下容器日志，确认 API 容器和 worker 容器都正常连上了数据库。

提示：Dify 部署在 CentOS 7 上时，注意系统自带的 Docker 版本可能过旧。Dify 需要 Docker Compose V2 插件，CentOS 7 的默认 yum 源里没有，得手动安装 compose 插件到/usr/libexec/docker/cli-plugins/目录，否则docker compose命令会提示找不到。

2.2 CentOS 7 环境下的兼容性问题

我在一台 CentOS 7.9 的服务器上做过部署测试，踩了比较典型的两个坑。第一是内核版本和 Docker 存储驱动冲突。旧内核配合 OverlayFS 有时会异常，表现为容器启动后文件系统只读。第二是 Docker 服务内存不足，Dify 全家桶跑起来后，API、Worker、数据库、向量库加起来大约要吃 3-4GB 内存，如果服务器只有 2G 内存，很容易出现数据库容器被 OOM 杀掉的诡异现象。

对于 CentOS 7 我建议：先升级内核到长期支持版本，或者至少把 Docker 升级到 20.10 以上；内存不足的机器老老实实加 swap，并且把 Elasticsearch 或 Weaviate 的堆内存调小，否则启动即崩溃，日志里全是Native memory allocation (mmap) failed。

还有一点值得留意：CentOS 7 的防火墙（firewalld）默认规则比较严格。Dify 默认使用 80 端口对外提供 Web 服务，如果服务器上跑着 Nginx，必须把端口配置错开。当时我直接改了 .env 里的EXPOSE_NGINX_PORT=8080，省去了防火墙的各种麻烦。

2.3 Windows 下做功能验证的方案

有部分同事的电脑是 Windows，想本地起一套 Dify 先试效果。Windows 上最省力的方式是安装 Docker Desktop，然后同样用 docker compose 拉项目。但这里有一个新手极易踩的坑：Dify 的 docker compose 里端口映射用的是80:80，如果本机端口被占用，容器能起来但页面打不开。排查时先看docker compose ps，再检查端口占用，不要反复重启容器。

Windows 上我还遇到过文件挂载问题：Dify 会把上传的文档、日志、证书持久化到 docker 目录下的 volume 中。如果用的是 WSL2 后端，容器访问 Windows 文件系统的性能很差，上传大 PDF 时容易超时。建议在 WSL2 内部完成整个项目的部署，不要让 docker 跨文件系统挂载。

注意：Docker Desktop 默认 2GB 内存限制对 Dify 可能不够。在 Docker Desktop 的 Settings -> Resources 里调到 4GB 以上，否则多个容器同时运行时会有莫名其妙的 502。

2.4 SSL 和模型凭证那些莫名其妙的错

部署完成后，进入管理后台配置模型供应商。热词里提到“dify ssl错误”，这个错误最常出现在本地部署时连接云端模型 API 的场景，例如用 HTTPS 调用 OpenAI-compatible 接口时，容器内的 CA 证书链不完整导致验证失败。表现是测试模型连接时，界面提示SSL error。

处理方式有两个：一是把模型 API 的网络请求代理到可信任的网关，保证证书链完整；二是在模型的API 类型里选择OpenAI-API-compatible模式，并通过环境变量覆盖 SSL 验证行为。不过最稳妥的做法是尽量给请求走正规域名和有效证书，而不是一刀切关闭验证。

另一个高频报错是An error occurred during credentials validation。这个我一开始以为是网络问题，反复检查 API Key 之后才发现是模型供应商类型选错。Dify 里不同模型供应商的凭证字段不一样，比如某些国产模型服务虽然在接口格式上兼容 OpenAI，但在 Dify 里要选择对应的供应商类型，而且 base URL 不能带多余的路径。正确填写格式应该是https://api.example.com/v1而不是https://api.example.com。

3. 知识库构建：从 100 页手册到高质量分段

3.1 文档清洗与格式归并

知识库质量的上限，在文档处理阶段就决定了。很多人直接上传 PDF 然后期待系统“智能处理”，这是不现实的——至少现在的开源工具链还没到这个水平。

我的处理流程是先把手头所有文档统一转成 PDF 或 Markdown，再进行清洗。Word 排版里常见的人工缩进、目录页、页眉页脚、批注框，这些内容如果不处理，会作为正文被切进知识库，检索时召回到一堆“第 2 页，共 100 页”这种垃圾片段，非常影响回答质量。

清洗工具我用的是 Pandoc 配合正则表达式做前置处理。比如把手册里大量的“图 3-1 设备前面板”这类标题保留为段落标题，把“（续）”这种跨页残留删除，把扫描图片层叠的文字用 OCR 提取出来再合并。这一步虽然繁琐，但值得做。

清洗完成后，还要注意文档内部的层级信息。手册里的“章节”“小节”“条款”在转成纯文本后会丢失结构化信息。因此我建议在清洗阶段保留一个“元数据模板”：每段文本前面标注其所属章节路径，例如[第4章 > 4.2 故障诊断 > 4.2.1 E203 错误]。这一步对后续引用溯源非常重要。

3.2 分段策略：切分逻辑决定检索上限

Dify 知识库创建时会有分段设置界面，里面有几个关键参数：分段标识符、最大分段长度、分段重叠长度。默认配置通常只是按换行符和 1000 字符切分，对技术手册来说效果一般。

技术手册的特点：列表密集、代码块多、步骤编号明显。如果用纯换行符切分，一个步骤列表可能被拦腰切断；代码块如果被切散，检索回来模型看不懂命令上下文。我最终选择了自定义分段规则。

分段标识符我加入了“。”和“\n”以及“步骤编号”的组合，不单纯依赖一种。最大分段长度设为 500 个字符，重叠长度设置为 50 个字符。这里的关键逻辑是：分段长度不一定越大越好，因为向量检索的精度会随片段变长而下降；但分段太小又会丢失上下文。500 字符对一个技术问答场景来说是比较合适的折中。

重叠区的作用是防止检索时“切割处恰好丢失关键信息”。举个例子，手册里“请勿在设备通电状态下插拔主板排线，否则会造成短路”这句话如果被切成两段，前一段末尾是“插拔主板”，后一段开头是“排线，否则造成短路”。当用户问“插拔排线有什么风险”时，两段单独向量化后都不太可能被高质量召回，重叠区让这个句子在切分点前后各保留一次，有效提升召回率。

3.3 父子分块与引用回溯

单纯分段切出来的是“叶子片段”，但一个答案如果需要完整的“操作背景 + 具体步骤 + 注意事项”，往往需要跨多个片段召回。Dify 提供了“父子分块”模式（Parent-Child 模式）：父块按大段落划分，保留完整上下文；子块按更细的粒度切分，用于向量化检索；系统先命中子块，再返回对应的父块给模型。

这个模式对 100 页手册这种内容非常适用。因为手册里很多“注意”“警告”后面跟的是一整段操作描述，如果只召回警告本身，模型不知道这个警告是针对哪个操作步骤，回答会显得孤立。父子分块让模型拿到的是具备上下文的完整段落。代价是 token 消耗变大，因为每次输入要附带父块内容，但这个成本在内部场景下可接受。

另一个容易忽略的是“引用回溯”设置在 Dify 里对应的是“引用归属”功能。开启后，对话回答会附带引用来源，例如来源: 手册V2.1_第6章。对于内部使用场景，这个功能不只是为了显示版权来源，更重要的是让使用者能回到原文验证 AI 说的话，减少“AI 胡说但我找不到依据”的信任问题。

3.4 图片和扫描件怎么处理

热词里有“rag知识库能存储图片嘛”，答案是能，但不能直接把图片丢进去就完事。图片里的文字不会被默认的文本解析器读取，必须先把图片内容转成文字才能参与检索。

对扫描版 PDF，我用 OCR 工具做了一次批量文字提取，然后把 OCR 出来的文本和原图关联保存。Dify 知识库上传时可以选择“文档”类型，把处理后的文本上传；图片本身如果需要在回答中展示，可以把图片放到对象存储或附件目录，在回答里以 Markdown 形式引用。

如果手册里有大量包含电路图、拓扑图的页面，建议不要强行做 OCR。线缆连接类图表转成文字后信息损失很大，机器根本看不出哪根线接哪个口。这种图更适合保留原图，并在知识库里单独建立一个“图表索引”：把图表标题和关键字录入文本，同时保存图片路径。用户问“设备背面接口分布”时，系统召回的不是图片，而是对应文字描述和图片路径说明。

心得：知识库不是越“多模态”越好。对文档场景，文字描述永远是检索的主力，图片是辅助展示。别花太多精力让模型“看懂图”，不如让模型“找到图对应的文字说明”。

4. 检索与生成：让 RAG 真正“答得准”

4.1 Embedding 模型选择

分段只是基础，真正决定召回质量的是 embedding 模型。Dify 支持在系统设置里配置多个 embedding 模型，不同知识库可以选用不同模型。我在对比中文文档场景后发现，通用英文 embedding 模型对中文技术术语的支持往往不如中文优化的模型。

这个项目我选用了 BGE-M3 系列。它的特点是支持中文、英文混合输入，对长文本和多语言实体有较好的表现。它还能输出 1024 维的向量，在 Dify 里可以直接通过本地模型服务接入，不依赖外部 API。对需要内网部署的场景，这是一大优势。

接入 Dify 时，需要把模型配置到“系统模型-Embedding 模型”里。这里有一个细节：检索测试结果显示的“相关性分数”并不是绝对的，不同 embedding 模型的分数区间不同，所以不要拿两个模型的分数直接对比，应该在同一模型下对比不同查询语句的召回结果。

4.2 召回模式的取舍

Dify 知识库默认有三种检索模式：向量检索、全文检索、混合检索。向量检索靠语义相似度，能处理“换个说法问同一件事”的情况；全文检索靠关键词匹配，能处理专有名词和故障码精确匹配。混合检索把两者结合起来，再通过 RRF 或分数融合排序。

对于技术手册，我的建议是无脑选混合检索。原因在于故障码、型号名、命令参数这类内容，语义检索经常“漂移”。例如用户提问“E203 复位失败”，向量检索可能召回一堆“设备复位”通用内容，而全文检索能精确定位到手册中所有包含“E203”的段落，二者结合才能在准确性和泛化性之间取平衡。

混合检索的速度会略慢，但在知识库规模不大（几千个片段）时感知不到差异。如果未来知识库膨胀到百万片段级别，再考虑切分索引和分库策略也不迟。

4.3 Rerank 重排的必要性

混合检索召回的片段可能有一二十条，但送给大模型的输入宽度有限，必须做第二步筛选。Dify 支持配置 Rerank 模型，这个组件的作用是对召回的候选片段做一次精细的相关性打分，把最符合用户当前问题语义的片段排到最前面。

我第一次测试时没有配置 Rerank，效果是：回答内容能找到相关信息，但顺序很乱，经常先说细节再说背景，读起来不像人话。配置了 Rerank 之后，模型拿到的片段顺序更符合问答逻辑，回答质量明显提升。

Rerank 模型的选型没有什么悬念，直接用了 BGE-reranker-base，同样跑在本地。Dify 里 Rerank 模型是在知识库的“检索设置”中单独配置的，和 Embedding 模型分开。需要留意的是，Rerank 模型对算力有一定要求，纯 CPU 推理会比较慢，建议用 GPU 机器部署，或者把 Rerank 的候选数量调小一点。

4.4 提示词编排和引用

知识库接好后，应用端的提示词决定了“拿到检索片段能否组织出好答案”。Dify 的聊天助手应用里有一个“上下文”变量，系统会把检索到的知识片段自动塞进去。我的提示词策略很简单：

• 开头明确角色：你是一名售后技术支持工程师
• 明确依据来源：只依据“上下文”中的知识内容回答，不要使用预训练记忆
• 处理缺失：如果上下文中没有相关信息，明确回答“手册中未找到相关内容”，并建议用户联系技术支持，不要编造
• 组织格式：先给结论，然后分点说明操作步骤，最后给出注意事项

这套提示词同时约束了模型的“行为边界”和“输出格式”。Dify 支持在“上下文”前插入相关的对话历史，实现多轮追问时系统会重新检索。注意，不要把检索逻辑写进提示词里，那是编排系统的工作。

此外，Dify 的聊天界面可以开启“引用和归属”展示。开启后，回答下方会显示“引用 #1, #2”，点击即可跳转到知识库对应文档。实测下来用户非常喜欢这个功能，因为他们能亲手验证 AI 的答案是否有出处。

5. 应用上线与验证：从“能聊”到“能用”

5.1 对话助手与 Agent 模式的差异

Dify 里创建应用时，可以选择聊天助手（Chatbot）或 Agent 模式。知识库 RAG 的基础应用一般是 Chatbot，它处理“问题 -> 检索 -> 生成”一步到位。而 Agent 模式则会结合用户的提问决定是否调用工具、调用哪个工具、需要几轮检索，它适合更复杂的任务编排。

这个项目里我两个模式都做了实验。简单问答场景下，Agent 模式的优势不明显，反而因为多了一次模型决策增加了延迟。但遇到“综合对比 E203 和 E205 两个错误码的异同”这类问题时，Agent 模式会先做一次检索，发现信息不足后自动调整关键词再检索，效果更贴近人工向手册的过程。

Agent 模式还有一个叫“Agentic RAG”的玩法：给 Agent 配一个“查阅知识库”的工具，并允许它多轮调用。这在手册内容高度碎片化、一个答案需要聚合多个章节的场景下非常有用。代价是需要更精细的提示词和工具描述，否则 Agent 会陷入无意义的反复检索。

5.2 用测试集量化效果

效果好不好不能靠感觉。Dify 应用页面可以开启“模型响应”的日志功能，把用户真实提问记录下来。但我更推荐先准备一批固定测试问法，围绕手册核心内容设计 30-50 个问题，每个问题手工写好标准答案或答案要点。

我用的评估维度有三个：召回准确率（检索片段是否包含关键信息）、回答准确性（模型生成是否和手册一致）、格式友好度（步骤是否清晰、是否给出注意事项）。对每一条测试问题都打勾，统计正确率。第一次测试我的正确率只有 68%，问题集中在“多个错误码一起出现”的复合问题上，后来调整分段策略和 Rerank 配置后提升到 90% 左右。

注意：Dify 的在线评测功能需要后期版本才支持，社区版建议用外部脚本或 Excel 管理测试集。关键是保持同一测试集多次评测，才能看出参数调整带来的真实效果。

5.3 多轮追问的上下文逻辑

上线后用户反馈里有一个高频场景：第一问“E203 怎么处理”回答正确，追问“那如果复位失败呢”就答非所问。这是因为缺省对话模式下，新一轮检索不一定带上历史问题，模型也可能丢失上一轮的焦点。

这个问题要从两方面解决。第一，Dify 应用设置里可以配置“对话轮次窗口”，把最近几轮对话历史一并作为上下文给模型；第二，在提示词里强调“如果用户的问题是在讨论上一轮提到的故障码，默认延续上一主题，不要理解成全新问题”。实测调整后，追问场景的正确率明显上升。

如果内部使用的时候允许用户上传截图或日志文件，还可以把“图片理解”能力和知识库问答结合起来。不过这个项目我没有开，因为设备日志属于敏感数据，线上演示时截个图还好，日常使用还得过合规审批。

6. 常见问题速查：部署和使用中遇到的高频报错

整理一下这个项目从搭建到落地期间遇到的高频问题，做成表格方便排查。

还有一类问题不是报错，但特别影响体验：用户问“这个手册多少钱”这类知识库外问题，模型会基于预训练记忆胡乱回答。我通过提示词和“知识库回答受限”功能把这类问题拦截掉，统一返回“手册未包含此信息”。内部使用的知识库应用不怕答不上来，最怕答错。

另外热词里提到的“dify 迁移”和“dify 二次开发”，顺手提两句：Dify 的迁移主要涉及 PostgreSQL 数据、向量库数据和文件存储三块，迁移前做好快照，版本跨度大的先备份再升级；二次开发一般是通过 Dify 的 API 网关做集成，不要直接改前端源码，否则升级时全丢。

7. 上线的最后一公里：模型参数与人员习惯

系统搭好只是第一步，真正让它被日常业务接受，需要调整几个容易被忽略的小参数。Dify 应用设置里的“温度”参数，我调到了 0.2 左右。知识库问答场景要的是稳定复述手册内容，不是创造性发挥，温度调高会出现“一本正经地过度解释”。

Top P 也按默认值不动。有些模型服务商文档里把 Top P 和温度并列介绍，但在知识库问答里同时调低两者会过度压制输出多样性，导致格式不稳定，答案出现“回答一半就截止”的情况。

上线后我还安排了一次小范围试用，让三位一线技术支持工程师用了一周，收集了他们的使用习惯。结果发现一个之前没想到的需求：他们不光问手册内容，还会问“系统日志里出现disk write error该怎么定位”，这个其实是需要结合手册和现场日志联合推理的问题，直接靠知识库 RAG 回答不了，得靠 Agent 流程串联多个工具。目前这个需求已经作为下一期的演进方向了。

经验：不要把 RAG 知识库当作“最终答案机器”，它是“高效查手册工具”。先解决 80% 的查阅类问题，再谈复杂推理和跨系统联动，这样项目周期可控，效果也更容易量化。

我个人在实际操作中最深的一个体会是：RAG 项目的重头戏从来不在“AI”那部分，而在文档处理和分段策略上。embedding 模型、Rerank 模型、提示词这些都是“标配”，谁都能选准；真正拉开效果差距的，是你愿不愿意花一整天去清洗那 100 页手册、一行一行看分段结果、反复用真实问题测试召回效果。Dify 的价值在于把这些环节串成了可以迭代优化的流水线，而不是替你解决内容质量问题。现在这个知识库已经稳定运行几周，每天被调用上百次，最让我满意的不是回答有多“聪明”，而是每一次回答都能明确告诉你“我依据了手册哪一章”——这种感觉，才是企业内部 AI 应用真正可靠的基石。