extractor-img-bbox-locate-202607

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 页码。

能力清单

• 1. 单字段精确定位
• 2. 批量多字段并行定位
• 3. 多页凭证支持（page_index）
• 4. 长图切片处理
• 5. 坐标验证（千分制绝对坐标）

工作流程

# 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进行字段提取）
• 提示词生成（冷启动）

合规约束

1. bbox 定位不涉及个人金融信息输出
2. 坐标精度可能有偏差，仅供下游提取参考

降级策略

VL 模型调用失败: 返回定位失败，标注数据缺口 字段在图片中不存在: 该字段 bbox 为空，标注"字段未找到" 多页凭证定位失败: 单页定位成功时仍返回部分结果

记忆管理

会话级缓存：同一图片的字段定位结果缓存至会话结束，TTL = 会话生命周期

评估指标

| 指标 | 目标 | | 定位准确率 | ≥ 90%（bbox与人工标注重叠率） | | 单字段定位延迟 | ≤ 5s | | 批量定位延迟 | ≤ 20s（10字段） |

审计日志

记录工具调用链、入参（字段数/图片数）、出参摘要（定位字段数）、数据源（模型名称）、时间戳、模型版本、处理耗时

免责声明

本 bbox 定位结果由 AI Agent 自动生成，仅供参考，精度可能存在偏差。

注意事项

• 坐标使用千分制绝对坐标（0-1000），需换算为像素坐标
• 批量定位格式包含 page_index（0-based）
• 多张图片视为同一凭证的多页
• 字段值是辅助定位信息，帮助模型更精确地定位

结束条件

满足以下任一条件时，结束技能执行：

1. 成功输出所有字段的 bbox 定位结果
2. fields 为空（返回错误）
3. 图片列表为空（返回错误）
4. 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范围：裁剪到有效范围并标注"坐标已修正"
• 多页凭证定位不一致：标注"多页定位可能有偏差"

文件引用

• 定位脚本：scripts/field_locator.py
• HTTP API 示例：references/http-api.md
• 处理流程详解：references/processing-flow.md
• 坐标系统详解：references/coordinate-system.md