Xinference 中 MinerU2.5-2509-1.2B 文档理解 OCR 模型：启动命令、/v1/images/ocr 调用链与引擎适配机制详解
【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference
本文围绕 Xinference 内置模型 MinerU2.5-2509-1.2B 展开。MinerU2.5-2509-1.2B 是 OpenDataLab 推出的文档理解视觉语言模型（VLM），在 Xinference 中既可作为 image 类型的 OCR 模型通过一行xinference launch命令拉起，也可走 vLLM/Transformers 引擎以对话 + 视觉（chat、vision）能力运行。读完本文，你将掌握该模型的规格与启动方式、Xinference 的 OCR 请求处理链路（含 PDF 光栅化与整档解析任务），以及 OCR 引擎注册与虚拟环境依赖解析的源码级机制，从而能独立部署并调用这套文档理解服务。
模型基本规格
按照官方模型页 doc/source/models/builtin/image/mineru2.5-2509-1.2b.rst 的记录，该模型的核心元数据如下：
| 属性 | 取值 |
|---|---|
| 模型名称 | MinerU2.5-2509-1.2B |
| 模型家族 | ocr |
| 能力（Abilities） | ocr |
| 可用 ControlNet | 无 |
| Model ID | opendatalab/MinerU2.5-2509-1.2B |
同一模型在 Xinference 的 LLM 内置模型表中也有登记，见 doc/source/models/builtin/llm/mineru2.5-2509-1.2b.rst 与 xinference/model/llm/llm_family.json。从 LLM 登记信息可以确认：
- 模型描述："MinerU2.5-2509-1.2B is a vision language model for document understanding."（面向文档理解的视觉语言模型）；
- 上下文长度：32768；
- 支持语言：英文（en）、中文（zh）；
- 能力：
chat、vision； - 模型架构：
Qwen2VLForConditionalGeneration，即基于 Qwen2-VL 架构微调的视觉语言模型； - 模型格式/规格：pytorch 格式，约 1.2B 参数（
1_2Billion），无量化版本（quantizations: none）； - 支持的引擎：vLLM、Transformers；
- 模型来源：Hugging Face 与 ModelScope 双源，Model ID 均为
opendatalab/MinerU2.5-2509-1.2B。
虚拟环境依赖（virtualenv）
从llm_family.json中该模型的virtualenv.packages字段可以看到，Xinference 会为这个模型自动准备独立虚拟环境，依赖包括：
transformers>=4.45.0 # 仅当 engine == "Transformers" mineru-vl-utils[transformers] # 仅当 engine == "Transformers"，MinerU 官方工具库 vllm_dependencies # 仅当 engine == "vllm" qwen-vl-utils qwen_omni_utils audioread #system_torch#、#system_numpy#（复用系统级 torch/numpy，避免重复安装）这说明该模型与 MinerU 官方推理工具链深度绑定：Transformers 引擎下会额外安装mineru-vl-utils来提供 MinerU 的提示词/后处理能力；vLLM 引擎下则复用 Xinference 的vllm_dependencies。这种按引擎条件注入依赖的机制由 Xinference 的虚拟环境管理器统一处理（见 xinference/core/virtual_env_manager.py）。
启动模型
image 类型启动（OCR 服务）
官方文档给出的启动命令为：
xinference launch --model-name MinerU2.5-2509-1.2B --model-type image执行后 Xinference 会拉取opendatalab/MinerU2.5-2509-1.2B并注册为一个 image 类型、具备ocr能力的模型。服务启动后，RESTful API 默认监听端口为9997（定义于 xinference/constants.py 中的XINFERENCE_DEFAULT_ENDPOINT_PORT = 9997），可通过http://localhost:9997/v1/models查看已启动的模型列表。
LLM 类型启动（对话 + 视觉）
由于该模型在 LLM 表中同样登记了 pytorch/1_2 规格、vLLM 与 Transformers 双引擎，也可以按 LLM 方式启动：
xinference launch --model-engine ${engine} --model-name MinerU2.5-2509-1.2B \ --size-in-billions 1_2 --model-format pytorch --quantization none其中${engine}取vllm或Transformers（none是 llm_family.json 中当前唯一登记的量化项）。以 LLM 方式启动后，模型以带视觉输入能力的对话模型对外提供/v1/chat/completions服务，适合"看图问文档内容"的交互式场景；以 image 方式启动则面向批量文档识别的/v1/images/ocr场景。
OCR 请求链路：/v1/images/ocr
路由注册
OCR 接口由 image 路由模块注册，xinference/api/routers/images.py 将POST /v1/images/ocr挂载到api.create_ocr。请求为 multipart 表单，包含三个字段：
| 字段 | 类型 | 说明 |
|---|---|---|
model | Form（必填） | 已启动模型的 UID |
image | File（必填） | 图片或 PDF 的原始字节 |
kwargs | Form（可选） | JSON 字符串，承载task、pages、dpi、request_id等控制参数 |
PDF 输入处理
create_ocr的实现位于 xinference/api/restful_api.py 附近，其输入处理逻辑依赖 xinference/api/pdf_ocr.py，要点如下：
- PDF 探测：
is_pdf_upload(content_type, head)通过 Content-Type 与文件魔数（PDF_MAGIC）双重判断上传物是否为 PDF； - 逐页光栅化：普通 OCR 任务会调用
rasterize_pdf将 PDF 渲染为逐页位图（内部用worst_case_parse_peak_pixels等函数基于像素预算计算安全缩放因子，避免超大页面撑爆显存），随后逐页调用模型实例的ocr()，最后用merge_ocr_page_results合并各页文本； - 整档解析任务：
WHOLE_DOCUMENT_OCR_TASKS = frozenset({"parse"})（xinference/api/pdf_ocr.py）定义了整文档解析路径——当kwargs中task="parse"时，模型自行解析整份 PDF（而非逐页位图），此时要求必须是 PDF 上传，且不支持pages、dpi参数，缩放上限由 xinference/model/image/ocr/deepdoc.py 中的MAX_PARSE_ZOOMIN/parse_zoomin控制； - 权限与任务追踪：入口处执行
_check_model_access做模型访问鉴权，并通过_add_running_task(request_id)将请求纳入运行任务追踪，便于取消与审计。
调用示例（以 curl 表示，实际以图片方式上传）：
curl -X POST "http://localhost:9997/v1/images/ocr" \ -F "model=<model_uid>" \ -F "image=@./scan.png"若上传 PDF 并希望整档解析，则在kwargs中传{"task": "parse"}。
OCR 引擎调度
模型侧的引擎选择逻辑集中在 xinference/model/image/ocr/ocr_family.py：
- 每个 OCR 引擎实现
OCRModel子类，声明required_libs并通过类方法match(model_family)声明自己能跑哪些模型规格； generate_engine_config_by_model_name在模型加载期遍历所有引擎类，把匹配成功的ocr_class写入OCR_ENGINES（结构为{模型名 -> {引擎名 -> [引擎参数]}}）；- 启动时
create_ocr_model_instance（xinference/model/image/core.py）通过check_engine_by_model_name_and_engine（或带虚拟环境感知版本的..._with_virtual_env）按"模型名 + 引擎 + 格式 + 量化"四元组定位具体引擎类；虚拟环境路径还支持engine_markers旁路校验——当模型以虚拟环境方式部署、且请求引擎在模型家族标记中时，可跳过静态兼容性检查直接返回该引擎的首选实现（见 xinference/model/image/ocr/ocr_family.py）。
vLLM 侧的 OCR 实现统一收敛在 xinference/model/image/ocr/vllm.py，其ocr()方法对 Qwen2-VL 系模型（MinerU2.5-2509-1.2B 即属此架构）采用如下关键参数：
- 图像缩放预算：
min_pixels = 448*448、max_pixels = 2880*2880，即单张输入图会被限制在该像素区间内，兼顾小字识别精度与显存占用； - 生成长度：
max_new_tokens默认 16384，适应长文档一次性输出； - 提示词通过
apply_chat_template(..., enable_thinking=False)构建，关闭思考模式，直出识别文本； - 输出经
_postprocess_output清洗（filter_imgtags可去除残留图像标签）。
与项目其余 OCR 模型的关系
Xinference 的 image 内置模型目录（见 doc/source/models/builtin/image/index.rst）收录了 GOT-OCR2_0、DeepSeek-OCR、HunyuanOCR、PaddleOCR-VL、Unlimited-OCR 等一批 OCR 模型，它们与 MinerU2.5-2509-1.2B 共享同一套ocr_family引擎注册与/v1/images/ocr调用协议。MinerU 系列的差异化定位在于：它不是纯"像素到文本"的检测式 OCR，而是文档理解 VLM——既能走 image 类型的 OCR 接口批量抽取文本，也能作为带chat/vision能力的 LLM 直接对版式、表格、公式进行问答式理解，这一双重身份正是其同时出现在 image 与 llm 两处模型文档中的原因。
小结
- MinerU2.5-2509-1.2B 的 Model ID 为
opendatalab/MinerU2.5-2509-1.2B，pytorch 格式、无量化，pytorch 约 1.2B 参数，上下文 32768，支持中英文文档理解； - 以 OCR 服务启动：
xinference launch --model-name MinerU2.5-2509-1.2B --model-type image；以对话模型启动则附加--model-engine、--size-in-billions 1_2、--model-format pytorch等参数，引擎可选 vLLM 或 Transformers； - 服务默认端口 9997，OCR 统一入口为
POST /v1/images/ocr，支持图片逐页识别与task="parse"整档 PDF 解析两种路径； - 引擎适配与依赖隔离由
ocr_family的引擎注册表和虚拟环境管理器共同完成，Transformers 引擎会自动安装mineru-vl-utils以复用 MinerU 官方后处理。
【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
