智能体工程 · 11m
附件收到了,提取结果也对应同一份原件吗?
读完能做的判断:按清单、真实字节、结构和人工观察逐层绑定来源。
多模态输入校验与来源对齐
⏱ 阅读约 28 分钟 · 动手实践另计
本章保留教学代码、路径说明与历史验证结论;完整实验工程和运行记录未随本站及公开仓库分发。命令用于说明调用方式,复现需自行准备对应实现、数据与环境。
一句话带走:先确认文件结构能读、观察绑定到当前来源,再把缺失和冲突交给人;文件完整与标签一致都不等于理解正确。
输入校验的检查项
用四层表和状态表解释坏 PNG 与截断 WAV 的结果。在临时副本中改标签,观察冲突与 pending。
衔接:扫描件 OCR 与人工复核、表格分块与证据保真、提示注入与工具边界演练。示例依赖 Python 与夹具文件。
1.把“收到了”拆成四层
三份附件有效,不能推出设备一定是 XR-204。接收成功与语义正确之间,还有来源对应和复核。
| 层次 | 本章能检查什么 | 仍不能推出什么 |
|---|---|---|
| 格式可读 | UTF-8、PNG 块、PCM WAV 参数与帧数 | 内容真实、图像已完整解码 |
| 来源能对应 | 当前字节 hash 与 manifest、观察来源 hash 一致 | 文件出自谁、hash 是签名 |
| 人工标签是否冲突 | reviewed 标签归并,pending 保留 | 标注一定符合附件内容 |
| 语义提取与复核 | 明确记为 not_performed | OCR、ASR、多模态模型准确率 |
本章没有 OCR、ASR 或多模态模型。型号由人写进 manifest,origin 固定为 manual_fixture;程序没有从像素中读字。
检查点 1:三份文件都通过,能说模型理解了设备吗?
不能。semantic_validation 仍为 not_performed。11i 的真实 OCR 候选也需人工复核。
2.先检查完整清单,再碰文件
inspect_bundle(root, manifest) 要求调用方拥有目录、父路径可信且处理期间无并发替换。root 必须是真实目录,拒符号链接与 Windows reparse;这不是恶意文件系统竞争防线。
manifest 只有 schema_version、request_id、inputs、observations。版本是严格整数 1,true 不算整数。ID 只用 ASCII 字母数字、下划线或连字符,长一至六十四;inputs 一至八项,observations 零至十六项。role、tool、tenant 等未知字段拒绝。
输入只有 input_id、modality、filename、sha256。modality 为 text/image/audio。filename 长一至一百二十八,只用 ASCII 字母数字与 ._-;禁止连续两点、前导/末尾点、盘符、子目录和 Windows 保留设备名。ID 和忽略大小写的文件名不得重复。
先验证全部 schema 再读文件,末条观察无效也不先读附件。load_manifest 拒绝 JSON 重复键,不能靠“后键覆盖前键”隐藏冲突。
检查点 2:为什么 manifest 里的 tenant 不能当可信身份?
清单是待校验内容,不能认证;调用方独立建立可信身份与目录所有权。
3.用真实字节检查结构
文件须非空、最多一 MiB、为普通文件,拒链接、reparse、多硬链接。读取错误只给固定 code,不带路径、原文或堆栈。SHA-256 匹配后再检查扩展名与结构。
| modality | 固定扩展名 | 结构约束 |
|---|---|---|
| text | .txt | 严格 UTF-8,无 NUL,最多两千字符 |
| image | .png | PNG 签名、块边界、CRC、IHDR/IEND,正尺寸且最多二千万像素 |
| audio | .wav | 未压缩 PCM,单声道、16bit、16000Hz,时长大于零且不超过三秒 |
PNG 复用 ocr_lab._read_image,只做容器结构检查,非完整像素解码。纯文本改名 .png、改坏 CRC 后重算 hash,都仍被解析拒绝。
Python 3.12 wave 读取实际帧并核对 header。截掉尾部后重算 hash 仍因帧不足返回 invalid_audio。tone.wav 是 440Hz 纯音,没有语音或转写。
检查点 3:后缀、hash 和内容结构各自解决什么?
后缀限制类别,hash 绑定字节,解析器检查结构;三者都不能证明型号真实。
4.人工观察必须绑在当前来源上
观察只有 observation_id、input_id、source_sha256、origin、review、field、value。观察 ID 唯一,输入 ID 存在,来源 hash 等于当前输入 hash;同输入同 field 最多一项。
origin 为 manual_fixture,review 为 pending/reviewed。field 为 device_model/error_code,value 分别匹配 XR-三位数字与 E两位数字;自由文字、布尔值拒绝。
文字与图片各有两条 reviewed 标签,纯音没有观察。人工标注不代表语义验证;换文件版本后,旧 source_sha256 不能继续挂在同一 ID 上。
receipt 只有 request_id 与输入 ID/modality/hash/bytes、字符数、尺寸或采样元数据,标为 untrusted_content;不含正文、像素、路径或完整 manifest。demo 另存公开演示 manifest。
检查点 4:观察已 reviewed,为什么仍不叫“真实正确”?
reviewed 只让人工标签参加归并;它不是程序重新看过附件的证明。
5.先看冲突,再看待复核
summary 分 field 归并 reviewed 观察,保留不同值与参与的观察 ID;不投票选多数,不按模态顺序选值。
| 字段条件 | 字段 status | 后续 |
|---|---|---|
| 多个不同 reviewed 值 | conflict | needs_clarification,交人澄清 |
| 没有 reviewed 值 | needs_review | 等人工观察与复核 |
| 只有一个 reviewed 值 | agreed_annotation | 人工标签一致,语义未验证 |
pending 即使值相同也保留 ID,并让相关 field 的 needs_review=true;因此 agreed_annotation 与待复核可以同时存在。
最终优先 needs_clarification > needs_review > ready_for_human_review,只表示可交人看。missing_modalities 按 text/image/audio 列缺项;缺 audio 不脑补标签,也不使已有归并失效。
检查点 5:两条型号都写 XR-204,能说两种模态语义一致吗?
只能说人工标签一致,可能一起抄错。比较语义仍需真实提取和独立复核。
6.运行一个可重复的小实验
以下是原示例父项目目录内的 PowerShell 命令,原主 venv 位于示例目录内。输出必须全新,旧空目录也拒绝;重跑请换 reader-02。
examples/knowledge-assistant/.venv/Scripts/python.exe -S -X utf8 examples/knowledge-assistant/multimodal_lab.py demo --output examples/knowledge-assistant/.runtime/multimodal-reader-01
示例使用 Python 3.12,工作目录为 knowledge-assistant;-S 禁用 site 包,不需 Pillow。
python -S -X utf8 multimodal_lab.py demo --output .runtime/multimodal-reader-01
Get-Content .runtime/multimodal-reader-01/summary.json
省略 --output 会在模块 .runtime 创建 UTC 唯一目录。demo 修改 TemporaryDirectory 副本,只保存 summary.json 和公开 manifest.json。
实际 receipt:文字 144 bytes;PNG 1121 bytes、480×160;WAV 32044 bytes、16000 帧、1 秒。已运行摘要(examples/knowledge-assistant/validation/multimodal-demo-20261012T0900Z/summary.json)保存环境、参数、代码/夹具前后 hash 与逐项结果。
检查点 6:重跑为何拒绝旧空目录?
分开保存新旧结果,保留失败。退出码零只代表机械验收通过。
7.读逐项记录,不只读 pass
十七个场景当前执行十六项;符号链接创建权限不足跳过,真实硬链接拒绝已执行。scenarios 留 expected/observed/passed 与可适用的输入 hash、字节数。
| 记录组 | 找到的行为 |
|---|---|
| 有效、缺 audio、人工标签一致 | 可供人复核,缺项仍明确列出 |
| 无观察、pending、冲突 | 需要复核或澄清,不自动选答案 |
| 旧 hash、未知输入、重复观察 | 来源或 schema 拒绝 |
| 格式伪装、坏 CRC、截断 WAV | 真实解析拒绝 |
| ../路径、重复 JSON 键、旧输出目录 | 边界固定拒绝 |
坏媒体重算 hash 并同步观察绑定,确保拒绝来自真实解析。前后 fixture_sha256 相等证明本次未改夹具,不能证明防住所有文件系统竞争。
预计输入、JSON、IO 错误给固定 JSON 与退出码 2;机械验收失败或内部故障为 1。冲突符合预期就算机械通过,不能当识别质量分数。
检查点 7:invalid_audio 是否就是模型听错了?
不是。拒绝来自 WAV 参数或帧完整性;没有语音模型,也没有转写标签。
8.只改临时副本,观察状态变化
在自备示例目录 knowledge-assistant 中保存为 try_multimodal.py,用 python -S -X utf8 try_multimodal.py 运行,核对 conflict 与 pending。仅改临时副本。
import json
from pathlib import Path
import shutil
import tempfile
from multimodal_lab import inspect_bundle, load_manifest
source = Path('fixtures/multimodal')
manifest = load_manifest((source / 'manifest.json').read_text('utf-8'))
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp) / 'media'
shutil.copytree(source, root)
manifest['observations'][2]['value'] = 'XR-999'
manifest['observations'][1]['review'] = 'pending'
result = inspect_bundle(root, manifest)
print(json.dumps(result['summary'], indent=2))
预期 needs_clarification,型号保留两个值,pending 保留 text-error。删掉冲突观察后重调,仍为 needs_review;澄清冲突没有消除待复核。
走神救援:只看 semantic_validation、bad_png_crc、pending_label,分别说出“没做语义验证”“坏文件解析失败”“待复核不能丢”。
检查点 8:本章的结果可以直接入库或执行工具吗?
不可以。接口不产生答案、工具、Identity 或自动入库;真实提取与最终复核需要后续证据。