# 小米开源 Xiaomi-OCR-0：0.8B 文档理解模型，附 vLLM / Ollama 自托管教程 **URL:** \ **Category:** IT\ **Tags:** 开源, ai, 自建\ **Created:** [2026 年10 月 31 日 05:02 UTC](https://www.sunai.net/t/topic/1559 "2026-10-31T05:02:04Z")\ **Posts on this page:** 1\ **Page:** 1
作者： ![wood](https://www.sunai.net/user_avatar/www.sunai.net/wood/32/1032_2.png) [@wood](https://www.sunai.net/u/wood)\ 发布日期： [2026 年10 月 31 日 05:02 UTC](https://www.sunai.net/t/topic/1559/1 "2026-10-31T05:02:04Z")
Xiaomi-OCR-0 是小米开源的 0.8B 文档理解模型，以 Qwen3.5-0.8B-Base 为基础，使用约 1.7 亿条 OCR 相关样本训练。模型权重采用 Apache-2.0 许可证，除了识别文字，还能解析文档结构、提取指定字段，以及回答图片中的文字内容问题。 技术报告和模型权重于 2026 年 9 月 30 日发布，项目同时提供本地网页 Demo、MCP 服务和 Agent Skill。 ## 能做什么 - 将文档图片解析为 Markdown，公式输出为 LaTeX，表格经过后处理转换为嵌入 Markdown 的 HTML 表格。 - 按指定字段进行关键信息抽取（KIE），输出 JSON。 - 对文档图片进行视觉问答（VQA），例如查询票据上的金额、日期，或询问图表中的内容。 - 在本地网页中上传 PDF，逐页解析；通过 MCP 把这些能力接入 Agent。 PDF 需要先渲染成图片，再交给模型识别。网页 Demo 中，PDF 输入用于文档解析；KIE 和 VQA 使用图片输入。 ## 成绩怎么样 下表来自项目方公布的对比结果，三列均为相应基准的 Overall 得分，越高越好。“—”表示该表未提供成绩。 | 模型 | 参数量 | OmniDocBench v1.6 | Real5-OmniDocBench | Wild-OmniDocBench | | --- | --- | --- | --- | --- | | Xiaomi-OCR-0 | 0.8B | 96.83 | 95.24 | 87.94 | | TeleOCR | 1.2B | 96.87 | — | 88.53 | | OvisOCR2 | 0.8B | 96.58 | 92.29 | 87.91 | | PaddleOCR-VL-1.6 | 0.9B | 96.33 | 93.19 | 87.36 | | MinerU2.5-Pro | 1.2B | 95.75 | 88.94 | 87.33 | | GLM-OCR | 0.9B | 95.22 | 90.32 | 85.08 | Xiaomi-OCR-0 在这组结果中，Real5 得分最高；OmniDocBench v1.6 和 Wild 则略低于 TeleOCR。同为 0.8B 的 OvisOCR2 与它在 OmniDocBench v1.6、Wild 上的差距较小。 ![项目方公布的 OmniDocBench v1.6 参数效率对比](https://i.czl.net/r2/original/2X/d/dd2467a1fabba0a8e7b14db066e952396e5f0730.png) 文档问答方面，DocVQA、InfoVQA、ChartQA、OCRBench、TextVQA 五项得分的算术平均为 83.2，高于 Qwen3.5-0.8B 的 72.9 和 Qwen3.5-2B 的 80.9，低于 Qwen3.5-4B 的 84.9。这说明 OCR 专项训练带来了收益，不代表它在通用能力上超过更大的模型。 **上述三个文档解析基准使用的都是两阶段流程：先检测版面区域，再裁剪识别、恢复阅读顺序并组装结果。** 单独调用模型做整页识别，不等于复现这组成绩。95.24 也不是“任意文档有 95.24% 的字符识别正确率”。 ## 自托管前需要准备什么 项目网页与 MCP 要求 Python 3.10 或以上；推理框架还有自己的 Python、GPU 和驱动要求。下面 vLLM 路线以 Linux、Python 3.12 和兼容的 NVIDIA GPU 为例，Windows 可使用配置好 GPU 的 WSL2。vLLM 不原生支持 Windows。 0.8B 是参数规模，不是完整服务的显存占用。实际资源还包括视觉编码、图像分辨率、上下文、推理缓存和并发请求。项目安装说明没有给出统一的最低显存或吞吐保证，不能仅凭参数量判断某张显卡能否运行。 有两条部署路线： | 路线 | 用途与区别 | | --- | --- | | 原始权重 + vLLM / SGLang | 使用原始模型，运行时必须支持 Qwen3.5 多模态架构；本教程以 vLLM 为例 | | 社区 BF16 包 + Ollama | 安装步骤较少，包含视觉投影器，下载约 1.8 GB；目前为实验性方案 | ## 路线一：vLLM + 本地网页 ### 1. 获取项目 ```bash git clone https://github.com/xiaomi-research/Xiaomi-OCR-0.git cd Xiaomi-OCR-0 ``` ### 2. 创建独立推理环境 以下安装适用于驱动满足当前 vLLM wheel 要求的环境。CUDA、驱动或平台不匹配时，应按 vLLM 官方 GPU 安装指南选择对应构建，不要混用已有 PyTorch 环境。 ```bash python3.12 -m venv .venv-vllm source .venv-vllm/bin/activate python -m pip install --upgrade pip python -m pip install vllm ``` 当前版本需要支持 `Qwen3_5ForConditionalGeneration`。如果启动时报架构不支持，应核对 vLLM 的模型支持和版本，而不是改成纯文本模型加载。 ### 3. 启动模型服务 ```bash vllm serve xiaomi-research/Xiaomi-OCR-0 \ --host 127.0.0.1 \ --port 8000 \ --max-model-len 16384 ``` 首次启动会下载模型，加载完成后保留该终端。项目部分说明仍使用旧组织名 `SeerRay-Lab/Xiaomi-OCR-0`，Hugging Face 目前将其重定向到 `xiaomi-research/Xiaomi-OCR-0`；服务名称应以实际接口返回为准。 在另一个终端检查模型列表： ```bash curl -fsS http://127.0.0.1:8000/v1/models ``` ### 4. 启动网页 在另一个终端进入项目目录，为网页单独创建环境： ```bash cd Xiaomi-OCR-0 python3.12 -m venv .venv-demo source .venv-demo/bin/activate python -m pip install --upgrade pip python -m pip install -r requirements.txt export XIAOMI_OCR_LOCAL_URL=http://127.0.0.1:8000/v1 export XIAOMI_OCR_MODEL=xiaomi-research/Xiaomi-OCR-0 python demo/server.py --port 8787 ``` 如果 `/v1/models` 返回的模型 ID 不同，把 `XIAOMI_OCR_MODEL` 改为对应 ID。环境变量要在启动网页的终端中设置。 浏览器打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)，先选一张清晰图片，用整页模式确认识别正常，再测试 PDF、字段抽取和问答。整页模式不需要 PaddleX。 服务器部署时，可以通过 SSH 隧道访问网页，不必直接开放端口： ```bash # 在自己的电脑执行，将 user 和 server 替换为服务器信息 ssh -N -L 8787:127.0.0.1:8787 user@server ``` 然后在自己电脑打开同一地址。推理服务保持监听 `127.0.0.1`，网页 Demo 也只接受回环地址作为推理后端。 ## 路线二：Ollama + 本地网页 先安装支持 Qwen3.5 的 Ollama，并确认本地服务已运行。项目记录的测试版本为 Ollama 0.35.0。 ```bash ollama pull longwayxu/xiaomi-ocr-0:bf16 ``` 这个社区包包含语言模型和视觉投影器，约 1.8 GB。进入项目目录，在网页 Python 环境中运行： ```bash # 首次使用时创建环境并安装依赖；已有 .venv-demo 可直接激活 python3.12 -m venv .venv-demo source .venv-demo/bin/activate python -m pip install -r requirements.txt export XIAOMI_OCR_BACKEND=ollama export XIAOMI_OCR_MODEL=longwayxu/xiaomi-ocr-0:bf16 export XIAOMI_OCR_LOCAL_URL=http://127.0.0.1:11434/v1 python demo/server.py --port 8787 ``` 打开 [http://127.0.0.1:8787](http://127.0.0.1:8787)。以上为 Bash 命令；Windows 原生环境激活虚拟环境和设置环境变量时，需要使用对应的 PowerShell 写法。 识别入口应使用项目网页或 MCP。只执行 `ollama pull`，不会自动配置项目所用的图片预处理、非思考提示词和解码设置。 Ollama 路线尚未确认与原始权重精度一致。项目记录的一次 Apple Silicon 小样本对齐测试中，7 个输入的 token 数全部相同，但完整回复只有 5 个相同，公式案例存在差异。这不是准确率统计，也不能将原始权重的榜单成绩直接套到 Ollama 或其他 GGUF 转换版上。 ## 可选：启用区域解析 对于版式规整的印刷文档，可以安装 PP-DocLayoutV3 版面检测依赖，让系统按区域裁剪、并发识别，再恢复阅读顺序。 先按 PaddlePaddle 官方安装指南，为当前操作系统、Python 和 CPU/GPU 安装适配的 PaddlePaddle，然后在运行网页的环境中执行： ```bash python -m pip install -r requirements-paddlex.txt # 仅让版面检测使用 CPU，不会把主 OCR 模型切换到 CPU export XIAOMI_OCR_LAYOUT_DEVICE=cpu python demo/server.py --port 8787 ``` 该依赖清单包含 `paddlex[cv]` 和 `shapely`，不能只安装普通 `paddlex`。首次使用还可能下载 PP-DocLayoutV3 权重。 切换网页到区域模式后，需要实际提交一次区域解析任务确认安装完成。网页显示模型已连接，并不代表版面检测依赖也已安装。 手写、书法、古籍、场景文字及不规则版式，项目建议优先使用整页模式，以免区域切分错误导致上下文丢失。严格复现榜单还要使用项目提供的评测配置和两阶段流程，不能只看网页模式名称。 ## 可选：接入 MCP 模型服务可用后，在项目根目录执行。下面以 vLLM 为例： ```bash XIAOMI_OCR_LOCAL_URL=http://127.0.0.1:8000/v1 \ XIAOMI_OCR_MODEL=xiaomi-research/Xiaomi-OCR-0 \ bash skills/xiaomi-ocr/install.sh ``` 安装脚本会创建 MCP 的 Python 环境、安装依赖并生成 `mcp-config.json`。将其中的服务配置合并到所用客户端的 MCP 配置中，然后重启或重新扫描服务。 如果使用 Ollama，将 URL 改成 `http://127.0.0.1:11434/v1`，模型名改成 `longwayxu/xiaomi-ocr-0:bf16`。安装脚本需要显式传入这两个变量，不能只用 `XIAOMI_OCR_BACKEND=ollama` 代替。 MCP 提供 `ocr_image`、`ocr_pdf`、`kie_image`、`vqa_image` 四个工具。图片/PDF 预处理、提示词、表格转换等由工具处理；MCP 环境中的区域模式依赖需要单独安装，不能用网页环境的安装结果代替。 ## 常见问题 - **网页连不上模型：** 先检查推理进程和 `/v1/models`，再核对网页终端中的 URL、模型 ID。切换推理后端后重启网页进程。 - **整页正常、区域报错：** 检查 PaddlePaddle、`paddlex[cv]`、`shapely` 和布局权重是否装在实际使用的 Python 环境里。 - **显存不足：** 降低并发、输入分辨率或上下文配置，再用自己的文档验证质量。模型参数小不代表整个推理服务只占很少显存。 - **长文输出截断：** 项目默认输出预算为 4096 tokens，16384 的上下文还需容纳图片和提示词。不能把输出预算直接设成全部上下文长度。 ## 项目链接 - [GitHub 项目](https://github.com/xiaomi-research/Xiaomi-OCR-0) - [Hugging Face 模型与许可证](https://huggingface.co/xiaomi-research/Xiaomi-OCR-0) - [技术报告](https://arxiv.org/abs/2609.36136) - [手动安装与 MCP](https://github.com/xiaomi-research/Xiaomi-OCR-0/blob/main/INSTALL.md) - [Ollama 配置与精度验证记录](https://github.com/xiaomi-research/Xiaomi-OCR-0/blob/main/OLLAMA.md) - [网页 Demo 说明](https://github.com/xiaomi-research/Xiaomi-OCR-0/blob/main/demo/README.md) - [两阶段评测流程](https://github.com/xiaomi-research/Xiaomi-OCR-0/blob/main/evaluation_pipeline/README_zh.md) - [vLLM GPU 安装指南](https://docs.vllm.ai/en/latest/getting_started/installation/gpu/) - [PaddlePaddle 安装指南](https://paddlepaddle.github.io/PaddleX/latest/installation/paddlepaddle_install.html)