企业官网建设流程全解析

1. 为什么 Dify 被越来越多团队当成 AI 应用底座？

过去一年里，大模型应用落地的方式发生了很明显的变化。早期很多团队是直接调 OpenAI 或国产大模型的 API，把 key 写在代码里，prompt 靠程序拼接，文档检索自己写向量库逻辑，流程编排全靠代码堆。但这种做法在真正做产品时会遇到几个绕不开的问题：模型切换成本高、提示词反复改要重新发版、知识库和对话逻辑耦合太深、给非技术同事演示时全靠开发人员操作。Dify 这类 LLMOps 平台解决的就是这些问题。

Dify 是一个开源的大模型应用开发平台，核心定位是让开发者用可视化方式编排 Agent、工作流和 RAG 知识库应用，同时保留 API 接入能力。它不是一个简单的聊天框封装，而是把模型管理、提示词管理、知识库、工具调用、日志观测、数据集标注这些环节统一到一个平台里。你可以把它理解为面向 LLM 应用的“后端低代码平台”：复杂逻辑用工作流画出来，模型统一接入，知识库可视化管理，最终通过 API 或网页嵌入对外提供服务。

这篇文章会围绕一个相对完整的实战链路展开：用 Docker 完成 Dify 私有化部署，接入本地或云端大模型，搭建一个基于 RAG 的知识库，创建一个带有工具调用能力的 Agent（示例场景选择三角洲游戏攻略问答 Agent），最后把应用嵌入到网页里。对于正在做 AI 应用选型、或者想在企业内部搭建私有化大模型平台的团队来说，这套流程可以作为直接参考的落地路径。

2. 环境准备与 Docker 部署

2.1 部署前需要确认的环境

在开始之前，先明确一下整套环境需要什么。Dify 本身是前后端分离的项目，后端使用 Python Flask 框架，前端是 Next.js，数据库使用 PostgreSQL，缓存使用 Redis，向量存储可选 Weaviate 或 Qdrant。官方提供了一键部署的 docker-compose 文件，所以对使用者的要求并不高，只要 Docker 环境正常即可。

如果你是 Windows 用户，需要注意 Docker Desktop 启动时比较常见的virtualization support not detected问题。这个报错通常是因为 BIOS 中没有开启虚拟化，或者 WSL2 没有正确安装。最简单的处理方式是：在任务管理器的“性能”页签查看虚拟化是否已启用，如果未启用，进入 BIOS 开启 Intel VT-x 或 AMD-V；同时确保控制面板里“适用于 Linux 的 Windows 子系统”功能已被勾选。

2.2 获取 Dify 源码与 docker-compose 文件

Dify 官方推荐的方式是克隆 GitHub 仓库，然后使用其中的 docker 目录启动服务。操作如下：

git clone https://github.com/langgenius/dify.git cd dify/docker

进入dify/docker目录后，可以看到.env.example文件。首次部署需要复制一份环境变量文件：

cp .env.example .env

这里需要说明一下，.env文件里包含了很多服务初始化变量，比如 PostgreSQL 密码、Redis 密码、向量数据库类型等。官方给的默认值可以直接用，但如果要在多环境部署，建议把密码改成强密码。Dify 的 compose 文件会读取.env中定义的变量来生成容器配置，直接修改docker-compose.yaml里的值反而可能造成不一致，这一点要格外注意。

2.3 启动 Dify 服务

环境变量文件准备好之后，执行启动命令：

docker compose up -d

第一次启动需要拉取多个镜像，包括api、web、postgres、redis、weaviate（或qdrant）等。镜像体积比较大，建议保持网络稳定。启动完成后，可以查看容器状态：

docker compose ps

正常情况下，你会看到api、web、db、redis、weaviate等容器处于 running 状态。Dify 的前端服务默认监听 3000 端口。打开浏览器访问：

http://localhost:3000

如果出现初始化管理员账号的页面，说明服务已经正常启动。在首次访问时，系统会要求设置管理员邮箱和密码，这一步完成之后进入主界面。

