离线、CPU-only 的 PDF / 图片 → Markdown / LLM 文本转换器：免视觉大模型、免 GPU、免云。
doc-textify 是面向纯文本大模型的"视觉前置编译器"：把 PDF、扫描件、截图与拍照文档中的文字事实编译为 Markdown、TXT、低 Token 文本协议与 JSON 结构化数据，再交给不具备视觉能力（或不希望消耗图像 Token）的大模型阅读：
PDF / Image -> doc-textify -> Markdown / TXT / LLM Text / JSON -> Text-only LLM
识别管线全部在本机 CPU 上完成：OCR、PDF 解析、版面分析、图表与表格提取均不调用 GPT、Gemini、Claude、Qwen-VL 等视觉大模型，文档可以不离开你的机器。它不是通用视觉大模型的替代品——对自然照片、复杂场景、情绪、意图等开放式视觉理解，视觉大模型仍更合适。
- 中英混排 OCR 与 CJK 规范化：全角→半角、CJK 间多余空格清理、混淆字纠正、中英边界空格；
--lang auto自动检测语言 - PDF 双路径：数字 PDF 优先抽取原生文字层；扫描 PDF 渲染为图片走 OCR（
--force-ocr强制） - 图像预处理：自动 deskew / 方向纠正（默认开启，
--no-deskew关闭）、--handwriting手写优化（CLAHE + 多 PSM + EasyOCR 回退） - 版面分析：标题 / 段落 / 列表识别、页眉页脚与页码过滤、公式块检测；双栏阅读顺序（左栏自上而下 → 右栏）
- 三策略表格提取：pdfplumber（原生 PDF）→ 分隔线网格（OpenCV）→ 列间隙对齐回退
- 图表结构化提取：面板检测、K-means 自动颜色聚类（
--chart-colors可手工指定）、网格线/刻度坐标校准（含 log 轴）、区间 / 散点数据 + ± 误差表达 - 公式处理：规则式 LaTeX 重建（常开，扫描公式转为
$$...$$）；--formula-ocr启用 pix2tex / Tesseract eq 后端 - 6 种输出格式 + JSON sidecar；批量 / 并行 / 断点续跑（
--workers、--resume、--batch-size、--dry-run） - 可评测：expected-JSON 结构化评分（
doc-textify-eval）与 benchmark 框架（doc-textify-bench）
要求 Python 3.10+：
pip install -e ".[all]"[all] 安装 opencv-python-headless（图表 CV 分析）；pdfplumber、EasyOCR、pix2tex 为可选增强，缺失时自动降级。Tesseract OCR 需自行安装（doc-textify 不内置、不随 pip 分发）：从 tesseract-ocr/tesseract 安装并加入 PATH，或设置环境变量 TESSERACT_CMD；中英混排请同时安装 chi_sim 与 eng 语言数据。
doc-textify --help# 数字 PDF → 全部格式
doc-textify input.pdf --out outputs --format all
# 扫描 PDF（强制 OCR，中英混排）
doc-textify scanned.pdf --out outputs --format all --force-ocr --lang chi_sim+eng
# 图片 → 面向 LLM 的紧凑文本
doc-textify photo.jpg --out outputs --format llm --lang chi_sim+eng
# 自动语言检测 + RAG-ready 分块
doc-textify paper.pdf --out outputs --format deepseek --rag-ready --lang auto
# 批量并行 + 断点续跑
doc-textify "scans/*.pdf" --out outputs --format md --workers 4 --resumeLLM 文本由 DOC_TEXTIFY_LLM_PROTOCOL v2 头、[page N] 页面节与 type→ text 块行构成，图表以 [CHART] 记号输出区间与散点数据。
| 格式 | 文件 | 内容 |
|---|---|---|
md |
{stem}.md |
Markdown：页面、标题、段落、表格、图表、公式 |
txt |
{stem}.txt |
纯文本 |
llm |
{stem}.llm.txt |
紧凑文本协议 v2（块类型 + 置信度） |
llm-v1 |
{stem}.llm.txt |
兼容旧版协议 v1 |
deepseek |
{stem}.ds.txt |
面向 DeepSeek tokenizer 的极简格式（TSV 表格、[CHART] 记号） |
--rag-ready |
{stem}.rag.txt |
RAG 分块：<!-- CHUNK --> 标记、页号元数据、一致标题层级、数据块上下文窗口 |
| 恒常写入 | {stem}.json |
页面、块、bbox、置信度、chart_data 与元信息 |
--format 取值：md / txt / llm / llm-v1 / deepseek / both（md+txt）/ all（md+txt+llm），默认 both；JSON sidecar 始终生成，--rag-ready 可与任意格式叠加。
| 参数 | 说明 |
|---|---|
--out |
输出目录（默认 outputs/） |
--format |
主输出格式，见上表 |
--lang |
Tesseract 语言代码：eng、chi_sim+eng 等；auto 自动检测（默认 eng） |
--force-ocr |
PDF 跳过原生文字层，强制 OCR |
--min-confidence |
OCR 词置信度阈值（默认 45.0） |
--deskew / --no-deskew |
自动纠偏 / 方向纠正（默认开启） |
--chart-colors |
图表颜色列表，如 red,blue；auto 自动检测（默认） |
--handwriting |
手写优化模式 |
--formula-ocr |
公式 OCR（首次使用可能需下载模型） |
--rag-ready / --chunk-size N |
RAG 分块输出 / 每块最大字符（默认 2000） |
--recursive / -r |
递归扫描输入目录 |
--workers / -w |
并行进程数（0 = 自动 = CPU 数） |
--no-batch |
多文件时顺序处理 |
--resume |
跳过输出已存在的文件，断点续跑 |
--batch-size N |
本次最多处理 N 个文件（与 --resume 组合增量处理） |
--dry-run |
仅列出将处理的文件 |
--per-file-dir |
每个输入文件独立输出子目录 |
--output-suffix |
输出文件名追加后缀，如 _v2 |
# 先转换，再用人工标注的 expected JSON 做结构化评分
doc-textify image.jpg --out outputs --format all --lang chi_sim+eng
doc-textify-eval --actual outputs/image.json --expected expected/image.expected.json --out report.md
# 批量 benchmark：按 manifest 逐文档评分并输出 gap 分析报告
doc-textify-bench --dataset benchmarks/dataset/ --output-dir outputs/ --report-dir benchmarks/results/评分维度：图像/页面表示、关键术语、面板与坐标轴布局、图表区间与散点结构化、不确定性说明。
doc-textify/
├── doc_textify/
│ ├── cli.py # CLI：批量 / 并行 / 断点续跑
│ ├── extractors.py # OCR 管线、deskew、语言检测、列顺序
│ ├── layout.py # 版面分析：页眉页脚 / 标题 / 双栏 / 公式块
│ ├── chart.py # 图表结构化提取（面板 / K-means 颜色 / 区间 / 散点）
│ ├── calibration.py # 坐标校准（线性 / log 轴）
│ ├── table_extraction.py # 三策略表格提取
│ ├── formula_ocr.py # 规则式 LaTeX 重建与公式 OCR
│ ├── renderers.py # 6 种输出渲染
│ ├── evaluation.py # expected-JSON 评测
│ └── models.py # Block / Page / Document 数据模型
├── scripts/ # doc-textify-bench、doc-textify-eval 入口
├── benchmarks/dataset/ # manifest.json + expected 标注
├── tests/ # 28 个确定性单测
└── pyproject.toml # 版本、依赖、入口与 extras
- Tesseract 需自行安装：仓库不内置便携版，也不随 pip 分发；未安装时图片输入输出占位块并提示。
- 不做自然场景理解：面向文档、表格、图表、截图与扫描件；自然照片、开放视觉问答请交给视觉大模型。
- 复杂表格与手写体仍不稳定：合并单元格、潦草手写、低质量拍照识别准确率有限。
- 公式重建是规则式的：简单公式（下标、希腊字母、分式）表现良好，复杂公式建议启用
--formula-ocr。 - benchmark 样例不完整：manifest 声明 12 份样例文档，当前仓库仅入库 1 份（
robertson_1990_sbt.pdf），其余待补充。 - 图表坐标校准：极端 log 轴与高噪声图仍可能出现读数偏差，输出自带 ± 误差与置信度提示。
本项目采用 MIT License。欢迎贡献：新增 OCR / 文档解析后端、补充 benchmark 样例、改进图表 / 表格 / 公式解析、优化 LLM 文本协议、完善测试与文档。