diff --git a/docs/en/usage/quick_usage.md b/docs/en/usage/quick_usage.md index b17f3dd0..e03df369 100644 --- a/docs/en/usage/quick_usage.md +++ b/docs/en/usage/quick_usage.md @@ -8,12 +8,12 @@ export MINERU_MODEL_SOURCE=modelscope For more information about model source configuration and custom local model paths, please refer to the [Model Source Documentation](./model_source.md) in the documentation. ## Quick Usage via Command Line -MinerU has built-in command line tools that allow users to quickly use MinerU for PDF parsing through the command line: +MinerU has built-in command line tools that allow users to quickly use MinerU for document parsing through the command line: ```bash mineru -p -o ``` > [!TIP] ->- ``: Local PDF/image file or directory +>- ``: Local `PDF` / image / `DOCX` file or directory >- ``: Output directory >- Without `--api-url`, the CLI launches a temporary local `mineru-api` >- With `--api-url`, the CLI connects to an existing local or remote FastAPI service directly @@ -28,7 +28,6 @@ If you need to adjust parsing options through custom parameters, you can also ch ## Advanced Usage via API, WebUI, http-client/server -- Direct Python API calls: [Python Usage Example](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py) - FastAPI calls: ```bash mineru-api --host 0.0.0.0 --port 8000 @@ -42,8 +41,10 @@ If you need to adjust parsing options through custom parameters, you can also ch >- Synchronous parsing endpoint: `POST /file_parse` >- Task query endpoints: `GET /tasks/{task_id}`, `GET /tasks/{task_id}/result` >- API outputs are controlled by the server and written to `./output` by default + >- Uploads currently support `PDF`, image, and `DOCX` files > >`POST /tasks` returns immediately with a `task_id`. `POST /file_parse` uses the same task manager internally, waits for the task to finish, and then returns the final result synchronously. + >When a task is waiting in the queue, both the submission response and task-status response may include `queued_ahead` to indicate how many tasks are ahead of it. >Tasks are tracked only in-process for a single `mineru-api` instance. Task status is not preserved across service restarts, `--reload`, or multi-process deployments. >Completed or failed tasks are retained for 24 hours by default, then their task state and output directory are cleaned automatically. After cleanup, task status and result endpoints return `404`. >Use `MINERU_API_TASK_RETENTION_SECONDS` and `MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS` to adjust retention and cleanup polling intervals. @@ -70,6 +71,9 @@ If you need to adjust parsing options through custom parameters, you can also ch >curl http://127.0.0.1:8000/tasks//result >curl http://127.0.0.1:8000/health >``` + > + >HTTP asynchronous call code example: [Python version](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py) + - Start Gradio WebUI visual frontend: ```bash mineru-gradio --server-name 0.0.0.0 --server-port 7860 @@ -77,6 +81,18 @@ If you need to adjust parsing options through custom parameters, you can also ch >[!TIP] > >- Access `http://127.0.0.1:7860` in your browser to use the Gradio WebUI. + >- Without `--api-url`, Gradio starts a reusable local `mineru-api`; with `--api-url`, it reuses an existing local or remote service. + >- The WebUI currently accepts `PDF`, image, and `DOCX` uploads. + +- Use `mineru-router` for multi-service / multi-GPU orchestration: + ```bash + mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto + ``` + >[!TIP] + > + >- `mineru-router` exposes the same `/health`, `/tasks`, `/file_parse`, `/tasks/{task_id}`, and `/tasks/{task_id}/result` interface set as `mineru-api`. + >- Repeat `--upstream-url` to aggregate multiple existing `mineru-api` services, or use `--local-gpus` to launch local workers automatically. + >- It is intended for advanced multi-service, multi-GPU, and unified-entry deployments. - Using `http-client/server` method: ```bash diff --git a/docs/zh/usage/quick_usage.md b/docs/zh/usage/quick_usage.md index 845fbadf..548fd7e1 100644 --- a/docs/zh/usage/quick_usage.md +++ b/docs/zh/usage/quick_usage.md @@ -8,12 +8,12 @@ export MINERU_MODEL_SOURCE=modelscope 有关模型源配置和自定义本地模型路径的更多信息，请参考文档中的[模型源说明](./model_source.md)。 ## 通过命令行快速使用 -MinerU内置了命令行工具，用户可以通过命令行快速使用MinerU进行PDF解析： +MinerU内置了命令行工具，用户可以通过命令行快速使用MinerU进行文档解析： ```bash mineru -p -o ``` > [!TIP] -> - ``：本地 PDF/图片 文件或目录 +> - ``：本地 `PDF` / 图片 / `DOCX` 文件或目录 > - ``：输出目录 > - 未传 `--api-url` 时，CLI 会自动拉起本地临时 `mineru-api` > - 传入 `--api-url` 时，CLI 会直连远端或已有本地 FastAPI 服务 @@ -28,7 +28,6 @@ mineru -p -o ## 通过api、webui、http-client/server进阶使用 -- 通过python api直接调用：[Python 调用示例](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py) - 通过fast api方式调用： ```bash mineru-api --host 0.0.0.0 --port 8000 @@ -42,8 +41,10 @@ mineru -p -o >- 同步解析接口：`POST /file_parse` >- 任务查询接口：`GET /tasks/{task_id}`、`GET /tasks/{task_id}/result` >- API 输出目录由服务端固定控制，默认写入 `./output` + >- 上传文件当前支持 `PDF`、图片与 `DOCX` > >`POST /tasks` 会立即返回 `task_id`；`POST /file_parse` 会在内部提交到同一个任务管理器，等待任务完成后同步返回最终结果。 + >当任务处于排队状态时，任务提交结果和状态查询结果中可能会返回 `queued_ahead` 字段，用于表示前方排队任务数。 >任务为单进程、进程内状态实现，服务重启、`--reload` 热重载或多进程部署后不保证仍可查询历史任务状态。 >默认任务完成或失败后保留 24 小时，随后自动清理任务状态和输出目录；清理后访问任务状态或结果会返回 `404`。 >可通过环境变量 `MINERU_API_TASK_RETENTION_SECONDS` 和 `MINERU_API_TASK_CLEANUP_INTERVAL_SECONDS` 调整保留时长与清理轮询间隔。 @@ -70,6 +71,9 @@ mineru -p -o >curl http://127.0.0.1:8000/tasks//result >curl http://127.0.0.1:8000/health >``` + > + >http异步调用代码示例：[Python版本](https://github.com/opendatalab/MinerU/blob/master/demo/demo.py) + - 启动gradio webui 可视化前端： ```bash mineru-gradio --server-name 0.0.0.0 --server-port 7860 @@ -77,6 +81,18 @@ mineru -p -o >[!TIP] > >- 在浏览器中访问 `http://127.0.0.1:7860` 使用 Gradio WebUI。 + >- 未传 `--api-url` 时，Gradio 会自动拉起可复用的本地 `mineru-api`；传入 `--api-url` 时则会复用已有本地或远端服务。 + >- WebUI 当前支持上传 `PDF`、图片与 `DOCX` 文件。 + +- 通过 `mineru-router` 进行多服务 / 多 GPU 编排： + ```bash + mineru-router --host 0.0.0.0 --port 8002 --local-gpus auto + ``` + >[!TIP] + > + >- `mineru-router` 对外暴露与 `mineru-api` 一致的 `/health`、`/tasks`、`/file_parse`、`/tasks/{task_id}`、`/tasks/{task_id}/result` 接口。 + >- 可重复使用 `--upstream-url` 聚合多个已有 `mineru-api` 服务，也可通过 `--local-gpus` 自动拉起本地 worker。 + >- 适用于多服务、多 GPU 和统一入口部署场景。 - 使用`http-client/server`方式调用： ```bash