Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion docs/en/usage/cli_tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,9 @@ The wrapper defaults to port 8003, accepts multipart, and calls upstream Tasks;
mineru-kit webui --server-name 127.0.0.1 --server-port 7860
```

Without `--api-url`, Gradio manages a loopback `mineru-kit api-server`. With `--api-url`, it connects only to that V1 service. `mineru-webui` is retained as a command-name alias and accepts the same modern options; it does not restore legacy Gradio options or HTTP routes.
Without `--api-url`, Gradio manages a loopback Router with one API worker. With `--api-url`, it connects only to that V1 service. `mineru-webui` accepts the same options.

`--task-timeout` limits execution time per file in managed mode (default: `3600` seconds). For example: `mineru-webui --max-pages 20 --preload-models --task-timeout 600`. Uploads, queue time and model startup are excluded. On timeout, affected requests fail and Router replaces the worker before accepting more work; the failed document is not retried automatically. `MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS` controls startup waiting separately.

Gradio accepts only `--tier auto|flash|basic|standard|advanced`, defaulting to `auto`, for the managed API Server ceiling. The old `--api-server-tier` option has been removed. The UI and Tasks share the Standard → Basic → Flash → Advanced default order; Advanced is automatic only when it is the sole available tier.

Expand Down
7 changes: 6 additions & 1 deletion docs/next/cli/mineru-kit-api-server.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ SaaS 可按共同契约仅发布 standard,原生文档由同一服务解析。

非连续精确集合只用于 Python 工厂或部署方自己的服务配置,不能通过本地 CLI 表达。原 `--tiers standard` 只开放 standard,与新 `--tier standard` 的上限展开语义不同。

WebUI、Router、Doclib 的托管 standard 均只开放到 standard,不再隐含 advanced;需要时显式配置 advanced。WebUI 默认配置为 auto,Router、Doclib 仍为 standard。Doclib 的 `parse_server.local.managed_tier` 支持 basic、standard、advanced,其原生执行路径保持现状。Advanced 的模型检查与下载使用 Standard 模型配置。
WebUI、Router、Doclib 的托管 standard 均只开放到 standard,不再隐含 advanced;需要时显式配置 advanced。WebUI 和 Router 默认配置为 auto,Doclib 仍为 standard。Doclib 的 `parse_server.local.managed_tier` 支持 basic、standard、advanced,其原生执行路径保持现状。Advanced 的模型检查与下载使用 Standard 模型配置。

## 4. self-hosted 与 managed

Expand Down Expand Up @@ -128,6 +128,11 @@ OCR 模式通过每次 `POST /v1/tasks` 请求的 `ocr_mode` 设置,可选 `au

模型默认在首次解析时懒加载。`--preload-models` 会在 Basic、Standard 或 Advanced 服务启动时提前初始化所需模型或 VLM 客户端,并在失败时让能力接口返回明确错误;该参数对 Flash 无操作,但 Flash OCR 首次使用时仍需要小模型资源。Doclib managed parse-server 会自动启用模型预加载。

### 执行超时

`--task-timeout` 控制每个文件的实际执行期限,默认 `3600` 秒,必须为正整数;Python 工厂对应 `task_timeout_seconds`。计时从取得执行名额开始,包含解析和产物打包,不包含上传、排队、下载及启动预加载。
超时后任务进入失败终态、服务拒绝继续接单;独立 API 不自行杀死宿主,由部署方重建。Router 托管模式另有父进程监督,即使 API 事件循环或取消清理挂起,也能回收整个 worker 并恢复。

### 服务日志级别

