怎么优雅地在GPUStack上使用minerU？

如果你搞过 AI 知识库，那你一定听过 MinerU 的大名。这家伙专治各种不服——哦不，专治各种复杂的 PDF 文档，甭管是密密麻麻的公式还是乱七八糟的表格，它都能精准地转成 Markdown 格式。在 AI 知识库里，海量的 PDF 嗷嗷待哺，等着被转成 MD 喂进去呢。

官方提供了minerU的推理文档，但遗憾的是，它并不直接支持 MinerU 的fast api模式。访问minerU的官网可以看到，MinerU 官方其实提供了 Fast API 接口——直接上传 PDF、提交解析任务、然后异步拿结果，一条龙服务。之前集团里很多应用都是基于这套接口开发的，用起来那叫一个香。

如果 GPustack 也能接入这个 Fast API 接口，那下游服务迁移的时候就不用大动干戈了，美滋滋。

那咱们就来盘一盘怎么搞。

1.添加推理后端

先在机器上拉取 MinerU 的官方镜像，本文演示的镜像是 mineru:3.1.11 在【推理后端】中点击添加后端

默认命令走起，直接启动 MinerU 的 API 模式

mineru-api --host 0.0.0.0 --port {{port}} --allow-public-http-client

版本号中配置对应的镜像名称

2.启动镜像

那么接下来就来启动minerU

在部署中点击本地路径

模型路径就是用/tmp 占位 推理后端一定要选择自定义的minerU版本

千万记得启用通用代理！后面有大用

接下来就是激动人心的等待环节——看 MinerU 服务启动完成~

3.访问服务

这时候，GPustack 平台提供的「通用代理」功能就派上用场了

那么问题来了：这个模型的路由 ID 是多少呢？别慌，调一下 GPustack 这个接口就能查到

{
  "items": [
    {
      "id": 48,
      "created_at": "2026-07-01T08:04:41.971882Z",
      "updated_at": "2026-07-01T08:44:55.594322Z",
      "weight": 100,
      "model_id": 38,
      "name": "minerU-api-deployment",
      "route_name": "minerU-api",
      "route_id": 41,
      "state": "active"
    },

从返回的结果来看 minerU-api 的路由id 是 41 那么现在就可以请求模型啦~~~

口说无凭，咱们来写个 Python 脚本调一下试试

import requests
import json
import os
import time
from typing import List

# ================= 配置区域 =================
# 文件解析接口 (保持不变)
PARSE_URL = "XXXXX/model/proxy/41/file_parse"
# API 鉴权，从环境变量读取 GPUSTACK_API_KEY
API_KEY = "gpustack_XXXXXXX"

# ===========================================

# 文件解析相关函数保持不变
def parse_file(file_path, output_file):
    """
    调用 file_parse 接口解析文件
    """
    # 与 curl 一致的 form 参数
    data = {
        "return_middle_json": "false",
        "return_model_output": "false",
        "return_md": "true",
        "return_images": "false",
        "end_page_id": "99999",
        "parse_method": "auto",
        "start_page_id": "0",
        "lang_list": "ch",
        "output_dir": "./output",
        "return_content_list": "false",
        "backend": "vlm-engine",
        "table_enable": "true",
        "formula_enable": "true"
    }

    files = {"files": open(file_path, "rb")}

    headers = {}
    if API_KEY:
        headers["Authorization"] = f"Bearer {API_KEY}"

    try:
        response = requests.post(PARSE_URL, data=data, files=files, headers=headers)
        print(f"状态码: {response.status_code}")
        print(f"响应体: {response.text[:1000]}")
        response.raise_for_status()
        # 尝试解析 JSON
        try:
            result = response.json()
        except ValueError:
            result = {"raw_text": response.text}

        with open(output_file, "w", encoding="utf-8") as f:
            json.dump(result, f, ensure_ascii=False, indent=2)

        print(f"解析成功: {file_path} -> {output_file}")
        return result
    except Exception as e:
        print(f"解析失败: {file_path}, 错误: {e}")
        return None
    finally:
        files["files"].close()

# ================= 主程序 =================
if __name__ == "__main__":
    # 输入文件
    input_pdf = r"C:/Users/XXXXXX.pdf"
    # 输出文件
    output_json = os.path.join(os.path.dirname(__file__), "output", "1.json")

    # 确保输出目录存在
    os.makedirs(os.path.dirname(output_json), exist_ok=True)

    print(f"开始解析: {input_pdf}")
    result = parse_file(input_pdf, output_json)

瞅一眼日志，可以看到 MinerU API 模型已经顺利拿到了请求

那么问题又来了：更进一步，能不能把自定义的业务服务也挂载到 GPustack 上呢？

嘿嘿，那就留到下一期再聊吧，敬请期待~

About GPUStack

GPUStack 是由 GPUStack.ai 所推出的开源项目。GPUStack.ai 成立于2022年，是 AI Infra 解决方案提供商，目前已完成5300万元种子轮融资。创始团队成员均来自业界应用广泛的 Kubernetes 管理平台 Rancher 的核心团队。其中，联合创始人及 CTO 梁胜博士是前 SUSE 全球工程及创新总裁，加入 SUSE 之前，梁胜博士于2014年9月创立全球著名的容器管理平台公司 Rancher Labs 并担任 CEO。

我们的愿景是赋能企业可以在任意环境使用人工智能以实现业务的卓越运营。GPUStack 是实现这一目标的重要一步。

使用 GPUStack 迅速搭建你的专属 MaaS 平台！开始在本地快速构建 GPU 集群，运行和使用各种 AI 模型，赋能您的 AI 应用。

【开源地址】：github.com/gpustack/gpustack