CheckByAI：AI 物流票据智能解析平台 — Coze + LangGraph 双引擎 + PaddleOCR

项目背景

CheckByAI 是一个面向物流行业的智能票据解析平台。它的核心场景是：物流公司每天收到大量 Excel 运单数据，每单附带装卸货磅单图片，需要人工核对图片中的毛重/皮重/净重与 Excel 填写数据是否一致——这是典型的重复性高强度劳动。

CheckByAI 的目标就是用 AI 替代这个人工审核流程：上传 Excel → 自动解析 → 下载磅单图片 → PaddleOCR 识别 → LLM 重量一致性校验 → 人工复核兜底。

系统架构

项目采用 Spring Boot 3.2.2 后端 + Vue 3 前端 + Python LangGraph 多智能体 的混合架构：

┌─ 用户上传 Excel ─────────────────────────────────────────┐ ↓ ┌─ Spring Boot 后端 ──────────────────────────────────────────┐ │ Auth / Task / Callback / Review / AI Chat │ └────────┬──────────────┬───────────────┬───────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─ RabbitMQ ─┐ ┌─ Coze 工作流 ─┐ ┌─ LangGraph 多智能体 ─┐ │ 异步队列 │ │ (云端批量审核) │ │ (本地 OCR+LLM 校验) │ │ 任务分发 │ │ │ │ │ └─────────────┘ └────────────────┘ └──────────┬───────────┘ │ ▼ ┌─ PaddleOCR ─┐ │ 图片文字识别 │ └──────────────┘

AI 引擎双通道

这是项目最大的技术亮点——双 AI 引擎互补：

1. Coze 工作流（主流程）：通过 Coze API 调用预定义的工作流（workflow-id: 7595443144305852425），处理大批量 Excel 数据审核。Coze 工作流在云端执行，适合高吞吐、标准化的审核任务。

2. LangGraph 多智能体（本地 Python 服务）：基于 LangGraph 构建的 4 节点多 Agent 协作系统，本地执行。适合需要 PaddleOCR 图片识别的场景，数据处理不出网。

LangGraph 多智能体工作流

这是项目中最有技术深度的部分——一个完整的 LangGraph 多 Agent 协作流水线：

节点编排

Coordinator → ExcelAgent → Coordinator → OcrAgent → Coordinator → ThinkAgent → Coordinator → END

各节点职责

节点	职责	技术
CoordinatorAgent	协调员，状态路由与决策分发	LangGraph StateGraph
ExcelAgent	解析 Excel 文件，提取物流单据数据（发货/收货、装卸货图片 URL）	pandas
OcrAgent	下载图片链接，调用 PaddleOCR 进行文字识别	PaddleOCR, requests
ThinkAgent	调用 DeepSeek LLM，执行重量一致性校验分析	langchain_openai

关键代码片段

from langgraph.graph import StateGraph, END

class AgentState(TypedDict):
    records: List[Dict[str, Any]]
    current_index: int
    current_phase: str  # excel | ocr | think | done
    results: List[Dict[str, Any]]
    errors: List[str]

workflow = StateGraph(AgentState)
workflow.add_node("coordinator", coordinator_node)
workflow.add_node("excel_agent", excel_agent_node)
workflow.add_node("ocr_agent", ocr_agent_node)
workflow.add_node("think_agent", think_agent_node)

workflow.set_entry_point("coordinator")
workflow.add_conditional_edges(
    "coordinator", router,
    {"excel": "excel_agent", "ocr": "ocr_agent", "think": "think_agent", "done": END}
)
workflow.add_edge("excel_agent", "coordinator")
workflow.add_edge("ocr_agent", "coordinator")
workflow.add_edge("think_agent", "coordinator")

PaddleOCR 实战

from paddleocr import PaddleOCR

ocr = PaddleOCR(device="cpu")
res = ocr.predict(img_path)
text_lines = extract_text_lines_from_ocr_result(res)

OCR 处理的踩坑记录（代码中有详细注释）：