`mineru-kit api-server`、`mineru-api` 和 `python -m mineru.parser.api_server` 均支持 `--log-level`,
Expand Down
19 changes: 17 additions & 2 deletions docs/next/cli/mineru-kit-webui.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ UI 也可安装在独立环境,通过 `--api-url` 连接推理服务。
pip install mineru
```

自动启动本地 V1 API server:
自动启动本地 Router 和唯一的 V1 API worker:

```bash
mineru-kit webui
Expand All @@ -63,7 +63,7 @@ mineru-kit webui \
--api-key "$MINERU_API_KEY"
```

未指定 `--api-url` 时,Gradio 会启动一个 loopback `mineru-kit api-server`。本地 server 默认使用 `--tier auto`,由 API Server 按硬件和有效后端推荐 PDF/图片上限;可用 `--tier flash|basic|standard|advanced` 显式指定上限。原生文档始终支持并固定 flash。所有文件通过 Tasks 提交 hash 清单,缓存未命中时上传,同机也不使用路径免上传。
未指定 `--api-url` 时,Gradio 会托管一个 loopback Router,由 Router 监督唯一的 API worker。worker 继承设备可见性,默认 `--tier auto`,由 API Server 按硬件和有效后端推荐 PDF/图片上限;可显式指定上限。原生文档始终支持并固定 flash。所有文件通过 Tasks 提交 hash 清单,缓存未命中时上传。

未指定 `--server-port` 时,界面由 Gradio 从 `7860` 开始寻找空闲端口;可通过 `GRADIO_SERVER_PORT` 设置起始端口、`GRADIO_NUM_PORTS` 设置尝试数量(默认 `100`)。显式指定 `--server-port 7861` 时只尝试该端口,覆盖环境变量;该端口已被占用则启动失败。界面最终访问地址以启动输出为准,与内部 API server 的端口不同。

Expand All @@ -76,6 +76,7 @@ mineru-kit webui \
| `--server-name` / `--server-port` | Gradio UI 的监听地址和端口;省略端口时自动寻找空闲端口。 |
| `--output-dir` | 本地 UI 产物根目录,默认 `./output`。 |
| `--max-pages` | 单次 PDF 解析的最多页数,必须为正整数;省略则不限制。不限制非 PDF。 |
| `--task-timeout` | 托管 worker 的单文件执行期限,单位秒,默认 `3600`,必须为正整数;外部 `--api-url` 模式由远端配置期限。 |
| `--tier` | 自托管 API Server 的上限:`auto`(默认)、`flash`、`basic`、`standard`、`advanced`;指定 `--api-url` 时忽略。 |
| `--api-server-concurrency` | 自动启动 server 的最大并发任务数。 |
| `--api-server-preload-models` | 在自动启动阶段预加载模型。 |
Expand All @@ -87,6 +88,20 @@ Gradio 只保留 `--tier`,不接受旧名 `--api-server-tier`。Gradio 不接

指定外部 `--api-url` 时,Gradio 校验 `/v1/health` 和 `/v1/tiers` 后直接使用该服务。公开 tiers 只约束 PDF/图片;原生文档同样上传给远端,不因列表中缺少 flash 而启动本地补充服务或增加 PDF 档位。认证只用于所连接服务,连接或解析失败保持原错误。

## 执行超时与恢复

```bash
mineru-webui --max-pages 20 --preload-models --task-timeout 600
```

执行期限从取得解析名额开始,到解析和服务端产物写出完成;上传、排队、客户端下载及启动预加载不计入。取消后的实际清理仍受监督。
超时请求返回 `task_timeout`,同一旧 worker 上其他未完成请求返回 `worker_restarted`。Router 回收旧进程及模型子进程后重新加载,期间界面显示“解析服务恢复中”。问题文件不自动重试;本地尚未提交的排队请求在恢复后继续。

连续三次启动恢复失败后停止自动重试,并显示恢复失败。已物化到 WebUI 的产物保留;尚未取得的旧 worker 产物不保证可用。
`MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS` 继续单独控制模型启动等待,默认 `300` 秒,ModelScope 可保留 `1800` 秒;它不受 `--task-timeout 600` 缩短。

SDK 的 `MinerUApiParser(poll_timeout_seconds=3600)` 控制客户端等待预算;显式 `None` 等待服务端终态。托管 WebUI 使用后者并由 Router 监督执行,外部 API 模式保留一小时客户端等待预算。

## 解析流程

界面一次提交一个文件,支持 `filetypes.PARSEABLE_EXTENSIONS` 中的 PDF、图片、Office/ODF、RTF、HTML、MHTML/MHT、CSV/TSV、EPUB 和 OFD。
Expand Down
9 changes: 5 additions & 4 deletions docs/next/cli/mineru-kit.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ mineru-api --host 127.0.0.1 --port 8000 --tier standard

`mineru-kit` 参数暂不划分 `stable` / `experimental` 等稳定性等级。第一阶段保持参数体系简单,后续只有在兼容性压力明确出现时再引入分级。

`mineru-kit webui` 是无状态的 V1 API 客户端界面。未指定 `--api-url` 时,它会自动托管一个 loopback `mineru-kit api-server`;指定 URL 时只连接已有的 V1 服务,不会静默改连官方远程服务。`mineru-webui` 提供为同一新版命令的独立入口,不再提供旧 HTTP 协议或旧参数。
`mineru-kit webui` 是无状态的 V1 API 客户端界面。未指定 `--api-url` 时,它会自动托管一个 loopback Router,由 Router 管理唯一的 API worker;指定 URL 时只连接已有的 V1 服务。`mineru-webui` 提供同一新版命令的独立入口。

当前 `mineru-kit parse` 已确定:

Expand All @@ -88,10 +88,11 @@ mineru-api --host 127.0.0.1 --port 8000 --tier standard

当前 `mineru-kit router` 已确定:

- 入口参数包括 `--host`、`--port`、`--reload`、`--upstream-url`、`--local-gpus`、`--worker-host`、`--worker-tier`、`--worker-concurrency`、`--preload-models`、`--admin-api-key`。
- 入口参数包括 `--host`、`--port`、`--reload`、`--upstream-url`、`--local-gpus`、`--worker-host`、`--worker-tier`、`--worker-concurrency`、`--task-timeout`、`--preload-models`、`--admin-api-key`。
- `--upstream-url` 可重复,用于接入已有 MinerU V1 API base URL。
- `--local-gpus` 支持 `auto`、`none` 或 GPU CSV,例如 `0,1,2`。
- 本地 worker 统一启动 `mineru-kit api-server`;`--worker-tier` 是包含较低档位的上限,可选 flash/basic/standard/advanced,默认 standard;`--worker-concurrency` 默认 `1`。
- `--local-gpus` 支持 `auto`、`inherit`、`none` 或 GPU CSV,例如 `0,1,2`;`inherit` 仅启动一个继承设备环境的 worker,不枚举或重写可见 GPU。
- 本地 worker 统一启动 `mineru-kit api-server`;`--worker-tier` 可选 auto/flash/basic/standard/advanced,默认 auto,由各 worker 在自己的设备环境中沿用 API server 的自动选档逻辑确定上限;显式指定档位时,上限包含较低档位;`--worker-concurrency` 默认 `1`。
- `--task-timeout` 为每个文件取得解析名额后的执行秒数上限,默认 `3600`,必须为正整数;排队和上传不计入。Router 独立监督本地 worker 的实际执行和取消清理,超时后结束旧请求并重建 worker;外部 upstream 不由本层终止或重启。
- Router 提供 V1 health、models、tiers、usage、按 ID 操作 Files,以及 `/v1/tasks` JSON 创建、按 ID 查询/取消、逐文件上传和结果下载;不提供任务或文件列表。
- Router 只接受显式声明的参数,不再透传未知模型引擎参数;需要额外调优时应部署独立 upstream。
- tasks 与 files 的公共路由状态保存在当前进程内,Router 重启后不保证旧公共 ID 继续可用。
Expand Down
4 changes: 3 additions & 1 deletion docs/zh/usage/cli_tools.md
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,9 @@ mineru-kit file-parse-server --api-url http://127.0.0.1:8000
mineru-kit webui --server-name 127.0.0.1 --server-port 7860
```