这里特别提醒一点：Dify 的web容器对外暴露的是 3000 端口，但实际项目中可能和已有服务冲突。如果 3000 端口被占用，可以在.env中修改EXPOSE_NGINX_PORT变量，然后重新执行docker compose up -d，前端入口也会随之改变。

2.4 升级与迁移注意事项

热词里出现了dify迁移和dify安装教程的需求，这里稍微扩展一句。Dify 的版本迭代速度很快，升级时一般执行下面的操作：

git pull origin main cd docker docker compose down docker compose up -d

但要注意，docker compose down 会删除容器，如果后端数据存储在 Docker Volume 中，数据不会丢失。如果迁移到另一台服务器，需要把 Docker Volume 目录一起备份，尤其是 PostgreSQL 和向量数据库的卷目录。这个操作属于有风险的生产级变更，建议先在一台测试机上演练一遍，确认数据完整再动生产环境。

3. 大模型接入：本地模型与云端 API 的选择

Dify 本身不提供模型算力，它只是模型的管理和调用网关。所以部署完 Dify 之后，第一步要做的就是接入模型。在“设置 - 模型供应商”页面里，可以看到 OpenAI、Azure OpenAI、Anthropic、通义千问、文心一言、智谱、Ollama 等多家供应商。不同供应商的接入方式略有差异，但大方向一致：配置 API Key、模型名称、模型类型。

3.1 接入云端大模型 API

以 OpenAI 为例，进入模型供应商页面，找到 OpenAI，填入 API Key 和对应的 Base URL。如果使用的是国内云的兼容接口，Base URL 可以改成对应的网关地址。这里不涉及任何特殊网络操作，只需要填官方控制台提供的合法密钥即可。

填写完成后点击“保存”，Dify 会调用一次凭据校验接口。如果出现an error occurred during credentials validation报错，常见原因有三个：

对于国内用户，更省心的方式可能是接智谱 GLM、通义千问这类国产模型，它们在控制台申请 API Key 之后即可使用，而且很多新用户都有免费额度。需要提醒的是，不同模型在工具调用、函数调用的支持力度上不同，Agent 类型的应用尽量选择支持工具调用的大模型，否则 Dify 需要依赖提示词方式模拟工具调用，在复杂场景下稳定性会差一些。

3.2 接入本地大模型（Ollama）

如果企业内部对数据安全要求较高，或者不想按 token 付费，可以部署本地大模型和 Dify 配合使用。Ollama 是目前最简单的本地模型运行时之一。在服务器上安装 Ollama 后，先拉取模型：

ollama pull qwen2.5:7b

然后启动模型服务：

ollama serve

Ollama 默认监听 11434 端口。回到 Dify 的模型供应商页面，找到 Ollama，按照下面的方式配置：

如果你是用 Docker Compose 启动的 Dify，宿主机 IP 不能写localhost，因为容器内部访问localhost指向的是容器本身。在 Linux 上可以填http://172.17.0.1:11434或宿主机局域网 IP；在 macOS 上填http://host.docker.internal:11434。Docker Desktop 会自动把host.docker.internal解析到宿主机，这是很多新手第一次接入本地模型最常见的坑。

3.3 免费大模型 API 和企业私有化的取舍

热词里反复出现“免费大模型api”和“企业大模型私有化部署”，这里结合选型给大家一个相对务实的判断标准：

• 个人学习和原型验证阶段，优先用云端免费额度或低价格模型，比如智谱、通义、百炼的试用额度，省时省力。
• 企业内部知识库场景，如果数据不敏感，可以先用云端 API 快速验证产品价值；如果数据敏感，就必须考虑私有化模型，Ollama + Qwen、vLLM + Qwen 都是可行的方向。
• 混合策略也是常见做法：对话模型用云端，Embedding 模型用本地。因为 Embedding 模型参数规模小，本地跑起来压力不大，而对话场景对模型质量更敏感。

