GPUStack 与 Dify 深度集成实战：本地 LLM、Embedding、Rerank 与多模态模型的接入指南-开发者社区

后端
人工智能
模型推理服务
集群管理
可观测性

【免费下载链接】gpustack

A GPU cluster manager for high-performance AI model serving (vLLM, SGLang) and on-demand SSH-accessible GPU instances.

项目地址：https://gitcode.com/gh_mirrors/gp/gpustack

本文面向需要把 GPUStack 托管的本地大模型能力接入 Dify 平台的开发者，完整演示从 GPUStack 侧部署模型、创建 API Key，到 Dify 侧安装 GPUStack 插件、配置系统模型，再到在 Studio 与 Knowledge 中实际使用 LLM 对话、RAG 检索排序与 VLM 图像输入的全流程。读完本文，你将掌握一套可复制的本地模型 + Dify 应用搭建方案，并理解其背后基于 OpenAI 兼容 API 与 Rerank API 的对接原理。

Dify 可以借助 GPUStack 提供的能力，使用本地部署的 LLM（大语言模型）、Embedding（向量化）、Reranking（重排序）、图像生成、语音转文本（Speech-to-Text）与文本转语音（Text-to-Speech）等模型能力。这套集成方案特别适合需要数据私密、成本可控、可离线运行 RAG 与智能体应用的场景。

集成架构一览

整个集成的数据流向非常简单清晰：

GPUStack 负责模型的部署与推理，对外暴露统一的 HTTP 推理 API（OpenAI 兼容端点/v1与 Jina 兼容的/v1/rerank等）；
Dify 通过官方 GPUStack 插件连接到 GPUStack 的 API 端点；
Dify 中的各类模型（对话模型、Embedding 模型、Rerank 模型）在运行时由 Dify 转发请求到 GPUStack，GPUStack 再将其调度到具体的模型实例上执行。

GPUStack 的 OpenAI 兼容 API 路由实现在 gpustack/routes/openai.py，它把/v1下的一组端点（如GET /v1/models、POST /v1/chat/completions、POST /v1/embeddings等）统一代理到实际运行模型的 Worker 上，并内置了基于权重的多实例负载均衡与流式响应支持。Dify 之所以能无缝接入，正是因为 GPUStack 对外提供的协议与 OpenAI 标准接口兼容。

第一步：在 GPUStack 部署所需模型

打开 GPUStack Web UI，进入Deployments（部署）页面，点击Deploy Model（部署模型），依次部署你需要的模型。以下是针对 Dify 集成场景的一组常用模型示例：

模型名称	在 Dify 中的用途
`qwen3-8b`	对话/文本生成（Chat Model），用于 Studio 中的应用对话
`qwen2.5-vl-3b-instruct`	视觉语言模型（Vision），用于图片理解与多模态对话
`bge-m3`	Embedding 模型，用于 Knowledge（知识库）中文档向量化
`bge-reranker-v2-m3`	Rerank 模型，用于知识库检索结果的重排序

部署完成后，在模型的 Operations（操作）中找到API Access Info（API 访问信息），这里会展示该模型对应的 API 端点地址、请求示例与认证方式，是后续配置 Dify 时的关键参考信息。

从源码看模型调用链路

部署好的模型并不会在 GPUStack 内网凭空暴露给外部应用，而是通过统一网关分发。以 OpenAI 兼容端点为例，get_api_router() 会在/v1下注册models列表接口以及各推理端点；请求进入后，proxy_request_by_model 会完成以下工作：

校验调用者权限（model_allowed_for_user）；
根据请求体中的model字段解析对应的模型路由（Model Route）与其可用目标实例；
按权重随机选择一个运行中的目标实例（对应LoadBalancer与ModelRouteTarget.weight的逻辑）；
将请求代理转发到承载该模型实例的 Worker，若请求要求stream: true则返回 SSE 流式响应。

这意味着在 Dify 中配置好模型名与 API Key 后，所有推理请求都会自动被 GPUStack 路由到正确的实例上，无需关心底层实例分布。

第二步：创建 GPUStack API Key

Dify 连接 GPUStack 需要一份具备推理权限的 API Key，创建步骤如下：

在 GPUStack UI 中进入Access Control（访问控制）>API Keys页面；
点击New API Key（新建 API Key）；
填写名称后点击Save（保存）；
复制生成的 API Key 并妥善保存，供后续 Dify 配置使用。

从源码实现看，API Key 的生成与校验逻辑位于 gpustack/routes/api_keys.py 与 gpustack/api/auth.py：密钥使用API_KEY_PREFIX前缀与generate_access_key/generate_secret_key生成（见 gpustack/security.py），请求时通过Authorization: Bearer <api_key>头（HTTPBearer）或X-API-Key头携带。Dify 插件在调用 GPUStack 时即使用该密钥完成身份认证。

