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

本文介绍如何将 GPUStack 中本地部署的大语言模型（LLM）、Embedding 向量模型与 Rerank 重排序模型接入 MaxKB，从而为 MaxKB 知识库问答提供完全私有化的模型能力。读完本文，你将掌握从模型部署、API 访问信息获取、MaxKB 部署与模型配置，到创建知识库与发布 AI Agent 的完整闭环流程，并理解/v2/rerank端点为何需要启用 Generic Proxy 的底层原理。

集成方案总览

MaxKB 是开源的智能知识库问答系统，支持接入大语言模型、Embedding 模型和 Rerank 模型，用于构建基于私有知识库的 AI 助手。GPUStack 作为统一的 GPU 集群管理与模型服务平台，为 MaxKB 提供三个关键角色：

• 对话模型：负责根据检索到的知识生成回答（如qwen3.5-35b-a3b）；
• Embedding 模型：负责将知识库文档切分后的片段向量化，供语义检索使用（如qwen3-embedding-4b）；
• Rerank 模型：负责对检索结果进行重排序，提升答案相关性（如qwen3-reranker-4b）。

三者配合，MaxKB 才能完成"知识入库 → 语义检索 → 重排序 → 大模型生成"的完整知识问答链路。

第一步：在 GPUStack 中部署模型

进入部署页面

在 GPUStack UI 中，导航到Deployments（部署）页面，点击Deploy Model（部署模型）按钮，即可开始部署所需的模型。GPUStack 内置模型目录（model-catalog.yaml），其中收录了 Qwen3 系列 Embedding 与 Reranker 模型，可直接从目录选择，无需手工填写 Hugging Face 模型 ID。

本指南以三个模型为例：

说明：Embedding 与 Reranker 类模型推理资源占用较小，通常会由 GPUStack 调度到与推理后端（如 vLLM）兼容的 GPU 节点上。从 GPUStack 调度器对模型类别的处理看（参见 vllm_resource_fit_selector.py），Embedding 与 Reranker 模型在资源适配上有专门的处理逻辑，可放心部署。

依次完成以下部署：

• qwen3.5-35b-a3b：在 Deploy Model 中选择该模型，确认推理后端与显存配置后点击部署；
• qwen3-embedding-4b：作为 Embedding 模型部署；
• qwen3-reranker-4b：作为 Rerank 模型部署。

在 Playground 中验证模型

模型部署完成后，建议先在 GPUStack 的Playground（模型测试台）中分别验证三个模型是否能正常响应，确认推理服务正常后再进行 MaxKB 对接。

第二步：获取模型访问信息

MaxKB 需要通过 OpenAI 兼容接口访问 GPUStack 上的模型，因此需要从 GPUStack 获取三项关键信息：Base URL、Model Name 与 API Key。

获取 Base URL 与 Model Name

1. 在 GPUStack 左侧边栏打开Routes（模型路由）页面；
2. 在对应模型路由右侧点击More actions menu（更多操作菜单），选择API Access Info（API 访问信息）。

记录以下信息：

Base URL Model Name API Key

其中 Base URL 的格式为http://your-gpustack-url/v1，即 GPUStack 对外提供的 OpenAI 兼容 API 入口。GPUStack 的 API 网关对/v1下的/chat/completions、/embeddings等 OpenAI 风格路径做统一路由（参见 gateway/utils.py 中openai_model_prefixes的定义），这也是 MaxKB 能直接填写该地址的原因。

示例：

Base URL: http://your-gpustack-url/v1 Model Name: qwen3.5-35b-a3b qwen3-embedding-4b qwen3-reranker-4b API Key: gpustack_xxxxxxxxxxxxx

创建 API Key

提示：如果还没有 API Key，可以按照 GPUStack UI 中的引导提示创建一个 API Key。API Key 以gpustack_前缀开头，是 MaxKB 访问 GPUStack 模型接口的凭证，请妥善保管。

第三步：部署 MaxKB

MaxKB 官方提供 Docker 镜像，可通过一条命令完成部署：

