GPUStack 自定义后端系列 | MinerU：打造超强 PDF 文档解析服务

随着 GPUStack v2 的发布，我们迎来了备受期待的 自定义后端 功能！这意味着除了 GPUStack 原生支持的推理后端（如 vLLM、SGLang 等），你现在可以将任意模型推理引擎接入 GPUStack 进行统一的管理和调度。

今天，我们就以 MinerU 为例，手把手教你如何在 GPUStack 中运行这个强大的 PDF 文档提取工具，解锁高效的文档解析能力！

🧐 什么是 MinerU？

MinerU 是一款专注于复杂 PDF 文档解析的开源工具，能够将包含公式、表格等复杂元素的 PDF 精准转换为 Markdown 格式。通过 GPUStack 的自定义后端功能，你可以轻松获得一个私有化的文档解析 API 服务。

🛠️ 第一步：准备 MinerU 镜像

为了方便大家快速上手，我们已经预先打包好了开箱即用的镜像（版本 v2.7.0），推荐直接拉取使用：

docker pull swr.cn-south-1.myhuaweicloud.com/gpustackcommunity/mineru:v2.7.0

注意： 官方 Dockerfile 使用的是旧版本的 vLLM。如果您在 RTX 5090 等新设备上运行，请修改 Dockerfile 以升级 vLLM 并重新构建镜像。

📝 第二步：注册自定义后端

镜像准备好后，我们需要在 GPUStack 中将其注册为一个新的后端。

1. 进入 GPUStack 管理界面。
2. 展开侧边栏，选择 Inference Backends。

3. 点击 Add Backend，填入以下配置：

为了方便大家复制，这里提供等效的 YAML 配置：

backend_name: MinerU-custom
default_run_command: mineru-vllm-server --port {{port}} --served-model-name {{model_name}}
version_configs:
  v2.7.0:
    image_name: swr.cn-south-1.myhuaweicloud.com/gpustackcommunity/mineru:v2.7.0
    custom_framework: cuda
default_version: v2.7.0

除了手动填写表单，你也可以点击界面右上角 “YAML Mode”，通过直接粘贴 YAML 代码的方式快速完成配置：

配置完成后的效果如下所示：

🚀 第三步：部署模型并绑定后端

后端注册完成后，就可以像部署普通 LLM 一样部署 MinerU 了。

1. 打开 Deployments，点击 Deploy Model。

2. 在部署配置中，选择我们刚刚注册的 MinerU 后端。

由于镜像内已预置模型权重，此处的 /tmp 仅作为路径占位。这可能导致系统对显存资源的估算出现偏差，因此建议选择 手动调度 (Manual Scheduling) 模式。

此外，由于 mineru-vllm-server 底层基于 vllm serve，您可以通过参数配置 --gpu-memory-utilization 等选项以精确控制资源使用。

⚠️ 重要提醒：
虽然 MinerU 提供了兼容 OpenAI API 的接口，但它是一个专用模型，仅用于文档处理，不具备通用对话能力。请勿将其作为通用聊天模型使用。

部署成功后，你会看到状态变为 Running：

查看日志确认启动无误：

💻 第四步：开始使用 MinerU

现在，你的 GPUStack 已经具备了 MinerU 的能力！你可以使用 MinerU 自带的 CLI 工具来快速测试 PDF 解析。

ℹ️ 小贴士：
当前版本的 mineru CLI 需要对依赖库 mineru-vl-utils 进行优化才能支持参数传递（详见 PR #34：https://github.com/opendatalab/mineru-vl-utils/pull/34）。如果直接在代码中使用 HttpVlmClient 调用 API，则不需要此处理。

获取 API 接入信息

在 Deployments 页面，点击对应模型的右侧菜单，选择 “API Access Info”：

CLI 调用示例

# 设置模型名称
export MINERU_VL_MODEL_NAME=mineru
# 注意：这里请使用你自己的 API Key
export MINERU_VL_API_KEY=gpustack_3519fc0369a06fae_c434118c1cc0e07f3dfe998c6416522c
# 开始解析 PDF
mineru -p example.pdf -o outputs -b vlm-http-client -u http://192.168.50.12

运行结果如下：

🌟 探索更多

GPUStack 的自定义后端功能拥有无限可能！

• 更多社区后端： https://github.com/gpustack/community-inference-backends
• 贡献你的后端： 欢迎提交 PR 分享您的配置。

🙌 加入社区

如果您在使用过程中遇到问题，欢迎加入我们的社区进行交流。

如果二维码失效，请访问 GPUStack 项目主页获取最新入口：https://github.com/gpustack/gpustack/blob/main/docs/assets/wechat-group-qrcode.jpg