未传 `--api-url` 时,Gradio 会托管 loopback `mineru-kit api-server`;传入后只连接指定的 V1 服务。`mineru-webui` 保留为命令名兼容别名,接受相同的新版参数,不恢复旧 Gradio 参数或 HTTP 路由。
未传 `--api-url` 时,Gradio 会托管 loopback Router,由 Router 管理唯一的 API worker;传入后只连接指定的 V1 服务。`mineru-webui` 接受相同参数。

`--task-timeout` 设置托管 worker 的单文件执行期限,默认 `3600` 秒;例如 `mineru-webui --max-pages 20 --preload-models --task-timeout 600`。上传、排队和模型启动不计入。超时后旧请求明确失败,Router 重建 worker 后继续处理后续请求,不自动重跑问题文件。`MINERU_LOCAL_API_STARTUP_TIMEOUT_SECONDS` 单独控制启动等待。

Gradio 只保留 `--tier auto|flash|basic|standard|advanced`,默认 `auto`,仅用于自托管 API Server 的上限。旧参数 `--api-server-tier` 已移除。界面与 Tasks 共享默认选档顺序 Standard → Basic → Flash → Advanced;仅开放 Advanced 时自动选择它。

Expand Down
11 changes: 10 additions & 1 deletion mineru/doclib/app.py
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ async def startup() -> None:
from .background.watch import WatchLoop
from .core.db import DatabaseManager
from .core.fts import FTSManager
from .core.fts_content import migrate_fts_contents
from .services.cleanup_svc import CleanupService
from .services.config_svc import ConfigService
from .services.ingest_svc import IngestService
Expand All @@ -90,6 +91,7 @@ async def startup() -> None:
state.db_ready.set()

