1. 为什么选择 Dify 来管理你的本地大模型？

如果你和我一样，是个喜欢折腾本地大模型的人，那你肯定经历过这样的场景：电脑上跑着 Ollama，服务器上挂着 VLLM，每个模型都有自己的 API 地址和调用方式。想做个简单的聊天应用，得自己写前端、调 API、处理上下文；想搞个知识库问答，光是向量数据库和检索逻辑就能折腾好几天。更别提想把这些能力组合成一个自动化工作流了，那简直是“从入门到放弃”的真实写照。

这时候，Dify 就像一位全能管家，它把所有这些脏活累活都打包好了。简单来说，Dify 是一个开源的大模型应用开发平台。你不用再关心怎么去调用不同模型的 API，怎么写复杂的 Prompt，或者怎么搭建 RAG（检索增强生成）系统。在 Dify 里，这些都被做成了可视化的“乐高积木”，你只需要拖拖拽拽，就能拼装出功能强大的 AI 应用。

我最初接触 Dify，就是被它“开箱即用”的特性吸引的。当时我需要快速给团队内部搭建一个基于私有文档的问答机器人，要求数据绝对不能出本地。从零开始写代码？时间成本太高。用一些闭源的 SaaS 平台？数据安全又不放心。Dify 完美地解决了这个矛盾：它提供了企业级的应用框架，同时代码完全开源，可以部署在你自己的服务器上。更重要的是，它对本地模型的支持非常友好，无论是轻量级的 Ollama，还是追求极致性能的 VLLM，都能无缝接入。这意味着你可以用自己熟悉的、在本地微调过的模型，快速构建出功能丰富的应用，整个过程就像搭积木一样简单直观。

2. 十分钟搞定 Dify 基础环境部署

纸上得来终觉浅，绝知此事要躬行。说再多不如动手装一遍。Dify 官方推荐使用 Docker Compose 部署，这几乎是目前最省心、环境最干净的方式了。别被“Docker”这个词吓到，其实操作起来就像安装一个软件一样简单。

2.1 部署前的准备工作

在开始之前，你需要确保你的机器上已经安装了 Docker 和 Docker Compose。如果你的系统是 Ubuntu，安装命令非常直接。打开终端，依次执行下面几条命令，就能把 Docker 引擎和 Compose 插件装好：

# 更新软件包索引
sudo apt-get update
# 安装必要的依赖包，以便 apt 可以通过 HTTPS 使用仓库
sudo apt-get install ca-certificates curl
# 添加 Docker 的官方 GPG 密钥
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
# 设置 Docker 的稳定版仓库
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
# 再次更新，并安装 Docker 引擎和 Compose 插件
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

安装完成后，运行 docker --version 和 docker compose version 来验证一下。看到版本号输出，就说明环境准备好了。这里有个小坑我踩过：有些老教程或者旧系统里，用的命令是 docker-compose（带横杠），而现在 Docker 官方更推荐集成式的 docker compose（空格）。如果你遇到命令不存在的错误，可以检查一下安装的是否是 docker-compose-plugin。

2.2 一键启动 Dify 服务

环境就绪，我们就可以“克隆” Dify 了。我习惯把这类工具放在一个统一的目录下管理，比如 ~/workspace/ai/tools。打开终端，执行下面的命令序列：

# 进入你的工作目录，如果不存在就创建
mkdir -p ~/workspace/ai/tools && cd ~/workspace/ai/tools
# 克隆 Dify 的代码仓库，--depth=1 只拉取最新提交，速度更快
git clone --depth 1 https://github.com/langgenius/dify.git
# 进入 Docker 部署目录
cd dify/docker
# 复制环境变量配置文件模板
cp .env.example .env

关键的步骤来了，启动所有服务。只需要一行命令：

docker compose up -d

这个 -d 参数代表“后台运行”。执行后，Docker 会开始拉取 PostgreSQL、Redis、Web 服务、后端 API 等一系列镜像，并自动配置网络和依赖。第一次运行可能需要几分钟，取决于你的网速。完成后，用 docker compose ps 查看一下所有容器的状态，确保它们都是 Up (healthy) 或 Up 状态。

2.3 访问与管理你的 Dify 平台

服务跑起来后，怎么访问呢？非常简单。

• 本地访问：直接在浏览器打开 http://localhost。
• 服务器访问：用你的服务器公网 IP 或域名替换，比如 http://你的服务器IP。

