bykof/peekaboolean

源码: https://github.com/bykof/peekaboolean

peekaboolean

窥视图像，获取布尔值（以及选项与评分）。

一个轻量级视觉语言模型，能够快速回答关于图像的键入问题，足以在笔记本电脑上流畅运行。你发送一张图像、一个 state（上下文）以及任意数量的命名问题。每个问题属于以下三种类型之一：

• choice：从你提供的选项中选择一项，每个选项都有自己的描述
• score：将图像放置在你提供的序数标尺上（任意级别数）
• noul：是/否，以概率形式返回

模型从不生成文本。它仅对调用者编写的选项进行评分，因此只返回你询问的答案，概率经过校准，并且训练中从未见过的标尺也能像熟悉的标尺一样有效工作。

• 骨干网络：SmolVLM-500M-Instruct (https://huggingface.co/HuggingFaceTB/SmolVLM-500M-Instruct)，对语言模型应用 LoRA，视觉塔保持冻结
• 输出头：骨干网络自身的 logit(是) − logit(否) 用于判断“此提议答案是否正确？”
• 训练：从 Qwen3-VL-30B-A3B（一个本地教师模型，负责编写并标注请求）蒸馏得到，并结合公开的 VQA 数据
• 延迟：在 M1 Pro 上处理包含六个问题（28 个选项）的请求，约 400 毫秒 p95（MPS，512 像素）；桌面 GPU 上约 60 毫秒
• 权重：GitHub 发布 v0.1.0 (https://github.com/bykof/peekaboolean/releases/tag/v0.1.0)（CC BY-NC 4.0 许可证，详见 Licence）

构建过程以及哪些方法有效、哪些无效：docs/REPORT.md。

快速开始

git clone https://github.com/bykof/peekaboolean && cd peekaboolean
uv sync --python 3.13
curl -L https://github.com/bykof/peekaboolean/releases/download/v0.1.0/peekaboolean-500m.tar.gz | tar xz
uv run python -m peekaboolean.serve --adapter peekaboolean-500m \
    --image photo.jpg --request requests/general.json --max-edge 512

--adapter 接受本地检查点目录或 Hugging Face 仓库 ID。基础模型会在首次使用时下载。--device 选择 cuda、mps 或 cpu（默认：自动）。

一个请求（requests/general.json）：

{
  "state": "仅根据图像中可见内容作答。",
  "questions": {
    "kind": {
      "type": "choice",
      "instructions": "这是什么类型的图像？",
      "criteria": {
        "photo": "真实场景的照片",
        "screenshot": "应用程序或网站截图",
        "document": "扫描或拍摄的文档页面",
        "chart": "图表、图形或示意图"
      }
    },
    "sharpness": {
      "type": "score",
      "instructions": "图像清晰度如何？",
      "criteria": [
        "非常模糊",
        "有些模糊",
        "可接受",
        "清晰"
      ]
    },
    "person_visible": {
      "type": "noul",
      "instructions": "图像中是否可见人物？"
    }
  }
}

一张图表图像的答案示例：

{
  "answers": {
    "kind": {"type": "choice", "choice": "chart", "confidence": 0.755, "probabilities": {"photo": 0.0002, "screenshot": 0.180, "document": 0.004, "chart": 0.817}},
    "sharpness": {"type": "score", "score": 1.96, "confidence": 0.151, "probabilities": {"0": 0.114, "1": 0.176, "2": 0.346, "3": 0.363}, "legend": {"0": "非常模糊", "1": "有些模糊", "2": "可接受", "3": "清晰"}},
    "person_visible": {"type": "noul", "noul": 0.047}
  }
}

score 是预期的级别索引（0 = 第一级别）。noul 是 P(是)。

在 Python 中，可加载一次并重复使用：

from peekaboolean.serve import load, evaluate

model, processor, calibration = load("peekaboolean-500m", device="mps", merge=True)
result = evaluate(model, processor, state, questions, "photo.jpg", calibration, max_edge=512)

state、instructions 和每个选项可以是字符串、对象或列表。noul 类型问题可以有自己的措辞："criteria": {"true": "...", "false": "..."}。每个问题独立评分，因此答案不依赖于选项顺序或请求中的其他问题。

本地界面

uv run python -m peekaboolean.ui --adapter peekaboolean-500m

在 http://127.0.0.1:8765 上打开页面。拖放文件夹或图像（或选择、粘贴），编写问题，点击排序（⌘↵）。每张图像落入其答案对应的箱中；清单列出每个答案及其概率，导出 JSON 保存 {request, results, errors}。choice 选项每行一个，格式为 key: description，score 级别每行一个从最低开始，yes/no 措辞可选，格式为 yes: ... / no: ...。JSON 视图以上述格式编辑相同的请求。图像保留在本机上。

界面实时排序 42 张 Wikimedia Commons 图像

在 M1 Max（MPS，512 像素）上实时处理：来自 Wikimedia Commons 的 42 张图像使用 requests/general.json 中的三个问题（页面默认）在 8.9 秒内完成排序，模型处理时间每张 206 毫秒。相同的图像、作者和许可证列于 docs/demo-images.tsv；获取它们并拖放 data/demo 到页面：

mkdir -p data/demo && tail -n +2 docs/demo-images.tsv | while IFS=$'\t' read -r file url _; do curl -sSfL -A "peekaboolean-demo (https://github.com/bykof/peekaboolean)" -o "data/demo/$file" "$url"; done

服务模式

--mode（默认 auto）；所有模式在 fp32 下返回相同答案：

• shared：编码一次图像和状态，然后使用 KV 缓存对每个选项作为后缀进行评分
• single：所有内容在一次前向传递中完成；对于 MPS 上的小型请求更快
• auto：最多 8 个选项时使用 single，超过则使用 shared
• naive：每个问题一次前向传递；参考路径 serve --check 断言三者一致。

python -m peekaboolean.benchmark 测量每种图像尺寸和请求形状的热延迟（--breakdown 获取各阶段时间）。校准温度分别针对 256、384 和 512 像素拟合。除非延迟要求使用更小尺寸，否则以 512 像素提供服务。

结果

留出测试集，512 像素。图像分割基于内容哈希，因此测试图像在训练中未被见过。“教师”组是由教师模型编写的请求，衡量与教师的对齐程度，而非与真实情况的对齐。

未训练列来自 4000 行验证样本。v6 在其自身（v6）测试集上测量，v8b 在完整 v7/v8 测试集（21k 问题）上测量；两者使用相同的图像分割。每组 JSON 报告附在 GitHub 发布中。

Mac 延迟（M1 Pro，MPS，fp32，--mode auto，512 像素）：包含六个问题、28 个选项的请求，500M 骨干网络的 p95 延迟约为 380–400 毫秒。256M v6 模型：单个 noul 116 毫秒，六个问题的请求 230 毫秒。

局限性

• 与教师模型的准确率不等于与人类的准确率。目前尚无公开的、人类标注的、针对请求形状问题的接受集。
• v7 训练中移除了图像美学内容；模型的美学评分与纯文本先验相比并无优势。
• 模型从人脸估计年龄、性别以及“儿童或成人”（FairFace 训练数据）。这些估计携带了数据的偏见，并且对于个体而言错误率足够高，绝不能用于决定关于某个人的任何事情。它也会回答关于绘画和卡通角色的此类问题。
• 选项独立评分，因此模型无法比较仅因对比度不同而异的选项（“较大的那个”）。

训练你自己的模型

生成此检查点的所有内容都在 src/peekaboolean 中。流程如下：

1. prepare_general.py：来自 The Cauldron (https://huggingface.co/datasets/HuggingFaceM4/the_cauldron) 的类型化问题（VQAv2、CLEVR、TextVQA、DocVQA、ChartQA、Screen2Words、AI2D），仅训练分区
2. prepare_teacher.py：本地 Qwen3-VL-30B-A3B（vLLM）为每张图像编写一个请求并标注（参见模块文档字符串；在其自身的 vLLM 环境中运行）
3. prepare_v6.py：混合公开和教师行，添加计数标尺，针对已知答案行调整教师的概率
4. prepare_age.py：FairFace 年龄、性别和儿童/成人问题
5. pipeline.py：train_general.py → 每尺寸校准和测试报告（postprocess.py）→ 延迟基准测试，作为分离的后台任务
6. full_test.py：在测试集的每一行上评估检查点

每个版本的确切设置见 docs/REPORT.md。所有运行均使用一块 RTX PRO 6000（96 GB）。docs/legacy-qwen-v1-v2.md 描述了早期的 Qwen3-VL-4B 美学实验（train.py、prepare_ava.py、prepare_aadb.py 等）。

许可证

• 代码：Apache-2.0（LICENSE）
• 权重：CC BY-NC 4.0。基础模型和教师模型为 Apache-2.0，但部分训练数据仅允许研究用途（DocVQA；AVA 和 AADB 图像，教师模型曾为其编写问题）或携带 GPL-3.0（ChartQA）。因此权重仅发布用于研究和非商业用途。详情见模型卡片。

引用

参见 CITATION.cff。