通过OpenAI兼容接口将本地vLLM服务接入Dify工作流的配置验证

文章导读
把本地 vLLM 服务接入 Dify 工作流,核心是让 Dify 能通过 OpenAI 兼容的 /v1/chat/completions 接口调用 vLLM。这个方案只解决“模型可被调用”和“配置正确”两层问题,不解决模型质量、并发上限或工作流编排效率。前提是 vLLM 服务已经用正确的模型参数启动,并且 Dify 所在网络能访问 vLLM 的地址。
📋 目录
  1. A 前置条件
  2. B 在 Dify 中填写 OpenAI 兼容配置
  3. C 用 curl 验证接口连通性
  4. D 在 Dify 工作流中验证接入
  5. E 失败时的回退与排查顺序
A A

把本地 vLLM 服务接入 Dify 工作流,核心是让 Dify 能通过 OpenAI 兼容的 /v1/chat/completions 接口调用 vLLM。这个方案只解决“模型可被调用”和“配置正确”两层问题,不解决模型质量、并发上限或工作流编排效率。前提是 vLLM 服务已经用正确的模型参数启动,并且 Dify 所在网络能访问 vLLM 的地址。

前置条件

先确认三件事,避免在 Dify 侧反复排查:vLLM 服务启动时是否开启了 OpenAI 兼容服务;模型名称是否完整;端口是否对 Dify 实例开放。vLLM 默认监听 8000 端口,可以用 curl 直接验证。

curl http://127.0.0.1:8000/v1/models

返回 JSON 中应包含模型 id,这个 id 就是稍后在 Dify 里填写的“模型名称”。如果请求这个接口失败,先处理 vLLM 的启动参数或防火墙,不要先改 Dify。

在 Dify 中填写 OpenAI 兼容配置

进入 Dify 的“设置 - 模型供应商”,选择 OpenAI-API-compatible 或同类兼容供应商。通常需要填四类信息:API 基础地址、API Key、模型名称、上下文长度。基础地址写成 http://<vllm_host>:8000/v1,不要漏掉 /v1。vLLM 默认不校验 API Key,但 Dify 通常会要求必填,可以随便填一个非空字符串,比如 local-vllm。模型名称必须和 /v1/models 返回的 id 完全一致,包括大小写和符号。

上下文长度先填模型实际支持的最大长度,比如 8192,但实际可用长度还取决于显存和 KV cache 设置。如果后续请求报长度超出错误,再按 vLLM 日志里的实际限制调整,不必在一开始追求精确。

用 curl 验证接口连通性

在 Dify 所在的机器执行下面的请求,替换模型名和 prompt,确认 vLLM 能正常返回 chat completion 响应。这一步能隔离 Dify 配置问题,也能判断 vLLM 服务本身是否可用。

curl http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen2.5-7B-Instruct",
    "messages": [{"role": "user", "content": "返回 ok"}],
    "max_tokens": 20
  }'

如果返回包含 choices[0].message.content 的 JSON,说明接口链路正常。如果返回 404,检查 URL 是否包含 /v1;如果返回 400,检查 messages 格式和 max_tokens 是否超限。

通过OpenAI兼容接口将本地vLLM服务接入Dify工作流的配置验证

在 Dify 工作流中验证接入

在 Dify 工作流里添加 LLM 节点,选择刚才配置的模型供应商和模型名。先给一个最简单的 prompt,比如“只回复:已连接”,然后运行一次工作流,查看节点输出。

验证时重点看三处:节点是否把请求发送到 vLLM;vLLM 日志是否有对应请求记录;Dify 是否正常解析返回内容。如果 Dify 报错,常见原因是模型名称不一致、API 基础地址末尾多了一个斜杠、或 Dify 服务无法访问 vLLM 地址。可以先用 curl 从 Dify 容器内部再执行一次,确认网络通。

失败时的回退与排查顺序

接入失败时按顺序自查:先看 vLLM 的启动日志,确认模型是否加载完成,是否报过 OOM;再用 curl 直连确认接口可用;然后检查 Dify 的模型供应商表单;最后看 Dify 的后端日志。不要在同一时间修改多个变量。

如果 curl 正常但 Dify 报错,优先确认 Dify 容器里的网络能否访问 vLLM 地址。若 vLLM 和 Dify 都在同一台机器,Dify 容器内访问宿主机时不能直接用 localhost,需要改用 Docker 的 host.docker.internal 或宿主机局域网 IP。vLLM 的启动命令中 `--served-model-name` 可以自定义对外暴露的模型名;如果不想暴露完整路径模型名,可以先用这个参数缩短模型名,再同步修改 Dify 里的配置。

最后保留一条保守建议:不要在生产工作流里直接接入未压测过的 vLLM 服务。先在小流量、可回滚的场景下验证模型响应和超时行为,再逐步放开。