1. ndarray JSON 序列化失败：PaddleOCR 返回的结果中包含 numpy 类型，直接 json.dumps 会报错。解决方案：自定义 _json_default 函数统一处理 numpy ndarray/标量→Python 原生类型。
2. OCRResult 类型兼容性：不同版本的 PaddleOCR 返回的对象类型不同（dict vs OCRResult 对象）。解决方案：通过 hasattr 判断对象类型，分叉处理。
3. 图片文件名碰撞：多行数据的图片在同一目录下载，清空目录时删掉了还未处理的图片。解决方案：每行使用独立的临时子目录。

重量校验逻辑

ThinkAgent 的核心 Prompt 要求：

• 关键字段完整性检查：Excel 必须装货重量/卸货重量；OCR 必须毛重/皮重或净重
• 重量逻辑合规性验证：毛重大于皮重；净重大于 0；净重=毛重-皮重，允许 ±0.01 吨误差
• 重量一致性判定：偏差 5%~10% 标记异常；3‰~5% 标记提醒
• 单位与格式统一：公斤→吨 (/1000)

Spring Boot 后端核心模块

模块	说明
WorkflowService	Coze 工作流集成，批量提交 Excel 数据（每批 8 行），接收回调结果
AiAssistantService	LangChain4j + DeepSeek 的 AI 对话助手
RagService	RAG 检索增强生成，文档向量化（Milvus）与语义检索
TaskReviewService	人工审核工作台，审核状态流转与风险等级标注
CallbackService	Coze 工作流回调处理，分批回调数据聚合
TaskProcessConsumer	RabbitMQ 异步消费者，解耦任务提交与处理
ExcelService	Excel 文件解析与数据提取
DocumentParserService	文档解析（TXT/PDF/Word），支持多格式向量化

消息队列与幂等性

项目采用 RabbitMQ 做异步任务分发，Redis 做三层幂等控制：

1. 用户任务去重：SETNX userId + contentHash，10 分钟过期
2. 消息消费去重：SETNX messageId，24 小时过期
3. 回调处理去重：SETNX callbackTaskId，防止 Coze 重复回调

前端组件

前端基于 Vue 3，核心组件：FileUpload（Excel 上传）、Dashboard（任务列表与进度）、ReviewWorkbench（人工审核工作台，支持低/中/高/严重四级风险标注）、AiAssistant（RAG 对话）、DataMonitor（MySQL 监控面板）、LogisticsManagement（物流订单管理）。

技术栈

后端：Spring Boot 3.2.2, Spring WebFlux, MyBatis-Plus, MySQL 8.0+, Redis, RabbitMQ AI：Coze 工作流 (workflow-id: 7595443144305852425), LangGraph (Python), PaddleOCR, DeepSeek Chat, Milvus 前端：Vue 3 + Vue Router + Axios + Vite 部署：Nginx 反向代理, JDK 17+, Python 3.10+

踩坑记录

1. PaddleOCR 序列化坑：numpy ndarray 不能被 json.dumps 直接序列化，导致 LangGraph 节点间传输出错
2. OCR 结果类型不统一：不同版本返回的对象类型不同（dict 或 OCRResult 对象）
3. 图片文件名碰撞：多行数据图片在同一目录下载互相覆盖
4. Excel 三份数据长度不一致：base/pull/push 行数不一致导致数据错位
5. RabbitMQ 手动确认：自动确认模式下抛异常导致消息被跳过

总结

CheckByAI 是我做过的最复杂的全栈 + AI 项目。它不是一个简单的"任务分发平台"，而是一个专门为物流行业设计的智能票据解析系统。最大的技术亮点是双 AI 引擎互补设计——Coze 做云端高吞吐批量审核，LangGraph 做本地敏感数据处理的 OCR + 校验。四个 LangGraph 节点的编排（Coordinator→Excel→OCR→Think）完整覆盖了"数据读取→图片识别→LLM 分析"的自动化管线，PaddleOCR 的踩坑与修复也为后续其他 AI 项目积累了宝贵经验。