4. RAG 知识库：从原理到完整配置

4.1 RAG 到底是什么，为什么要用知识库

RAG 的全称是 Retrieval-Augmented Generation，检索增强生成。通俗解释是：当用户问一个问题时，系统不直接让大模型硬答，而是先从知识库里检索相关文档片段，把检索到的内容作为上下文和问题一起交给大模型，让大模型基于给定材料生成回答。

这种做法的价值很明显。大模型的训练数据有时间截断，对于企业内部文档、产品说明书、特定领域的实时内容，模型根本没见过。直接问，模型要么编造答案，要么回答“我不知道”。引入知识库之后，模型变成了一个“带着材料回答问题的人”，准确率会大幅提升。

在 Dify 中创建一个知识库非常简单。进入“知识库”页面，点击“创建知识库”，上传文档，系统会进行文本清洗、分段、向量化三步处理。最终文档会被拆成多个文本块，每个块通过 Embedding 模型转换成向量，存入向量数据库。用户提问时，系统将问题转换成向量，在向量库中执行相似度检索，找出最相关的若干文本块。

4.2 RAG 知识库与 KG 知识库的区别

搜索材料里出现了kg知识库、rag知识库和结构知识库区分以及应用场景，这里值得展开讲一下。RAG 知识库存储的是非结构化文本块，适合处理文档、手册、聊天记录这类内容，它的优点是搭建速度快，不需要定义实体关系，缺点是只做向量检索时对复杂逻辑推理支持有限。

KG（Knowledge Graph，知识图谱）知识库则是把知识建模成实体和关系，比如“《三角洲行动》的护甲分为 A、B 两级”，这里“护甲”和“等级”就是实体，它们之间的关系是“分为”。KG 适合处理强关联、多跳查询场景，但对文本抽取质量要求很高，建模成本也大。

Dify 目前主要还是以 RAG 路线为主，对于大多数文档问答场景，RAG + 正确的分段策略已经够用。如果未来遇到知识图谱需求，可以考虑引入专门的图数据库，再通过 API 集成到 Dify 工作流中。优先把 RAG 用明白，再去碰 KG，这个顺序对大多数团队更合理。

4.3 决定 RAG 效果的分段策略

很多同学把知识库效果不好归咎于“模型不行”，但实际影响最大的是分段（Chunking）策略。以游戏攻略类文档为例：

• 分段过大：比如把整篇攻略塞进一个 chunk，检索出来的内容太宽泛，大模型抓不住重点，回答就会啰嗦、偏题。
• 分段过小：比如把一句“护甲值减少50%”单独成段，上下文不完整，模型无法理解这句话是哪个模式下的规则。
• 合理分段：按章节或小节拆分，每段控制在 200 到 500 字左右，尽量保证一段包含一个完整知识点。

Dify 创建知识库时，可以在“分段设置”里调整分段标识和最大长度。对于政务法规类文档，可以按条款编号分段；对于游戏攻略类文档，按 Markdown 标题分段就很合适。同时开启“父子分段”或增加重叠字符数，能让检索结果在片段完整性和回答性能之间取得平衡。

4.4 实操上传与检索测试

为了演示，我们在 Dify 中创建一个名为“三角洲行动攻略库”的知识库，导入一篇游戏指南，分段方式选择自动分段的增强模式，索引方式选高质量（用 Embedding 模型）。上传完成后进入“召回测试”页面，输入类似“三角洲行动的护甲机制是什么”，查看召回结果。

这里要留意一个常见误区：召回测试看到的结果是“检索到什么”，不是“最终回答什么”。如果召回结果里已经出现了正确片段，但最终回答不对，问题出在提示词编排；如果召回结果里压根没有相关内容，问题出在分段或 Embedding 模型。这个排查思路可以帮你快速定位问题。

5. 三角洲游戏 Agent：工具调用与工作流编排

5.1 Agent 基本概念与架构选择

