GPUStack × MaxKB：打造强大易用的开源企业级智能体平台

随着企业内部 AI 应用越来越多，越来越多团队开始关注两个核心问题：

• 如何高效管理和部署本地大模型
• 如何快速构建企业知识库与 AI Agent

如果你同时在寻找这两个问题的解决方案，那么 GPUStack + MaxKB 的组合非常值得尝试。

• GPUStack：专注于 GPU 资源管理与模型部署，支持多节点集群和多模型服务。
• MaxKB：一个开源的企业级知识库与 AI 应用平台，可以快速构建知识库问答和 AI Agent。

通过将 GPUStack 提供的模型服务接入 MaxKB，就可以非常方便地构建一个 可落地的企业 AI 知识助手。

本文将从零开始，完整演示整个流程。

📌 本文内容

1. 部署最新 GPUStack v2.1.0
2. 在 GPUStack 中部署所需模型
3. 获取 GPUStack 模型接入信息
4. 部署 MaxKB
5. 在 MaxKB 中接入 GPUStack 模型
6. 实战示例：制作 GPUStack 文档知识库

安装 GPUStack v2.1.0

1. 安装 GPUStack Server

sudo docker run -d --name gpustack-server \
  --restart unless-stopped \
  -p 80:80 \
  -v gpustack-data:/var/lib/gpustack \
  -v /data/gpustack_cache:/var/lib/gpustack/cache \
  gpustack/gpustack:v2.1.0 \
  --bootstrap-password "123" \
  --debug

执行如上启动命令后，打开浏览器访问：

http://your_host_ip

即可进入 GPUStack UI，用户名密码：admin/123。

2. 创建集群

GPUStack 以 集群（Cluster） 为单位管理 Worker 节点。

新部署的 GPUStack Server 会提示创建第一个集群，我们点击：

Create Your First Cluster

按照界面提示完成创建即可。

也可以在侧边栏进入 Clusters 页面，点击 Add Cluster 手动创建。

3. 添加 Worker

创建完集群后，系统会提示 Add Worker。

我们按照界面提示继续操作即可。

也可以在侧边栏 Workers 页面点击 Add Worker 进行添加。

执行引导界面中的检查命令：

如果驱动和容器工具安装正确，将看到两个 OK。

如果显示 not configured，可以点击提示中的链接查看依赖说明，并按实际环境安装缺失组件。

1. Model Cache Volume Mount：将该目录挂载到模型缓存目录 /var/lib/gpustack/cache。
2. GPUStack Data Volume：将该目录挂载到数据目录 /var/lib/gpustack。

随后执行 Worker 启动命令：

sudo docker run -d --name gpustack-worker \
   -e "GPUSTACK_RUNTIME_DEPLOY_MIRRORED_NAME=gpustack-worker" \
   -e "GPUSTACK_TOKEN=gpustack_7b42996d3f5571d5_8181f986537c100369eaa2dfcf6d6359" \
   --restart=unless-stopped \
   --privileged \
   --network=host \
   --volume /var/run/docker.sock:/var/run/docker.sock \
   --volume gpustack-worker-data:/var/lib/gpustack \
   --volume /data/gpustack_cache:/var/lib/gpustack/cache \
   --runtime nvidia \
   gpustack/gpustack:v2.1.0 \
   --server-url http://192.168.50.14 \
   --worker-ip 192.168.50.14

在 GPUStack 中部署模型

点击侧边栏 Deployments 打开模型部署页面。

如果当前没有部署模型，页面中间会出现 Deploy Now 按钮。

点击该按钮进入 Model Catalog 页面，选择所需模型并按照提示部署即可。

更多部署方式可以查看右上角 Deploy Model 菜单。

本文示例部署以下三个模型：

• Qwen3-Reranker-4B
• Qwen3-Embedding-4B
• Qwen3.5-35B-A3B

部署时可根据实际情况调整显存占用比例。

部署 Qwen3-Reranker-4B

部署完成后，可以在 Playground 中进行测试。

部署 Qwen3-Embedding-4B

部署完成后可在 Playground 中测试。

部署 Qwen3.5-35B-A3B

这里额外设置 PYPI_PACKAGES_INSTALL 环境变量，用于升级 transformers 库。

部署完成后在 Playground 中测试。

获取 GPUStack 模型接入信息

打开侧边栏 Routes 页面。

点击 Route 右侧三个点菜单，选择：

API Access Info

记录以下信息：

Base URL
Model Name
API Key

示例：

Base URL: http://192.168.50.14/v1

Model Name:
qwen3.5-35b-a3b
qwen3-reranker-4b
qwen3-embedding-4b

API Key:
gpustack_xxxxxxxxxxxxxxxxx

API Key 可以按照界面提示自行创建。

部署 MaxKB

MaxKB 支持 Docker 一键部署：

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

默认账号密码：

admin / MaxKB@123..

首次登录会提示修改密码，按照提示修改即可。

在 MaxKB 中接入 GPUStack 模型

在 MaxKB 顶部导航栏选择 Model。

点击右上角 Add Model。

注意：
API URL 和 API Key 只有在 Base Model 输入并回车后 才会显示。

按照同样方式添加：

• qwen3-reranker-4b
• qwen3-embedding-4b

其中 qwen3-reranker-4b 需要开启 通用代理（Generic Proxy）：

原因是 MaxKB 使用的是：

/v2/rerank

API 端点。

配置完成后如下：

实战示例：制作 GPUStack 文档知识库

打开顶部 Knowledge 页面，点击 Create 创建知识库， 这里选择 Web Knowledge。

填入 GPUStack 文档地址，MaxKB 会自动抓取并解析页面内容。

抓取完成后如下：

创建 AI Agent

进入 Agent 页面。

点击 Create 创建 Agent。

配置完成后点击 Publish 发布 Agent。

发布成功后即可开始对话。

对话演示

打开对话界面：

示例效果：

🙌 加入 GPUStack 社区

如果你已经开始使用 GPUStack，
或者正在探索 本地大模型 / GPU 资源管理 / AI Infra，
欢迎加入我们的社区交流群，一起交流实践经验、踩坑记录与最佳方案。

👉 社区入口（持续更新）
https://github.com/gpustack/gpustack/blob/main/docs/assets/wechat-group-qrcode.jpg