docker run -d \ --name maxkb \ --restart always \ -p 8080:8080 \ -v ~/.maxkb:/opt/maxkb \ 1panel/maxkb

参数说明：

启动成功后，访问http://your-server:8080即可进入 MaxKB 登录页面。

默认登录凭证：

admin / MaxKB@123..

首次登录后，请按照页面提示修改默认密码，避免默认凭证暴露带来的安全风险。

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

添加对话模型

1. 在 MaxKB UI 顶部的导航栏中，点击Model（模型）进入模型管理页面。

2. 点击Add Model（添加模型），配置模型信息：

配置要点如下：

• Base Model（基础模型）：必须与 GPUStack 中部署的模型名称完全一致，即qwen3.5-35b-a3b；
• API URL（接口地址）：填写http://your-gpustack-url/v1；
• API Key（接口密钥）：填写在 GPUStack 中创建的 API Key。

注意：API URL和API Key两个输入框会在输入 Base Model 并按下回车键之后才出现，这是 MaxKB 根据模型名称自动识别供应商类型后的正常交互流程，按顺序填写即可。

添加 Embedding 与 Rerank 模型

用同样的方法依次添加另外两个模型：

• qwen3-embedding-4b（Embedding 模型）：

• qwen3-reranker-4b（Rerank 模型）：在配置该模型时，需要开启 Generic Proxy（通用代理）。

为什么 Rerank 模型必须开启 Generic Proxy？原因是 MaxKB 调用 Rerank 模型时使用的是以下端点：

/v2/rerank

这与标准 OpenAI 接口路径不同。GPUStack 的 API 网关专门为 Rerank 端点做了版本兼容处理：在 gateway/utils.py 中，/rerank路径被声明了additional_versions=["/v2"]，即同时支持/v1/rerank与/v2/rerank两种访问形式；请求会由 rerank.py 中的POST /rerank路由接收，并代理转发到对应模型实例。开启 Generic Proxy 后，MaxKB 才能正确访问/v2/rerank端点完成重排序调用。

校验模型列表

三个模型全部配置完成后，应能在模型列表中看到它们：

第五步：创建知识库

1. 在 MaxKB 中导航到Knowledge（知识）页面；
2. 点击Create（创建），选择Web Knowledge（网页知识库）类型。

3. 输入一个文档 URL 或其他数据源地址，MaxKB 会自动爬取并解析页面内容，然后使用已配置的 Embedding 模型将其向量化存入知识库。

爬取完成后的知识库状态：

提示：除了 Web Knowledge，MaxKB 还支持文档上传等其他知识库类型，均可复用 GPUStack 提供的 Embedding 模型完成向量化。

第六步：创建并发布 AI Agent

1. 进入Agent（智能体）页面；
2. 点击Create（创建）新建一个智能体。

3. 为智能体配置：

• Chat model（对话模型）：选择qwen3.5-35b-a3b；
• Knowledge base（知识库）：选择上一步创建的知识库；
• Retrieval settings（检索设置）：配置召回数量、相似度阈值等检索参数（Rerank 模型会在此环节对召回片段重排序）。

4. 配置完成后，点击Publish（发布）激活智能体。

第七步：开始对话

打开智能体的聊天界面，即可开始与基于知识库的 AI 助手交互：

此时，助手可以基于已连接的知识库与 GPUStack 上部署的模型，回答与知识库内容相关的问题——对话生成由 LLM 完成，语义检索由 Embedding 模型支撑，相关性优化由 Rerank 模型负责，整个问答链路完全运行在本地 GPU 集群上，无需依赖外部模型服务。

常见问题排查

总结

通过 GPUStack + MaxKB 的组合，可以在本地 GPU 集群上构建一套完整的私有化知识库问答系统：GPUStack 负责模型部署、路由与 OpenAI 兼容 API 暴露，MaxKB 负责知识库管理、检索增强与 Agent 编排。本指南涉及的三个模型角色（Chat / Embedding / Rerank）与/v2/rerank端点适配是集成成败的关键，按照本文步骤逐一配置即可快速上线。

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