第一次打开会进入初始化页面，设置一下管理员账号密码，就能进入 Dify 的主界面了。整个界面非常清爽，左侧是应用、知识库、工作流等核心功能导航。

关于日常维护，我再分享几个常用命令：

• 更新 Dify：项目迭代很快，新功能频出。更新时，进入 dify/docker 目录，执行：

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

  这里要注意，如果官方更新了 .env.example 文件，你需要对比一下自己本地的 .env 文件，把新增的配置项手动加进去，否则新功能可能无法生效。
• 重启服务：有时候修改了配置，或者单纯想重启一下，就用：

  docker compose down
  docker compose up -d
  

3. 手把手接入 Ollama 本地模型

Dify 本身不提供模型，它是个“调度中心”。我们要做的第一件事，就是把本地已经跑起来的模型“介绍”给 Dify 认识。Ollama 因为其极简的部署和丰富的模型库，成为了很多开发者在本地跑模型的首选。下面我就以 Ollama 为例，详细走一遍接入流程。

3.1 在 Dify 中配置 Ollama 供应商

首先，确保你的 Ollama 服务已经在运行。在终端输入 ollama list，应该能看到你已经拉取到本地的模型列表，比如 llama3.2:1b, qwen2.5:7b 等。

然后，我们登录 Dify 后台进行配置。点击页面右上角的头像，选择 “设置”，在设置侧边栏中找到 “模型供应商”。你会看到一个长长的列表，里面包含了 OpenAI、Anthropic、Ollama、VLLM 等几乎所有主流模型提供商。找到 Ollama，如果旁边显示“未安装”，点击一下安装按钮。安装是瞬间完成的，其实就是激活这个插件。

安装好后，点击 Ollama 卡片上的 “添加模型” 按钮，会弹出一个配置表单。这里有几个关键字段需要填写：

• 模型名称：这个不是随便起的，必须和你用 ollama list 看到的模型名称完全一致。比如我本地有个 qwen2.5:7b 的模型，这里就填 qwen2.5:7b。Dify 后续会把这个名称传递给 Ollama 服务来调用对应的模型。
• 基础 URL：这是连接的关键。默认很多人会填 http://localhost:11434，但这往往是错误的根源。因为 Dify 运行在 Docker 容器内，对于容器来说，localhost 指的是容器自己，而不是宿主机。所以我们需要填宿主机的 IP 地址。假设你宿主机的 IP 是 192.168.1.100，那么这里就填 http://192.168.1.100:11434。
• 其他选项：如模型类型（聊天/补全）、上下文长度、价格（本地模型可设为0）等，可以暂时使用默认值，后续根据模型特性再精细调整。

填好后点击保存，如果配置正确，Dify 会尝试连接 Ollama 服务并获取模型列表，成功后会显示一个绿色的“有效”状态。

3.2 解决棘手的“Connection refused”问题

上面说的“填宿主机IP”是最常见的情况，但实际部署时，尤其是跨 Docker 网络时，可能会遇到更复杂的网络问题。我遇到过好几次保存配置时，Dify 报错 Connection refused，或者 Failed to connect。别慌，我们可以一步步排查。

第一步，检查 Ollama 服务监听地址。 默认情况下，Ollama 只监听 127.0.0.1:11434，这意味着只有本机可以访问。我们需要让它监听所有网络接口（0.0.0.0），这样 Docker 容器才能连上。修改 Ollama 的系统服务配置：

sudo vim /etc/systemd/system/ollama.service

在 [Service] 这个区块里，添加一行环境变量配置：

Environment="OLLAMA_HOST=0.0.0.0:11434"

保存退出后，重新加载系统守护进程并重启 Ollama：

sudo systemctl daemon-reload
sudo systemctl restart ollama

然后用 sudo netstat -tulnp | grep 11434 命令验证，如果看到 0.0.0.0:11434 或者 :::11434，说明修改成功。

第二步，检查宿主机防火墙。 如果你的系统开启了防火墙（如 UFW），需要放行 11434 端口：

sudo ufw allow 11434/tcp
sudo ufw reload

第三步，进行连接测试。 在宿主机上，用 curl 命令测试一下 Ollama 的 API 是否正常工作：

curl http://192.168.1.100:11434/api/tags

这条命令会请求 Ollama 的模型列表接口。如果返回一个包含你模型信息的 JSON，说明 Ollama 服务本身没问题，且网络可通。

