AI Agent Engineer

AI Agent Engineer

图文音视频输入合同

6 min read

图文音视频输入合同

本节目标

不从某个 SDK 调用开始，而是先定义媒体对象、任务需要的证据、允许的处理和失败条件。

通用媒体清单

每个资产至少记录：

{
  "asset_id": "A-001",
  "declared_mime": "video/mp4",
  "detected_mime": "video/mp4",
  "bytes": 1250000,
  "sha256": "placeholder-not-a-real-file",
  "source": {
    "kind": "user_upload",
    "locator": "opaque-server-side-id",
    "revision": "record-at-runtime"
  },
  "authorization": {
    "purpose": "answer_this_request",
    "policy_version": "record-at-runtime"
  },
  "classification": "personal",
  "retention_policy": "record-at-runtime",
  "language_hint": "zh-CN",
  "duration_ms": 42000,
  "contains_personal_data": true
}

真实系统中 sha256 由完整字节流计算，不能使用占位值；它只绑定字节，不证明内容真实。本库项目只操作合成元数据。declared_mime 来自请求，detected_mime 应由可信解析器检测，两者冲突时拒绝或隔离。经过转码、裁剪或解包后应为派生物另记哈希、parent_asset_id 与 transform 版本，不能沿用原件哈希。

classification、允许处理位置与 authorization 必须由认证后的服务端资产记录、对象级授权/ACL 与策略求值，而不是相信文件名、EXIF、远程 URL 参数或调用方自己填写的 JSON；权限未知时，外发默认拒绝并要求人工或本地受限流程确认。

图像输入

关注尺寸、方向、颜色空间、透明度、多页容器、文字大小和感兴趣区域。任务可能需要：

  • 全图语义；
  • OCR 文字；
  • 区域框与对象关系；
  • 图表坐标/图例；
  • 原图与裁剪图的映射。

缩小图片能降成本，却可能让小字不可读。旋转/裁剪后要保存变换参数，才能把证据框映射回原图。

音频输入

关注采样率、声道、位深、时长、语言、说话人和时间轴。可产生转写、说话人片段、事件标签或声学特征。立体声合并、降采样和去噪会改变证据，必须记录。

转写不是所有任务的充分表示：判断警报声、音乐段落、情绪或说话人重叠需要保留音频线索。

视频输入

视频同时包含空间、时间和可能的音频。输入合同应说明：

  • 处理全片还是指定时间窗；
  • 抽帧策略与帧率；
  • 是否提取音轨与字幕；
  • 如何对齐 frame timestamp、音频时间和字幕；
  • 快速动作或画面文字是否需要更密采样；
  • 结论要引用哪段时间。

截至 2026-07-22，Google Gemini 视频理解文档仍公开了其 File API 的默认抽帧/音频处理与媒体分辨率说明，并明确这些速率可能变化。这是供应商处理快照，不是证据合同：关键任务不能把内部采样假定为无损，应自行预处理、记录采样参数，并在目标任务上验证。

文档与混合输入

PDF、PPT 或网页可能同时含文字、表格、图像和阅读顺序。保留页码、版面框、标题层级与附件关系。仅提取纯文本会丢失“这个数属于哪一列”。

选择输入方式

常见 API 提供内联字节、已上传文件、远程 URI 等方式。选择依据是大小、重复使用、数据驻留和保留期，不是方便程度。供应商限制会变化，应在适配器里配置，而不是散落在业务逻辑。

输入失败策略

  • 格式不支持：返回 supported_types，不自动伪装扩展名。
  • 资产过大/过长：要求分段或降采样，并说明可能损失。
  • 必需模态缺失：拒绝回答依赖该模态的结论。
  • 媒体损坏：隔离并记录解析错误。
  • 无授权个人数据：不发送到外部模型。
  • 数据分类或授权无法从可信记录确认：停止外发，返回 authorization_required 或升级人工；不要以调用方自报的“public”降级。
  • 多模态冲突：并列证据并升级人工，不静默选一个。

练习与自测

为“上传会议视频，产出带时间戳的决策清单”写输入合同。自测：只有自动字幕时能否判断屏幕共享的表格数值？远程 URL 可访问是否等于允许长期保存？

下一步

继续 融合架构直觉。

参考资料

Backlinks