mnote/services/mineru/README.md

MinerU OCR 服务

为满足 rebuild.md 阶段 D 第 9 项的要求，这里提供一份最小化的 MinerU OCR 部署脚本集，便于在本地启动 127.0.0.1:18888 的 OCR 服务，并与 ingest_service / mindrag 插件联动。

目录结构

services/mineru/
├─ README.md                # 使用说明（当前文件）
├─ setup.ps1                # 克隆/更新官方 MinerU 仓库并建立 Python 虚拟环境
├─ start.ps1                # 从虚拟环境中启动 MinerU HTTP 服务
├─ requirements.txt         # 额外依赖（如 fastapi/uvicorn），方便离线安装
└─ src/                     # `setup.ps1` 自动 clone 的 MinerU 官方代码

⚠️ 说明：MinerU 官方仓库体积较大且依赖多种外部模型。这里的脚本仅负责准备环境与示例启动流程，实际运行仍需参考官方文档完成模型下载、配置等步骤。

安装步骤

1. 确保已安装 Python 3.10+、git、pip。
2. 执行 ./setup.ps1（可选参数见脚本头部）：

   cd services/mineru
   ./setup.ps1 -PythonExe python -RepoUrl https://github.com/opendatalab/MinerU.git
   

   • 首次执行会在 services/mineru/src clone 官方代码，并在 .venv 目录创建虚拟环境。
   • 如果官方仓库已存在，脚本会尝试 git pull，以保持最新。
3. 根据官方 README（https://github.com/opendatalab/MinerU/blob/master/README_zh-CN.md）下载或配置所需模型、权重文件，并将相关路径写入 src/.env 或官方配置文件中。
4. 启动服务：

   ./start.ps1 -Host 127.0.0.1 -Port 18888
   

   • 默认使用 uvicorn 启动 mineru.api.server:app（如官方仓库版本不一致，可在脚本中调整 -ModulePath 参数）。
   • 启动后可访问 http://127.0.0.1:18888/health，scripts/check_env.ps1 会据此校验。

与 ingest_service / mindrag 集成

• scripts/check_env.ps1 现已新增 -MineruEndpoint 参数，会自动检测 /health 是否返回 200。
• mindrag 插件的 RAG 面板（PanelRag.vue）以及 ingest_service 的 OCR 逻辑，会读取环境变量或设置面板中指定的 OCR 源：
  • 选择 “MinerU OCR” 时，请确保 start.ps1 已启动服务，并在配置中填写 http://127.0.0.1:18888。

常见问题

1. 如何更改监听地址/端口？
   start.ps1 支持 -Host 与 -Port 参数，同时可通过环境变量 MINERU_HOST、MINERU_PORT 覆盖。

2. 如何与 Supabase 同步 OCR 结果？
   ingest_service 会把 MinerU 识别结果写回思源 /api/asset/setImageOCRText，并同步 note_blocks.properties.ocr_text 至 Supabase。只要 MinerU 服务可用，链路即可打通。

3. 如何卸载或重新安装？
   删除 services/mineru/.venv 与 services/mineru/src 即可清理，再重新执行 setup.ps1。

如需 Docker 化或模型缓存策略，可在此目录继续扩展 docker-compose.yml 或 Makefile。当前脚本重点是给定制版思源提供一套可复用的部署入口。