第四步，在 Docker 内部测试。 这是最直接的验证方法。进入 Dify 的后端 API 容器内部，执行同样的 curl 命令：

# 先找到 Dify API 容器的名字或ID
docker compose ps | grep api
# 假设容器名是 dify-api-1，则进入容器
docker exec -it dify-api-1 bash
# 在容器内安装 curl（如果未自带）
apt-get update && apt-get install -y curl
# 测试连接宿主机 Ollama
curl http://192.168.1.100:11434/api/tags

如果容器内也能成功获取模型列表，那么 Dify 的配置就一定能成功。如果容器内失败，而宿主机成功，那问题就出在 Docker 网络层面，可能需要检查 Docker 的网络模式，或者使用 Docker 的 host 网络模式来绕过网络隔离（但会牺牲一些隔离性）。

4. 高性能之选：接入 VLLM 推理引擎

如果说 Ollama 是方便快捷的“家用轿车”，那 VLLM 就是追求极致吞吐量和低延迟的“性能跑车”。它采用了先进的 PagedAttention 注意力算法，能极大地优化 GPU 显存利用，在批量处理请求时优势明显。如果你的应用场景是高频调用、需要处理大量并发请求，或者模型比较大（比如 70B 参数），VLLM 会是更好的选择。

4.1 部署并配置 VLLM 服务

VLLM 通常作为一个独立的 API 服务运行。首先，你需要在一个有 GPU 的环境（可以是你的开发机，也可以是另一台服务器）上启动 VLLM。假设我们使用 Qwen2.5-7B-Instruct 模型：

# 使用 pip 安装 vllm
pip install vllm
# 启动一个 vllm 的 api 服务器，指定模型和端口
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --served-model-name Qwen2.5-7B-Instruct \
    --port 8000 \
    --host 0.0.0.0

这里有几个参数很重要：

• --model：指定 Hugging Face 上的模型 ID，vllm 会自动下载。
• --served-model-name：这个模型在 API 中叫什么名字，后面 Dify 配置会用到。
• --host 0.0.0.0：和 Ollama 一样，让服务监听所有网络接口，方便其他服务调用。
• --port 8000：服务端口。

服务启动后，你可以用类似的方法测试：curl http://你的服务器IP:8000/v1/models。如果返回模型信息，说明 VLLM 服务正常。

4.2 在 Dify 中接入 VLLM

步骤和接入 Ollama 非常相似。进入 Dify 的 设置 -> 模型供应商，找到 VLLM 并安装插件（如果未安装）。然后点击“添加模型”。

在配置表单中，关键字段如下：

• 模型名称：这里填的模型名称，必须和 VLLM 启动时 --served-model-name 参数指定的名称完全一致。比如我们上面用的是 Qwen2.5-7B-Instruct。
• API Endpoint URL：这是 VLLM 服务的 OpenAI 兼容 API 地址。格式是 http://你的VLLM服务器IP:8000/v1。注意末尾的 /v1 不能少，因为 VLLM 完全遵循 OpenAI 的 API 格式。
• 模型类型：选择“聊天”或“补全”，根据你的模型特性来选。像 Qwen2.5、Llama 这类对话模型，就选“聊天”。
• 上下文长度：这里可以填写模型实际支持的最大上下文长度，比如 32768。填写准确的数值有助于 Dify 更好地管理对话历史。

保存之后，Dify 会去验证连接。因为 VLLM 的 API 格式和 OpenAI 一模一样，所以兼容性通常非常好，一次成功的概率很高。

4.3 Ollama 与 VLLM 该如何选择？

看到这里你可能有点疑惑，两个都能接本地模型，我该用哪个？根据我的实战经验，可以这么选：

选择 Ollama 的场景：

• 追求极简部署：一条 ollama run 命令就能把模型跑起来，不需要关心 Python 环境、CUDA 版本。
• 模型管理方便：ollama list/pull/rm 命令可以像管理 Docker 镜像一样管理模型。
• 资源有限：Ollama 对显存和内存的优化做得不错，在消费级显卡上跑 7B、13B 的模型体验很好。
• 快速原型验证：想快速试试某个新模型的效果，Ollama 是最快的方式。

选择 VLLM 的场景：

• 追求极致性能：需要高吞吐量、低延迟，尤其是在批量处理提示词（batch inference）时，VLLM 的 PagedAttention 能带来数倍的性能提升。
• 部署大型模型：需要部署 70B 或更大参数量的模型，VLLM 的显存优化技术能让你在有限的 GPU 上跑起更大的模型。
• 需要 OpenAI 完全兼容的 API：你的其他工具链严重依赖 OpenAI API 格式，VLLM 可以无缝替换，迁移成本为零。
• 生产环境服务：需要更精细的控制，如动态批处理、量化加载、多 GPU 并行等高级特性。

