Puker_Judge

Puker_Judge 是基于 HuggingFaceTB/SmolVLM2-2.2B-Instruct 微调的两阶段扑克牌拼接候选判断模型。

本仓库发布的是两个 PEFT LoRA adapter，而不是重复上传两份基础模型：

binary_adapter/：判断一张已经拼好的候选牌面是 VALID 还是 INVALID。
rank_adapter/：从同一组碎片产生的 2–4 个几何可行候选中选择图案最连贯的一个。
processor/：训练时使用的 SmolVLM2 processor 和 tokenizer。

第二阶段由第一阶段权重初始化后继续训练，但推理时不要同时叠加两个 adapter。做单候选判断时加载 binary_adapter，做多候选选择时加载 rank_adapter。

能做什么

这两个模型只负责视觉判断，不负责枚举几何拼法，也不直接输出机械臂坐标：

CV/几何算法检测碎片并枚举能够填满目标矩形的候选拼法；
候选只有一个时，可用 binary_adapter 判断其图案是否合理；
候选有 2–4 个时，用 rank_adapter 选择最佳候选；
候选超过4个时，先去重或使用 binary_adapter 逐张筛选到 Top-4，再交给 rank_adapter。

安装

BF16：

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

在 Linux x86-64 NVIDIA GPU 上使用 bitsandbytes INT4：

pip install -r requirements-int4.txt

INT4主要建议用于 rank_adapter。实测中，rank adapter 在Joker三候选顺序轮换上保持了BF16的判断；但 binary adapter 的一个测试集VALID样本在INT4下翻转成了INVALID。因此单候选二分类默认应使用BF16，除非已经在自己的数据上重新验证 INT4准确率。

输入图像规范

单候选二分类

输入一张透视矫正后的完整候选牌面：

推荐规范尺寸：600×360 像素，对应物理尺寸比例 100:60；
牌面应紧密裁剪，尽量删除桌面、机械臂、阴影和大面积背景；
所有碎片必须位于同一个目标矩形内；
整张牌旋转180°仍视为同一个正确答案；
不要添加候选编号或多选题边框。

多候选排序 board

模型实际接收的是一张包含所有选项的 board，而不是多张独立图片。

board：1280×820；
固定2列×2行布局；
选项数必须是 2、3或4，不能超过4；
每个候选先规范化为 600×360；
标签必须为连续数字 1, 2, 3, 4，放在候选图外部；
少于4个选项时，未使用的格子保持空白；
所有候选必须来自同一张牌、同一组碎片，并且在几何上都可行；
各候选应使用相同的裁剪、尺度、背景和成像处理，避免让模型利用无关差异。

infer_rank.py 可以接收2–4张候选图并自动生成符合训练格式的 board。

Prompt

建议保持训练时的英文 prompt，不要随意改写。

二分类 prompt

Judge whether this geometrically assembled playing card has coherent rank, suit, border, portrait, symbols, and continuous artwork. A whole-card 180-degree rotation is valid. Answer VALID or INVALID only.

输出只能是：

VALID

或：

INVALID

多候选排序 prompt

下面的 {labels} 要根据选项数生成，例如3个候选就是 1, 2, 3：

All displayed candidates are geometrically valid reconstructions made from the same playing-card pieces. Select the candidate whose rank, suit, outer border, portrait, symbols, and line artwork form one coherent original playing card. A whole-card 180-degree rotation is equivalent. The available labels are {labels}. Answer with one label only.

输出只能是一个候选编号。

使用方法

单独判断一个候选的正误

BF16：

python infer_binary.py candidate.jpg

INT4 NF4（实验性，binary默认推荐BF16）：

python infer_binary.py candidate.jpg --int4

输出示例：

{
  "prediction": "VALID",
  "raw_output": "VALID",
  "quantization": "int4-nf4"
}

从2–4张候选图中选择

脚本会自动生成 candidate_board.jpg：

python infer_rank.py \
  candidate_1.jpg \
  candidate_2.jpg \
  candidate_3.jpg \
  --board-output candidate_board.jpg \
  --int4

输出示例：

{
  "selected_label": 2,
  "selected_file": "/path/to/candidate_2.jpg",
  "candidate_count": 3
}

如果已经自行生成了 board：

python infer_rank.py \
  --board-image candidate_board.jpg \
  --candidate-count 3 \
  --int4

直接用 Transformers + PEFT 加载

from pathlib import Path

import torch
from huggingface_hub import snapshot_download
from peft import PeftModel
from transformers import AutoModelForImageTextToText, AutoProcessor

repo_dir = Path(snapshot_download("TuWaveGod/Puker_Judge"))
processor = AutoProcessor.from_pretrained(repo_dir / "processor")
base = AutoModelForImageTextToText.from_pretrained(
    "HuggingFaceTB/SmolVLM2-2.2B-Instruct",
    torch_dtype=torch.bfloat16,
).to("cuda")
model = PeftModel.from_pretrained(
    base,
    repo_dir / "rank_adapter",
).eval()