使用 Gradio 界面¶

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

启动界面¶

在仓库根目录运行：

chmod +x ./cartex
export PATH="$PWD:$PATH"
cartex ui --open

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

启动多个独立 UI 实例¶

Cartex 支持同时运行多个彼此独立的 UI 进程。为每个实例指定不同端口和实例 ID。

cartex ui --port 7860 --instance-id ui_a --debug-dir debug/ui_a
cartex ui --port 7861 --instance-id ui_b --debug-dir debug/ui_b

也可以自动一键启动多个实例：

cartex ui-multi --count 3 --start-port 7860 --open

命令会为每个实例打印访问 URL（例如 http://127.0.0.1:7860、:7861、:7862），并自动创建按实例隔离的调试目录。

默认情况下，每次 ui-multi 启动都会创建唯一的调试会话根目录：

• debug/ui_multi_<timestamp>/

每个实例的终端日志会写入：

• debug/ui_multi_<timestamp>/<instance_id>/ui.log

示例：

tail -f debug/ui_multi_20260413_011500_123456/ui_01/ui.log
tail -f debug/ui_multi_20260413_011500_123456/ui_02/ui.log

如果希望所有实例日志直接输出到当前终端，可加 --inherit-logs。

在 --inherit-logs 模式下，每行日志都会带来源前缀，便于区分：

• [stdout][ui_01] ...
• [stderr][ui_02] ...

参数说明：

• --port：为每个实例绑定不同端口
• --host：监听地址（默认 127.0.0.1）
• --instance-id：写入该进程的运行元数据与 run ID
• --debug-dir：将调试产物写入隔离目录
• --debug-root：为 ui-multi 指定实例目录根路径；默认每次启动自动创建唯一会话根目录

这样可以在并发 QA 运行中避免调试产物冲突。

上传文件¶

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

页码¶

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

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

模板选择¶

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

附加列¶

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

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

运行选项¶

界面提供两个执行开关：

• High Accuracy Tables (BBox Crop)
  在阶段一启用“表格检测 + 按 bbox 裁剪提取”。该选项仅影响表格提取；上下文提取流程不变。
• Single Specialist Mode (Monolithic)
  绕过路由与专业策略分阶段执行，在阶段三直接运行单体 ENRICHMENT 提示词。

当两者同时启用时，提取阶段走高精度表格路径，富化阶段仍走单体模式。

运行管道¶

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

1. [1/3] 提取 — 在指定页面上检测表格和上下文条目。Page Preview 图库更新为每页带彩色边界框叠加的标注图：蓝色为主表，绿色为辅助表，橙色为上下文区域。每张页面图像标注其页码。处理多页时，图库显示所有页面及其各自的标注。
2. [2/3] 路由 — 默认模式下，路由器选择专业策略、规划执行顺序并分配上下文；单体模式下，该阶段会被跳过。
3. [3/3] 富化 — 默认模式运行分阶段专业策略；单体模式执行一次通用富化调用，然后输出富化行数。

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

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

并行处理多个文档（CLI）¶

做基准批跑或回归批量测试时，建议使用进程并行批处理，而不是同时打开多个 UI 标签页。

cartex batch --jobs misc/jobs.sample.json --workers 4 --output-dir debug/batch_parklane_kingsbrook

Jobs 清单格式¶

准备一个 JSON 数组，每个对象代表一个文档任务。

[
  {
    "job_id": "parklane_p1",
    "file_path": "misc/Parklane.pdf",
    "page_numbers": [1],
    "template": "glass_schedule",
    "use_table_bbox_crop": false,
    "force_monolithic": false
  },
  {
    "job_id": "kingsbrook_p1_2",
    "file_path": "misc/Kingsbrook.pdf",
    "page_numbers": [1, 2],
    "template": "standard_takeoff",
    "extra_columns": ["Source Type"]
  }
]

每个任务支持的键：

• job_id（可选）：用于汇总与产物命名的稳定标识
• file_path（必填）：PDF 路径
• page_numbers（必填）：从 1 开始的页码列表
• template（必填）：TemplateType 值（如 standard_takeoff、glass_schedule）
• columns（可选）：显式完整列列表（覆盖模板默认列）
• extra_columns（可选）：在模板默认列后追加字段
• use_table_bbox_crop（可选）：为该任务开启高精度表格提取
• force_monolithic（可选）：为该任务开启单体富化模式

批处理产物¶

每次批处理会写出：

• <output-dir>/summary.json：每个任务的状态（ok/failed）与产物路径
• 每个任务一个独立 JSON 产物：包含输入元数据、错误状态与富化行结果

这样可以在多文档批跑时保持审计可追踪，不会混淆不同样本的输出。

读取调试输出¶

每次成功运行都会在当前配置的调试根目录下写入一个运行目录：

• 默认：debug/run_.../
• 使用 --instance-id <id> 且未显式传入 --debug-dir：debug/<id>/run_.../
• 使用 --debug-dir <path>：<path>/run_.../

每个运行目录包含：

• <run_dir>/<run_id>_rows.json
• <run_dir>/<run_id>_contexts.json
• <run_dir>/<run_id>_tables.json
• <run_dir>/annotated-pages/（带 bbox 叠加的页面图 + manifest）

每个文件都包含共享 meta 对象和一个负载键：

• rows.json => { "meta": ..., "rows": [...] }
• contexts.json => { "meta": ..., "contexts": [...] }
• tables.json => { "meta": ..., "tables": [...] }
• annotated-pages/manifest.json => 每页叠加图的路径与尺寸信息

共享 meta 字段如下：

启用 High Accuracy Tables 时，运行目录还会包含 table-crops/，其中有 manifest.json 与各表格裁剪图。

rows 中的每条记录包含 data（富化列值）、field_sources（逐列来源归因）、confidence 和 reasoning。field_sources 与 reasoning 是排查字段来源最关键的信息。