简单总结：轻量级、个人使用、求方便选 Ollama；高性能、生产环境、大规模服务选 VLLM。 好消息是，在 Dify 里你可以同时接入两者，根据不同的应用需求选择不同的模型供应商，非常灵活。

5. 从接入到优化：提升模型效能的实战技巧

模型接入了，能跑通了，这仅仅是第一步。要让 AI 应用真正好用、稳定，还需要一系列的优化和调试。这部分才是真正体现经验价值的地方，我把自己踩过坑后总结的几个关键点分享给你。

5.1 模型参数调优：不是所有默认值都适合你

在 Dify 的模型配置页面，保存按钮上方有一个 “高级参数设置” 的折叠区域，点开它，你会发现一个新世界。这里面的每一个参数，都直接影响着模型的输出效果和速度。

• 温度（Temperature）：这是控制输出随机性的最重要参数。值越高（如 0.8、1.0），输出越创造性、越多样，但也可能更胡说八道；值越低（如 0.1、0.2），输出越确定、越保守，适合事实性问答。我一般会在创意写作类应用里调到 0.7-0.9，在知识库问答里调到 0.1-0.3。
• Top P：另一种控制随机性的方法，和温度可以配合使用。它表示从累积概率超过 P 的最小词集合中采样。通常设置 0.7-0.9 能取得不错的效果。我的经验是，如果你不太理解它的原理，可以先保持默认，优先调整温度。
• 最大生成长度（Max Tokens）：这个参数限制了模型单次回复的最大长度。设得太小，回答可能被截断；设得太大，又会浪费资源并可能让模型“跑偏”。对于一般的对话，1024 或 2048 通常足够。对于长文总结或写作，可能需要 4096 甚至更多。关键是要根据你模型的实际上下文长度来设置，不要超过模型的能力上限。
• 停止序列（Stop Sequences）：告诉模型看到哪些字符串就停止生成。这在构建工作流时特别有用。比如，你可以设置 “\n\n用户：” 作为停止序列，这样模型在生成完自己的回答后，一旦它开始模拟用户提问就会自动停止，避免出现“自言自语”的循环。

调参没有银弹，最好的方法就是创建一个测试应用，用一批有代表性的问题，反复调整这些参数，对比输出结果，找到最适合你场景的“甜蜜点”。

5.2 系统提示词（System Prompt）的魔力

在 Dify 中创建应用时，有一个叫做 “提示词编排” 的核心区域。其中，“系统提示词”是很多新手会忽略，但老手极其重视的部分。你可以把它理解为给模型的一份“岗位说明书”。

系统提示词在对话开始前就注入给模型，它定义了模型的角色、能力边界、回答格式和禁忌。一个精心设计的系统提示词，能极大提升对话的准确性和可控性。举个例子，如果你要做一个客服机器人，系统提示词可以这样写：

你是一个专业、友好且高效的客服助手。你的主要职责是解答用户关于产品使用、账单和售后服务的问题。
请遵循以下规则：
1. 始终使用中文回复。
2. 如果用户的问题需要查询知识库，请根据提供的上下文信息回答。
3. 如果信息不足，请礼貌地请用户提供更多细节，切勿编造信息。
4. 回答应简洁明了，重点突出，必要时使用列表。
5. 如果遇到无法处理的问题（如投诉、技术故障），请引导用户联系人工客服。
你的回答应以“您好！”开头。

通过这样的系统提示词，你就在模型“自由发挥”的倾向之上，套上了一个符合业务需求的“框架”。实测下来，一个好的系统提示词，比单纯在用户问题前加几句说明，效果要好得多。

5.3 利用上下文对话与记忆

Dify 内置了强大的对话上下文管理功能。在应用配置的“上下文”部分，你可以设置“最大上下文轮次”。这意味着 Dify 会自动帮你维护一个对话历史窗口，并将最近几轮的对话内容，作为上下文传递给模型。

这个功能对于实现连贯的多轮对话至关重要。比如，用户先问“什么是机器学习？”，接着又问“它有哪些主要类型？”，如果没有上下文，模型可能不知道“它”指代什么。有了上下文管理，第二个问题会连同第一个问题和回答一起送给模型，模型就能做出准确的指代回答。