state.fts = FTSManager(state.db)
await migrate_fts_contents(state.db, state.fts, data_dir=data_dir, latex_delimiters=cfg.render.latex_delimiters)
state.config_svc = ConfigService(state.db)
state.telemetry_svc = TelemetryService(TelemetryStore(state.db))
await state.telemetry_svc.initialize()
Expand All @@ -107,7 +109,13 @@ async def startup() -> None:
telemetry_svc=state.telemetry_svc,
)
state.parse_execution_svc = ParseExecutionService(
state.db, state.fts, state.config_svc, data_dir, health=state.health, telemetry_svc=state.telemetry_svc
state.db,
state.fts,
state.config_svc,
data_dir,
health=state.health,
latex_delimiters=cfg.render.latex_delimiters,
telemetry_svc=state.telemetry_svc,
)
state.scan_svc = ScanService(
state.db,
Expand Down Expand Up @@ -404,6 +412,7 @@ def __init__(self) -> None:
"exclude_rules",
"files",
"fts_contents",
"fts_rebuild_queue",
"fts_filenames",
"parses",
"parsing_rules",
Expand Down
2 changes: 1 addition & 1 deletion mineru/doclib/core/db.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@
from ...errors import ServerBusyError
from ..config_defaults import CONFIG_DEFAULTS

SCHEMA_VERSION = 2
SCHEMA_VERSION = 3
_MIGRATIONS_DIR = Path(__file__).resolve().parent.parent / "migrations"

_T = TypeVar("_T")
Expand Down
10 changes: 9 additions & 1 deletion mineru/doclib/core/fts.py
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ async def replace(
"INSERT INTO fts_contents (sha256, tier, text, title, author) VALUES (?, ?, ?, ?, ?)",
(sha256, tier, tokenized, title or "", author or ""),
),
("DELETE FROM fts_rebuild_queue WHERE sha256=?", (sha256,)),
]
)

Expand All @@ -82,6 +83,7 @@ async def search(self, query: str, limit: int = 200) -> list[FtsContentSearchRow
"SELECT sha256, title, author, tier, "
"snippet(fts_contents, 2, '<mark>', '</mark>', '...', 40) AS snippet, rank "
"FROM fts_contents WHERE fts_contents MATCH ? "
"AND sha256 NOT IN (SELECT sha256 FROM fts_rebuild_queue) "
"ORDER BY rank LIMIT ?",
(fts_query, limit),
),
Expand All @@ -94,7 +96,13 @@ async def get_tier(self, sha256: str) -> Tier | None:
return cast(Tier | None, row["tier"]) if row else None

async def delete(self, sha256: str) -> None:
await self.db.execute("DELETE FROM fts_contents WHERE sha256=?", (sha256,))
"""同时移除正文索引和待迁移标记,防止已失效文档被重新索引。"""
await self.db.execute_atomic(
[
("DELETE FROM fts_contents WHERE sha256=?", (sha256,)),
("DELETE FROM fts_rebuild_queue WHERE sha256=?", (sha256,)),
]
)

# ── fts_filenames ────────────────────────────────────────────

Expand Down
Loading
Loading