热词中出现多次agent、agent架构、ai agent。通俗地说，Agent就是让大模型不只是“聊天”，而是能自主决策：观察用户输入，拆解任务，调用工具，观察结果，再决定下一步动作的智能体。

在 Dify 中创建一个 Agent 应用有两种主要方式：

三角洲游戏 Agent 更适合使用 Chatflow 工作流。整个流程可以这样设计：用户输入问题 → 知识库检索 → 游戏百科工具查询 → 大模型总结回答。这样的设计既借助了 RAG 知识库补充攻略知识，又利用外部工具查询实时数据，同时用大模型作为最终的“主持人”组织答案。

5.2 工作流节点设计

创建一个 Chatflow 应用，命名为“三角洲行动战术助手”。在画布上依次添加以下节点：

1. 开始节点：接收用户输入。
2. 知识检索节点：关联“三角洲行动攻略库”，设置 topK 为 4，相似度阈值 0.5。
3. 工具节点：接入一个自定义 HTTP 工具，用于查询游戏弹药数据或地图信息。Dify 支持 OpenAPI schema 方式导入工具，也支持直接填写 URL 和参数映射。
4. 大模型节点：选用前面接入的对话模型，将知识库检索结果和工具返回结果拼接进系统提示词，让模型基于材料作答。
5. 结束节点：输出最终答案。

下面给一个工具接入的示例配置，假设我们需要一个根据武器名称返回弹匣容量的 HTTP API：

openapi: 3.0.0 info: title: Game Weapon API version: 1.0.0 servers: - url: https://your-game-api.example.com paths: /weapon/{name}: get: operationId: getWeaponInfo parameters: - name: name in: path required: true schema: type: string responses: '200': description: success

将这个 schema 导入 Dify 的工具列表，Dify 会自动解析出工具入参。实际请求的地址需要根据你的后端服务修改，这里的 URL 仅为示例。

5.3 提示词设计示例

在 Agent 或 Chatflow 的大模型节点中，提示词直接决定回答质量。下面是三角洲游戏助手系统提示词的一个参考模板：

你是“三角洲行动战术助手”，负责回答关于《三角洲行动》游戏机制、装备、地图、玩法的问题。 回答规则： 1. 优先参考知识库检索结果和工具查询结果，不要编造数据。 2. 如果知识库中没有相关内容，明确告知用户当前资料暂未覆盖。 3. 回答时给出数据来源，帮助用户判断可信度。 4. 保持简洁，先给出结论，再解释原因。

这段提示词里最关键的规则是第一条。很多 Agent 应用最后效果“一本正经胡说八道”，往往就是提示词里没有强约束模型必须基于检索内容回答。

5.4 调试与日志观测

Dify 的 Chatflow 画布上有一个“运行”按钮，可以在调试面板中单步执行。启动一次运行后，能看到知识检索节点命中了哪些文本块、工具节点返回了什么内容、大模型节点最终生成了什么结果。这在排查 RAG 和 Agent 问题时非常有用。

生产运行之后，在“日志”页面可以看到每次会话的完整过程。如果某次回答离预期很远，先看日志里是否检索到了相关片段，再看提示词变量是否被正确注入。日志是整个链路中最容易被忽略但价值最高的部分。

6. 网页嵌入与发布

6.1 网页嵌入的原理

Dify 创建的每一个应用都可以发布为可嵌入的 Web App。这个功能对实际项目非常实用：不需要单独写一个前端聊天页面，只需要在现有网站里嵌入一段 iframe 代码，对话界面就能直接工作。

在应用管理页的“发布”标签中，选择“嵌入 iframe”，Dify 会生成一段类似下面的代码：

<iframe src="http://localhost:3000/chat/your-app-token" style="width: 100%; height: 700px; border: none;" ></iframe>

把这段代码放到你自己的网页 HTML 中，比如活动页、产品官网、内部管理后台，都可以。Dify 的 Web App 支持流式回答，用户交互体验和原生页面差别不大。

