[lottshin]

背景

关联 #266（“OCR 功能依赖 GPU，能否用多模态模型做识别”），为其中“用多模态模型做识别”的诉求提供一个可直接选择的引擎。

本 PR 新增 minicpm_ocr 引擎：Yuxi 只把 PDF 页面/图片发送给用户自托管的 vLLM（MiniCPM-OCR 1.0 的 OpenAI 兼容服务），不在 API 镜像内加载模型，也不需要本机 GPU。定位与现有 deepseek_ocr 相同——远端 VLM 识别，逐页返回文本。

改动

• backend/yuxi/infrastructure/document_parsing/engines/minicpm_ocr.py：新引擎，复用 DocumentEngine 契约、PDFIUM_LOCK 与 render_pdf_page_image，PDF 逐页渲染后识别，图片直接读取。
• engines/__init__.py：注册 minicpm_ocr（支持 .pdf/.png/.jpg/.jpeg/.bmp/.webp，与 deepseek_ocr 一致）。
• modules/documents/options.py：新增 minicpm_ocr_opts（api_url、可选 api_key、model），环境变量 MINICPM_OCR_API_URL / MINICPM_OCR_API_KEY。前端配置页由服务端字段驱动，无需改动。
• 文档：docs/advanced/document-processing.md 增加引擎说明与 vLLM 启动命令；新增 decision record。

协议细节

官方 vLLM 部署要求每个请求携带多模态切片参数，缺少时服务端拒绝或降质，因此请求固定包含：

{
  "mm_processor_kwargs": {"downsample_mode": "4x", "max_slice_nums": 9},
  "chat_template_kwargs": {"enable_thinking": false},
  "temperature": 0.01, "top_p": 0.001, "top_k": 1,
  "repetition_penalty": 1.0, "no_repeat_ngram_size": 100
}

• 消息顺序为 image_url → Text Recognition:，与官方示例一致。
• 未配置 API Key 时不发送 Authorization，兼容未启用 --api-key 的部署。
• finish_reason != "stop" 或正文不是字符串时失败，沿用 parser 既有发布边界，不产生 document.md。
• 健康检查读取同服务的 /v1/models。

验证

• pytest test/unit/knowledge/test_minicpm_ocr.py test/unit/knowledge/test_parser_capabilities.py -q → 20 passed
• pytest test/unit/knowledge -q -m "not slow" → 534 passed, 1 skipped
• pytest test/unit/services/test_ocr_service.py -q → 15 passed（包含新增的 MINICPM_OCR_API_URL 解析用例）
• ruff check（改动文件）→ 通过；python3 scripts/ci/verify_engineering_contracts.py → 通过
• test/integration/api/test_system_router_api.py 需要真实 Compose 栈，本机 skipped，未计入通过；已同步更新其 option_keys 断言。

未验证：本机没有 GPU / vLLM 服务，未做真实 MiniCPM-OCR 调用，协议层回放不代表识别质量。另外本机 test/unit/services 的 5 个 skills/workspace 用例与 test/unit/config 的 docker compose 用例失败，stash 本次改动后基线同样失败，与本次改动无关。

取舍

• 不引入 minicpm-ocr pip SDK（PP-DocLayoutV3 版面检测），因为它会带来 torch/paddle 级依赖与模型下载，和“不要求本机 GPU”的目标冲突。
• 输出是逐页纯文本，不恢复跨页阅读顺序与表格/公式结构；需要版面输出时继续使用 MinerU / PaddleOCR 系列引擎，文档中已注明。

[Yuchuan925]

动机和方案并不认可。以及未实机验证