在实际 AI 应用开发中将大模型能力快速、稳定地集成到业务系统里是很多团队面临的共同挑战。直接调用模型 API 虽然简单但很快就会遇到对话管理、上下文处理、知识库检索、工作流编排等一系列复杂问题。Dify 作为一个开源的 LLM 应用开发平台其核心价值就在于提供了一个中间层让开发者可以像搭积木一样通过配置而非大量编码的方式将大模型接入到具体的应用场景中。本文将以一个典型的“智能客服问答”场景为例带你从零开始完成在 Dify 中接入大模型、配置知识库、创建应用并对外提供服务的完整流程。无论你是想快速验证一个 AI 产品想法还是希望为现有系统增加智能对话能力这篇教程都能提供一条清晰的实践路径。1. 理解 Dify 的核心定位与工作流在开始动手之前需要先厘清 Dify 在整个技术栈中的位置以及它如何简化大模型应用的开发。很多开发者初次接触时容易把它和单纯的模型服务或 API 网关混淆。1.1 Dify 是什么不是模型而是应用编排器Dify 不是一个新的大模型也不是一个模型托管服务。它的官方定义是“LLM 应用开发平台”。你可以把它理解为一个功能强大的“胶水”和“控制台”。它的核心工作是模型抽象与管理将 OpenAI、Azure OpenAI、Anthropic、国内各大模型厂商乃至本地部署的模型如通过 Ollama、vLLM 部署的的 API 差异统一封装。开发者无需关心每个模型 API 的具体调用参数在 Dify 中通过统一的界面进行选择和配置。应用逻辑编排提供可视化的工作流编辑器让你可以拖拽组件来定义应用的逻辑。例如一个问答流程可能包含“接收用户问题 - 检索知识库 - 将检索结果和问题组合成提示词 - 调用大模型生成回答 - 对回答进行后处理如敏感词过滤- 返回结果”。这个过程在 Dify 中可以通过连线几个节点来完成无需编写复杂的流程控制代码。上下文与记忆管理自动处理对话历史的管理包括上下文窗口的限制、历史消息的摘要或选择性保留这对于实现多轮连贯对话至关重要。知识库集成支持上传多种格式的文档TXT、PDF、Word、PPT、Markdown 等自动进行文本分割、向量化处理并集成高效的检索能力让大模型能够基于你提供的私有知识进行回答。简单来说如果你直接调用模型 API你需要自己处理提示词工程、上下文管理、文件解析、向量检索、流程编排等所有事情。而 Dify 将这些能力产品化让你通过配置就能获得一个功能相对完备的 AI 应用后端。1.2 典型工作流从用户问题到智能回答为了更直观地理解我们看一下在一个配置了知识库的 Dify 应用中一次用户查询是如何被处理的用户输入用户在聊天界面或通过 API 发送问题“我们公司的退货政策是什么”请求路由Dify 后端接收到请求识别出对应的应用配置。知识库检索根据应用配置Dify 将用户问题转化为查询向量在已构建的知识库向量数据库中搜索最相关的文档片段。提示词组装Dify 将检索到的相关片段、用户原始问题、系统预设的指令如“你是一个专业的客服助手”以及可能的对话历史按照预设的模板组装成一个完整的提示词Prompt。模型调用将组装好的提示词发送给预先配置好的大模型例如 GPT-4并等待模型返回结果。结果处理与返回Dify 接收模型返回的文本可能进行后处理如格式整理然后将最终答案返回给用户。整个过程开发者只需要在 Dify 控制台完成“配置模型”、“上传知识文档”、“设计提示词模板”和“发布应用”这几步背后的复杂链路均由 Dify 自动完成。2. 环境准备与 Dify 的部署选择Dify 提供了多种部署方式以适应不同场景。对于学习和初步开发我们推荐使用 Docker Compose 进行本地部署这是最快捷、依赖最少的方式。2.1 系统与环境要求在开始部署前请确保你的开发环境满足以下基本要求组件最低要求推荐配置说明操作系统Linux, macOS, Windows (WSL2)Linux (Ubuntu 20.04) 或 macOSWindows 原生环境部署复杂强烈建议使用 WSL2。Docker20.10最新稳定版所有部署方式都依赖 Docker。Docker Compose2.0最新稳定版用于编排多个服务容器。CPU/RAM2核 / 4GB4核 / 8GB 以上运行向量数据库和 Dify 服务本身需要一定资源。磁盘空间10GB50GB用于存放镜像、数据库和上传的文档。网络可访问互联网稳定连接首次运行需要拉取镜像且需要能访问你所选大模型的 API。注意如果你计划使用本地部署的大模型如通过 Ollama则无需访问外部模型 API但需要确保本地模型服务已启动且网络可达。2.2 通过 Docker Compose 一键部署这是官方推荐且最常用的方式。它会在本地启动一组容器包括 Dify 后端 API、前端界面、数据库PostgreSQL、向量数据库Weaviate/Qdrant和 Redis 缓存。获取部署文件打开终端创建一个工作目录并下载官方提供的docker-compose.yml文件。mkdir dify cd dify curl -o docker-compose.yml https://raw.githubusercontent.com/langgenius/dify/main/docker/docker-compose.yml如果下载缓慢可以手动从 Dify 的 GitHub 仓库docker目录下复制内容。启动服务在包含docker-compose.yml文件的目录下执行以下命令。docker-compose up -d首次执行会从 Docker Hub 拉取所有必要的镜像可能需要几分钟时间。-d参数表示在后台运行。验证服务状态使用以下命令查看容器是否全部正常启动。docker-compose ps正常情况下你应该看到dify-api,dify-web,postgres,redis,weaviate等容器的状态均为Up。访问控制台在浏览器中打开http://localhost:3000。如果一切顺利你将看到 Dify 的初始化界面按照提示创建第一个管理员账号。2.3 常见部署问题排查如果在部署或访问过程中遇到问题可以按以下顺序排查问题现象可能原因检查与解决执行docker-compose up -d失败1. Docker 服务未运行。2. 端口冲突3000, 5432, 6379, 8080等。3. 镜像拉取失败。1. 运行docker version检查 Docker 状态。2. 运行netstat -tuln | grep 端口号检查端口占用可在docker-compose.yml中修改映射端口。3. 检查网络或尝试手动拉取镜像docker pull langgenius/dify-web:latest。访问localhost:3000无法连接1. 容器启动失败。2. 防火墙或安全软件阻止。1. 运行docker-compose logs dify-web查看前端容器日志。2. 运行docker-compose logs dify-api查看后端容器日志常见错误是数据库连接失败。初始化页面报数据库连接错误PostgreSQL 容器尚未完全启动或初始化。1. 等待片刻再刷新。2. 查看 PostgreSQL 容器日志docker-compose logs postgres。3. 尝试重启服务docker-compose down docker-compose up -d。上传文档构建知识库失败向量数据库Weaviate服务异常。1. 检查 Weaviate 容器状态docker-compose logs weaviate。2. 确保内存充足向量数据库对内存有一定要求。3. 在 Dify 中接入你的第一个大模型成功部署并登录 Dify 控制台后首要任务就是配置一个大模型供应商这是所有 AI 应用能力的源泉。Dify 支持众多模型这里我们以接入 OpenAI 的 GPT 模型和本地 Ollama 的 Llama 3 模型为例。3.1 接入云端模型以 OpenAI 为例云端模型稳定、能力强适合生产环境。你需要一个有效的 OpenAI API Key。进入模型配置在 Dify 控制台左侧菜单栏点击「模型供应商」-「模型配置」。添加 OpenAI 供应商点击「添加模型供应商」在列表中找到「OpenAI」并点击。填写配置信息关键配置项如下供应商名称自定义如My-OpenAI。API Key填入你的 OpenAI API Key。API 端点通常使用默认的https://api.openai.com/v1。如果你使用 Azure OpenAI 或其他代理需要修改此处。模型列表点击「获取模型列表」Dify 会自动调用 OpenAI 接口获取你账户下有权限的模型如gpt-4o,gpt-4-turbo-preview,gpt-3.5-turbo等。保存与测试点击「保存」然后在模型列表中找到刚添加的供应商点击「测试」选择其中一个模型如gpt-3.5-turbo输入简单提示词如“Hello”查看是否能正常返回结果。测试成功意味着模型通道已打通。3.2 接入本地模型以 Ollama 为例对于数据隐私要求高、或想体验开源模型的场景可以在本地通过 Ollama 运行模型再接入 Dify。安装并运行 Ollama首先在本地安装 Ollama访问 Ollama 官网下载。安装后在终端拉取并运行一个模型例如 Llama 3。# 拉取模型首次运行需要下载大小约几个GB ollama pull llama3:8b # 运行模型服务默认端口 11434 ollama run llama3:8b # 通常我们会让服务在后台运行可以使用 ollama serve 或配置为系统服务确保 Ollama 服务在http://localhost:11434可访问。在 Dify 中配置 Ollama 供应商在「模型供应商」中点击「添加模型供应商」选择「Ollama」。供应商名称如Local-Ollama。API 端点填写http://host.docker.internal:11434。这里使用host.docker.internal让 Docker 容器能访问到宿主机的服务。如果 Dify 不是 Docker 部署的则填写http://localhost:11434。模型列表由于 Ollama 的模型列表接口可能不标准Dify 可能无法自动获取。我们需要手动添加模型。手动添加模型在「模型配置」页面点击「添加模型」。模型供应商选择刚创建的Local-Ollama。模型名称填写 Ollama 中的模型名称如llama3:8b。这是最关键的一步必须与ollama list中显示的名称完全一致。模型类型选择「文本生成」。模型能力根据模型实际情况选择Llama 3 通常支持「聊天」和「推理」。测试模型保存后在模型列表中测试llama3:8b输入提示词看是否正常响应。3.3 模型配置的关键参数解析在配置或使用模型时你会遇到一些关键参数理解它们对优化应用效果很重要参数含义常见值/影响建议Max Tokens模型单次生成的最大令牌数。1024, 2048, 4096 等。设置过小可能导致回答被截断。根据模型上下文窗口和你的需求设置通常 1024-2048 能满足多数对话。Temperature控制输出的随机性。0.0 ~ 2.0。值越高输出越随机、有创造性值越低输出越确定、保守。对于事实性问答建议较低 (0.1-0.3)对于创意写作可以调高 (0.7-0.9)。Top P核采样参数控制生成时的词汇选择范围。0.0 ~ 1.0。与 Temperature 配合使用通常调整一个即可。常用值 0.7-0.9。Frequency Penalty降低重复词汇出现的概率。-2.0 ~ 2.0。正值惩罚重复使文本更多样。如果发现模型经常重复短语可以设置为 0.1 ~ 0.5。Presence Penalty降低重复话题出现的概率。-2.0 ~ 2.0。正值鼓励模型谈论新话题。用于多轮对话避免模型老调重弹可设为 0.1 ~ 0.3。4. 构建一个基于知识库的智能问答应用模型接入后我们来创建一个具备私有知识问答能力的应用。这是 Dify 最核心的功能之一。4.1 创建应用与选择编排方式创建新应用在控制台首页点击「创建应用」输入应用名称如“产品客服助手”选择应用类型为「对话型应用」。理解编排模式Dify 提供了两种构建应用的模式提示词编排简易模式适用于简单的问答、对话场景。你主要通过设计系统提示词Prompt和关联知识库来定义助手行为。工作流编排高级模式通过可视化拖拽节点的方式构建复杂的处理流程可以包含条件判断、多模型调用、代码执行等。对于初次使用建议从「提示词编排」开始。4.2 创建与配置知识库知识库是让模型“拥有”私有信息的关键。创建知识库在左侧菜单进入「知识库」点击「创建知识库」命名为“产品手册”。上传文档进入知识库详情页点击「上传文件」支持直接上传 TXT、PDF、Word、Excel、PPT、Markdown 等文件。你也可以通过「同步网站」功能抓取网页内容。注意对于 PDF 等复杂格式Dify 会尝试提取文字和表格。上传后务必点击「处理」按钮系统会对文档进行分段、向量化并存入向量数据库。配置处理参数上传后在文件列表右侧点击「修改处理方式」关键参数如下分段方法按“符号”或“长度”分割。通常按符号如句号、换行分割更符合语义。文本分块大小每个文本块的最大长度字符数。太小会丢失上下文太大会影响检索精度。一般 500-1000 字符是常用范围。文本分块重叠相邻文本块之间的重叠字符数。这有助于避免一个完整的句子或概念被割裂到两个块中。通常设置为分块大小的 10%-20%。检查处理状态处理完成后状态会变为“已索引”。你可以点击「预览」查看文档被分割成的具体文本块这是后续检索的基本单元。4.3 设计提示词与关联知识库现在回到我们创建的“产品客服助手”应用。配置提示词在应用的「提示词编排」页面找到「系统提示词」输入框。这里是你定义助手角色和核心行为的地方。例如你是一个专业、友好的产品客服助手负责解答用户关于我们公司产品的疑问。 请严格根据提供的知识库内容来回答问题。如果知识库中没有相关信息请如实告知用户“根据现有资料我暂时无法回答这个问题”不要编造信息。 回答时请简洁、清晰分点说明如果信息较多。关联知识库在「上下文」部分开启「知识库」开关。然后从下拉列表中选择我们刚才创建的“产品手册”知识库。设置检索参数检索模式通常选择「向量检索」它基于语义相似度查找相关文本块。Top K每次检索返回的最相关文本块数量。通常 2-5 个即可太多可能导致提示词过长或引入噪声。相似度阈值仅返回相似度高于此值的文本块。可以过滤掉完全不相关的结果。初期可以设为 0观察效果后再调整。选择对话模型在「模型」部分选择你之前配置好的模型例如gpt-3.5-turbo或llama3:8b。可以在这里微调模型的Temperature等参数。4.4 测试与优化应用实时测试在页面右侧的「预览」对话窗输入一个你知道在知识库文档中存在的问题。例如如果你的产品手册提到了“退货期限是30天”你可以问“请问商品买回来后多久可以退货”分析结果查看助手的回答是否准确引用了知识库内容。在「预览」窗格上方可以开启「显示推理过程」这能让你看到系统实际发送给模型的完整提示词。从知识库中检索到了哪些文本片段。模型生成的原始回复。 这个功能对于调试提示词和检索效果至关重要。优化迭代如果回答不准确检查检索到的文本块是否相关。可能需要对文档重新处理调整分块大小或重叠度。如果回答未引用知识库检查系统提示词是否足够强调“根据知识库回答”或者尝试调整检索的Top K值。如果回答格式不佳在系统提示词中更明确地指定输出格式要求。5. 发布应用与集成应用测试满意后就可以发布并提供给最终用户使用了。Dify 提供了多种集成方式。5.1 发布与获取 API 密钥发布应用在应用配置页面的右上角点击「发布」。发布后应用配置将被锁定避免在测试过程中被意外修改。你可以随时创建新的版本进行迭代。获取 API 密钥在左侧菜单进入「设置」-「API 密钥」创建一个新的密钥。妥善保管此密钥它将在调用 API 时用于身份验证。5.2 集成方式Web 站点嵌入Dify 为每个应用生成了一个独立的聊天窗口可以直接嵌入到你的网站中。在应用「发布」后的页面找到「访问地址」下的「站点地址」复制提供的 iframe 代码或 JavaScript 代码片段粘贴到你的网站 HTML 中即可。通过 API 调用这是最灵活的集成方式。Dify 提供了标准的 RESTful API。API 端点http://你的Dify地址/v1/chat-messages(对话) 或/v1/completion-messages(补全)。认证在 HTTP Header 中添加Authorization: Bearer 你的API密钥。请求示例(使用 cURL)curl --location http://localhost:3000/v1/chat-messages \ --header Authorization: Bearer app-xxxxxx \ --header Content-Type: application/json \ --data { inputs: {}, query: 你们公司的产品支持哪些支付方式, response_mode: streaming, // 或 blocking conversation_id: , // 首次可为空后续传入以实现多轮对话 user: user-123 // 用户标识 }响应如果response_mode设为streaming将以 Server-Sent Events (SSE) 流式返回设为blocking则阻塞等待完整响应后返回。5.3 监控与日志在生产环境中监控应用的使用情况和问题排查至关重要。日志在 Dify 控制台的「日志与标注」页面可以查看所有对话的历史记录、请求的详细参数、模型响应以及消耗的 Token 数量。这对于分析用户问题分布、优化提示词和核算成本非常有用。标注你可以在这里对模型的回答进行「好评」或「差评」标注这些反馈数据可以用于后续的模型微调或应用优化。6. 进阶使用工作流编排复杂场景当简易的提示词编排无法满足复杂逻辑时就需要使用工作流。例如一个客服流程可能需要先判断用户意图 - 如果是产品咨询则检索知识库 - 如果是订单查询则调用内部 API 获取数据 - 最后统一用模型生成回答。在工作流编辑器中你可以拖拽各种节点开始节点接收用户输入。LLM 节点调用大模型可用于意图识别、内容生成等。知识库检索节点从指定知识库查找信息。代码节点执行 Python 代码可以调用外部 API、处理数据。条件判断节点根据变量值决定流程分支。回答节点将最终结果返回给用户。通过连线将这些节点组合起来就能构建出满足复杂业务逻辑的 AI 应用。工作流的设计需要更系统的规划建议在熟悉 Dify 基础功能后再深入探索。7. 生产环境部署与最佳实践将 Dify 用于生产环境需要考虑更多关于稳定性、安全性和性能的因素。部署架构不建议将开发环境的 Docker Compose 直接用于生产。生产环境应考虑分离服务将 PostgreSQL、Redis、Weaviate/Qdrant 等中间件部署在独立的、可扩展的服务集群中。使用云服务考虑使用云托管的数据库和向量数据库服务如 PGVector on RDS, Qdrant Cloud。高可用为 Dify 的 API 和 Web 服务配置多个实例并通过负载均衡器分发请求。安全配置修改默认端口生产环境不要使用默认的 3000 端口。启用 HTTPS通过 Nginx 或云负载均衡器配置 SSL/TLS 证书。管理 API 密钥严格控制 API 密钥的权限遵循最小权限原则定期轮换密钥。网络隔离确保 Dify 服务部署在受保护的网络环境中数据库等中间件不直接暴露在公网。数据与知识库管理定期备份定期备份 PostgreSQL 中的元数据和向量数据库中的索引。文档更新策略建立知识库文档的更新流程。更新文档后需要在 Dify 中重新上传并“处理”文件以更新向量索引。版本控制利用 Dify 的应用版本功能在发布重大更新前创建新版本便于回滚。性能与成本优化缓存策略对于常见问题可以考虑在应用层增加缓存避免重复检索和模型调用。模型选型根据场景选择合适的模型。简单的 FAQ 问答可能用gpt-3.5-turbo就够了复杂的推理再用gpt-4。平衡效果与成本。监控 Token 消耗密切关注日志中的 Token 使用量特别是知识库检索会显著增加提示词长度从而增加成本和延迟。优化文本分块和检索 Top K 值有助于控制 Token 数。通过以上步骤你不仅完成了从零到一在 Dify 中接入大模型并创建应用也对生产环境的考量有了基本认识。Dify 的核心价值在于将大模型应用的通用能力标准化和产品化让开发者能更专注于业务逻辑本身。接下来你可以尝试更复杂的工作流或者探索其 Agent、模型微调集成等高级功能以构建更强大的 AI 应用。