6.2 鉴权与访问控制

默认情况下，iframe 嵌入的连接是公开的，谁拿到 URL 都能访问。如果只希望特定用户使用，有两个方向：

• 用 Web App 的 API 接口代替 iframe，在后端调用 Dify API，把应用令牌放到服务端，不在前端暴露。
• Dify 提供 API 访问令牌机制，通过Authorization: Bearer <app-token>调用/chat-messages接口。这是生产环境更推荐的做法。

下面是一个 Python 调用 Dify 对话接口的示例：

import requests url = "http://localhost:3000/v1/chat-messages" headers = { "Authorization": "Bearer app-xxxxxxxxx", "Content-Type": "application/json" } payload = { "inputs": {}, "query": "三角洲行动中哪把冲锋枪最适合近距离作战？", "response_mode": "blocking", "user": "user-123", "conversation_id": "" } resp = requests.post(url, headers=headers, json=payload) print(resp.json())

这个示例说明的是接入思路：iframe 适合快速演示，API 方式适合集成到正式系统。使用 API 时需要妥善保存应用令牌，不要把令牌硬编码在前端页面中。

7. 常见问题与排查清单

7.1 高频报错汇总

7.2 排查清单

遇到 Dify 异常时，不建议直接重装。按下面的顺序排查会更高效：

1. 看容器状态：docker compose ps，确认异常容器的名字。
2. 看容器日志：docker compose logs <container-name>，找到关键报错行。
3. 看模型配置：确认供应商页面是否能通过凭据校验。
4. 看知识库状态：确认文档分块和索引是否完成。
5. 看应用日志：定位失败节点发生在检索、工具还是模型生成环节。

8. 最佳实践与工程建议

8.1 配置管理建议

Dify 的.env文件在集群化部署中应当纳入配置管理，不要直接塞进代码仓库。内部部署可以把敏感变量放到密钥管理系统中，启动时动态注入。涉及docker compose down和配置变更时，先在一台测试机完整验证，再操作生产环境。

8.2 知识库更新机制

知识库不是“上传一次就不管了”。文档更新后，要重新执行索引。对于高频更新内容，可以考虑把文档放进对象存储，用脚本自动触发 Dify 的文档更新接口。但在动手之前，建议先确认你使用版本的 Dify 知识库 API 是否可用，各版本接口有一定差异。

8.3 成本与性能优化

大模型 API 调用成本是生产环境的主要风险之一。可以从四个方向控制：

• 设置模型节点的最大 token 上限，避免长文本上下文消耗过多。
• 合理设置知识库检索 topK，不需要一次性塞入太多片段。
• 在路由层做简单缓存，相同的问题直接命中缓存答案。
• 对 Agent 工具调用增加超时限制，避免某个工具故障导致整条链路变慢。

8.4 Agent 安全边界

热词里出现了agent安全，这里必须强调一句。如果需要给 Agent 接入执行类工具，比如修改数据库、发送邮件、调用支付接口，务必遵循最小权限原则。工具节点应该只暴露必要的动作，不能把整个系统的写接口直接交给模型调用。同时记录 Agent 每一次工具调用的输入输出日志，便于审计和回溯。

9. 总结与进一步学习方向

这篇文章从 Docker 部署 Dify 开始，走完了大模型接入、RAG 知识库构建、三角洲游戏 Agent 工作流编排、网页嵌入和 API 接入的完整链路。掌握了这些内容，你已经具备在企业内部搭建一套可用的大模型问答应用的基础能力。

接下来可以继续深入的方向包括：Dify 的插件机制与自定义工具开发、用 Dify 的 API 与 Spring Boot 后端整合、基于 Weaviate 或 Qdrant 的向量检索调优、使用 vLLM 部署更大参数的私有化模型。每一步都值得做一次独立实验，光是“把知识库效果调好”这一个主题，就能展开非常多细节。希望这篇文章能帮你把环境搭起来、把第一个应用跑通，然后带着真实的问题继续往前走。