xiaomi-ocr

Xiaomi-OCR-0

在需要 OCR、文档解析、KIE 或 OCR-VQA 的任务中使用此 Skill。推理在用户的设备上运行，使用 Hugging Face 检查点 SeerRay-Lab/Xiaomi-OCR-0 和 SGLang、vLLM 或实验性的 Ollama 后端。MCP 服务负责提示词、图像/PDF 预处理、可选的版面分割、裁剪处理、并发和输出格式化。请调用任务工具；不要使用单独的工具或直接模型请求来重现这些步骤。

此仓库的 MCP 会将推理请求发送到 MCP 服务主机上的环回 HTTP 端点；它不会调用 Mify。其他已安装的 Skill 或服务可能也使用 xiaomi-ocr 这个名称。在说明文件处理位置之前，请根据工具描述和配置确认所选的 MCP。使用远程 MCP 时，image_path 和 pdf_path 指向该服务的文件系统，而不是 Agent 的设备。

设置本地推理

选择推理后端

遵循用户明确指定的后端/模型偏好和准确性要求。否则：

• 现有本地服务： 复用可用的 Xiaomi-OCR-0 端点及其配置的后端/模型。检查 MCP 配置、运行中的服务及其模型列表；仅凭 OpenAI 兼容 URL 无法确定运行时。除非与用户要求冲突，否则保留可用的后端。
• 支持的 GPU 环境： 优先使用 SGLang 或 vLLM 搭配原始的 SeerRay-Lab/Xiaomi-OCR-0 检查点，尤其是对准确性要求较高的任务。复用兼容的已安装运行时和缓存权重。若需全新设置，请检查当前官方运行时对主机和 Qwen3_5ForConditionalGeneration 的支持情况；若支持，则选择 vLLM，否则在兼容时选择 SGLang。
• SGLang/vLLM 不可用或不适用的桌面/本地设置： 如果主机内存足以运行 BF16 模型，则使用兼容 Qwen3.5 的 Ollama。这是便捷的本地方案，也适用于兼容的 macOS 设置。请阅读完整仓库中的Ollama 设置说明。默认使用 longwayxu/xiaomi-ocr-0:bf16；若已存在则复用，否则在用户授权设置/下载后拉取。不要擅自换成量化标签。

Ollama 仍处于实验阶段：选择它时，请说明文档中记载的公式差异。BF16 权重并不能证明与 HF 输出一致。如果用户要求结果与 HF 等效，应优先通过 SGLang/vLLM 使用原始检查点；如果该方案不可用，请说明限制，并在选择 Ollama 前与用户协商准确性方面的取舍。不要仅凭后端名称就承诺数值等效。

运行 MCP 安装程序之前，请设置以下三个变量，以免意外保留先前后端的值：

服务	XIAOMI_OCR_BACKEND	XIAOMI_OCR_LOCAL_URL（默认值）	XIAOMI_OCR_MODEL（默认值）
SGLang / vLLM	openai	http://127.0.0.1:8000/v1	SeerRay-Lab/Xiaomi-OCR-0
Ollama	ollama	http://127.0.0.1:11434/v1	longwayxu/xiaomi-ocr-0:bf16

对于现有服务，请使用其实际的环回端口和所提供的模型名称。安装程序会将这些值保存到 MCP 配置中。图像预处理和任务提示词都应由此 MCP 服务负责，包括使用 Ollama 时。

安装并连接

1. 检查现有服务、运行时安装、缓存权重和可用内存；根据上述规则选择后端。说明所选方案，以及所需的环境创建或下载。若现有设置授权涵盖这些更改，则使用该授权；仅在缺少授权或存在尚未解决的兼容性／准确性选择时征求确认。用户无需先选择运行时即可开始安装。

2. 如果缺少所选运行时，请根据其当前官方安装指南检查操作系统、GPU、驱动程序以及相关 CUDA/PyTorch 环境。对于 SGLang/vLLM，必须支持 Qwen3_5ForConditionalGeneration。对于 Ollama，请遵循链接中的设置说明。默认情况下，应复用兼容的安装，而不是替换其他运行时。

