panda/agent_jrxml
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: OCR字段提取集成修复 + 会话切换无限循环修复 + 一键启动脚本

Browse Source 
- process_input 传入17个默认中文字段（修复空列表导致零字段提取）
- OCR提取结果自动注入 LLM 上下文
- save_session_node/load_session_node 持久化 session_id（修复切换会话无限 rerun）
- app.py 会话切换后显式设置 session_id（纵深防御）
- 新增 start.bat / stop.bat 一键启动/停止脚本
- 更新 CLAUDE.md + CODE_GUIDE.md 文档

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
panda
2026-05-20 10:17:05 +08:00
parent c9f003e1b7
commit da79640259
6 changed files with 166 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CLAUDE.md
+7
View File
@@ -8,6 +8,9 @@
## 启动命令
**方式 1 — 一键启动（Windows）**：双击 `start.bat`，自动打开两个窗口分别运行验证服务和 UI。停止用 `stop.bat`。
**方式 2 — 手动启动**：
```bash
# 终端 1 — 验证服务（必须先启动）
python -m uvicorn validation_service.main:app --port 8001 --host 0.0.0.0
@@ -57,6 +60,7 @@ agent/graph.py (LangGraph 状态机)
├──► backend/error_kb.py 错误知识库: 指纹去重 + ChromaDB 持久化
├──► backend/file_parser.py 文件解析: PDF/DOCX/图片/文本
├──► backend/layout_analyzer.py A4布局分析: OCR + 行分组 + JRXML行匹配
├──► backend/ocr_extractor.py OCR字段提取: 两阶段4策略精确提取单据字段值
├──► backend/validation.py HTTP 客户端: POST /validate
├──► backend/session.py 会话持久化: JSON 文件 CRUD
└──► validation_service/ 独立 FastAPI: 结构检查 + XSD 校验
@@ -78,6 +82,7 @@ agent/graph.py (LangGraph 状态机)
| `backend/error_kb.py` | ErrorKB — 错误指纹去重 + ChromaDB 持久化 + 语义检索 | 中 |
| `backend/file_parser.py` | 文件解析: PDF/DOCX/图片(EasyOCR→PaddleOCR回退)/文本 | 中 |
| `backend/layout_analyzer.py` | A4模板分析: 比例检测/EasyOCR→PaddleOCR元素提取/行分组/JRXML行匹配 | 中 |
| `backend/ocr_extractor.py` | OCR单据字段提取: 两阶段流水线 + 4种策略(精确KV/模糊KV/正则/表格) + 17个默认中文字段 | 中 |
| `backend/embeddings.py` | 嵌入模型工厂 (HuggingFace/OpenAI) | 低 |
| `backend/validation.py` | 验证服务 HTTP 客户端 | 低 |
| `backend/session.py` | 会话 JSON 文件 CRUD | 低 |
@@ -166,6 +171,8 @@ agent/graph.py (LangGraph 状态机)
- **XSD 校验可选**: 需要 `validation_service/schemas/jasperreport_7_0_6.xsd` 存在。
- **rag 子模块**: 内部有独立的管线脚本（`batch_chunker.py` → `embed_chunks.py` → `import_to_chroma.py`），通常不需要在主项目中运行。
- **OCR 引擎**: 优先使用 EasyOCR（Windows 兼容性更好，`pip install easyocr`），回退 PaddleOCR。两者均未安装时仅返回图片元信息，建议至少安装 EasyOCR。
- **OCR 字段提取**: `process_input` 自动检测上传图片，调用 `OcrExtractor` 提取 17 个常见中文字段（发票代码/号码/金额/日期等），提取结果自动注入 LLM 上下文。
- **会话持久化**: `session_id` 现已包含在 `save_session_node` 的持久化字段中，避免切换会话时因 `session_id` 丢失导致的无限 rerun bug。
- **MAX_RETRY**: 默认 3 次。重试耗尽后 `pending_failure_context` 记录失败信息，下次用户输入时自动注入。
- **验证最小内容检查**: 验证服务额外检查至少 1 个 `<band>` + 1 个 `<textField>` 或 `<staticText>`，拦截空壳 JRXML。
- **torchvision**: `transformers` 库的懒加载需要 `torchvision`，已作为依赖安装。
CODE_GUIDE.md
+100 -3
View File
@@ -18,6 +18,7 @@
10. [错误自增长知识库](#10-错误自增长知识库)
11. [布局分析器](#11-布局分析器)
12. [文件解析器](#12-文件解析器)
12b. [OCR 单据字段提取器](#12b-ocr-单据字段提取器)
13. [验证服务](#13-验证服务)
14. [会话持久化](#14-会话持久化)
15. [Streamlit UI：apppy](#15-streamlit-uiapppy)
@@ -52,8 +53,9 @@ cp .env.example .env
### 启动
需要**两个终端**同时运行：
**一键启动（推荐）**：双击 `start.bat`，自动打开两个窗口分别运行验证服务和 UI。停止用 `stop.bat`。
**手动启动**（需要两个终端）：
```bash
# 终端 1 — 验证服务（必须先启动）
python -m uvicorn validation_service.main:app --port 8001 --host 0.0.0.0
@@ -124,6 +126,9 @@ streamlit run app.py --server.port 8501
│layout_ │
│analyzer │
│.py │
│ocr_ │
│extractor │
│.py │
│file_ │
│parser.py │
│validation│
@@ -188,6 +193,10 @@ class AgentState(TypedDict, total=False):
# ── 失败上下文传递 ──
pending_failure_context: dict # 重试耗尽后暂存失败信息，下次用户输入时自动注入
# ── OCR 单据字段提取 ──
ocr_extraction_result: dict # OCR字段提取结果（来自 OcrExtractor）
uploaded_file_path: str # 上传图片的临时路径
```
**数据流向**：每个节点函数接收 `state`，修改后返回 `state`（实际上是 dict）。LangGraph 自动合并返回值到全局状态。
@@ -314,7 +323,7 @@ def build_graph():
`agent/nodes.py` 是系统的"血肉"，每个节点实现一个处理步骤。
### 6.1 process_input — 记录输入 + 自动注入失败上下文
### 6.1 process_input — 记录输入 + 自动注入失败上下文 + OCR 字段提取
```python
def process_input(state: AgentState) -> Dict:
@@ -335,12 +344,36 @@ def process_input(state: AgentState) -> Dict:
# 追加到工作历史（含注入后的内容）
state["conversation_history"].append({"role": "user", "content": user_input})
# OCR 单据字段精确提取（处理上传的图片文件）
uploaded_path = state.get("uploaded_file_path", "")
if uploaded_path and Path(uploaded_path).is_file():
if suffix in (".png", ".jpg", ".jpeg", ".bmp", ".webp"):
extractor = OcrExtractor()
ocr_result = extractor.extract(uploaded_path, [
"发票代码", "发票号码", "开票日期", "合计金额", "校验码",
"价税合计", "总金额", "日期", "金额", "数量", "单价", "税率",
"购买方名称", "销售方名称", "货物名称", "规格型号",
"不含税金额", "税额",
])
if ocr_result.get("ocr_available"):
state["ocr_extraction_result"] = ocr_result
# 将提取到的字段注入 LLM 上下文
non_empty = [f for f in extracted_fields if f.get("field_value")]
if non_empty:
ocr_context = "[OCR 单据字段提取结果]\n" + ...
user_input = f"{ocr_context}\n\n{user_input}"
# 重置本轮字段
state["retry_count"] = 0
state["user_modification_request"] = user_input
```
**注意**：维护了两个对话历史 — `conversation_history` 可能被压缩，`full_conversation_history` 永不丢失。失败上下文注入仅影响工作历史，全量历史保留原始消息。
**注意**：
- 维护了两个对话历史 — `conversation_history` 可能被压缩，`full_conversation_history` 永不丢失
- 失败上下文注入仅影响工作历史，全量历史保留原始消息
- OCR 字段提取在 `process_input` 阶段自动执行，提取到的字段值同时存入 `ocr_extraction_result` 和注入到 `user_input` 前缀供 LLM 使用
- `session_id` 已包含在持久化字段中，避免切换会话时的无限 rerun bug
### 6.2 manage_context — 上下文压缩
@@ -763,6 +796,66 @@ def parse_file(file_path, file_type="") -> dict:
---
## 12b. OCR 单据字段提取器
`backend/ocr_extractor.py` — 两阶段精确提取单据图像中的字段值。
### 12b.1 数据模型
```python
@dataclass
class OcrTextElement: # OCR 文本元素，含精确坐标
text: str
x_min, y_min, x_max, y_max: float
confidence: float = 1.0
# 属性: center_x, center_y, width, height, bbox
@dataclass
class ExtractedField: # 提取的字段结果
field_name: str
field_value: str
bbox: list[float]
confidence: float
extraction_method: str # exact_match / kv_pair / regex / table_match / none
@dataclass
class ExtractionResult: # 完整提取结果
file_path: str
image_size: tuple
fields: list[ExtractedField]
all_elements: list[OcrTextElement]
errors: list[str]
ocr_available: bool
```
### 12b.2 两阶段流水线
**阶段1 — 文档分析** (`_analyze_document`):
- 加载图片 → `_ocr_elements_enhanced()` → EasyOCR(ch_sim+en) → PaddleOCR 回退
- 按 `OCR_CONFIDENCE_THRESHOLD` (默认 0.5) 过滤低置信度元素
- 返回按 (y, x) 排序的 `OcrTextElement` 列表
**阶段2 — 字段提取** (`_extract_field`):
按优先级尝试 4 种策略：
1. **精确键值对** (`_exact_kv_match`, conf=0.95/0.85): 同一元素中 "字段名: 值" 模式
2. **模糊键值对** (`_fuzzy_kv_match`, conf=0.75/0.60): 相邻元素匹配，同行/下一行搜索
3. **正则模式** (`_regex_match`, conf=0.70/0.60): 12 种预定义模式 (发票代码/号码/金额/日期等)
4. **表格结构** (`_table_match`, conf=0.55): 行列分组 + 表头匹配
### 12b.3 集成点
- **`process_input`**: 检测到上传图片后自动调用，传入 17 个默认中文字段
- **结果注入**: 提取到的字段值自动拼入 `user_input` 前缀（`[OCR 单据字段提取结果]`）
- **结果展示**: `app.py` 总结卡片中 "🔍 OCR 单据字段提取结果" 折叠区
### 12b.4 回退能力
- 任一 OCR 引擎不可用时静默回退，不影响主流程
- 两种复用路径: `extract()` (全流程) 和 `extract_from_layout_result()` (复用已有布局分析)
- 便捷函数: `extract_ocr_fields()`, `extract_from_layout()`
---
## 13. 验证服务
`validation_service/main.py` — 独立的 FastAPI 进程，提供 JRXML 验证。
@@ -1168,10 +1261,14 @@ st.json(state) # 打印完整状态（调试用，记得删除）
| `backend/embeddings.py` | ~49 | 嵌入模型工厂 |
| `backend/file_parser.py` | ~194 | 多格式文件解析 |
| `backend/layout_analyzer.py` | ~495 | A4 模板布局分析 |
| `backend/ocr_extractor.py` | ~797 | OCR 单据字段精确提取 (两阶段+4策略) |
| `backend/validation.py` | ~27 | 验证服务 HTTP 客户端 |
| `backend/session.py` | ~113 | 会话 JSON CRUD |
| `prompts/loader.py` | ~54 | Prompt 热重载 |
| `prompts/*.md` (7 个) | — | Prompt 模板 |
| `validation_service/main.py` | ~130 | FastAPI 验证服务 |
| `tests/test_ocr_extraction.py` | ~543 | OCR 提取器单元测试 (48 项) |
| `start.bat` | — | 一键启动脚本 (Windows) |
| `stop.bat` | — | 一键停止脚本 (Windows) |
| `.env.example` | ~62 | 配置模板 |
| `requirements.txt` | ~32 | Python 依赖 |
agent/nodes.py
+23 -3
View File
@@ -123,7 +123,13 @@ def process_input(state: AgentState) -> Dict:
try:
from backend.ocr_extractor import OcrExtractor
extractor = OcrExtractor()
ocr_result = extractor.extract(uploaded_path, [])
default_fields = [
"发票代码", "发票号码", "开票日期", "合计金额", "校验码",
"价税合计", "总金额", "日期", "金额", "数量", "单价", "税率",
"购买方名称", "销售方名称", "货物名称", "规格型号",
"不含税金额", "税额",
]
ocr_result = extractor.extract(uploaded_path, default_fields)
if ocr_result.get("ocr_available"):
state["ocr_extraction_result"] = ocr_result
_node_log.info(
@@ -134,6 +140,20 @@ def process_input(state: AgentState) -> Dict:
"fields": len(ocr_result.get("fields", [])),
},
)
# 将提取到的字段注入到对话上下文，供 LLM 使用
extracted_fields = ocr_result.get("fields", [])
non_empty = [f for f in extracted_fields if f.get("field_value")]
if non_empty:
lines = ["[OCR 单据字段提取结果]"]
for f in non_empty:
lines.append(
f"- {f['field_name']}: {f['field_value']}"
f"（置信度: {f['confidence']:.0%}, 方法: {f['extraction_method']}）"
)
ocr_context = "\n".join(lines)
user_input = f"{ocr_context}\n\n{user_input}"
# 同时更新工作对话历史中的最后一条
conv_history[-1]["content"] = user_input
except Exception as e:
_node_log.warning(f"OCR 字段提取失败: {e}")
state["ocr_extraction_result"] = {"error": str(e)}
@@ -357,7 +377,7 @@ def load_session_node(state: AgentState) -> Dict:
if data and data.get("agent_state"):
saved = data["agent_state"]
# 恢复核心字段（不覆盖当前请求的 user_input / stage）
for key in ("conversation_history", "full_conversation_history",
for key in ("session_id", "conversation_history", "full_conversation_history",
"current_jrxml", "final_jrxml", "compressed_history",
"session_name", "created_at", "history_states"):
if key in saved and key not in ("user_input", "stage"):
@@ -379,7 +399,7 @@ def save_session_node(state: AgentState) -> Dict:
try:
from backend.session import save_session
persistable = {}
for key in ("conversation_history", "full_conversation_history",
for key in ("session_id", "conversation_history", "full_conversation_history",
"current_jrxml", "final_jrxml", "compressed_history",
"status", "error_msg", "history_states"):
if key in state:
app.py
+1
View File
@@ -408,6 +408,7 @@ with st.sidebar:
"切换会话",
extra={"from_session": current_session_id, "to_session": new_sid},
)
data["agent_state"]["session_id"] = new_sid
st.session_state.agent_state = data["agent_state"]
st.session_state.messages = []
st.rerun()
start.bat
+27
View File
@@ -0,0 +1,27 @@
@echo off
echo ============================================
echo JRXML 代理 - 全自动启动 (验证服务 + UI)
echo ============================================
set STREAMLIT_SERVER_HEADLESS=true
echo.
echo [1/2] 启动验证服务 (端口 8001)...
start "JRXML 验证服务" cmd /c "cd /d %~dp0 && .venv\Scripts\python -m uvicorn validation_service.main:app --port 8001 --host 0.0.0.0"
timeout /t 3 /nobreak >nul
echo [2/2] 启动 Streamlit UI (端口 8501)...
start "JRXML UI" cmd /c "cd /d %~dp0 && .venv\Scripts\streamlit run app.py --server.port 8501"
timeout /t 3 /nobreak >nul
echo.
echo ============================================
echo 启动完成
echo 验证服务: http://localhost:8001
echo UI 界面: http://localhost:8501
echo ============================================
echo.
echo 关闭此窗口不会停止服务。关闭服务窗口或运行 stop.bat 停止。
pause
stop.bat
+8
View File
@@ -0,0 +1,8 @@
@echo off
echo 正在停止 JRXML 代理服务...
taskkill /fi "WINDOWTITLE eq JRXML 验证服务*" /f 2>nul
taskkill /fi "WINDOWTITLE eq JRXML UI*" /f 2>nul
echo 已停止。
pause