Skip to content
GitLab

feat: OpenCC zh_t2s mapper with eval/bench and docs refresh

Merged yujiwen requested to merge feature/chinese-t2s-mapper into master

Summary

本 MR 在 master（foundation 最小集）之上新增 繁体→简体 mapper（OpenCC） 及完整的 eval / benchmark 范式，并刷新算子与需求方向文档。

  • mapper_zh_t2s：支持 MinerU 风格 nested JSON（type=text）与 flat / Arrow 列批处理
  • 测试分层：单元测试（CI）+ eval 回归（-m eval）+ item vs arrow 性能基线（-m bench）
  • 文档：重写 OPERATORS.md、highlevel_direction.md、modularization_vision.md；移除已过时的 Legacy Docker/MinerU 运行手册

目标分支：master
源分支：feature/chinese-t2s-mapper

Commits

Commit 说明
45ba425 feat: add zh_t2s mapper with eval/bench harness and updated docs
b42c870 docs: refresh operator framework and requirement direction docs

主要变更

1. 算子：mapper_zh_t2s

文件：backend/foundation/operators/mapper/zh_traditional_to_simplified_mapper.py

项 说明
op_name mapper_zh_t2s
引擎 opencc-python-reimplemented（默认 t2s）
nested 模式 递归 JSON，仅转换 type="text" 节点的 target_col
flat 模式 顶层列转换；缺列 / 非 str 静默跳过
Arrow flat 列 batch（当前为逐行 OpenCC 基线，bench 已记录）
metrics 可选 ZhT2SMetricsHooks（items / text_nodes / arrow_rows）

依赖：backend/foundation/pyproject.toml 新增 opencc-python-reimplemented>=0.1.7

2. 单元测试

文件：backend/foundation/tests/test_zh_traditional_to_simplified_mapper.py（26+ 用例）

覆盖：convert_* 纯函数、nested/flat process_item、流式 process、registry、Arrow 路径、错误包装、OperatorError metrics 语义。

3. Eval / Benchmark

目录：backend/foundation/eval/zh_t2s/

组件 说明
cases/smoke_*.jsonl flat / nested / arrow / strings smoke 用例（入库）
test_eval_correctness.py @pytest.mark.eval 端到端 golden
test_bench_compare_paths.py @pytest.mark.bench item vs arrow 耗时对比
scripts/generate_strings_corpus.py 本地生成 full_strings.jsonl（gitignore）
conftest.py --eval-dataset、--bench-rows 等；参数 > 0 校验

pytest 默认 addopts = "-m 'not eval and not bench'"，CI 仅跑 tests/。

4. 文档

文档 变更
docs/OPERATORS.md 对齐当前 foundation 算子框架（中文）
docs/requirement/highlevel_direction.md 重构为核心算子能力需求清单
docs/requirement/modularization_vision.md 项目模块化方向与防走偏红线
README.md / backend/foundation/README.md 结构、测试分层、zh_t2s 示例
eval/zh_t2s/README.md eval/bench 完整指南（中文）

删除（过时 Legacy）：BRANCH_SCOPE.md、Docker/MinerU 运行手册、ownership.md 等；交叉引用已改指向 modularization_vision / highlevel_direction。

代码审视要点（已处理）

  • bench 文件命名为 test_bench_compare_paths.py，目录级 -m bench 可收集
  • --bench-rows / --bench-batch-size / --bench-rounds 在 fixture 中前置校验，避免 ZeroDivisionError
  • Arrow 路径：非 str 列静默透传；内部错误包装为 OperatorError(ARROW_PROC_ERROR)

Test plan

  • uv sync --group dev
  • uv run ruff check backend/foundation
  • uv run pytest backend/foundation/tests -v — 47 passed
  • uv run pytest backend/foundation/eval/zh_t2s -m eval -v — 7 passed
  • uv run pytest backend/foundation/eval/zh_t2s -m bench --collect-only — 1 test collected
  • Reviewer 阅读 operators/mapper/zh_traditional_to_simplified_mapper.py docstring 行为表
  • Reviewer 确认 Legacy 文档删除范围可接受
  • （可选）本地 10 万行 bench：eval/zh_t2s/README.md

合并说明

  • 本 MR 仅扩展 foundation，不恢复 FastAPI / pipeline / MinerU OCR 运行时
  • 新增运行时依赖 OpenCC（纯 Python wheel，无 GPU）
  • CI（foundation-ci）不变：仍只跑 backend/foundation/tests

快速验证命令

uv sync --group dev
uv run pytest backend/foundation/tests -v
uv run pytest backend/foundation/eval/zh_t2s -m eval -v
Edited by yujiwen