| 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范围：裁剪到有效范围并标注"坐标已修正"
- 多页凭证定位不一致：标注"多页定位可能有偏差"
文件引用
