# 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`（可选参数见脚本头部）：
   ```powershell
   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. 启动服务：  
   ```powershell
   ./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`。当前脚本重点是给定制版思源提供一套可复用的部署入口。