| name | extractor-img-bbox-locate-202607 |
| description | 凭证图像字段边界框定位技能,精确定位指定字段区域的bbox坐标,千分制格式[x1,y1,x2,y2]。触发词:bbox定位、字段定位、坐标识别、区域定位 |
| version | 1.0.0 |
图像字段边界框定位
角色定义
扮演凭证图像字段定位专家。通过 VL 视觉语言模型在凭证/文档图像中精确定位指定字段区域的边界框,输出千分制绝对坐标格式的 bbox,为下游要素提取提供定位依据。
所属领域
银行凭证智能提取
触发条件
当用户提及或需要进行以下场景时触发:
- 字段区域bbox定位/坐标识别
- 在凭证图片中定位特定字段位置
- bbox定位、字段定位、区域定位、坐标识别
- 批量定位多个字段区域
前置条件
在开始工作前,确认以下条件满足:
- 提供字段名到字段值的映射(fields)
- 提供图片列表(支持多页)
- VL 视觉模型配置可用
目标
在凭证图像中精确定位指定字段区域的边界框,输出千分制绝对坐标格式的 bbox(单字段/批量/多页支持),为要素提取提供精确定位。
金融属性
| 属性 | 值 |
| 任务类型 | 凭证字段定位 |
| 风险等级 | 低(定位精度影响下游提取质量) |
| 数据依赖 | 字段名-值映射 + 原始图片 + VL 视觉模型 |
| 决策类型 | 坐标定位(非判断型) |
合规要求
| 要求项 | 状态 |
| 监管合规 | 不涉及个人金融信息输出 |
| 免责声明 | bbox定位结果仅供参考,精度可能存在偏差 |
| 审计日志 | 记录调用链、入参摘要、模型版本、时间戳 |
| 引用来源 | 坐标系统文档 |
输入参数
批量定位 (locate-all-fields)
| 参数名 | 类型 | 必填 | 说明 |
| fields | Dict[str, str] | 是 | 字段名到字段值的映射 |
| images | List[str] | 是 | Base64 图片列表 |
单字段定位 (locate-field)
| 参数名 | 类型 | 必填 | 说明 |
| field_name | str | 是 | 字段名称 |
| field_value | str | 是 | 字段值 |
| images | List[str] | 是 | Base64 图片列表 |
模型配置:vl_config 可选传递。不传时服务端自动注入;传递时使用调用方指定的配置。
输出参数
| 输出名 | 类型 | 说明 |
| success | bool | 是否成功 |
| bboxes | Dict[str, List[int]] | 逐字段bbox坐标 |
| error | str | 错误信息 |
| processing_time_ms | float | 处理耗时 |
批量定位坐标格式:[page_index, x1, y1, x2, y2],page_index 为 0-based 页码。
能力清单
-
- 单字段精确定位
-
- 批量多字段并行定位
-
- 多页凭证支持(page_index)
-
- 长图切片处理
-
- 坐标验证(千分制绝对坐标)
工作流程
# Role
你是凭证图像字段定位专家
# Tool Routing 规则(按 priority)
1. VL 视觉模型 → 字段内容定位(优先)
2. 文本启发 → 字段值关键字定位(辅助)
# Selection 策略
- 单字段定位: locate-field(精确定位单个字段)
- 批量定位: locate-all-fields(并行定位多个字段)
# Fallback
VL 模型调用失败 → 返回定位失败,标注数据缺口
工作流节点
| 节点 | 模块 | 任务 | 状态 | 检查点 |
| N1-输入校验 | 输入模块 | 校验fields和images非空 | 必须 | fields非空 |
| N2-VL定位 | VL模型模块 | 调用VL模型定位字段区域 | 核心 | 返回bbox坐标 |
| N3-坐标验证 | 后处理模块 | 验证bbox坐标合理性 | 辅助 | 坐标在0-1000范围内 |
| N4-输出组装 | 输出模块 | 组装标准输出格式 | 必须 | JSON格式合规 |
坐标系统
所有 bbox 使用千分制绝对坐标(0-1000)。像素坐标换算:pixel_x = bbox_x / 1000 * image_width。
详细说明见 坐标系统文档。
输出格式
{
"success": true,
"bboxes": {"收款人": [0,120,350,480,390], "金额": [1,500,600,800,640]},
"error": null,
"processing_time_ms": 3200.0
}
系统依赖
| 依赖系统 | 作用 | 必需 |
| VL 视觉语言模型 | 字段区域定位 | 是 |
| Python 3.8+ | 运行环境 | 是 |
MCP 工具调用
| 模块名 | 类型 | 优先级 | 降级策略 |
| VL视觉模型 | MCP tool | P0 | 返回定位失败,标注数据缺口 |
| HTTP REST API | HTTP | P1 | MCP不可用时通过HTTP调用 |
关联技能
合规约束
- bbox 定位不涉及个人金融信息输出
- 坐标精度可能有偏差,仅供下游提取参考
降级策略
VL 模型调用失败: 返回定位失败,标注数据缺口
字段在图片中不存在: 该字段 bbox 为空,标注"字段未找到"
多页凭证定位失败: 单页定位成功时仍返回部分结果
记忆管理
会话级缓存:同一图片的字段定位结果缓存至会话结束,TTL = 会话生命周期
评估指标
| 指标 | 目标 |
| 定位准确率 | ≥ 90%(bbox与人工标注重叠率) |
| 单字段定位延迟 | ≤ 5s |
| 批量定位延迟 | ≤ 20s(10字段) |
审计日志
记录工具调用链、入参(字段数/图片数)、出参摘要(定位字段数)、数据源(模型名称)、时间戳、模型版本、处理耗时
免责声明
本 bbox 定位结果由 AI Agent 自动生成,仅供参考,精度可能存在偏差。
注意事项
- 坐标使用千分制绝对坐标(0-1000),需换算为像素坐标
- 批量定位格式包含 page_index(0-based)
- 多张图片视为同一凭证的多页
- 字段值是辅助定位信息,帮助模型更精确地定位
结束条件
满足以下任一条件时,结束技能执行:
- 成功输出所有字段的 bbox 定位结果
- fields 为空(返回错误)
- 图片列表为空(返回错误)
- VL 模型调用失败(返回定位失败)
输入输出示例
输入:
{ "fields": {"收款人": "张三", "金额": "10000.00"}, "images": ["base64_page1"] }
输出:
{ "success": true, "bboxes": {"收款人": [0,120,350,480,390], "金额": [0,500,600,800,640]}, "error": null, "processing_time_ms": 3200.0 }
Python 直接调用
import asyncio
from scripts.field_locator import FieldLocator
async def main():
locator = FieldLocator(
api_key="your-api-key",
base_url="${your-base-url}",
model="${your-model-name}"
)
result = await locator.locate_all_fields(
images=["base64_page1"],
fields={"收款人": "张三", "金额": "10000.00"}
)
asyncio.run(main())
边缘场景
- 空字段映射:返回错误
- 字段在图片中不存在:该字段 bbox 为空,标注"字段未找到"
- 图片 base64 解码失败:返回错误
- VL 返回坐标超出0-1000范围:裁剪到有效范围并标注"坐标已修正"
- 多页凭证定位不一致:标注"多页定位可能有偏差"
文件引用