将 Dify 接入 vLLM 后端：用 vLLM 为 Dify 提供高性能 LLM 推理服务的完整部署指南

本文以 vLLM 仓库中的 Dify 部署文档为主线，讲解如何以 vLLM 作为后端推理引擎，为开源 LLM 应用平台 Dify 提供模型服务：从安装 vLLM 环境、启动 OpenAI 兼容的 vllm serve 服务，到用 Docker Compose 拉起 Dify、在 Dify 中配置 vLLM 模型提供方并创建测试聊天机器人。读完本篇，你可以独立完成"Dify + vLLM"的端到端部署，并理解两者之间基于 OpenAI 兼容接口的对接原理。

背景：Dify 与 vLLM 的分工

Dify 是一个开源的 LLM 应用开发平台，它将智能体工作流（agentic AI workflow）、RAG 流水线、Agent 能力、模型管理与可观测性等功能整合在一个直观的界面中，帮助开发者快速从原型走向生产环境。Dify 本身不做推理加速，而是把模型推理委托给外部模型提供方——它原生支持将 vLLM 配置为模型提供方（Model Provider），从而借助 vLLM 的高吞吐、显存高效的推理能力来服务大语言模型。

两者之间的连接纽带是 OpenAI 兼容的 HTTP API。vLLM 的 vllm serve 命令启动的 HTTP 服务实现了 OpenAI 的 Completions API 与 Chat API 等接口（详见 OpenAI 兼容服务器文档），因此 Dify 只需按 OpenAI 客户端的方式填写 API Endpoint URL（形如 http://host:port/v1）即可调用。这也是为什么文档强调 vLLM 服务端必须加载"支持的 chat completion 模型"——Chat Completions API 仅适用于带 chat template 的文本生成模型。

前置条件

部署前需要完成两件事：准备 vLLM 环境，以及安装 Docker 与 Docker Compose（用于部署 Dify）。

pip install vllm

同时请确保系统已安装 Docker 引擎和 Docker Compose。Dify 侧的所有服务（Web、API、Worker、数据库、缓存等）都将由 Docker Compose 编排启动。

部署步骤

以下步骤完整继承自仓库中的 Dify 部署文档，按顺序执行即可。

第一步：启动 vLLM 服务

选择一个支持 chat completion 的模型启动 vLLM 服务：

vllm serve Qwen/Qwen1.5-7B-Chat

vllm serve 是 vLLM CLI 的 serve 子命令，其入口实现在 serve.py。从源码可以看到，该子命令的描述明确定位为 "Launch a local OpenAI-compatible API server to serve LLM completions via HTTP"，并在非 gRPC 模式下经由 launcher 模块 的 setup_server / run_server 拉起 API 服务器；参数解析统一由 cli_args.py 中的 make_arg_parser 完成，可通过 --help=ModelConfig、--help=Frontend 或 --help=all 按分组查看所有可配置项。服务默认监听 8000 端口，因此示例中 Dify 侧的 Endpoint 通常填 http://{vllm_server_host}:8000/v1。

第二步：用 Docker Compose 启动 Dify

按照 Dify 官方的快速启动方式部署：

git clone https://github.com/langgenius/dify.git
cd dify
cd docker
cp .env.example .env
docker compose up -d

关键点：cp .env.example .env 这一步不能跳过——Docker Compose 依赖该 .env 文件中的环境变量（如服务端口、密钥等）完成初始化；docker compose up -d 以守护模式启动全部服务。

第三步：初始化登录

打开浏览器访问 http://localhost/install，配置基础登录信息（管理员账号等）并登录 Dify。

第四步：安装 vLLM 模型提供方

登录后，点击右上角的用户菜单（头像图标下方），进入 Settings（设置），点击 Model Provider（模型供应商），在列表中找到 vLLM 提供方并点击安装。

第五步：填写 vLLM 提供方参数

安装后需要填写模型提供方详情，各项取值如下（以第一步的示例模型为例）：

配置项	取值
Model Type	LLM
Model Name	Qwen/Qwen1.5-7B-Chat
API Endpoint URL	http://{vllm_server_host}:{vllm_server_port}/v1
Model Name for API Endpoint	Qwen/Qwen1.5-7B-Chat
Completion Mode	Completion

