单证处理
概述
单证处理是货代智能 Agent 的核心能力之一，通过 document_extraction 智能体类型实现 PDF 运输单证的自动识别和结构化提取。
当前支持的单证类型：
- 海运订舱确认书 (Booking Confirmation)
- 更多单证类型持续扩展中
架构设计
document_extraction 智能体基于 LangGraph 多节点工作流实现，处理流程如下：
flowchart LR
Upload[上传 PDF] --> Ingest[pdf_ingest]
Ingest --> Process[pdf_processor]
Process --> Extract[data_extraction]
Extract --> Validate[validation]
Validate --> Report[pdf_reporter]
Extract -.->|重试| Process
Validate -.->|重试| Process核心节点说明
| 节点 | 功能 | 说明 |
|---|---|---|
pdf_ingest |
初始化 | 创建上下文消息和元数据 |
pdf_processor |
PDF 转图片 | 使用 PyMuPDF 将 PDF 页面渲染为 base64 PNG |
data_extraction |
LLM 提取 | 使用视觉语言模型提取结构化数据 |
validation |
数据校验 | 验证必填字段和格式 |
pdf_reporter |
生成报告 | 汇总提取结果 |
重试机制
- 全局重试计数器：最多 3 次（可配置）
- LLM 调用重试：每节点最多 3 次，指数退避（2s, 4s, 8s）
- 结构化输出失败自动回退到 JSON 解析模式
数据模型
提取结果使用 ShippingBookingData Pydantic 模型，包含 100+ 个字段：
| 字段类别 | 示例字段 |
|---|---|
| 订舱信息 | booking_number, transport_mode |
| 各方信息 | shipper_information, consignee_information, notify_information |
| 港口信息 | port_of_loading, port_of_discharge, destination |
| 船舶信息 | carrier, vessel, voyage |
| 集装箱 | container_information (尺寸/数量), container_mode |
| 货物 | cargo_type, commodity, total_weight, total_volume |
| 日期 | etd, eta, cargo_ready_date |
| 合规 | ams, isf, aci, ics2 |
| 字段检测 | field_detections (含 bbox 坐标) |
API 接口
创建提取任务
POST /agents/{agent_id}/extraction-jobs
Content-Type: multipart/form-data
source_file: <PDF 文件>
查询任务列表
GET /agents/{agent_id}/extraction-jobs
获取任务详情（含下载链接）
GET /agents/{agent_id}/extraction-jobs/{job_id}
删除任务
DELETE /agents/{agent_id}/extraction-jobs/{job_id}
配置
[agent_types.document_extraction]
default_model = "qwen3-vl-plus-2025-12-19"
default_provider = "dashscope"
max_retries = 3
max_pages = 20
dpi = 300
temp_dir = "/tmp/doc_extraction_workdir"
文件存储路径
| 文件类型 | MinIO 路径 |
|---|---|
| 源 PDF | document_extraction/{agent_id}/{job_id}/source/{filename} |
| 结果 JSON | document_extraction/{agent_id}/{job_id}/output/result.json |