第三步：在 Dify 中安装 GPUStack 插件

进入 Dify UI，点击右上角的PLUGINS（插件），选择Install from Marketplace（从应用市场安装），搜索 GPUStack 插件并点击安装。

第四步：在 Dify 中接入 GPUStack 模型

插件安装完成后，进入Settings > Model Provider > GPUStack（设置 > 模型供应商 > GPUStack），点击Add Model（添加模型），填写以下字段：

Model Type（模型类型）：根据模型的实际能力选择，例如对话模型选 Chat、向量模型选 Embedding、重排序模型选 Rerank；
Model Name（模型名称）：必须与 GPUStack 上部署的模型名称完全一致，例如qwen3-8b、bge-m3；
Server URL（服务地址）：填写http://your-gpustack-url。注意两点：
- 不要使用localhost，因为在 Dify 容器内localhost指向的是容器自身的内网，无法访问宿主机上的 GPUStack；
- 如果 GPUStack 使用了自定义端口，务必在 URL 中带上端口号，并确保该地址能被 Dify 容器内部访问（可以用curl验证连通性）。
API Key：填入上一步从 GPUStack 复制的 API Key。

填写完成后点击Save保存：

按需重复此步骤添加其他模型，然后在System Model Settings（系统模型设置）中把刚添加的模型分别指定为默认的 Chat、Embedding 与 Rerank 模型并保存：

实战一：在 Knowledge 中构建 RAG 知识库

模型配置完成后，即可在Studio（工作台）与Knowledge（知识库）中使用这些模型。以下是构建一个基于 RAG 的知识库问答应用的完整流程：

进入Knowledge，创建一个知识库并上传你的文档资料；
配置 Chunk Settings（分段设置）与 Retrieval Settings（检索设置）。其中：
- 使用前面添加的Embedding 模型为文档内容生成向量索引；
- 使用Rerank 模型对检索命中的片段进行重排序，提升最相关内容的排序优先级；
文档导入成功后，进入Studio创建一个应用，为该应用关联刚创建的知识库，并选择对话模型（如qwen3-8b）即可开始交互问答。

Rerank 能力背后的 API 支撑

需要说明的是，标准 OpenAI 兼容 API 并不包含rerank端点。GPUStack 专门提供了 Jina 兼容的 Rerank API 路径/v1/rerank，实现在 gpustack/routes/rerank.py，其请求模型包含model、query、documents与可选的top_n、return_documents字段，响应则按index、document、relevance_score返回每个候选片段的排序得分。Dify 中的 Rerank 模型正是通过该端点工作，从而在知识库检索阶段完成"先召回、再精排"的两阶段流程。更多接口细节可参考 Inference APIs 说明。

实战二：在 Studio 中对话与多模态输入

完成知识库问答后，还可以进一步体验多模态能力：

在 Studio 中把模型切换为视觉语言模型qwen2.5-vl-3b-instruct；
移除之前关联的知识库（纯多模态对话场景通常不需要 RAG）；
在应用设置中启用Vision（视觉）能力；
在对话输入框上传一张图片并发送，模型即可读取图片内容进行多模态交互。

常见问题与排查建议

Server URL 连通性失败：先确认 GPUStack 服务端口是否开放、防火墙是否放行；再在 Dify 容器内执行curl http://your-gpustack-url/v1/models（携带 API Key）验证连通性，避免使用localhost。
模型名称不匹配：Dify 中的 Model Name 必须与 GPUStack 部署名称严格一致，GPUStack 通过请求体中的model字段解析路由，名称不一致会直接导致Model not found错误（见 proxy_request_by_model 中的 404 分支）。
模型未就绪：若模型实例尚未完成启动（状态非 Running），GPUStack 会返回"无可用运行实例"类错误（对应 gpustack/routes/openai.py 的ServiceUnavailableException），请等待实例就绪后重试。
需要非 OpenAI 兼容 API：若某个模型提供 OpenAI 之外的自定义 API，可在 GPUStack 部署模型时开启Enable Generic Proxy功能，通过/model/proxy/<model_route_id>/<upstream-path>路径式转发访问目标模型，详细说明见模型部署管理文档。

至此，你已经完成 GPUStack 与 Dify 的完整集成：本地模型通过 OpenAI 兼容 API 供给 Dify，知识库检索借助 Embedding + Rerank 实现高质量 RAG，多模态对话由 VLM 模型提供视觉理解能力，整个过程数据保留在本地集群，适合对隐私与成本敏感的 AI 应用场景。