OpenPecha/outline-detection

# 藏文文本边界检测 `outline_detection` 用于检测一段藏文文本在哪里结束、另一段在哪里开始，它使用模式规则（yig mgo ༄༅、章节标记 ༈、结尾短语）以及可选的 CRF 序列标注器。该工具基于对数万个已标注边界片段的分析构建而成。 ## 安装 ``` pip install -e . # core (rule-based detection + evaluation) pip install -e ".[crf]" # also install CRF extras (scikit-learn, sklearn-crfsuite) ``` 要求 Python 3.9+。（`pip install -r requirements.txt` 会执行包含 `[crf]` 的可编辑安装。） ## Python API ``` from outline_detection import detect_breakpoints text = "...རྫོགས་སོ།། ༄༅། །next text..." detect_breakpoints(text) # {"breakpoints": [0, 152, 410, ...]} ``` `detect_breakpoints` 返回一个字典，其中包含键 `breakpoints`，其值是基于规则的检测器找到的边界**起始索引**（字符偏移量）列表。 选项： ``` detect_breakpoints(text, profile="precision") # recall | balanced | precision detect_breakpoints(text, min_confidence=0.5) # override threshold detect_breakpoints(text, detailed=True) # adds per-boundary confidence + rule ``` ### OCR 页面模式（可选） 对于以页面序列形式输出的 OCR，可选的页面布局规则 (I–L) 使用**行密度**而不是正字法信号。默认情况下它们是关闭的，并且在连续（单页）文本中不起作用： ``` detect_breakpoints( ocr_text, rule_i_empty_page=True, # an empty page marks a break rule_j_sparse_tail=True, # dense page then two sparse pages line_threshold=4, # T: "few lines" cutoff page_delimiter="\f", # form feed (default), "blank"/"blankN", or regex ) ``` 请参阅 [docs/rules.md](docs/rules.md#page-layout-rules-il) 获取完整的规则集。 ## CLI 安装后会提供一个 `outline-detect` 命令。 **检测**边界（输入文本 -> 输出 JSON）： ``` outline-detect detect mytext.txt # {"breakpoints": [0, 152, 410]} echo "..." | outline-detect detect - # read from stdin outline-detect detect --text "རྫོགས་སོ།། ༄༅། །next" --pretty outline-detect detect mytext.txt -o result.json ``` 针对已标注数据进行**评估**： ``` outline-detect evaluate data/breakpoints_context_snippets_unique.json --profile balanced --tolerance 15 outline-detect evaluate data/breakpoints_context_snippets_unique.json --all-profiles --tolerance 15 ``` **分析**边界模式： ``` outline-detect analyze data/breakpoints_context_snippets_unique.json ``` 使用边界标记**标注**原始文件： ``` outline-detect predict data/samples/INPUT.txt --profile balanced ``` **CRF**（需要安装 `[crf]` 额外依赖）： ``` # 带有 feature cache 和 post-train eval 的 full-corpus train outline-detect crf train data/breakpoints_context_snippets.json \ --save-model --features-cache reports/models/crf_features.pkl \ --eval-file data/breakpoints_context_snippets_unique.json # 评估已保存的模型 outline-detect crf evaluate data/breakpoints_context_snippets_unique.json \ --model reports/models/boundary_crf.pkl --tolerance 15 outline-detect crf predict data/samples/INPUT.txt --model reports/models/boundary_crf.pkl ``` ## 数据 | 文件 | 大小 | |------|------| | `data/breakpoints_context_snippets.json` | 82,560 个已标注片段 | | `data/breakpoints_context_snippets_unique.json` | 31,591 个去重后的片段 | | `data/samples/` | 用于预测演示的可选原始 `.txt` 文件 | 已标注 JSON 中的边界使用 ``（或 ``）标记。 **Hugging Face Hub:** | 资源 | 仓库 | |----------|------| | 完整片段 (82,560) | [ganga4364/tibetan-outline-boundary-snippets-full](https://huggingface.co/datasets/ganga4364/tibetan-outline-boundary-snippets-full) | | 去重基准 (31,591) | [ganga4364/tibetan-outline-boundary-snippets-unique](https://huggingface.co/datasets/ganga4364/tibetan-outline-boundary-snippets-unique) | | CRF 完整版（生产环境） | [ganga4364/tibetan-outline-boundary-crf-full](https://huggingface.co/ganga4364/tibetan-outline-boundary-crf-full) | | CRF 无偏版（客观评估） | [ganga4364/tibetan-outline-boundary-crf-unbiased](https://huggingface.co/ganga4364/tibetan-outline-boundary-crf-unbiased) | ``` hf download ganga4364/tibetan-outline-boundary-snippets-unique --repo-type dataset hf download ganga4364/tibetan-outline-boundary-crf-unbiased boundary_crf.pkl --local-dir ./reports/models ``` ## 输出 `evaluate`、`analyze`、`predict` 和 `crf` 会将结果写入 `./reports/` 目录下（相对于您运行命令的位置；除 `.gitkeep` 外均已被 gitignore 忽略）： | 目录 | 内容 | |-----------|----------| | `reports/evaluations/` | `rule_based_evaluation_*.md` | | `reports/analysis/` | `boundary_report_*.md` / `.json` | | `reports/diagnostics/` | `false_negatives.json` | | `reports/models/` | CRF `.pkl` 模型 | | `reports/` | `predicted_boundaries.txt`, `crf_predicted.txt` | ## 结果（去重语料库，±15 字符） | 方法 | F1 | |--------|-----| | 基于规则（平衡） | **0.601** | | CRF 完整版 | 0.571 | | CRF 无偏版 | 0.555 | 基于规则的**平衡**版本达到了约 63% 的精确率和约 57.5% 的召回率。主要激活的规则是：**A** (yig mgo) 和 **G** (༈)。请参阅 [docs/evaluation.md](docs/evaluation.md) 获取完整的对比和重新生成命令。 ## 文档 - [docs/terminology.md](docs/terminology.md) — 藏文信号、标记、指标 - [docs/rules.md](docs/rules.md) — 规则 A–H（正字法）和 I–L（页面布局） - [docs/workflow.md](docs/workflow.md) — 完整的分步工作流 - [docs/huggingface.md](docs/huggingface.md) — Hub 数据集和模型 - [docs/evaluation.md](docs/evaluation.md) — 基准测试结果 - [docs/README.md](docs/README.md) — 文档索引 - [CHANGELOG.md](CHANGELOG.md) — 发布说明 ## 仓库结构 ``` ├── pyproject.toml ├── requirements.txt ├── src/ │ └── outline_detection/ # api, cli, detector, evaluation, analyzer, crf, utils, paths ├── data/ # Annotated JSON corpora and samples/ ├── docs/ # Static reference ├── scripts/ # Training, comparison, and Hub upload helpers └── reports/ # Generated outputs (gitignored) ```