3. 启动所选服务，并将其绑定到回环地址。对于 Ollama，请遵循链接中的说明并使用上述模型标签。对于 SGLang/vLLM，示例如下（根据硬件调整张量并行度和内存限制）：

   python -m sglang.launch_server \
     --model-path SeerRay-Lab/Xiaomi-OCR-0 \
     --host 127.0.0.1 --port 8000 --context-length 16384
   

   vllm serve SeerRay-Lab/Xiaomi-OCR-0 \
     --host 127.0.0.1 --port 8000 \
     --trust-remote-code --max-model-len 16384
   

   如果引擎无法加载模型或接收图像，请查阅其当前兼容性说明。如果现有设置授权不涵盖升级，请先取得升级授权。不要切换到托管端点。连接 MCP 后，先验证实际图像请求，再报告推理已就绪。

4. 复用或克隆完整的 GitHub 仓库。MCP 会导入其中共享的 evaluation_pipeline/ 和 postprocess/ 模块。在该检出目录的 skills/xiaomi-ocr/ 中运行安装程序（Codex 使用 bash install.sh --agent=codex，其他 Agent 使用 bash install.sh）。如果使用独立的 Skill，请将 XIAOMI_OCR_REPO 设置为完整检出目录。 运行 bash install.sh 前，请说明它会创建私有 .venv、下载 requirements.txt 中的包，并在适用时向 Codex 配置中注册一条 MCP 配置项。如果有现成的兼容 MCP 环境，请复用。在尚未获得相关授权时，创建环境或下载依赖前须取得用户授权。对于其他 Agent，请将生成的 mcp-config.json 配置项合并到当前 Agent 的 MCP 设置中，不要替换无关配置项，然后重启或重新扫描。MCP 服务仅连接到模型的回环监听器。

5. 完成完整的 Agent 辅助安装时，除非用户要求仅设置页面模式，否则应包含印刷文档区域模式。将 PaddlePaddle/PaddleX 包以及可能下载的 PP-DocLayoutV3 权重纳入设置计划说明。如果现有设置授权涵盖这些下载，则使用该授权；仅在授权不涵盖时征求确认。

   根据官方 PaddlePaddle 安装指南和 PaddleX 安装指南，检查操作系统、Python 版本、CPU/GPU 支持情况和可用 GPU 内存。 在 MCP 环境中安装兼容的 PaddlePaddle wheel，然后使用该环境中的 Python 运行 -m pip install -r <repo>/requirements-paddlex.txt。其中包含 paddlex[cv] 和 shapely；仅安装普通 paddlex 不足以支持 PP-DocLayoutV3。复用兼容的包和缓存权重。如果 GPU 内存有限，请使用受支持的 CPU 构建，并在 MCP 环境中设置 XIAOMI_OCR_LAYOUT_DEVICE=cpu。如果 Demo 使用单独的 Python 环境，设置 Demo 时也要在那里安装区域处理依赖。 在本地加载 PP-DocLayoutV3（首次使用时可能会下载其 权重），然后先通过一次真实的 ocr_image 调用（设置 mode="region"）进行验证，再报告区域模式已就绪。区域检测、 裁剪和 OCR 均在 MCP 服务内部完成。如果平台不受支持或设置失败，请报告失败的步骤，并保留已验证的页面 OCR、KIE 和 VQA 功能； 不要默默地将页面模式说成区域模式。

官方运行时参考： SGLang Qwen3.5 指南 · vLLM Qwen3.5 模型实现 · vLLM 支持的模型。

选择合适的任务和文档模式

• 印刷、版式规整的文档：使用 ocr_image 或 ocr_pdf，并设置 mode="region"。MCP 在本地运行 PP-DocLayoutV3、裁剪区域、并发发送独立请求，然后恢复阅读顺序并合并输出。模型提示词要求使用 OTSL；MCP 会在返回的 Markdown 中将表格转换为 HTML，并格式化 LaTeX 公式。
• 场景文字、手写笔记、书法、古籍或版式不规则的文档： 使用 mode="page"。区域检测可能会错误地拆分行、栏或相连的手写内容，导致上下文丢失并加剧识别错误。整页模式可以保留这些关联。
• 关键信息提取：调用 kie_image。如果输出键已知，请传入 fields；MCP 会构建 Schema 提示词并返回解析后的 JSON。对于通用键值提取，请将 fields 留空。
• 关于文档图像的问答：使用图像和问题调用 vqa_image。MCP 会应用简洁的回答格式。
• PDF：调用 ocr_pdf，并根据相同的文档指南选择页面模式或区域模式。优先使用本地文件路径，而不是 base64，以避免负载被截断。

可用的 MCP 工具有 ocr_image、ocr_pdf、kie_image、vqa_image 和 runtime_status。页面／区域预处理和后处理均在这些调用内部完成。

