| --- |
| license: apache-2.0 |
| base_model: HuggingFaceTB/SmolVLM2-2.2B-Instruct |
| library_name: peft |
| pipeline_tag: image-text-to-text |
| tags: |
| - smolvlm2 |
| - peft |
| - lora |
| - visual-ranking |
| - playing-card |
| - puzzle |
| language: |
| - en |
| --- |
| |
| # Puker_Judge |
| |
| `Puker_Judge` 是基于 |
| [`HuggingFaceTB/SmolVLM2-2.2B-Instruct`](https://huggingface.co/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`。 |
|
|
| ## 能做什么 |
|
|
| 这两个模型只负责视觉判断，不负责枚举几何拼法，也不直接输出机械臂坐标： |
|
|
| 1. CV/几何算法检测碎片并枚举能够填满目标矩形的候选拼法； |
| 2. 候选只有一个时，可用 `binary_adapter` 判断其图案是否合理； |
| 3. 候选有 2–4 个时，用 `rank_adapter` 选择最佳候选； |
| 4. 候选超过4个时，先去重或使用 `binary_adapter` 逐张筛选到 Top-4，再交给 |
| `rank_adapter`。 |
|
|
| ## 安装 |
|
|
| BF16： |
|
|
| ```bash |
| python -m venv .venv |
| source .venv/bin/activate |
| pip install -r requirements.txt |
| ``` |
|
|
| 在 Linux x86-64 NVIDIA GPU 上使用 bitsandbytes INT4： |
|
|
| ```bash |
| 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 |
|
|
| ```text |
| 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. |
| ``` |
|
|
| 输出只能是： |
|
|
| ```text |
| VALID |
| ``` |
|
|
| 或： |
|
|
| ```text |
| INVALID |
| ``` |
|
|
| ### 多候选排序 prompt |
|
|
| 下面的 `{labels}` 要根据选项数生成，例如3个候选就是 `1, 2, 3`： |
|
|
| ```text |
| 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： |
|
|
| ```bash |
| python infer_binary.py candidate.jpg |
| ``` |
|
|
| INT4 NF4（实验性，binary默认推荐BF16）： |
|
|
| ```bash |
| python infer_binary.py candidate.jpg --int4 |
| ``` |
|
|
| 输出示例： |
|
|
| ```json |
| { |
| "prediction": "VALID", |
| "raw_output": "VALID", |
| "quantization": "int4-nf4" |
| } |
| ``` |
|
|
| ### 从2–4张候选图中选择 |
|
|
| 脚本会自动生成 `candidate_board.jpg`： |
|
|
| ```bash |
| python infer_rank.py \ |
| candidate_1.jpg \ |
| candidate_2.jpg \ |
| candidate_3.jpg \ |
| --board-output candidate_board.jpg \ |
| --int4 |
| ``` |
|
|
| 输出示例： |
|
|
| ```json |
| { |
| "selected_label": 2, |
| "selected_file": "/path/to/candidate_2.jpg", |
| "candidate_count": 3 |
| } |
| ``` |
|
|
| 如果已经自行生成了 board： |
|
|
| ```bash |
| python infer_rank.py \ |
| --board-image candidate_board.jpg \ |
| --candidate-count 3 \ |
| --int4 |
| ``` |
|
|
| ## 直接用 Transformers + PEFT 加载 |
|
|
| ```python |
| 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() |
| ``` |
|
|
| ## 训练信息 |
|
|
| - 基础模型：SmolVLM2-2.2B-Instruct； |
| - LoRA：rank 16，alpha 32，dropout 0.05； |
| - 最大图像长边：1280； |
| - 最大文本长度：2048； |
| - rank训练场景：18,000； |
| - rank验证/测试场景：各1,000； |
| - binary训练样本：33,300； |
| - binary验证/测试样本：各1,850； |
| - 使用52张标准扑克牌资产，不包含大小王； |
| - 训练样本包括普通随机、偏心平行四边形、中心双切、全等对称和近似对称困难样本。 |
|
|
| ## 已做的实拍检查 |
|
|
| 模型曾在训练集外的 Joker 实拍候选上进行顺序轮换检查。正确候选分别位于 |
| 1、2、3号位置时，rank adapter 的原始生成结果分别为1、2、3。使用 |
| bitsandbytes INT4 NF4 后结果仍保持一致。该结果只是一组定性检查，不应视为完整 |
| 统计评测。 |
|
|
| ## 限制 |
|
|
| - rank adapter 只训练过最多4个选项，禁止直接构造超过4项的大型 board； |
| - binary adapter 对INT4量化更敏感，单候选判断默认使用BF16； |
| - board内不存在正确答案时，模型仍会被迫选择一个编号； |
| - 透视畸变、反光、遮挡、碎片间隙或候选缩放不一致可能影响判断； |
| - 模型不保证识别所有未见过的牌面和印刷风格； |
| - 输出是视觉判断，不是几何证明，也不是机械臂控制策略； |
| - 建议将正确候选轮换到不同board位置重复2–3次，并对原始生成编号投票，以减小位置偏置。 |
|
|
| ## License |
|
|
| 本模型基于 Apache-2.0 许可的 SmolVLM2-2.2B-Instruct。扑克牌源图和训练数据不包含在本仓库中。 |
|
|