两个占位符需要按实际环境替换：{vllm_server_host} 是运行 vllm serve 的机器地址，{vllm_server_port} 是 vLLM 监听端口（默认 8000）。注意 Model Name 与 Model Name for API Endpoint 的区别：前者是 Dify 界面中展示和选择的逻辑名称，后者是真正发送给 vLLM 的 /v1/chat/completions 请求体中 model 字段的内容，必须与 vllm serve 加载的模型标识一致。

第六步：创建测试聊天机器人

进入 Studio → Chatbot → Create from Blank，在类型中选择 Chatbot，即可创建一个空白聊天应用。

第七步：开始对话

点击刚创建的聊天机器人打开聊天界面，发送消息即可与背后的 Qwen/Qwen1.5-7B-Chat 模型交互。至此，Dify 的 Web 界面 → Dify 后端 → vLLM OpenAI 兼容 API → 模型的完整链路即被打通。

深入理解：请求是如何从 Dify 流到 vLLM 的

Dify 配置中的 API Endpoint URL 末尾统一以 /v1 结尾，对应 vLLM 暴露的一组 OpenAI 兼容端点。根据 OpenAI 兼容服务器文档，vLLM 至少支持以下 API：

• Completions API（/v1/completions），适用于文本生成模型；
• Chat Completions API（/v1/chat/completions），适用于带 chat template 的文本生成模型——Dify 聊天场景走的就是这条路径；
• 此外还有 Chat Completions batch API（/v1/chat/completions/batch）、Responses API、Embeddings API 以及语音转写/翻译 API 等，可在同一 vLLM 实例上复用。

由此可以给出两条与 Dify 对接直接相关的结论：

1. 模型选择约束：若在 Dify 中把 vLLM 作为提供方却选择了纯文本（非 chat）模型，/v1/chat/completions 请求将无法按预期工作，这正是原文档要求"supported chat completion model"的原因；
2. 采样参数透传：vLLM 支持 OpenAI API 之外的参数（如 top_k），通过 OpenAI Python 客户端的 extra_body 传入，例如 extra_body={"top_k": 50}。Dify 在编排中对模型行为有细粒度控制需求时，可以关注这一通道。

另外，vLLM 服务默认会应用 Hugging Face 模型仓库中的 generation_config.json，即模型创建者推荐的采样默认值可能会覆盖接口默认值；若希望关闭该行为，可在启动服务端时传 --generation-config vllm。

生产环境的注意事项

• API Key 的覆盖范围：若为 vllm serve 配置了 --api-key（或 VLLM_API_KEY 环境变量），需要注意该密钥只保护 /v1、/v2、/inference 路径前缀下的请求，同服务器上的其他端点（如 /invocations）不受保护。因此不要单独依赖 --api-key 作为安全边界，生产部署建议置于反向代理之后，完整说明见 API Key 鉴权限制（该文档亦在 OpenAI 兼容服务器文档 开头以警告形式提示）。
• 网络可达性：Dify 运行在容器内，API Endpoint URL 必须是从 Dify 网络命名空间可达的地址。若 vLLM 与 Dify 不在同一宿主机，不要把 localhost 写死在 Endpoint 里；同机部署时还需确认容器网络能路由到宿主机的 8000 端口。
• 验证服务是否就绪：在 Dify 保存提供方配置之前，可以先用任意 OpenAI 客户端直接请求 http://{host}:8000/v1/chat/completions，或直接访问 /v1/models 确认模型标识与 Model Name for API Endpoint 填写值一致，以缩小排障范围。

小结

本文完整复刻并扩展了 vLLM 仓库中 Dify 部署文档的实操流程：pip install vllm 准备环境 → vllm serve 启动 OpenAI 兼容推理服务 → Docker Compose 拉起 Dify → 安装并配置 vLLM 模型提供方 → 创建聊天机器人验证链路。核心要点在于 Dify 与 vLLM 之间以 /v1 下的 OpenAI 兼容接口为契约：模型必须支持 chat completion，Model Name for API Endpoint 必须与 vLLM 侧模型标识严格一致，且生产环境应结合反向代理与 API Key 做好端点保护。