ocr_image、ocr_pdf 和 kie_image 接受 max_tokens（默认值为 4096）。 对于 OCR，该值是页面模式下每页或区域模式下每个区域的最大输出量。 所有区域类型均使用所提供的值，每个 PDF 页面／区域也都有各自的预算。KIE 将其应用于单次提取。显式传入的参数会覆盖服务器中 XIAOMI_OCR_MAX_TOKENS 的默认值。 如果输出被截断，只有在图像／提示词 token 与请求的输出量之和适合推理服务器的上下文窗口时，才应增大该值。若发生上下文溢出错误，则需要减小输出预算或缩小输入。vqa_image 使用固定的 1024-token 预算来生成简洁回答。

运行时监控

使用 runtime_status({}) 获取简明概览：已解析的设备、活动任务、容量以及最近完成的三个任务。使用 runtime_status({"request_id":"…" }) 跟踪特定任务，无需探测硬件。ID 会显示在进度消息中，并在 OCR 结果后单独的 Runtime: 文本块中显示。第一个内容块仍然是 OCR 结果；不要将运行时块包含在提取的文档文本中。最近完成的八个任务摘要在被淘汰或此进程重启前仍可查询；ID 不可用时会返回 found: false，而不是捏造的完成状态。使用 verbose: true 查看活动任务的逐页和阶段详情；仅当概览需要新鲜的设备信息时才使用 refresh: true（否则会缓存 30 秒）。此信息仅报告此服务进程，不包括其他 Demo/MCP 进程。任务设备信息是该任务期间最近观测到的证据；如需新鲜的设备信息，请在概览中请求。记录的缓存时长是观测时的缓存年龄。使用 display_device 查看适合人类阅读的设备位置，使用 gpu_indices 查看主机 nvidia-smi 卡号。原始预测器 device 可能使用进程本地的 CUDA 索引，不得将其替换为物理索引。设备标签不会公开 UUID。必须通过运行时元数据确认 CPU；缺少 NVIDIA 工具或 GPU 驻留都不能证明是在 CPU 上执行。CPU + GPU 保留已报告的卸载信息。此操作不会加载模型。报告运行时解析出的设备及其来源，并与已配置／请求的设备分开说明。未加载或无法观测的设备仍属未知。PaddleX 可能会自动选择 GPU；设置 XIAOMI_OCR_LAYOUT_DEVICE=cpu 后，在重启 MCP 后会选择 CPU 布局。不要仅仅因为用户请求监控就更改设备位置。

当客户端支持 MCP 进度时，在工具请求元数据中加入唯一的 _meta.progressToken。进度涵盖布局加载／检测、队列等待、推理、PDF 页／区域和组装，并包含等待期间的心跳。转发这些更新，不要臆造完成百分比。协议的 progress 数字是递增的事件序号，并非百分比或工作量计数。使用共享摘要中的 pages 和 regions 统计工作量：页数统计已处理的页面，包括 failed 页面和成功处理的 blank 页面；PDF 区域总数统计已发现的区域，直到 total_is_final 为 true。phase、active_pages、elapsed_ms、last_activity_ms（距离非心跳事件的时间）、error 和 warning 可说明当前进展。仅凭静默不能证明任务已卡住。终止状态可区分已完成、部分完成、失败和已取消。即使客户端不支持进度，仍可获取结构化 stderr 日志和最终结果中的 _meta.xiaomi_ocr 摘要。其他 OCR 调用运行时，仍可查询 runtime_status。

输出处理

保留模型的阅读顺序和 Markdown 格式。不要补全无法读取的内容；保留模型的不确定性。表格转换和文档组装在 MCP 内部完成。不要要求 Agent 调用单独的后处理器。对于 KIE，保留 JSON 键和值；对于 VQA，返回简洁的答案，不要添加缺乏依据的细节。

如果 MCP 报告本地模型不可用，请先检查已配置的服务，然后遵循上述后端选择和设置授权规则。如果区域模式报告缺少 PaddleX/PaddlePaddle，请说明所需的额外软件包和可能需要下载的版面权重，然后使用现有授权；如果授权不涵盖安装操作，请征求许可。在此期间，整页模式仍可使用。

Demo 和 MCP 通过相同的 execute_tool 和 CallMonitor 实现运行。 每个服务进程最多同时运行两个任务，OCR 推理并发数默认为四（XIAOMI_OCR_CONCURRENCY）。任务繁忙错误需要在任务完成后重试。Demo 将图像快照合并为每秒两次中间更新，并每秒轮询一次正在运行的 PDF 任务；空闲页面不会轮询硬件。