v0.5.0

經緯·Contexture v0.5.0

面向人文学科的文献结构化提取平台 — 架构系统化版本。

Highlights

• Runtime 层 — 新增 aih_contexture/runtime/，统一 CLI / UI / API 的任务执行契约
• Middle JSON — 新增 aih_contexture/middle/，作为统一机器中间表示层，支持 scholarly Markdown 导出
• Backend 能力目录 — 新增 aih_contexture/backends/，含 catalog、diagnostics、doctor
• Layout 后端 — Surya / VLM Layout / MinerU / Paddle PP-DocLayout 等多后端支持
• OCR 后端 — Surya / Calamari / PaddleOCR-v5 / PaddleOCR-VL / Tesseract 等
• VLM 泛化与特化 — 支持 PaddleOCR-VL / MinerU-VL 特化路径，含页面级 checkpoint
• Markdown 后处理 — 正式 runtime mode，支持印刷页码审阅与修复，支持MinerU原生json渲染为contexture标准的scholar markdown
• 评估工具 — layout comparison / scholarly Markdown evaluation / smoke manifest
• 147 个测试文件，发布前 285 passed targeted regression

完整变更记录见 [CHANGELOG.md](https://github.com/AIH-Infra/aih-contexture/blob/main/CHANGELOG.md)

**Full Changelog**: https://github.com/AIH-Infra/aih-contexture/commits/v0.5.0

AIH-Contexture v0.3.1

在0.3.0版本上修复了安装脚本的一些小错误。

AIH-Contexture v0.3.0

AIH-Contexture 0.3 更新说明

AIH-Contexture 0.3 是一次面向实际批量文献转换的功能升级。相比 0.1，0.3 从基础 OCR / 文档结构化版本，升级为包含 VLM 泛化、VLM 特化、Churro/Chandra、Markdown 后处理、页码修复与可诊断输出的完整发布版。

本版本的核心目标，是让扫描书、历史文献、报刊、古籍和复杂页眉页脚材料在转换为 Markdown / JSON 后，能够更稳定地保留页级溯源信息，并支持后续 RAG、校勘和人工复核。

主要变化

0.3 的主要变化集中在以下方面：

• 核心转换器、处理器、渲染器和 VLM / Churro / Chandra 输出链路重构。
• 新增 Markdown 后处理体系，支持印刷页码审阅和修复。
• 页码、页眉页脚、脚注、章节标题和 LLM 修正处理器显著升级。
• 新增 Chandra、Churro、VLM JSON 输出解析工具。
• 新增或重构 OCR 服务抽象、Churro 服务、LM Studio native 服务等。
• 新增页码处理、Markdown 后处理、VLM 异步转换相关测试。

核心升级：页级溯源系统的稳定化与增强

0.1 已经引入页码锚点和印刷页码识别能力。0.3 并不是重新发明这一体系，而是在 0.1 的基础上，将页码处理进一步稳定化、诊断化和后处理化。

0.3 继续沿用两类分页信息：

• {n}：表示 PDF / 机器页序，是稳定的机器定位锚点。
• <!-- Page: X -->：表示印刷页码，用于人工阅读、引用和校勘。

本版本的改进重点在于：更稳定地选择印刷页码候选，更完整地保留页眉页脚上下文，并在 Markdown 输出后提供审阅、诊断和可选修复能力。

页码识别机制升级

0.3 对 0.1 已有的页码处理机制进行了增强。印刷页码选择不再只依赖单一命中结果，而是经过多候选收集、评分、去重和跨页选择。

新版机制会综合考虑：

• 页眉 / 页脚区域中的候选文本；
• 候选页码的格式；
• 候选所在区域和对齐方式；
• 候选与页面边缘的距离；
• 页码序列的连续性与合理性。

这降低了日期、年份、卷号、期号、正文数字被误识别为页码的概率，尤其适合报刊、历史文献和复杂页眉页脚材料。

页眉页脚信息保留

0.3 不再只把页眉页脚作为页码提取来源，也会将其作为页面元数据保留下来。Markdown 渲染时可以输出：

<!-- page-header: ... -->
<!-- page-footer: ... -->

这有助于在后续 RAG、校对和人工复核中保留页面边界信息，而不是只保留一个最终页码。

Markdown 印刷页码后处理

0.3 新增 Markdown 后处理体系，可以在转换完成后再次审阅 Markdown 中的分页结构。

后处理模块会解析：

• {n} 页锚点；
• <!-- Page: X --> 印刷页码注释。

并支持：

• 标准化阿拉伯数字和罗马数字；
• 判断页码类型；
• 建立页码序列观察；
• 识别稳定段、异常点和边界候选；
• 在启用应用模式时，对缺失或异常的印刷页码进行修复或移除。

默认策略是审阅优先。也就是说，0.3 提供页码修复能力和诊断报告，但是否实际改写 Markdown 输出取决于 UI 或配置是否开启应用模式。

LLM 辅助印刷页码修正

0.3 新增 LLM 辅助印刷页码修正能力。它会在需要时基于 Markdown 快照、当前页面结构和印刷页码序列，辅助判断复杂页码问题，并在配置允许时写回修正结果。

这形成了两级页码修正结构：

• 规则层：负责候选解析、序列判断和异常检测；
• LLM 层：用于辅助处理复杂、不规则或稀疏的页码序列。

VLM 泛化模式增强

0.3 对 VLM 泛化模式进行了重要重构，尤其是 OpenAI-compatible 路线。

主要变化包括：

• VLM 输出继续以结构化 JSON 为核心；
• Teacher prompt 改为更稳定的 JSON schema 表达；
• 防幻觉默认开启；
• bbox 作为高级选项默认开启；
• 图片描述改为非强制开关；
• thinking / reasoning 请求级默认关闭；
• 增加逐页 diagnostics 和 response metadata。

这让非 JSON、坏 JSON、缺字段、字段类型错误、HTTP 错误、截断、重试耗尽和 Markdown 转换失败等问题能够被更清楚地定位。

VLM / Churro / Chandra 输出链路增强

0.3 新增或重构了 VLM、Churro 和 Chandra 的输出解析链路，使不同后端的页级信息和错误诊断更容易进入最终 Markdown 或 JSON 输出。

这些改进可以更早暴露空 XML、坏 XML、空文档等问题，也有助于保持多后端之间的页码、页锚点和页级诊断一致性。

Markdown 输出变化

0.3 的 Markdown 渲染器在分页输出中可以组织以下信息：

1. {n} 页锚点；
2. 页面分隔符；
3. 可选页眉注释；
4. 可选页脚注释；
5. <!-- Page: X --> 印刷页码注释；
6. 可选图片描述注释。

这比 0.1 更适合后处理、人工复核和 RAG 精确溯源。

脚注与边注默认行为调整

0.3 对脚注和边注默认行为进行了修正：

• 边注识别默认关闭；
• 边注关闭时，不再提示模型输出 Marginal-Note 标签；
• 边注关闭时，JSON 转 Markdown 不再强制渲染边注标签；
• 脚注不再生成 ↩ 返回箭头；
• confidence: null 不再导致 JSON 转 Markdown 阶段报错。

这些变化使默认 Markdown 输出更干净，也降低了后处理中的噪声。

Streamlit 与批处理体验改进

0.3 改进了 Streamlit 和本地启动体验：

• 上传上限提高到 1024 MB；
• 启动脚本会跳过已占用端口；
• VLM 泛化模式保留多页 PDF 串行文件处理和单页多文件批次处理两种并发语义；
• LM Studio / 本地 OpenAI-compatible 路线保持严格批次，一批全部完成后再进入下一批；
• VLM 泛化 UI 中新增或调整防幻觉、bbox、confidence、表格/公式增强、图片描述、边注识别等开关。

这些变化使 0.3 更适合大文件、本地模型和批量扫描页处理。

兼容性说明

从 0.1 升级到 0.3 时，需要注意：

1. {n} 仍然可用，但应理解为 PDF / 机器页序锚点，而不是印刷页码。
2. 印刷页码应从 <!-- Page: X --> 读取。
3. 如果下游系统以前把 {n} 和印刷页码混用，建议改为：
   • {n}：稳定定位；
   • <!-- Page: X -->：引用原书页码。
4. Markdown 中可能出现新增注释：
   • <!-- page-header: ... -->
   • <!-- page-footer: ... -->
   • <!-- image-description-N: ... -->
5. Markdown 后处理默认偏保守，页码修复能力存在，但默认以审阅和报告为主。
6. VLM 泛化 JSON 输出可能新增 diagnostics / response metadata 字段，下游 JSON 消费方应允许额外字段。
7. 边注默认关闭，如果需要识别眉批、边注、页边注释，需要在 UI 或配置中显式开启。
8. 脚注不再包含 ↩ 返回箭头。

从 0.1 升级到 0.3

如果机器上已经安装过 0.1，推荐优先采用“复用旧虚拟环境 + 只切换 0.3 代码”的软升级方式。

示例流程：

cd D:/AIH-infra-run/aih-contexture-master-0.3
source ../AIH-Contexture/.venv/Scripts/activate
python -m pip install -e . --no-deps
python -c "import aih_contexture; print(aih_contexture.__file__)"
contexture_gui --help
contexture_single --help

如果运行时报缺少个别新增包，再按需补装，例如：

pip install psutil lxml streamlit-ace

如果确认需要让 pip 按 0.3 的 pyproject.toml 补齐依赖，再执行：

pip install -e .

如果希望完全隔离 0.1 和 0.3，也可以新建独立虚拟环境：

cd D:/AIH-infra-run/aih-contexture-master-0.3
python -m venv .venv
source .venv/Scripts/activate
python -m pip install --upgrade pip
pip install -e .

扩展格式支持可安装：

pip install -e ".[full]"

模型缓存说明

通常不需要重新下载模型：

• LM Studio 模型由 LM Studio 管理，Python 包升级不会删除或重下这些模型。
• HuggingFace / Torch 模型缓存通常在用户缓存目录，不在项目代码目录。
• 只有当切换到 0.1 从未使用过的新模型名，或删除了原模型缓存，才会触发首次下载。

配置迁移建议

• 不要直接覆盖 0.3 的配置文件；优先在 0.3 UI 中重新选择模型、API profile、VLM 模式和输出格式。
• API Key、base URL、模型名可以从 0.1 手动复制到 0.3。
• LM Studio 路线只需要确认 base URL、端口和模型名仍然正确。
• VLM 泛化模式中，JSON 严格输出、thinking 关闭、防幻觉、bbox、边注默认关闭等行为与 0.1 不完全相同，应按 0.3 UI 重新确认。
• 下游如果依赖页码，应优先适配：{n} 表示机器页序，<!-- Page: X --> 表示印刷页码。

发布总结

AIH-Contexture 0.3 相比 0.1 的最大变化，是在既有页码锚点和印刷页码能力之上，增强页码候选选择、页眉页脚上下文保留、Markdown 后处理、LLM 辅助修正和 VLM diagnostics。

0.3 的页码增强可以概括为：

• 继续沿用 {n} 作为机器页序；
• 继续使用 <!-- Page: X --> 表达印刷页码；
• 新增或增强 page-header / page-footer 注释以保留版面上下文；
• 通过多候选打分降低日期、年份、卷期号误识别；
• 通过 Markdown 后处理审阅缺失和异常页码，并在显式启用应用模式时执行修复；
• 通过 LLM 辅助审阅复杂序列问题，并在配置允许时写回修正；
• 通过 VLM diagnostics 判断页码缺失是模型输出问题、JSON 问题还是下游解析问题。

因此，0.3 更适合历史文献、报刊、扫描书、古籍、带复杂页眉页脚的学术出版物，以及需要 RAG 精确溯源的文档结构化任务。

AIH-Contexture v0.1

AIH-Contexture 0.1 发布说明

AIH-Contexture 0.1 是项目作为独立人文学科文献结构化工具发布的首个版本。本版本在 Marker 相关开源能力的基础上，面向人文学科材料处理需求，加入页码锚点、印刷页码识别、边注处理、行内注处理、多后端 OCR / Layout 适配和批量处理能力。

0.1 的核心目标，是让扫描文献、学术出版物、古籍、档案和历史材料在转换为 Markdown / JSON 后，能够保留更适合人文学术使用的结构信息和页级定位信息。

项目定位

AIH-Contexture 面向的问题不是单纯“把 PDF 转成文本”，而是“如何让数字化文献能够被学术引用、复核和追溯”。

在人文学科场景中，材料结构化结果需要尽可能保留：

• 原文页面位置；
• 印刷页码；
• 页眉页脚；
• 边注和夹注；
• 章节结构；
• 后续 RAG / 知识图谱 / Agent 工作流可使用的页级锚点。

0.1 是这一方向的初始发布版本。

核心能力

OCR 与 Layout 后端可插拔

0.1 提供 OCR 和 Layout 后端可插拔架构，支持在不同处理路线之间切换。

OCR 后端包括：

• Surya
• Calamari
• Chandra
• VLM

Layout 后端包括：

• Surya
• YOLO
• DocLayout-YOLO
• VLM

这为后续针对不同文献类型、扫描质量和本地/云端模型环境进行组合提供了基础。

三种处理模式

0.1 提供三类处理路线：

• 传统 Pipeline；
• VLM 泛化；
• VLM 特化。

这些模式使 Contexture 可以同时面向传统 OCR/Layout 流程和视觉语言模型驱动的结构化流程。

页码锚点系统

0.1 引入页码锚点机制，用于在 Markdown 输出中保留页面级定位信息。

该能力是 Contexture 面向人文学科场景的重要基础：转换后的文本不只是可读文本，还应能够回到原 PDF 或原书页面，支持引用、复核和后续知识系统溯源。

印刷页码识别

0.1 支持从页眉、页脚等页面区域识别印刷页码，并支持多种页码形式：

• 阿拉伯数字；
• 罗马数字；
• 中文数字；
• 自定义正则规则。

这使其可以处理现代出版物、古籍、档案和多种历史文献中常见的页码形式。

页码序列修正

0.1 提供基于页码模式识别的序列修正能力，用于处理部分异常页码、缺失页码或识别不稳定的情况。

边注处理器

0.1 提供边注识别与结构化能力，用于处理页边批注、眉批、侧注等人文学科材料中常见的注释形态。

行内小字注处理器

0.1 支持行内注、夹注、割注等结构的处理，适合古籍、传统注疏和部分历史文献场景。

模板系统

0.1 提供面向不同材料类型的模板基础：

• modern_publications：现代学术出版物；
• chinese_ancient_books：中国古籍；
• german_gothic_print：德语哥特体印刷品；
• archive_documents：档案文献。

模板系统使不同文献类型可以在处理策略、页面结构和输出约定上保持可配置。

API Key 池与批处理能力

0.1 提供 API Key 池和批处理工具：

• 多 Key 并发；
• Round-robin 负载均衡；
• 失败自动冷却；
• GPU 内存自适应批处理参数计算。

这些能力用于支持较大规模的文献转换任务。

输出与使用场景

0.1 适用于以下场景：

• 扫描书或论文 PDF 转 Markdown；
• 人文学科材料结构化；
• 保留页级锚点以支持后续 RAG；
• 对古籍、报刊、档案等材料进行初步结构化；
• 比较不同 OCR / Layout 后端在特定材料上的效果。

开源基础与致谢

AIH-Contexture 0.1 基于多个开源项目和模型生态构建，特别包括：

• Marker
• Surya
• Chandra
• Calamari OCR

本项目在这些开源能力的基础上，面向人文学科文献结构化、页码溯源和学术引用需求进行了独立扩展。相关许可证与声明见仓库中的 LICENSE、MODEL_LICENSE 和 NOTICE 文件。