使用 Gradio 界面¶

Gradio 界面提供了一种基于浏览器的方式，无需编写任何代码即可针对 PDF 文件运行 Cartex 管道并检查富化结果。专为本地开发人员测试和 QA 运行而设计。

启动界面¶

在仓库根目录运行：

python ui/app.py

Gradio 默认在 7860 端口启动本地服务器并自动打开浏览器标签。若浏览器未自动打开，请访问 http://localhost:7860。

注意： 从仓库根目录运行此命令。请勿设置 PYTHONPATH=src——Cartex 使用 src. 前缀导入，设置该变量会导致模块双重身份 bug，使枚举比较静默失败。

使用 Upload PDF 文件选择器选取 PDF 文件。上传后，Page Preview 会渲染所选页码范围的第一页。当 Page Numbers 字段变化时，预览自动更新。

Page Numbers 字段接受逗号分隔的页码、范围或两者的组合：

页码从 1 开始计数。指定多个页码时，管道调用 extract_pages()，执行多页提取，对跨页上下文条目进行去重，并将所有检测到的表格合并为单个 ExtractionResult。

Template 下拉菜单控制富化时使用的列模式。每个选项对应 src/templates.py 中定义的一个 TemplateType 枚举值和固定的基础列列表。

显示名称	`TemplateType`	适用场景
Standard Takeoff	`STANDARD_TAKEOFF`	含开启方式、材质和粗开口的标准窗门清单
Standard Takeoff + TDL/SDL	`STANDARD_TAKEOFF_TDL`	同上，另包含分格类型（`Dividers TDL Type`、`Dividers SDL Type`）
Glass Schedule	`GLASS_SCHEDULE`	含层数、品牌、配置和间隔条列的专项玻璃清单
Shop Details	`SHOP_DETAILS`	含框架型材、五金、饰面及安装列的车间详图图纸

Additional Columns 复选框组允许将 FIELD_LIBRARY 中的字段追加到基础模板列之后。FIELD_LIBRARY 是 src/templates.py 中定义的全部已知字段集合。

所选列追加在模板默认列之后。已包含在所选模板中的列会静默去重——在使用 Glass Schedule 时选择 Special Notes 不会有任何效果。

点击 Run Pipeline 开始处理。Pipeline Log 实时显示三个阶段的进度：

[1/3] 提取 — 在指定页面上检测表格和上下文条目。Page Preview 更新为带彩色边界框叠加的标注图：蓝色为主表，绿色为辅助表，橙色为上下文区域。
[2/3] 路由 — 路由器选择适用于检测内容的专业策略。
[3/3] 富化 — 所选专业策略运行，输出富化行数。

处理成功后，Enriched Table 展示每条提取清单行的数据。除模板列外，还包含三个诊断列：

列	内容
`_confidence`	富化器的数值置信度分数
`_reasoning`	该行富化方式的自由文本说明
`_field_sources`	将每列名映射到产生该值的 `FieldSource` 的 JSON 对象（如 `auxiliary_table`、`text_rule`、`image_legend`、`dimension_card`）

若管道失败，结果表下方会出现 Error Traceback 面板，显示完整的 Python 调用栈。

每次成功运行均会在仓库根目录的 debug/ 目录写入一个 JSON 文件，文件名格式为 run_YYYYMMDD_HHMMSS.json。

调试文件包含以下顶级字段：

字段	类型	描述
`timestamp`	字符串	运行的 ISO 8601 时间戳
`file`	字符串	处理的 PDF 文件绝对路径
`pages`	整数数组	处理的 1 起始页码
`template`	字符串	使用的 `TemplateType` 值（如 `glass_schedule`）
`columns`	字符串数组	完整列列表，含附加列
`strategies`	字符串数组	已触发的专业策略名称，或 `["monolithic"]`
`total_rows`	整数	返回的富化行数
`context`	对象数组	提取的序列化 `TextContextModel` 和 `ImageContextModel` 条目
`rows`	对象数组	序列化的 `EnrichedRow` 对象

rows 中的每条记录包含 data（富化的列值）、field_sources（逐列来源归因）、confidence 和 reasoning。field_sources 和 reasoning 是诊断某列获得特定值原因的主要字段。

Tip

写入 debug/ 的调试 JSON 是每次运行的权威测试产物。报告结果或提交 bug 时，请附上相关的 run_*.json 文件——它记录了完整的提取上下文、策略选择及每行的逐字段来源。