WIP: baseline on fix/retry-failure-root-causes
This commit is contained in:
@@ -0,0 +1,207 @@
|
||||
# jaspersoft 五轮修正失败问题 — 现象文档
|
||||
|
||||
## 1. 问题概述
|
||||
|
||||
**触发场景**：用户上传一张车历卡（维修结算单）图片，系统通过 OCR 识别并生成 JRXML 报表模板。
|
||||
|
||||
**现象**：5 次自动修正循环全部失败，系统提示"[内容保真度不足] 得分 0.00/1.0"，最终无法生成可用 JRXML。
|
||||
|
||||
**测试会话**：`sessions/6d39a91e11c54f02bb70a62d856ea2d4.json`（2026-05-24 15:14）
|
||||
|
||||
---
|
||||
|
||||
## 2. 完整流程追踪
|
||||
|
||||
### 2.1 用户输入
|
||||
|
||||
- 上传文件：`e1113725c20fc4ec39bc9e4ab0caa6b2.jpg`（车历卡，1357×1920 RGB）
|
||||
- 用户输入：空（仅上传文件）
|
||||
|
||||
### 2.2 系统处理流程
|
||||
|
||||
```
|
||||
上传图片
|
||||
→ process_input 节点（OCR 字段提取 + 布局分析）
|
||||
→ layout_analyzer（34 行 × 1 列，A4 纵向）
|
||||
→ ocr_extractor（4 策略提取）
|
||||
→ classify_intent（= initial_generation）
|
||||
→ retrieve
|
||||
→ route_after_retrieve（有 layout_schema，走 generate_skeleton）
|
||||
→ generate_skeleton（生成 ~34k 字符骨架 JRXML）
|
||||
→ refine_layout（Band 级窗口化精调）
|
||||
→ map_fields（程序化字段替换 $F{field_N} → 真实字段名）
|
||||
→ validate（validate 节点）
|
||||
→ XSD 验证：✅ 通过
|
||||
→ OCR 保真度检查：❌ score=0.41 < 0.5 → 降级为 fail
|
||||
→ error_msg = "[内容保真度不足] 得分 0.41/1.0。元素覆盖不足：JRXML 仅有 142 个文本元素，OCR 源有 173 个文本元素（覆盖率 82%）。JRXML 中未声明任何字段，但 OCR 提取了结构化字段数据"
|
||||
→ 5 次 correct_jrxml 修正循环均失败
|
||||
→ 状态：fail（MAX_RETRY=5 耗尽）
|
||||
```
|
||||
|
||||
### 2.3 最终状态
|
||||
|
||||
```
|
||||
status: fail
|
||||
retry_count: 5
|
||||
error_msg: "[内容保真度不足] 得分 0.00/1.0。JRXML 仅有 0 个文本元素，OCR 源有 173 个文本元素（覆盖率 0%）"
|
||||
```
|
||||
|
||||
⚠️ **重要矛盾**：`current_jrxml`（24391 字符，142 个 textField）与 `error_msg`（"0 个文本元素"，score=0.00）存在矛盾。
|
||||
|
||||
验证服务审计（`validate-service-audit`）指出："6d39a91e has 0 text elements causing score=0.00"——说明在**触发 fail 的那个时间点**，JRXML 确实只有 0 个文本元素。
|
||||
|
||||
但 session 文件最终保存的 `current_jrxml` 是 24391 字符版本。`jrxml_versions` 最后一条记录的 `jrxml` 才是触发失败的真实版本。
|
||||
|
||||
**结论**：`current_jrxml` 在 5 次修正过程中被逐步侵蚀，最终版本是某个接近空壳的状态。`jrxml_versions[-1]` 中的 `jrxml` 才是真正的失败版本。
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键数据对比
|
||||
|
||||
### 3.1 JRXML 实际内容
|
||||
|
||||
session `6d39a91e` 的 `current_jrxml`：
|
||||
- 长度：24391 字符
|
||||
- `<textField` 标签数：284（含自闭合标签）
|
||||
- 完整 textField 元素：142 个
|
||||
- `<staticText>` 元素：0 个
|
||||
- `<field>` 声明：63 个
|
||||
- pageWidth/pageHeight：595×842（A4）
|
||||
- namespace：无 ns0: 前缀（✅ 已消除）
|
||||
|
||||
### 3.2 OCR 数据
|
||||
|
||||
layout_schema：
|
||||
- total_rows: 34
|
||||
- total_columns: 1
|
||||
- 总文本元素：173 个
|
||||
|
||||
ocr_extraction_result：
|
||||
- total_elements: 173
|
||||
- fields 数组：18 个字段，全部是**发票模板字段**
|
||||
- 不含税金额、价税合计、单价、发票代码、发票号码、合计金额、开票日期、总金额、数量、日期、校验码、税率、税额、规格型号、货物名称、购买方名称、金额、销售方名称
|
||||
- 正确匹配率：3/18（17%）
|
||||
|
||||
### 3.3 评分数据
|
||||
|
||||
`_check_ocr_fidelity` 实际运行结果：
|
||||
|
||||
```python
|
||||
# element_coverage 计算
|
||||
textField_count = 142 # 完整元素（非标签数）
|
||||
staticText_count = 0
|
||||
total_jrxml_elements = 142
|
||||
ocr_text_count = 173
|
||||
element_coverage = min(142/173, 1.0) = 0.82
|
||||
|
||||
# field_coverage 计算
|
||||
jrxml_fields = {"print_date", "repair_number", ..., "vehicle_plate", ...} # 63 个英文字段
|
||||
ocr_field_names = {"发票代码", "发票号码", "合计金额", ...} # 18 个中文字段
|
||||
matched = jrxml_fields ∩ ocr_field_names = ∅
|
||||
field_coverage = 0/18 = 0.0
|
||||
|
||||
# score 计算
|
||||
score = 0.0 * 0.5 + 0.82 * 0.5 = 0.41
|
||||
```
|
||||
|
||||
**评分公式**（`nodes.py:1251`）：
|
||||
```python
|
||||
score = round(field_coverage * 0.5 + element_coverage * 0.5, 3)
|
||||
```
|
||||
|
||||
**降级条件**（`nodes.py:1294`）：
|
||||
```python
|
||||
if fidelity["score"] < 0.5:
|
||||
state["status"] = "fail"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 已确认的根因
|
||||
|
||||
### 根因 1 — 评分逻辑设计错误（P0）
|
||||
|
||||
**问题**：`field_coverage` 将英文字段名和中文字段名做交集比对，在普通生成场景下永远为 0。
|
||||
|
||||
**原因**：
|
||||
1. LLM 生成英文字段名（`print_date`、`vehicle_plate`）是正确的设计选择
|
||||
2. OCR 提取器硬套发票模板，提取中文字段名（`发票代码`、`合计金额`）
|
||||
3. 两者来自完全不同的命名体系，不可能匹配
|
||||
4. `field_coverage=0` 是**预期行为**，而非错误
|
||||
|
||||
**修复方向**：评分公式改为只依赖 `element_coverage`，`field_coverage` 作为信息提示而非降级条件。
|
||||
|
||||
### 根因 2 — OCR 字段提取器无文档类型区分（P0）
|
||||
|
||||
**问题**：`backend/ocr_extractor.py` 对所有单据使用同一套发票字段模板（14 个字段）。
|
||||
|
||||
**现象**：
|
||||
- 车历卡被当作发票处理
|
||||
- 手机号 `13516727312` 被 6 个字段复用（发票代码/校验码/价税合计/单价/税率/不含税金额）
|
||||
- 字段名错配：发票号码→"服务套餐"、总金额→"钣金"、数量→"零件等级"
|
||||
|
||||
### 根因 3 — namespace 修复指令是条件触发（P1）
|
||||
|
||||
**位置**：`prompts/correction.md` 第 11 行
|
||||
|
||||
**问题**：namespace 修复指令只在错误消息**包含 "namespace" 关键词**时才激活，是条件触发而非无条件指令。
|
||||
|
||||
**现象**：
|
||||
- ecd592 session 所有 5 次修正的实际错误类型是"字段未声明"（`字段 'u53d1_u7968...' 在表达式中使用但未声明`），**不包含 "namespace" 关键词**
|
||||
- 因此 namespace 修复指令从未被激活
|
||||
- ns0: 前缀在前两次修正中持续存在，直到第 3 次才被 LLM 自发消除
|
||||
- 最终 `current_jrxml`（ecd592）仍有 `<ns0:jasperReport>`
|
||||
|
||||
**修复方向**：
|
||||
- `prompts/correction.md`：改为无条件指令（检查 JRXML 是否包含 `ns0:`，而非依赖错误类型）
|
||||
- `prompts/initial_generation.md` + `skeleton_generation.md`：添加删除 ns0: 前缀的无条件指令
|
||||
|
||||
### 根因 4 — 正则 `\w+` 不支持中文（低优先级）
|
||||
|
||||
**位置**：`nodes.py:1211`
|
||||
```python
|
||||
jrxml_fields = set(re.findall(r'<field name="(\w+)"', jrxml))
|
||||
```
|
||||
|
||||
**问题**：`\w` 匹配 `[a-zA-Z0-9_]`，不匹配中文。如果 JRXML 使用中文字段名，正则返回 0 个匹配。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验证服务的角色
|
||||
|
||||
**文件**：`validation_service/main.py`
|
||||
|
||||
- XSD 验证：通过（✅）
|
||||
- 结构检查：字段声明一致性、SQL SELECT 存在性、pageWidth/pageHeight
|
||||
- **结论**：XSD 验证通过，`correct_jrxml` 的 ns0: 消除也生效——真正导致 fail 的是 OCR 保真度评分
|
||||
|
||||
---
|
||||
|
||||
## 6. 现象描述的矛盾点（需进一步排查）
|
||||
|
||||
session `6d39a91e` 中存在数字矛盾：
|
||||
|
||||
| 指标 | session 中的值 | 矛盾说明 |
|
||||
|---|---|---|
|
||||
| 最终 `current_jrxml` | 24391 字符，142 个 textField | 这是最后一次修正后保存的最终版本 |
|
||||
| `jrxml_versions[-1].jrxml` | 触发 fail 的真实版本 | 审计团队确认"6d39a91e has 0 text elements causing score=0.00" |
|
||||
| `error_msg` score | "0.00/1.0" | 对应 `jrxml_versions[-1]`，而非 `current_jrxml` |
|
||||
|
||||
**核心矛盾已解决**：`current_jrxml`（24391 字符）是**最终状态**（修正耗尽后最后一次保存的版本），而触发 5 次 fail 降级的是 `jrxml_versions` 中各版本的 JRXML——这些版本在修正循环中被逐步侵蚀，最终版本 `jrxml_versions[-1]` 只有 0 个文本元素（score=0.00）。
|
||||
|
||||
`fidelity-check-audit` 用 Python 分析的是最终保存的 `current_jrxml`（score=0.5），而 `validate-service-audit` 分析的是 `jrxml_versions[-1]`（score=0.00）。**两者分析的不是同一个时间点的 JRXML**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 相关文件清单
|
||||
|
||||
| 文件 | 职责 | 备注 |
|
||||
|---|---|---|
|
||||
| `agent/nodes.py:1171-1257` | `_check_ocr_fidelity` | 评分逻辑（有 bug） |
|
||||
| `agent/nodes.py:1260-1350` | `validate` 节点 | 调用保真度检查 |
|
||||
| `agent/nodes.py:1382-1461` | `correct_jrxml` | 修正循环 |
|
||||
| `backend/ocr_extractor.py` | OCR 字段提取 | 无文档类型区分 |
|
||||
| `prompts/correction.md` | 修正 prompt | namespace 触发受限 |
|
||||
| `validation_service/main.py` | 验证服务 | XSD 通过 |
|
||||
| `sessions/6d39a91e11c54f02bb70a62d856ea2d4.json` | 测试会话 | 主测试数据 |
|
||||
| `sessions/ecd5921838004ab3bc4a1ef6ebd673d1.json` | 历史会话 | namespace 问题参考 |
|
||||
Reference in New Issue
Block a user