这里有一个性能权衡：保留的上下文轮次越多，对话越连贯，但每次请求携带的数据量也越大，会消耗更多 Token，增加响应时间。我的建议是，对于一般聊天应用，保留 5-10 轮对话是合理的；对于需要深度分析的长对话，可以适当增加，但要密切关注 API 的响应延迟。

6. 构建你的第一个 AI 应用：知识库问答机器人

理论说了这么多，我们最后来一个实战案例，把 Ollama/VLLM 的模型能力、Dify 的提示词编排和 RAG 功能串起来，打造一个真正可用的私有知识库问答机器人。这个场景非常实用，比如用来查询公司内部文档、个人知识库或者产品手册。

6.1 创建应用与选择模型

首先，在 Dify 左侧导航栏点击 “创建应用”，选择“对话型应用”，给它起个名字，比如“我的技术文档助手”。在模型配置环节，选择我们之前已经接入好的本地模型，比如 Ollama 里的 qwen2.5:7b 或者 VLLM 里的 Qwen2.5-7B-Instruct。这样，这个应用的基础对话能力就由我们本地的模型来提供了。

6.2 上传知识库并配置检索

接下来是关键一步：注入专属知识。点击左侧的 “知识库” 菜单，创建一个新的知识库，命名为“产品手册”。然后，你可以通过上传文件（支持 PDF、Word、TXT、Markdown 等）或者直接粘贴文本的方式，将你的文档资料添加进去。比如，你可以上传公司产品的 PDF 说明书。

上传后，Dify 会在后台自动进行文本提取、分块（Chunking）和向量化（Embedding），并将向量存储到它自带的向量数据库中。这个过程可能需要一点时间，取决于文档大小。

知识库创建好后，回到刚才创建的“我的技术文档助手”应用。在“提示词编排”界面的底部，找到 “上下文” 区域，点击“添加上下文”。选择“知识库”，然后勾选我们刚创建的“产品手册”知识库。这里有几个重要参数：

• 检索模式：通常选择“向量检索”，它根据语义相似度查找相关内容。
• 相似度阈值：可以过滤掉低相关度的片段，提高答案准确性，一般设在 0.6-0.8。
• 返回数量：每次检索返回几个文本片段，一般 2-5 个足够。

6.3 设计提示词与测试优化

现在，我们需要修改提示词，让模型学会利用检索到的知识。在系统提示词里，我们可以加入这样的指令：

你是一个专业的产品支持助手，请严格根据提供的“参考上下文”来回答用户问题。
参考上下文是来自产品官方文档的权威信息。
你的回答必须基于上下文，如果上下文没有提供足够信息，请如实告知用户“根据现有资料，我无法回答这个问题”，不要编造信息。
回答请清晰、有条理。

在用户问题输入框的上方，Dify 会自动插入一个变量 {{#context#}}，这个变量会在运行时被替换成从知识库中检索到的相关文本片段。这样，模型在生成回答时，就能“看到”这些专属知识了。

配置完成后，点击右上角的“发布”按钮，你的应用就上线了。你可以直接在 Dify 提供的聊天界面进行测试。试着问一些文档里明确有的问题，比如“产品 X 的主要特性是什么？”，再问一些文档里没有的问题，观察模型的表现。你会发现，对于有上下文支持的问题，回答非常准确；对于没有支持的问题，模型会按照提示词要求，诚实地说不知道，而不是胡编乱造——这正是 RAG 系统的核心价值所在。

6.4 后续迭代与监控

应用上线后，工作还没结束。Dify 提供了非常实用的 “日志与标注” 功能。所有用户的对话记录都会被保存下来。你可以定期查看这些日志，特别是那些回答效果不好或者被用户点“踩”的对话。

通过分析这些案例，你可以：

1. 优化知识库：是不是某些问题对应的文档片段没有被检索到？可能需要调整文档的分块大小或重叠度。
2. 优化提示词：是不是系统指令不够清晰？导致模型没有严格遵守“基于上下文”的规则。
3. 优化检索参数：相似度阈值是否合适？返回的片段数量是否足够？

这个过程是一个持续的闭环：构建 -> 测试 -> 分析 -> 优化。经过几轮迭代，你的机器人会变得越来越聪明、越来越可靠。我自己就用这个方法，把一堆杂乱的技术笔记变成了一个随时可问的“第二大脑”，效率提升非常明显。