Skip to content

AIH-Contexture v0.3.0

Choose a tag to compare

View all tags
@Baireinhold Baireinhold released this 27 Apr 10:54
· 3 commits to master since this release
v0.3.0
562ef8c

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 精确溯源的文档结构化任务。

Assets 2
Loading