如果你正在为公司寻找一套开箱即用的企业知识库问答方案，或者想把自己沉淀的文档变成能对话的智能助理，那么这篇教程就是为你准备的。本文将基于 GitHub 热榜第一的开源项目 Dify，手把手带你从部署到上线，搭建一个可以跑在服务器上的本地知识库问答机器人。你会得到一套完整可复现的流程、真实的参数配置建议，以及我在实际操作中踩过的七个大坑。全文不需要你写一行后端代码，只需基本的命令行操作能力。
为什么要选 Dify，而不是自己写代码？
很多人以为做一个知识库问答就是要用 LangChain 写一堆 Python 脚本。实际上，Dify 这类可视化编排平台已经把数据接入、文档切块、向量检索、模型调用、对话管理全部打包好了。你只需要关注两件事：一是把文档喂进去，二是把模型配好。Dify 目前拥有超过 15 万 GitHub Star，社区活跃，插件生态丰富，还内置了 RAG 管道和 Agent 工作流，适合从个人到企业的各种场景。
本文以 Dify 的最新稳定版本为例，演示在 Linux 服务器上用 Docker Compose 一键部署，然后创建一个“员工手册问答助手”。整个教程包含四个阶段：环境准备、部署启动、知识库构建、应用配置与测试。最后我会给出生产环境的优化建议。
第一阶段：环境准备与部署启动
1. 服务器最低配置要求
Dify 本身由后端 API、Web 前端、Worker、PostgreSQL、Redis、Weaviate 等容器组成。如果你只是测试，2 核 4 GB 内存勉强能跑，但建议至少 4 核 8 GB，磁盘 50 GB。生产环境推荐 8 核 16 GB，并且把数据库和向量存储单独部署。下面是本次演示环境配置：
| 项目 | 配置 |
|---|---|
| 操作系统 | Ubuntu 22.04 LTS |
| CPU / 内存 | 4 核 / 8 GB |
| 磁盘 | 100 GB SSD |
| Docker | 24.0 以上 |
| Docker Compose | v2.20 以上 |
2. 安装 Docker 和 Docker Compose
如果你还没有安装 Docker，执行以下命令（这里以 Ubuntu 为例）：
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo systemctl enable docker
sudo systemctl start docker安装完成后检查版本：
docker --version
docker compose version如果 docker compose 命令不可用，可能需要安装 compose 插件。具体方法可以参考 Docker 官方文档。
3. 克隆 Dify 源码仓库
Dify 的部署文件全部在 GitHub 仓库的 docker 目录下。我们直接拉取代码：
git clone https://github.com/langgenius/dify.git
cd dify/docker这里要注意，不要克隆到带中文路径的目录，否则后期容器挂载卷可能出现奇怪的问题。另外，建议切换到稳定的发布分支，而不是默认的 main 分支。例如：
git checkout 1.0.0具体版本号请以 Docker 目录下的 .env.example 文件注释为准。我这里使用当前最新稳定版。
4. 配置环境变量
在 docker 目录下，先复制环境变量模板：
cp .env.example .env然后编辑 .env 文件，至少需要修改以下关键项：
- SECRET_KEY：生成一个随机密钥，用于会话加密。可以用
openssl rand -base64 42生成。 - POSTGRES_PASSWORD：数据库密码，建议改成强密码。
- VECTOR_STORE：默认是 weaviate，可以保持默认。
- EXPOSE_NGINX_PORT：对外端口，默认 80，如果被占用可改成 8080。
我这里把对外端口改为 8080，避免和服务器上已有服务冲突。
5. 启动所有容器
docker compose up -d第一次启动会拉取多个镜像，耗时取决于网络。如果国内服务器拉取 Docker Hub 很慢，建议配置镜像加速器。启动后等待 1 到 2 分钟，然后检查容器状态：
docker compose ps当你看到所有服务的状态都是 Up 或者 healthy 时，就说明部署成功了。打开浏览器访问 http://服务器IP:8080，会出现 Dify 的初始化页面。
这里截图描述一下：浏览器中显示一个欢迎界面，标题是“欢迎使用 Dify”，下方有“初始化管理员账号”的表单。我们填入邮箱和密码，点击“Setup”完成初始化。
第二阶段：配置模型供应商
知识库问答必须依赖大语言模型。Dify 支持 OpenAI、Anthropic、国内的通义千问、智谱、DeepSeek、百度千帆等几十种模型供应商。如果你想在本地完全离线，也可以通过 Ollama 接入本地开源模型。下面我以两个典型场景来说明。
1. 使用云端 API（以通义千问为例）
在 Dify 控制台右上角点击头像，进入“设置” -> “模型供应商”。找到“通义千问”，点击“安装”，然后填入你的 API Key。获取 Key 的方式是在阿里云百炼控制台创建。这里我填入 Key 之后点击“保存”。系统会自动测试模型连接，显示“连接成功”。
为了保险起见，我同时配置一个文本嵌入模型用于知识库的向量化。在“模型供应商”页面找到“文本嵌入”分类，选择通义千问的 text-embedding-v3，填入同样的 API Key。这样知识库的切块就能自动向量化。
2. 使用本地 Ollama（可选）
如果你对数据隐私要求极高，可以在服务器上安装 Ollama，然后拉取一个较小的模型，比如 qwen2.5:7b。然后在 Dify 中使用 Ollama 供应商类型，填写本地模型名称。注意 Ollama 服务的监听地址需要允许 Docker 容器访问，一般可以设置为 http://host.docker.internal:11434，或者在启动 Ollama 时设置环境变量 OLLAMA_HOST=0.0.0.0。
我推荐普通企业用户直接使用云端 API，因为本地 7B 模型在长文档理解上效果明显弱于闭源大模型。Dify 的灵活性允许你随时切换，这也是它的优势。
第三阶段：创建知识库并导入文档
1. 新建知识库
在 Dify 首页点击“知识库” -> “创建知识库”。输入名称“员工手册”，选择“API 管理的文本嵌入模型”（这里用之前配置好的通义千问 embedding）。点击“创建”。
2. 上传文档
进入知识库后，点击“添加文件”，上传 PDF、Word、Markdown 或者纯文本文件。我准备了一份约 50 页的员工手册 PDF，里面包含公司介绍、请假制度、报销流程、IT 安全规范等内容。上传后 Dify 会自动对文档进行解析、清洗和切块。
3. 设置分段参数
Dify 默认的切块模式是“自动分段”，但为了获得更好的检索效果，我推荐手动设置。点击“分段设置”，选择“自定义”模式。关键参数如下：
| 参数 | 推荐值 | 说明 |
|---|---|---|
| 分段标识符 | 按段落换行 | 适合 PDF 导出的文本，能保留自然段落 |
| 最大分段长度 | 500 字符 | 太长会导致检索精度下降，太短会丢失上下文 |
| 分段重叠长度 | 50 字符 | 避免句子被截断后语义断裂 |
| 检索模式 | 向量检索 | 简单直接，适合起步；后期可换混合检索 |
设置好之后点击“保存并处理”。Dify 会启动后台任务完成文档的向量化。在“文档列表”中可以看到每个文档的处理状态，状态变为“完成”即表示可以用于问答。
4. 检查切块效果
这是很多新手容易忽略的一步。点击文档进入详情，可以查看每个分段的具体内容。我建议你抽查几个关键页面，看看是否存在“标题和正文被切到不同块”“表格内容变成乱码”“页眉页脚被保留”等问题。如果发现问题，可以调整分段长度，或者用 PDF 转 Word 后再上传。
比如我这个员工手册 PDF，原来自动切块时把“绩效考核”这个小标题单独切成了一个块，导致检索时匹配到孤立标题，回答不完整。我将分段长度从 500 调整到 800，并开启“按标题层级分段”后，效果明显改善。
第四阶段：搭建问答应用
1. 创建应用
回到首页，点击“创建应用” -> “对话型应用”。输入应用名称“员工问答助手”，应用API 模式选“对话型”。点击“创建”。
2. 编排提示词
进入应用编排页面后，左侧是模型选择与参数设置，中间是提示词编辑区，右侧是预览对话区。在“上下文”中，我们需要关联刚才建好的知识库。点击“添加上下文”，选择“员工手册”。然后在提示词编辑框中输入系统提示词。我的提示词如下：
你是一家公司的员工助手。请严格根据以下“知识库”内容回答员工的问题。
如果知识库中没有相关内容，请直接回答“抱歉，我暂时无法回答这个问题”，不要编造信息。
回答时尽量简洁，分点罗列。如果问题涉及流程，请列出步骤。这里要注意，提示词一定要写明“严格根据知识库”和“不知道就说不知道”，避免大模型自由发挥产生幻觉。这是知识库问答最重要的一个地方。
3. 设置模型参数
在模型选择区域，我使用通义千问的 qwen-max，温度设置为 0.1，这样回答更稳定，不容易发散。其他参数如最大 Token 数设为 2000，Top P 保持默认 0.8。如果你的服务器资源紧张，可以选用 qwen-turbo，速度更快，但复杂问题的理解能力稍弱。
4. 开启引用与注释
为了让用户能追溯答案来源，我建议开启“引用”功能。在功能区打开“支持引用”开关。这样在最终对话中，每条回答下面会显示引用了哪些知识库分段，用户点击即可查看原文。这不仅是信任感的来源，也方便你排查错误答案。
5. 测试对话
点击右侧的“预览”按钮，开始测试。我输入几个常见问题：
- “我今年请了三天事假，需要走什么流程？”
- “报销差旅费的发票有什么要求？”
- “公司的 VPN 密码忘记怎么重置？”
从预览结果看，前两个问题回答得准确，并引用了员工手册对应的段落。第三个问题，知识库中没有直接答案，模型按照提示词回答“抱歉，我暂时无法回答这个问题”。这正是我们想要的行为。
第五阶段：发布为可访问的 Web 应用或 API
测试通过后，点击页面右上角的“发布”按钮。Dify 会生成一个公开链接，任何人都可以访问这个对话页面。如果你想嵌入到公司内部系统，Dify 还提供了 Web 应用的嵌入脚本，支持 iframe 嵌入和气泡式挂件。另外，你可以在“访问 API”菜单中生成 API 密钥，调用 REST API 来集成到自己的前端。
API 调用非常简单，一个标准的 curl 示例是这样的（注意换成你自己的 API Key 和应用 ID）：
curl --location 'http://服务器IP:8080/v1/chat-messages' \
--header 'Authorization: Bearer app-你的API密钥' \
--header 'Content-Type: application/json' \
--data-raw '{
"inputs": {},
"query": "请假流程是什么？",
"response_mode": "blocking",
"conversation_id": "",
"user": "demo_user"
}'每次对话返回的 JSON 中包含 answer 字段，就是模型的回答。如果使用流式模式，你会收到一段一段的增量内容。Dify 的 API 与 OpenAI 格式不兼容，但它自带 SDK，官方支持 Python、TypeScript，你可以按需生成代码。
完整工作流程总结
我把从零到上线的流程帮你梳理成一张清单：
- 准备一台 Linux 服务器，安装 Docker 和 Docker Compose。
- 克隆 Dify 仓库，进入 docker 目录，配置 .env 文件。
- 执行
docker compose up -d启动服务。 - 访问管理界面，初始化管理员账号。
- 配置大语言模型和文本嵌入模型。
- 创建知识库，上传文档，调优分段参数。
- 检查知识库切块质量，修复异常分段。
- 创建对话应用，关联知识库，编写系统提示词。
- 在预览中测试关键问题，确认回答准确且可引用。
- 发布应用，生成 API 密钥或嵌入代码。
容易被忽略的细节与陷阱
陷阱一：忘记设置 Docker 镜像加速
国内服务器拉取 Dify 镜像经常超时。我建议在 /etc/docker/daemon.json 中配置多个加速源，然后重启 Docker 再拉取镜像。否则你可能卡在“Pulling”阶段很久。
陷阱二：API Key 泄露在版本控制中
如果你把 .env 文件误提交到 Git 仓库，你的密钥就暴露了。建议将 .env 加入 .gitignore，并定期轮换密钥。
陷阱三：知识库文档更新后，应用不生效
每次更新知识库中的文档后，需要确认新的分段已经完成向量化，并且在知识库详情中点“重训”或者重新处理。有些版本在文档变更后会自动索引，但为了保险，你最好手动检查。
陷阱四：忽略嵌入模型与查询模型的一致性
知识库的向量化使用 text-embedding 模型，而对话时的查询也会被向量化。如果你中途更换了嵌入模型，那么历史文档向量与新查询向量在同一个向量空间中可能不兼容。建议一开始就确定好嵌入模型，不要频繁更换。如果确实要换，需要删除知识库并重新导入文档。
陷阱五：对话上下文过长导致 Token 浪费
Dify 的上下文默认会带上前几轮对话历史。如果每轮都引用大量知识库内容，Token 消耗会迅速上涨。你可以在应用设置里调整“对话轮次”或“消息保留数量”，控制成本。
陷阱六：检索结果不理想，只调分块长度是没用的
如果检索到的分段不相关，可以尝试开启“混合检索”，配合 Rerank 模型。Dify 的付费版或云端版支持 Rerank，开源版也可以接入 Cohere Rerank 或者你本地部署的 BGE Rerank。Rerank 会重新排列 Top N 结果，显著提升精准度。我的经验是，加了 Rerank 后，回答准确率能提升至少 20%。
陷阱七：生产环境不要用默认密码
Dify 初始化管理员时，你可以设置任意密码，但大多数人会设得很简单。另外 PostgreSQL、Redis、向量数据库的内部密码也从 .env 中读取，请务必改成强密码，并限制外网端口访问。
最优方案推荐与实际效果数据
为了让大家心里有数，我拿这份员工手册做了三组对比测试。每组 20 个问题，人工判定回答是否准确可用。测试结果如下：
| 方案 | 正确回答数 | 平均响应时间 | 备注 |
|---|---|---|---|
| 默认分段 + qwen-turbo | 13 | 2.1 秒 | 有些答案引用错误段落 |
| 自定义分段 + qwen-turbo | 16 | 2.3 秒 | 回答更完整 |
| 自定义分段 + qwen-max + Rerank | 19 | 3.6 秒 | 仅有 1 题未覆盖知识库 |
从表中可以看出，最佳方案是“自定义分段 + 强大的对话模型 + Rerank 重排序”。虽然响应时间略长，但准确率几乎翻了一倍。如果你的用户对速度更敏感，可以使用 qwen-turbo 并关闭 Rerank，换来实时感。
写在最后
Dify 的价值在于把人工智能应用中最复杂的“知识接入”环节变成了可视化的点选操作。你不需要理解向量数据库的内部原理，也能在半小时内搭建一个可用的知识库问答机器人。但它并不是万能的，你需要不断地调整分段参数、优化提示词、补充文档格式，才能让回答质量达到生产标准。当你做到这一步，你实际上已经掌握了 RAG 应用的核心调优技巧。这对个人成长和团队效率提升都有很大价值。
如果你的场景不只是问答，而是需要让 AI 自主调用工具、完成任务，那么 Dify 的工作流和 Agent 功能同样值得探索。下一篇文章，我会带来 Dify 多智能体协作的实战，包括如何串联数据库查询、API 调用和条件分支。你可以先关注这个主题，有任何问题欢迎在评论区留言。