图像、音频和视频

Oloproof 评估接收或生成图像、音频和视频的系统，而这些文件从不离开你的系统存放它们的地方。运行按引用记录每个文件；确定性检查度量文件的字节；评判模型可以看到图像、视频帧和音频；工作台在每个结论旁边显示它们。教程会在一个可运行的示例上用图像逐步演练。

记录媒体

你的系统用 current_case().media(...) 记录一个用例接收或生成的文件，每次调用记录为一个 media/v1 产物：

from oloproof import current_case, media_file, system

@system(name="captioner", version="v2", records=("media/v1",))
def caption(case):
    image = render(case["prompt"])            # your system writes its own file
    current_case().media([
        media_file(case["photo"], role="input"),
        media_file(image),                    # role="output" by default
    ])
    return {"caption": describe(image)}

在 oloproof.yaml 中，可调用对象系统声明 records: [media/v1]。每一项包含：

media_file(path) 根据一个本地文件填写这些字段。不会有任何内容被复制到 Oloproof 的存储中。之后读取该文件的一切，无论是检查、评判模型还是工作台，都通过 read_media 读取，它会拒绝大小或 sha256 与记录不符的字节：内容发生变化会停止运行，文件已不存在则该用例为缺失。只要你保留一次运行，就原样保留它的文件；把每个版本的输出写到各自的位置。在你自己的 @evaluator 中，read_media(item) 返回经过核对的字节。

无需模型的检查

media_check 度量某个角色的每个已记录项，当每一项都满足所声明的每个条件时通过：

  - type: media_check
    criterion: thumbnail_fits
    kind: image
    formats: [png, jpeg, webp]
    max_width: 256
    max_height: 256
    max_bytes: 50000

格式从文件的开头字节读取，因此保存为 .png 的 JPEG 会失败；图像尺寸和 WAV 时长从它们的文件头读取；视频的尺寸或 MP3 的时长用 ffprobe 度量。时长界限适用于音频和视频，尺寸界限适用于图像和视频。

image_matches_reference 在每张图像看起来都像参考图像时通过：它们的 64 位感知哈希最多相差 max_distance 位（默认为 8）。缩放或重新压缩过的副本只相差几位；空白图像、损坏的文件或不同的场景则不然。参考图像要么是所有用例共用的一个 reference_file，要么是每个用例的 expected 通过 reference_field 指明的路径。哈希读取的是布局和明暗，而不是颜色，因此它无法区分以相同方式拍摄的两件商品，而且有大片空白区域的平面图形比照片更容易让它变动。它需要 Pillow：pip install 'oloproof[media]'。

每个字段都在配置参考中。两种检查都从第一次运行起就作出决策，因为它们不调用模型。

能看到媒体的评判模型

带 media 的 rubric_judge 会看到用例中已记录的该角色（input、output 或 all）的媒体，每一项都在提示词中给出名称，这样评判模型就能区分输入和输出：

  - type: rubric_judge
    criterion: caption_matches
    provider: openai_compatible
    base_url: http://localhost:11434/v1
    model: qwen2.5vl
    rubric_text: Pass only if the caption truthfully describes the attached image.
    media: output
    video_frames: 4
    transcriber:
      model: whisper-1

• 图像按原样附加，每张最多 5 MB，每次评判最多 20 张。
• 视频以静态帧附加，这些帧在运行评判模型的机器上用 ffmpeg 截取：video_frames: 4 取四个等长区间各自的中点，[0.5, 2.0] 取这些时刻。
• 音频由 transcriber（一个兼容 OpenAI 的 /audio/transcriptions 端点，省略 base_url 时为 OpenAI 的端点）转写，转写文本进入提示词；或者，在 audio: native 下，它作为声音附加，供能听的模型使用（wav 和 mp3；不适用于 Anthropic 的模型）。

媒体的摘要是评判结果的键的一部分，因此变化了的媒体会被重新评判，没有变化的媒体则来自缓存。转写器和帧时间是评判模型版本的一部分，每个评判结果都保存它的转写文本和 ffmpeg 版本。为音频声明却没有转写器的评判模型，或在没有 ffmpeg 的机器上为视频声明的评判模型，会停止运行，而不是让这些用例成为缺失。托管模型对每张图像和每个词都计费。

验证媒体评判模型

能看到媒体的评判模型在人的标签表明它与人一致之前不决定任何事情，这与读取文本的评判模型完全一样：标注一个随机样本，然后运行 oloproof evaluators validate（评判模型）。在托管工作区中，评审队列会向评审者展示每个用例的媒体。更改模型、评分细则、media、帧或转写器都会产生一个新的评判模型，它需要自己的验证。

工作台中的媒体

用例的媒体显示在它的输出和结论旁边，出现在用例页面和评审队列中，并附有每个文件的类型、大小和摘要。

• 本地工作台从运行记录的位置（在你的机器上）读取每个文件，并且只在其 sha256 仍然匹配时显示它。
• 托管工作区从不接收媒体。查看者的浏览器从你网络中的 oloproof collect 获取每个文件，使用的是评审队列获取用例内容时所用的同一种短时有效票据（评判模型），并在显示之前核对其 sha256。没有收集器时，页面会列出每个文件的事实，并说明为什么不显示它。

推送的运行会在出站（egress）类别 artifacts 下携带 media/v1 记录，以及每个文件的保存位置；扣留 artifacts 的策略也会把这些位置留在你这一侧。

不支持的功能

• 生成媒体：你的系统制作它的文件，Oloproof 评估它们。
• 把媒体上传到 Oloproof：没有上传功能，无论托管还是本地。
• 通过 Anthropic 的 API 让模型观看完整视频或收听音频：在那里，视频依据帧来评判，音频通过转写文本来评判。
• 对音频或视频内容的确定性检查（词错误率、场景检测）：用 @evaluator 和 read_media 自己写一个。
• 音频或视频的感知哈希：image_matches_reference 只读取图像。