| # pdfsys-mnbvc · Roadmap |
|
|
| > 优化方案与实施计划 · v0.1 · 2026-04-17 |
| > |
| > 本文档把 [`PRD.md`](./PRD.md) 描述的目标转化为**带优先级、带工作量、带验收标准**的可执行任务池。PRD 回答"我们要做什么"，ROADMAP 回答"按什么顺序做、怎么做、做完怎么验证"。 |
|
|
| --- |
|
|
| ## 0 · 摘要 |
|
|
| **一句话**：设计文档与架构框架一流，工程基础设施缺失严重，6 个 stage 只落地了 1.5 个。 |
|
|
| **冲刺计划**：以 2 周"可协作化"冲刺（P0）作为一切后续工作的前提，再用 4 周打磨性能与可靠性（P1），最后 10–16 周补齐 6-stage 闭环（P2）。P3 是 PB 级规模化与生态，作为长期背景项。 |
|
|
| --- |
|
|
| ## 1 · 现状评分卡 |
|
|
| | 维度 | 状态 | 评分 | |
| |---|---|---| |
| | 设计文档（PRD） | 441 行，取舍清晰 | 9/10 | |
| | 架构分包 | 7 个 workspace 包，边界合理 | 8/10 | |
| | 核心契约（`pdfsys-core`） | frozen dataclass + 零依赖 + 原子写 | 9/10 | |
| | MVP 闭环（Router→MuPDF→Scorer） | 跑通 OmniDocBench-100 | 7/10 | |
| | **测试** | **零测试文件，零 CI** | **0/10** | |
| | **依赖管理** | 无 lock 文件，依赖无上界 | 2/10 | |
| | **Observability** | 无 logging，无 metrics | 2/10 | |
| | 实现完成度 | 2180 行，4/7 包是 stub | 3/10 | |
| | Demo & 贡献者体验 | Gradio + Cursor rules 完善 | 8/10 | |
|
|
| **关键风险**：当前状态下 1 人可 hack 前进；**任何超过 3 人的协作会立刻失控**——没有测试保护 parity、没有 CI、没有 lock 文件，第一次依赖升级就会毒化路由器。 |
|
|
| --- |
|
|
| ## 2 · 优化全景 |
|
|
| ``` |
| ┌──────────────────────────────────────────────────────────────────┐ |
| │ P0 工程基础（2 周，阻塞一切后续） │ |
| │ ├─ 1.1 测试框架 pytest + 关键单测 │ |
| │ ├─ 1.2 代码质量 ruff + mypy + pre-commit │ |
| │ ├─ 1.3 GitHub Actions CI │ |
| │ ├─ 1.4 uv.lock 入库 + 依赖上界 │ |
| │ └─ 1.5 Parity harness（router 回归守门） │ |
| ├──────────────────────────────────────────────────────────────────┤ |
| │ P1 性能与可靠性（4 周） │ |
| │ ├─ 2.1 Router 热路径优化（49 ms → 10 ms） │ |
| │ ├─ 2.2 Quality scorer 批量推理 │ |
| │ ├─ 2.3 structlog 日志系统 │ |
| │ ├─ 2.4 Prometheus metrics 导出 │ |
| │ └─ 2.5 错误分类 + quarantine 桶 │ |
| ├──────────────────────────────────────────────────────────────────┤ |
| │ P2 功能补全（8-12 周，按 PRD roadmap） │ |
| │ ├─ 3.1 Layout analyser（PP-DocLayoutV3 ONNX INT8） │ |
| │ ├─ 3.2 Pipeline parser（RapidOCR 简单版式） │ |
| │ ├─ 3.3 Stage-B router（layout-cache 驱动） │ |
| │ ├─ 3.4 VLM parser（MinerU 2.5 + LMDeploy） │ |
| │ ├─ 3.5 Stage-3 后处理 │ |
| │ ├─ 3.6 Stage-4 质量 / PII / MinHash 去重 │ |
| │ └─ 3.7 Stage-5 Parquet 打包 │ |
| ├──────────────────────────────────────────────────────────────────┤ |
| │ P3 规模化与生态（3-6 个月） │ |
| │ ├─ 4.1 datatrove 编排集成 │ |
| │ ├─ 4.2 Slurm / K8s runner │ |
| │ ├─ 4.3 对象存储后端（S3 / OSS / MinIO） │ |
| │ ├─ 4.4 中文 EduScore 训练 │ |
| │ └─ 4.5 竖排古籍 LoRA │ |
| └──────────────────────────────────────────────────────────────────┘ |
| ``` |
|
|
| --- |
|
|
| ## 3 · P0 工程基础（Week 1-2） |
|
|
| ### 3.1 测试框架 · pytest |
|
|
| **目标**：2 周内 `pdfsys-core` ≥ 90% / `pdfsys-router` ≥ 60% / `pdfsys-parser-mupdf` ≥ 60% 覆盖率。 |
|
|
| **为什么优先**：`.cursor/rules/01-architecture-invariants.mdc` 里 7 条不变式（BBox 归一化、frozen dataclass、原子写、schema 同构等）**全部可单测验证**。没有测试，"不要违反不变式"只是一句空话。 |
|
|
| **交付物结构**： |
|
|
| ``` |
| tests/ |
| ├── conftest.py # 共享 fixtures |
| ├── fixtures/pdfs/ # 5-10 个跨类型 PDF（< 100 KB/file，入库） |
| ├── unit/ |
| │ ├── core/ |
| │ │ ├── test_bbox.py # BBox 边界、转换、非法值 |
| │ │ ├── test_serde.py # to_dict/from_dict roundtrip |
| │ │ ├── test_cache.py # LayoutCache 原子写 + 崩溃恢复 |
| │ │ └── test_types.py # Backend / RegionType 枚举稳定性 |
| │ ├── router/ |
| │ │ ├── test_classifier_smoke.py # classify() 不 raise 任何畸形输入 |
| │ │ ├── test_feature_shape.py # 输出必须 124 列，列名锁定 |
| │ │ └── test_error_taxonomy.py # encrypted/corrupt/empty 错误分类 |
| │ ├── parser_mupdf/ |
| │ │ ├── test_extract_basic.py # 正常 PDF 段落抽取 |
| │ │ ├── test_bbox_normalized.py # 所有 bbox ∈ [0, 1] |
| │ │ └── test_corrupted_pdf.py # 坏 PDF 不 crash |
| │ └── bench/ |
| │ └── test_loop_never_raises.py # 坏 PDF 进去，JSONL 行出来 |
| ├── contract/ |
| │ ├── test_extracted_doc_schema.py # 所有 parser 输出同构 |
| │ └── test_cursor_rules_valid.py # .mdc frontmatter 合法 |
| └── integration/ |
| └── test_bench_smoke.py # python -m pdfsys_bench --limit 3 |
| ``` |
|
|
| **关键样例**： |
|
|
| ```python |
| # tests/unit/core/test_bbox.py |
| import pytest |
| from pdfsys_core import BBox |
| |
| class TestBBoxInvariants: |
| @pytest.mark.parametrize("x0,y0,x1,y1", [ |
| (-0.1, 0, 0.5, 0.5), # 负坐标 |
| (0, 0, 1.1, 0.5), # 超过 1 |
| (0.5, 0, 0.3, 0.5), # x1 < x0 |
| (0, 0, 0, 0), # 零面积 |
| ]) |
| def test_rejects_invalid(self, x0, y0, x1, y1): |
| with pytest.raises(ValueError): |
| BBox(x0=x0, y0=y0, x1=x1, y1=y1) |
| |
| def test_to_pixels_roundtrip(self): |
| box = BBox(0.1, 0.2, 0.9, 0.8) |
| assert box.to_pixels(1000, 500) == (100, 100, 900, 400) |
| ``` |
|
|
| ```python |
| # tests/unit/router/test_feature_shape.py |
| EXPECTED_COLUMNS = 124 |
| |
| def test_feature_vector_has_124_columns(sample_pdf): |
| router = Router() |
| decision = router.classify(sample_pdf) |
| assert not decision.error |
| assert len(decision.features) == EXPECTED_COLUMNS, ( |
| f"Feature vector drifted from 124 to {len(decision.features)}. " |
| "If intentional, retrain XGBoost weights." |
| ) |
| ``` |
|
|
| **实施步骤**： |
|
|
| 1. `uv add --group dev pytest pytest-cov pytest-xdist hypothesis` |
| 2. 根 `pyproject.toml` 加 `[tool.pytest.ini_options]` 和 `[tool.coverage.run]` |
| 3. `conftest.py` 提供 `sample_pdf` / `encrypted_pdf` / `corrupted_pdf` fixture |
| 4. 按上表顺序写测试（每天 1 个子目录） |
| 5. 加 `Makefile` 或 `scripts/test.sh`：`uv run pytest -n auto tests/` |
|
|
| **验收**：CI 跑通全部测试 < 2 分钟；三包覆盖率达标。 |
|
|
| **工作量**：1 人 · 10 天 |
|
|
| --- |
|
|
| ### 3.2 代码质量 · ruff + mypy + pre-commit |
|
|
| **目标**：零 ruff 错误、`pdfsys-core` 零 mypy 错误、commit 前自动拦截。 |
|
|
| **根 `pyproject.toml` 新增**： |
|
|
| ```toml |
| [tool.ruff] |
| target-version = "py311" |
| line-length = 100 |
| src = ["packages/pdfsys-core/src", "packages/pdfsys-router/src", |
| "packages/pdfsys-parser-mupdf/src", "packages/pdfsys-bench/src", |
| "demo"] |
| |
| [tool.ruff.lint] |
| select = ["E", "F", "W", "I", "B", "UP", "SIM", "PLC0415", "BLE001", "RET", "ARG"] |
| ignore = ["E501"] |
| per-file-ignores = { "packages/pdfsys-bench/**" = ["BLE001"] } |
| |
| [tool.mypy] |
| python_version = "3.11" |
| strict = true |
| exclude = ["^packages/pdfsys-parser-(pipeline|vlm)/", "^packages/pdfsys-layout-analyser/"] |
| |
| [[tool.mypy.overrides]] |
| module = ["pymupdf.*", "xgboost.*", "gradio.*"] |
| ignore_missing_imports = true |
| ``` |
|
|
| **`.pre-commit-config.yaml`**： |
|
|
| ```yaml |
| repos: |
| - repo: https://github.com/astral-sh/ruff-pre-commit |
| rev: v0.6.9 |
| hooks: |
| - id: ruff |
| args: [--fix] |
| - id: ruff-format |
| - repo: https://github.com/pre-commit/mirrors-mypy |
| rev: v1.11.2 |
| hooks: |
| - id: mypy |
| files: ^packages/pdfsys-core/ |
| - repo: local |
| hooks: |
| - id: no-committed-weights |
| name: Reject committed model weights |
| entry: bash -c '! git diff --cached --name-only | grep -E "\.(ubj|safetensors|pt|bin)$"' |
| language: system |
| pass_filenames: false |
| - id: validate-cursor-rules |
| name: Validate .cursor/rules YAML frontmatter |
| entry: python scripts/validate_rules.py |
| language: system |
| files: ^\.cursor/rules/.*\.mdc$ |
| ``` |
|
|
| **实施步骤**： |
|
|
| 1. `uv add --group dev ruff mypy pre-commit` |
| 2. 写上面两个配置 |
| 3. `uv run ruff check --fix .` + `uv run ruff format .` 修现存问题 |
| 4. `uv run mypy packages/pdfsys-core` 直到零错 |
| 5. `pre-commit install` 追加到 `scripts/setup_cursor.sh` |
| 6. 把 `03-doc-sync.mdc` 里提到的 `scripts/validate_rules.py` 落地 |
|
|
| **验收**：`pre-commit run --all-files` 全绿。 |
|
|
| **工作量**：1 人 · 3 天 |
|
|
| --- |
|
|
| ### 3.3 GitHub Actions CI |
|
|
| **`.github/workflows/ci.yml`**： |
|
|
| ```yaml |
| name: CI |
| on: |
| pull_request: |
| push: |
| branches: [main] |
| |
| jobs: |
| lint: |
| runs-on: ubuntu-latest |
| steps: |
| - uses: actions/checkout@v4 |
| - uses: astral-sh/setup-uv@v3 |
| with: { version: "0.4.x", enable-cache: true } |
| - run: uv sync --frozen |
| - run: uv run ruff check . |
| - run: uv run ruff format --check . |
| - run: uv run mypy packages/pdfsys-core |
| |
| test: |
| runs-on: ubuntu-latest |
| strategy: |
| matrix: |
| python: ["3.11", "3.12"] |
| steps: |
| - uses: actions/checkout@v4 |
| - uses: astral-sh/setup-uv@v3 |
| with: { python-version: "${{ matrix.python }}" } |
| - run: uv sync --frozen |
| - run: uv run python -m pdfsys_router.download_weights |
| - run: uv run pytest -n auto --cov --cov-report=xml tests/ |
| - uses: codecov/codecov-action@v4 |
| if: matrix.python == '3.11' |
| |
| parity: |
| runs-on: ubuntu-latest |
| if: contains(github.event.pull_request.changed_files, 'feature_extractor.py') |
| steps: |
| - uses: actions/checkout@v4 |
| with: { fetch-depth: 2 } |
| - uses: astral-sh/setup-uv@v3 |
| - run: uv sync --frozen |
| - run: uv run python -m pdfsys_router.download_weights |
| - run: bash scripts/check_parity.sh origin/main HEAD |
| ``` |
|
|
| **实施步骤**： |
|
|
| 1. 写上面 workflow |
| 2. 可选：`.github/workflows/preview-hf-space.yml` PR 自动部署预览 Space |
| 3. GitHub Settings → Branches 把 `main` 设为 protected、必须通过 CI |
|
|
| **验收**：PR 打开 3 分钟内看到 ✅ × 3。 |
|
|
| **工作量**：1 人 · 1 天 |
|
|
| --- |
|
|
| ### 3.4 uv.lock 入库 + 依赖上界 |
|
|
| **当前痛点**： |
| - `.gitignore:14` 把 `uv.lock` 排除了（反模式，lock 文件必须入库） |
| - 所有依赖只有下界：`pymupdf>=1.24` 明天升级到 2.0 会被自动拉进来 |
|
|
| **修复**： |
|
|
| 1. 从 `.gitignore` 移除 `uv.lock` |
| 2. 给所有依赖加上界（保守策略 major+1）： |
|
|
| ```toml |
| # packages/pdfsys-router/pyproject.toml |
| dependencies = [ |
| "pdfsys-core", |
| "pymupdf>=1.24,<2.0", |
| "xgboost>=2.0,<3.0", |
| "scikit-learn>=1.3,<2.0", |
| "pandas>=2.0,<3.0", |
| "numpy>=1.26,<3.0", |
| ] |
| ``` |
|
|
| 3. `uv lock && git add uv.lock` |
| 4. CI 用 `uv sync --frozen`（见 §3.3） |
|
|
| **工作量**：0.5 天 |
|
|
| --- |
|
|
| ### 3.5 Parity Harness |
|
|
| **背景**：`.cursor/rules/21-router-parity.mdc` 已描述 parity 验证流程，但**缺可执行脚本**。 |
|
|
| **`scripts/check_parity.sh`**： |
| |
| ```bash |
| #!/usr/bin/env bash |
| # Verify router ocr_prob drift between two refs. |
| # Usage: bash scripts/check_parity.sh <baseline_ref> <candidate_ref> |
| set -euo pipefail |
| |
| BASELINE="${1:-origin/main}" |
| CANDIDATE="${2:-HEAD}" |
| SAMPLE_DIR="${PARITY_SAMPLE_DIR:-tests/fixtures/pdfs}" |
| EPSILON="${PARITY_EPSILON:-1e-6}" |
| WORK_DIR="$(mktemp -d)" |
| trap 'rm -rf "$WORK_DIR"' EXIT |
| |
| run_bench() { |
| local ref="$1" out="$2" |
| git worktree add "$WORK_DIR/$ref" "$ref" |
| (cd "$WORK_DIR/$ref" && uv sync --frozen --quiet \ |
| && uv run python -m pdfsys_router.download_weights >/dev/null \ |
| && uv run python -m pdfsys_bench --pdf-dir "$SAMPLE_DIR" --out "$out" --no-quality) |
| git worktree remove --force "$WORK_DIR/$ref" |
| } |
| |
| run_bench "$BASELINE" "$WORK_DIR/baseline.jsonl" |
| run_bench "$CANDIDATE" "$WORK_DIR/candidate.jsonl" |
| |
| uv run python scripts/parity_diff.py \ |
| "$WORK_DIR/baseline.jsonl" "$WORK_DIR/candidate.jsonl" \ |
| --epsilon "$EPSILON" |
| ``` |
| |
| **`scripts/parity_diff.py`**：接收两个 JSONL、逐 PDF 对比 `ocr_prob`、漂移超阈值 exit 非零。 |
| |
| **工作量**：1 天 |
| |
| --- |
| |
| ## 4 · P1 性能与可靠性（Week 3-6） |
| |
| ### 4.1 Router 热路径优化 |
| |
| **现状**：49 ms/PDF（PRD 目标 ≤10 ms）。跑 1 PB 语料 ≈ 浪费 10+ 小时 CPU。 |
| |
| **优化点**（先 profile 后改，要求 P0 测试先到位）： |
| |
| #### (a) 去掉 pandas DataFrame 构造 |
| |
| ```python |
| # ❌ 现状 (packages/pdfsys-router/src/pdfsys_router/xgb_model.py) |
| df = pd.DataFrame([features]) |
| names = getattr(self.model, "feature_names_in_", None) |
| if names is not None: |
| df = df.reindex(columns=list(names), fill_value=0) |
| probs = self.model.predict_proba(df) |
| |
| # ✅ 优化：缓存列序 + numpy array |
| class XgbRouterModel: |
| def __init__(self, path): |
| self._feature_order: list[str] | None = None |
| |
| def predict_proba(self, features: dict[str, float]) -> float: |
| if self._feature_order is None: |
| self._feature_order = list(self.model.feature_names_in_) |
| arr = np.fromiter( |
| (features.get(k, 0.0) for k in self._feature_order), |
| dtype=np.float32, count=len(self._feature_order), |
| ).reshape(1, -1) |
| return float(self.model.predict_proba(arr)[0, 1]) |
| ``` |
| |
| 预估：~15 ms → ~2 ms。 |
| |
| #### (b) PyMuPDF 文本读取去重 |
| |
| `_get_garbled_text_per_page` 对每页 `get_text()`，后续 `compute_features_per_chunk` 对采样页再读一次——同一页读两次。 |
| 优化：读所有采样页文本时就缓存 `page → text` 字典，复用。预估 ~25 ms → ~12 ms。 |
| |
| #### (c) 早 return |
| |
| `is_encrypted` / `needs_pass` / `len(doc) == 0` 这类硬错误应在特征提取前 short-circuit。 |
| |
| **验收**：Parity harness 验证 `|diff(ocr_prob)| < 1e-6`；OmniDocBench-100 上 p50 ≤ 10 ms。 |
| |
| **工作量**：2-3 天 |
| |
| --- |
| |
| ### 4.2 Quality scorer 批量推理 |
| |
| **现状**：单条 3.6 s；10 万文档 ≈ 100 小时。 |
| |
| **改动**：`OcrQualityScorer.score_many` 从循环改成真正 batch： |
| |
| ```python |
| def score_many(self, texts: list[str], batch_size: int = 8) -> list[QualityScore]: |
| self._ensure_loaded() |
| torch = self._torch |
| results: list[QualityScore] = [] |
| for i in range(0, len(texts), batch_size): |
| batch = [t[:self.max_chars] or " " for t in texts[i:i + batch_size]] |
| enc = self._tokenizer( |
| batch, return_tensors="pt", truncation=True, |
| max_length=self.max_tokens, padding=True, |
| ).to(self._device) |
| with torch.inference_mode(): |
| logits = self._model(**enc).logits.squeeze(-1) |
| for j, text in enumerate(batch): |
| score = max(0.0, min(3.0, float(logits[j].item()))) |
| results.append(QualityScore( |
| score=score, |
| num_chars=len(text), |
| num_tokens=int(enc["attention_mask"][j].sum()), |
| model=self.model_name, |
| )) |
| return results |
| ``` |
| |
| **配套**：`pdfsys_bench.loop.run_loop` 改成"先全部 extract → 批量 score → 展回 JSONL"，保持输出顺序。 |
|
|
| **验收**：batch=8 相比 batch=1 吞吐 ≥ 3×；单样本数值差 `< 1e-3`。 |
|
|
| **工作量**：3 天 |
|
|
| --- |
|
|
| ### 4.3 structlog 日志系统 |
|
|
| **现状**：全仓 `print(...)` × 12 处；无级别、无结构。 |
|
|
| **方案**：`pdfsys-core` 之外的包引入 `structlog`（core 保持零依赖）： |
|
|
| ```python |
| # packages/pdfsys-router/src/pdfsys_router/_log.py |
| import structlog |
| log = structlog.get_logger("pdfsys.router") |
| |
| # 使用： |
| log.info("classified", backend=decision.backend.value, |
| ocr_prob=decision.ocr_prob, pdf=str(path), |
| num_pages=decision.num_pages) |
| ``` |
|
|
| 生产用 `JSONRenderer()`（便于 Grafana/ELK 摄入），dev 用 `ConsoleRenderer()`。 |
|
|
| **工作量**：2 天 |
|
|
| --- |
|
|
| ### 4.4 Prometheus metrics |
|
|
| **最小实现**： |
|
|
| ```python |
| # packages/pdfsys-bench/src/pdfsys_bench/_metrics.py |
| from prometheus_client import Counter, Histogram, start_http_server |
| |
| router_decisions = Counter("pdfsys_router_decisions_total", |
| "Router decisions by backend", ["backend"]) |
| router_latency = Histogram("pdfsys_router_duration_seconds", |
| "Router classification latency", |
| buckets=[0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0]) |
| extract_failures = Counter("pdfsys_extract_failures_total", |
| "Extraction failures", ["backend", "error_class"]) |
| |
| def enable_metrics_endpoint(port: int = 9000) -> None: |
| start_http_server(port) |
| ``` |
|
|
| `pdfsys-bench` CLI 新增 `--metrics-port` flag。 |
|
|
| **工作量**：2 天 |
|
|
| --- |
|
|
| ### 4.5 错误分类 + quarantine 桶 |
|
|
| **现状**：失败写 `extract_error: "classify_failed: X"` 自由字符串，无法聚合。 |
|
|
| **方案**：`pdfsys-core` 新增 `errors.py`： |
|
|
| ```python |
| from enum import Enum |
| |
| class ErrorClass(str, Enum): |
| OPEN_FAILED = "open_failed" |
| ENCRYPTED = "encrypted" |
| EMPTY = "empty" |
| CORRUPTED_STREAM = "corrupted_stream" |
| FEATURE_EXTRACTION_FAILED = "feature_extraction_failed" |
| MODEL_INFERENCE_FAILED = "model_inference_failed" |
| OOM = "oom" |
| UNKNOWN = "unknown" |
| ``` |
|
|
| `RouterDecision.error_class: ErrorClass` 替代自由字符串。Bench 按 class 聚合计数。 |
|
|
| Quarantine 桶：`out/quarantine/<error_class>/<sha256>.json` 保留失败记录（路径 + error + 完整特征向量，**不保留 PDF**），离线分析用。 |
|
|
| **工作量**：3 天 |
|
|
| --- |
|
|
| ## 5 · P2 功能补全（Week 7-16） |
|
|
| ### 依赖 DAG |
|
|
| ``` |
| Layout Analyser (3.1) ──┬──► Pipeline Parser (3.2) ──┐ |
| │ │ |
| └──► VLM Parser (3.4) ────┼──► Stage-3 (3.5) ──► Stage-4 (3.6) ──► Stage-5 (3.7) |
| │ |
| ┌──► Stage-B Router (3.3) ─────┘ |
| │ |
| (reads LayoutCache) |
| ``` |
|
|
| ### 5.1 Layout Analyser · P2-1 |
|
|
| **选型**：PP-DocLayoutV3 ONNX INT8（CPU ~50 ms/页），未来可接 docling-layout-heron。 |
|
|
| **交付物**： |
|
|
| ``` |
| packages/pdfsys-layout-analyser/src/pdfsys_layout_analyser/ |
| ├── __init__.py |
| ├── analyser.py # LayoutAnalyser 主类 |
| ├── runners/ |
| │ ├── pp_doclayoutv3.py # ONNX runtime 驱动 |
| │ └── heuristic.py # bbox 列数聚类 fallback |
| ├── render.py # PDF 页 → PNG（DPI 可调） |
| └── postprocess.py # 阅读顺序 + 跨栏合并 |
| ``` |
|
|
| **API**： |
|
|
| ```python |
| class LayoutAnalyser: |
| def __init__(self, config: LayoutConfig = LayoutConfig()): ... |
| def analyse(self, pdf_path: str | Path) -> LayoutDocument: ... |
| def analyse_with_cache( |
| self, pdf_path: str | Path, cache: LayoutCache |
| ) -> LayoutDocument: ... # idempotent |
| ``` |
|
|
| **验收**： |
| - OmniDocBench-100 上 mAP ≥ 0.85 |
| - CPU INT8 吞吐 ≥ 20 页/s/core |
| - `LayoutDocument` 能被 `LayoutCache.save/load` 完整 roundtrip |
| - 空 / 加密 / 损坏 PDF 全部不 crash |
|
|
| **工作量**：1 人 · 10 天 |
|
|
| --- |
|
|
| ### 5.2 Pipeline Parser · P2-2 |
|
|
| **选型**：RapidOCR（PaddleOCR ONNX 前向，无 Paddle 依赖）。 |
|
|
| **交付物**： |
|
|
| ``` |
| packages/pdfsys-parser-pipeline/src/pdfsys_parser_pipeline/ |
| ├── extract.py # extract_doc / extract_doc_bytes |
| ├── ocr_engine.py # RapidOCR wrapper (lazy load) |
| ├── region_processor.py # 按 RegionType 派发 |
| ├── image_cropper.py # bbox → image crop |
| └── markdown_emitter.py # region + OCR → Segment |
| ``` |
|
|
| **核心逻辑**： |
|
|
| ```python |
| def extract_doc(pdf_path, *, layout_cache: LayoutCache) -> ExtractedDoc: |
| layout = layout_cache.load_or_compute(pdf_path, analyser) |
| segments = [] |
| for page in layout.pages: |
| for region in page.regions: |
| img = crop_region_from_pdf(pdf_path, page.index, region.bbox) |
| text = ocr_engine.recognise(img, region.type) |
| segments.append(Segment( |
| index=len(segments), |
| backend=Backend.PIPELINE, |
| page_index=page.index, |
| type=region.type, |
| content=text, |
| bbox=region.bbox, |
| source_region_id=region.region_id, |
| )) |
| return ExtractedDoc( |
| sha256=sha256_of_file(pdf_path), |
| backend=Backend.PIPELINE, |
| segments=tuple(segments), |
| markdown=merge_segments_to_markdown(tuple(segments)), |
| stats={"page_count": len(layout.pages)}, |
| ) |
| ``` |
|
|
| **验收**： |
| - OmniDocBench 扫描件子集中文字符 F1 ≥ 0.90 |
| - 输出 schema 与 `parser-mupdf` 同构（`tests/contract/test_extracted_doc_schema.py` 保护） |
| - CPU 吞吐 ≥ 5 页/s/core |
|
|
| **工作量**：1 人 · 12 天 |
|
|
| --- |
|
|
| ### 5.3 Stage-B Router · P2-3 |
|
|
| 把当前 4 行 stub `decider.py` 做实： |
|
|
| ```python |
| def decide_complex_vs_simple( |
| layout: LayoutDocument, config: RouterConfig |
| ) -> Backend: |
| if not config.vlm_enabled: |
| return Backend.PIPELINE |
| if layout.has_complex_content: |
| return Backend.VLM |
| return Backend.PIPELINE |
| ``` |
|
|
| `Router._route()`：`ocr_prob ≥ threshold` 时先查 `LayoutCache`，命中 → 调 `decide_complex_vs_simple`；未命中 → 返回 `DEFERRED`。 |
|
|
| **工作量**：2 天 |
|
|
| --- |
|
|
| ### 5.4 VLM Parser · P2-4 |
|
|
| **选型**（PRD §4.4）：生产用 LMDeploy 驱动 MinerU 2.5-Pro 1.2B。 |
|
|
| **交付物**： |
|
|
| ``` |
| packages/pdfsys-parser-vlm/src/pdfsys_parser_vlm/ |
| ├── extract.py |
| ├── engines/ |
| │ ├── mineru.py # LMDeploy wrapper |
| │ └── paddleocr_vl.py # 备选 |
| ├── batching.py # dynamic batching |
| ├── rendering.py # 高 DPI 页面渲染 |
| └── fallback.py # OOM 降 batch 重试 |
| ``` |
|
|
| **关键约束**： |
| - Worker 常驻模型（单例懒加载） |
| - `max_batch_size=16, max_seq=8192`（PRD §4.4） |
| - 超长页：单页 > 8192 tokens 按 bbox 聚类切两块 |
| - 单页 OOM 自动降 batch 重试 ≤ 2 次后写 quarantine（见 §4.5） |
|
|
| **工作量**：1 人 · 15 天（含 LMDeploy 调通） |
|
|
| --- |
|
|
| ### 5.5 Stage-3 后处理 |
|
|
| 独立成新包 `packages/pdfsys-postproc/`： |
|
|
| ``` |
| ├── reading_order.py # 跨页合并、脚注挂回正文、双栏交错修正 |
| ├── paragraph_merge.py # 折行还原 + 中文断句 |
| ├── formula_norm.py # KaTeX 语法校验，失败转 image placeholder |
| ├── table_norm.py # HTML↔Markdown 双格式，行列校验 |
| └── unicode_norm.py # NFC + 全半角统一 + 零宽字符清理 |
| ``` |
|
|
| **工作量**：1 人 · 10 天 |
|
|
| --- |
|
|
| ### 5.6 Stage-4 质量 / PII / MinHash 去重 |
|
|
| 独立成 `packages/pdfsys-quality/`，复用 `datatrove` 的 MinHash block（PRD §4.6.5）： |
|
|
| ``` |
| ├── lang_id.py # GlotLID 段落级语种识别 |
| ├── heuristic.py # 重复 n-gram、非 CJK 比例、行长方差 |
| ├── edu_score.py # 中文 EduScore (fastText → DeBERTa-v3-tiny) |
| ├── pii.py # 正则 + NER 兜底 |
| └── dedup/ |
| ├── exact.py # md5 内容精确去重 |
| └── minhash.py # datatrove MinHash LSH wrapper |
| ``` |
|
|
| **工作量**：2 人 · 3 周（MinHash 跨 shard 需全局 shuffle，最复杂） |
|
|
| --- |
|
|
| ### 5.7 Stage-5 Parquet 打包 |
|
|
| 独立成 `packages/pdfsys-output/`： |
| - Parquet 分片 ~1 GB/shard，zstd 压缩 |
| - 分桶路径：`v1/lang=zh/source=arxiv/qb=high/shard-NNNNN.parquet` |
| - JSONL 镜像 + Markdown 抽样存档（每 shard 0.1%） |
|
|
| **工作量**：1 人 · 5 天 |
|
|
| --- |
|
|
| ## 6 · P3 规模化与生态（3-6 个月） |
|
|
| | 项 | 说明 | 工作量 | |
| |---|---|---| |
| | **datatrove 集成** | 把现有 stage 包成 `datatrove.Block`，原生 Slurm 后端 | 2-3 周 | |
| | **Slurm / K8s runner** | 新包 `pdfsys-runner`，支持 shard checkpoint + 反压 | 3-4 周 | |
| | **对象存储后端** | `pdfsys-core` 抽象 `FSBackend` 协议，支持 `file://` / `s3://` / `oss://` / `minio://` | 1-2 周 | |
| | **中文 EduScore 训练** | fastText → DeBERTa-v3-tiny 分类器 + 数据标注 | 4-6 周（含标注） | |
| | **竖排古籍 LoRA** | MinerU 2.5 针对性 LoRA 微调 | 4-6 周（GPU 密集） | |
|
|
| --- |
|
|
| ## 7 · 里程碑时间线 |
|
|
| | 里程碑 | 周 | 标志 | |
| |---|---|---| |
| | **M1 · 可协作化** | 2 | CI 绿灯；覆盖率达标；lock 文件入库；parity harness 守门 | |
| | **M2 · 生产级核心** | 6 | Router p50 ≤ 10 ms；scorer 3× 吞吐；统一 log+metrics；错误可聚合 | |
| | **M3 · 6-stage 打通** | 16 | 10 GB 数据集端到端跑完；三种 backend 同构 schema | |
| | **M4 · PB 就绪** | 24 | datatrove + Slurm runner；对象存储后端；TCO 估算入库 | |
| | **M5 · v0.1 数据集** | 32 | 首个 1 TB 级对外可发布数据集 + 评测报告 | |
|
|
| --- |
|
|
| ## 8 · Quick Wins · 两周内可立即启动 |
|
|
| 如果只能挑最高 ROI 的 5 件事立刻做： |
|
|
| 1. **写 15 个 core / router / parser-mupdf 单测** — 2 天 · 把不变式变成机器可验证 |
| 2. **配 ruff + pre-commit** — 0.5 天 · 新 PR 质量底线立起来 |
| 3. **写 `.github/workflows/ci.yml`** — 0.5 天 · 反馈从"review 时"提前到"push 时" |
| 4. **`uv.lock` 入库 + 依赖加上界** — 0.5 天 · 依赖不会突然不一样 |
| 5. **`scripts/check_parity.sh` + 10 个样本 PDF 入 fixtures** — 2 天 · router 改动自动守门 |
| |
| 合计 **5-6 个工作日**，换来"可协作化"的全部前提。强烈建议以这作为第一冲刺。 |
| |
| --- |
| |
| ## 9 · 风险与"不做的事" |
| |
| ### 必须克制的诱惑 |
| |
| - ❌ **不要在 P0 之前碰 stub 实现**——没有测试和 parity harness 保护，任何功能添加都是技术债的利息 |
| - ❌ **不要替换 PyMuPDF**——它在中文场景的工程成熟度是第一梯队，换 pdfminer/PyPDF2 会立刻倒退 |
| - ❌ **不要引入 LangChain / LlamaIndex**——这是数据处理 pipeline，不是 RAG 应用 |
| - ❌ **不要在 `pdfsys-core` 引入 pydantic**——现有 `dataclass(frozen=True, slots=True)` + `serde.py` 够用，换 pydantic 破坏零依赖不变式 |
| |
| ### 长期风险对应策略 |
| |
| | 风险 | 对应 | |
| |---|---| |
| | MinerU 2.5 新版许可变化 | PaddleOCR-VL 保持热备，`pdfsys-parser-vlm` 做成 engine 抽象 | |
| | PyMuPDF AGPL 限制 | 评估 pikepdf / pdfplumber 作为退路（低优先级） | |
| | PB 级对象存储成本失控 | P0 阶段写 `scripts/tco.py` 估算 | |
| | 中文 PII 召回不足 | NER 模型兜底，保留审计表便于事后补救 | |
| |
| --- |
| |
| ## 10 · 如何跟踪进度 |
| |
| - **短期（P0-P1）**：GitHub Projects / Milestones。每个子项一 issue，带验收标准。 |
| - **中期（P2）**：每个 stage 落地时开一个"tracking issue"聚合子 PR，`CHANGELOG.md` 按 SemVer 更新。 |
| - **长期（P3）**：PRD §10 的 P0/P1/P2/P3 roadmap 每月复盘一次，本文档 v0.N 同步迭代。 |
| |
| 进度状态在根 `README.md` §What's implemented 表里维护——按 `.cursor/rules/03-doc-sync.mdc` 的映射表，任何 Stage 状态从 ❌→✅ 都必须同步该表。 |
| |
| --- |
| |
| ## 附录 · 总量一览 |
| |
| | 阶段 | 周期 | 核心交付 | 人力 | |
| |---|---|---|---| |
| | **P0 工程基础** | 2 周 | pytest + ruff + CI + lock + parity | 1 人 | |
| | **P1 性能/可靠性** | 4 周 | router 5×、scorer 3×、log/metrics | 1-2 人 | |
| | **P2 功能补全** | 10-12 周 | 6 stage 闭环 | 2-3 人 | |
| | **P3 规模化** | 3-6 月 | datatrove + Slurm + PB 级运行 | 3-4 人 | |
| |
| 从 0 到"PB 级准备"约 24 周，累计约 20-30 人周。与 PRD §6 的资源预算 "100 × A100 + 32 节点 CPU 墙钟 ~2 个月"相匹配——**先把工具链造好，再把大算力接上**。 |
| |
