svoic/kantu-shixiang

看图识象 Kantu Shixiang v3

看图识象是一个小型「看图认物象」模型：给一张照片或一幅画，认出其中的山水花鸟人物等 121 类诗词常见物象，判断画种（照片／油画／版画／素描／水彩／国画），并指出物象大致落在哪一格。全部训练材料来自公有领域、开放授权或明示授权的来源，不含任何网络抓取或 AI 生成的图文。

Kantu Shixiang ("look at the picture, recognise the imagery") is a small multi-label tagger for 121 kinds of imagery common in classical Chinese poetry, with a 6-way medium classifier (photo / oil / print / drawing / watercolour / Chinese ink painting) and a coarse position. Every piece of training material is public-domain or openly licensed; nothing is web-scraped or AI-generated.

v3 相对 v2 What changed in v3

v2 的物象分类头只用照片训练，在古画上漏得多：桥、亭、舟船几乎认不出，人物误报多。v3 做了两件事：

1. 加入由人逐块判定的古画切块作训练材料，先只重训分类头（内部称「第三版草稿」，2026-11-06，未发布）；
2. 再用同一批材料微调图像编码器本身（Mitsua Japanese CLIP ViT-B/16，CC BY-SA 4.0 允许改动），分类头一起训；照片对原编码器做特征蒸馏，防止照片上的能力退化。

另加一个可选的滑窗细看模式：在整图＋四格之外再看 5 个局部（上中、左中、中央、右中、下中，共 10 视角），小船、小桥、远处的鸟更容易认出，用时约一倍。词表、画种、文件接口不变。

v2's imagery head was trained on photographs only and missed a great deal on classical paintings. v3 (a) adds painting tiles labelled tile-by-tile by people to the training material (first retraining the head only, an unreleased internal draft of 2026-11-06), then (b) fine-tunes the image encoder itself on the same material, with feature distillation to the original encoder on photographs so photo performance does not regress. An optional sliding-window mode looks at five extra crops (10 views in all) and catches small boats, bridges and distant birds at roughly double the cost. Vocabulary, medium classes and file interface are unchanged.

	v2 (2026-11-03)	v3 (2026-11-08)
物象类 Classes	121	121（不变）
图像编码器 Image encoder	Mitsua CLIP ViT-B/16 原样 unmodified	同一编码器，经人判古画切块微调 fine-tuned on human-judged painting tiles
照片训练材料 Photo training images	5,870,638（PD12M 全部 125 包）	分类头：同 v2 回放；编码器微调：其中 62,500 张回放＋蒸馏
古画训练材料 Painting training tiles	0（只用于画种头）	人判 3,347 块（9 类逐块勾选）＋ 画框核实 3,533 块
画上验收 mAP（留出 512 幅画的 1,410 块，11 类）Painting hold-out mAP	0.622	0.752；滑窗 0.766
独立尺子 mAP（Qwen3.6 逐块判断的 480 块国画）Independent yardstick mAP	0.557	0.687；滑窗 0.699
照片验收 mAP（本地留出 5,983 张有标签照片，20 类）Photo hold-out mAP	0.399	0.417
验收画块判为国画 Painting tiles classified as 国画	94.1%	99.8%
视角 Views	5	5，或滑窗 10
运行件体积 Runtime size	0.17 GB (fp16)	0.17 GB (fp16)

（表中三版的数都是本次在同一批验收材料、同一套算法上重算的，与 v2 模型卡上按另一套流程算出的旧数不完全一致。All numbers in this table were recomputed for every version on the same evaluation material with the same code; they differ slightly from the figures in the v2 model card, which used a different pipeline.）

人判古画材料怎么来的 How the painting labels were made：从 11,999 幅公有领域／CC BY 4.0 古画（台北故宫、ColBase、大都会、克利夫兰、史密森尼、普林斯顿、耶鲁等）的 210,960 块切块中，先按馆方品名圈出可能含舟船、桥、亭、房屋、人物、鸟、马、牛、月的候选，再由前几轮模型挑出它「拿不准」的块，共四批 3,347 块，由两位判者在硅谷诗韵中心的标注台上逐块勾选「画里看得出哪些物象」（不勾＝核实没有）。标签只来自人眼，没有用任何大模型写标签。按画随机留出 20%（512 幅画、1,410 块）不训，只作验收。

Painting labels: from 210,960 tiles of 11,999 public-domain / CC BY 4.0 paintings (National Palace Museum Taipei, ColBase, the Met, Cleveland, Smithsonian NMAA, Princeton, Yale and others), candidate tiles were first selected by museum titles and then by what earlier rounds were unsure about; 3,347 tiles in four batches were marked tile-by-tile by two human annotators on the SVOIC annotation site ("which of these nine objects can you see"; nothing marked = verified absent). No language or vision-language model wrote any label. 20% of paintings (512 paintings, 1,410 tiles) were held out for evaluation.

结构 Architecture

部件 Part	来源 Source	参数 Params	文件 File
图像编码器 Image encoder (ViT-B/16 + projection)	Mitsua Japanese CLIP ViT-B/16, ELAN MITSUA Project / Abstract Engine, CC BY-SA 4.0；本项目微调 fine-tuned here（见下）	86.4 M	encoder.safetensors (fp16, 165 MB)
物象分类头 Imagery head (121 classes, multi-instance over 5 or 10 views)	本项目训练 trained here	1.01 M	head.pt (3.9 MB)
画种分类头 Medium head (6 classes)	本项目训练 trained here	4.6 K	in head.pt
零样本文字向量 Zero-shot text vectors (19 words)	Mitsua text encoder, precomputed	–	zs_text.npz
门槛表 Thresholds (photo / painting; 5-view / 10-view)	校准见下 calibrated as below	–	thresholds.json, paint_thresholds.json
零样本补标规则 Zero-shot rules	门槛按新编码器换算，规则同 v2	–	zs_rules.json

一张图切成 5 个视角（整图 224×224，再把 448×448 的整图四等分），滑窗模式再加 5 个 224 窗（步长 112，与四格合成 3×3 九窗）；各视角过编码器得到 768 维特征；分类头给每个视角打 121 类分数，取最大值作整图分数，最大值所在视角即位置。画种与零样本只用整图视角。合计约 8,740 万参数。

Five views per image (whole image at 224, plus the four quadrants of a 448 resize); sliding-window mode adds five 224 windows at stride 112. A per-view head gives 121 scores per view; the max over views is the image score and the arg-max view the position. Medium and zero-shot use the whole-image view only. About 87.4 M parameters.

编码器微调 Encoder fine-tuning

• 解冻范围：ViT 全部 12 层、末层归一化、投影层（8,560 万参数）；分类头（101 万）同时训。
• 每步材料：16 块人判／画框核实古画块（只监督人判过的类，带掩码的 BCE）＋ 8 块只给画种头的国画块 ＋ 24 张照片（labels_v22 两层意象标签 BCE＋画种）。全部照片的特征对原编码器做余弦蒸馏（权 5），这是照片不退化的主要手段。
• 增广：四格随机改成滑窗偏移、随机左右翻转、轻微亮度抖动。
• 超参：编码器学习率 1e-5、分类头 1e-4，权重衰减 0.05，800 步，每 100 步验收，取画上 mAP 最高的第 700 步。单台 DGX Spark 约 3.9 小时。
• 材料量：古画块 训 5,457／验 1,410；画种块 14,836；照片 训 62,500（其中有标签 29,591）／验 5,983（有标签）。
• 另试过只解冻末 4 层（3,000 步）和末 8 层两种配方，画上 mAP 都顶在 0.75 左右：现在的瓶颈是人判材料量，不是解冻多少层。

All 12 transformer blocks, the final layer-norm and the projection were unfrozen (85.6 M parameters) and trained together with the head. Each step mixes 16 human-judged painting tiles (masked BCE on judged classes only), 8 painting tiles for the medium head and 24 photographs (two-level imagery BCE + medium); all photo features are distilled (cosine, weight 5) towards the original frozen encoder. Augmentation: random quadrant offsets, horizontal flips, slight brightness jitter. Encoder lr 1e-5, head lr 1e-4, weight decay 0.05, 800 steps, best painting mAP at step 700 (about 3.9 h on one DGX Spark). Unfreezing only the last 4 or 8 blocks reached the same ≈0.75 ceiling, so the remaining bottleneck is the amount of human-judged material, not the recipe.

支持的物象 Supported imagery (121)

词表与 v2 相同（人物 15、山水 22、天象 5、草木 19、飞禽 14、走兽与虫鱼 14、建筑 13、器物 13、泉、书、以及不可用的月、火），见 v2 模型卡。v3 的差别在画上：

• 画上可用 Usable on paintings：人、屋、花、马、舟船、桥、鸟、月。其中月在照片上仍不可用，只在画种判为国画时按画上门槛输出。
• 画上不可用 Not usable on paintings：亭（准确率 80% 时召回只有 12%，画上门槛设为永不触发；画上的亭多半会被认作「屋」）；牛（验收正例只有 6 块，门槛只能取 F1 点，可信度低）。
• 其余 100 多类在画上未经人判校准，沿用照片门槛。

The vocabulary is the same as v2. v3 is painting-calibrated for 人 (person), 屋 (house), 花 (flower), 马 (horse), 舟船 (boat), 桥 (bridge), 鸟 (bird) and 月 (moon; paintings only). 亭 (pavilion) remains unusable on paintings (12% recall at 80% precision; mostly recognised as 屋) and 牛 (ox) could not be calibrated. All other classes keep photo thresholds on paintings.

门槛 Thresholds

• 照片门槛（thresholds.json，th＝5 视角、th_slide＝滑窗 10 视角）：编码器改了，分数分布跟着变。每一类的门槛按「在同批 75,000 张未参训照片上判为『有』的比例与上一版相同」换算（上一版又是按同样办法从 v2 换算来的，v2 的门槛经 v1、v2 两轮人眼抽查认可）；不可用类不变。两版判法在这 75,000 张上一致率：画种 98.8%，判为照片的比例 77.6% 对 77.4%。
• 零样本门槛（zs_rules.json）：19 词同样按同比例换算；规则不变。
• 画上门槛（paint_thresholds.json，th_paint／th_paint_slide，只在画种判为国画时启用）：按留出验收集，取「准确率 ≥ 0.8」的最低分；亭设为永不触发。宁可漏，不可错：这组门槛是为给画师模型写训练说明定的。
• 油画、版画、素描、水彩上「人」的最低把握 0.4 沿用 v2。

Photo and zero-shot thresholds are rescaled so that each class fires on the same share of 75,000 held-out photographs as the previous version did (which in turn was rescaled from v2's human-checked thresholds). Painting thresholds are the lowest score reaching precision ≥ 0.8 on the painting hold-out (pavilion: never); separate values are shipped for 5-view and 10-view operation.

用法 Usage

pip install torch safetensors transformers pillow numpy
python3 shixiang.py your_picture.jpg            # 5 视角
python3 shixiang.py --slide your_picture.jpg    # 滑窗细看，10 视角

from PIL import Image
from shixiang import Shixiang
m = Shixiang('.')                                  # encoder.safetensors / head.pt / *.json / zs_text.npz
r = m.tag(Image.open('pic.jpg'), slide=False)      # painting=None → 按画种自动选门槛；slide=True 用滑窗门槛
print(r['kind'], r['tags'])

shixiang_fp16.onnx（167 MB）：输入 views float32 [B,V,3,224,224]，V 可为 5 或 10（视角 0 必须是整图），输出 scores [B,121]、view [B,121]、kind [B,6]、zs [B,19]、feat [B,768]。门槛与合并规则见 shixiang.py 的 decide()。与 PyTorch 对拍：12 张样图分数最大差 0.018，标签 23/24 一致（一处贴着门槛）。

训练材料与来源 Training data & lineage

• 图像编码器：Mitsua Japanese CLIP ViT-B/16（本身只用开放授权材料训练），本项目按上节微调。The encoder is Mitsua Japanese CLIP ViT-B/16, fine-tuned here as described above.
• 照片：v2 的 5,870,638 张 PD12M 公有领域图与人写标签（Wikimedia Commons 文件名与分类，CC BY-SA 4.0），分类头用全部回放；编码器微调用其中本地留存的 62,500 张回放＋蒸馏。见 v2 的 training_index.parquet。
• 古画切块：
  • 人判 3,347 块（李德雄 3,221、MingJu 126），九类逐块勾选，看不清 13 块不进训练；正例 人物 980、房屋 845、桥 441、舟船 395、亭 328、马 168、鸟 137、月 100、牛 64；核实无任何一类 1,114 块。
  • 画框核实 3,533 块：369 幅人工画框的画（v1、v2 的评测集）按框与块的几何交叠推出的块级标签（8 类）。因此 v2 模型卡里那张 369 幅画的评测表在 v3 上不能再用，v3 的画上评测改用按画留出的验收集。
  • 随机 14,836 块只作画种头的「国画」正例。
  • 画的来源：台北故宫（CC BY 4.0）、ColBase 国立文化财机构（政府标准利用规约）、大都会、克利夫兰、史密森尼国立亚洲艺术博物馆、普林斯顿、耶鲁、Newfields、LACMA、圣路易斯、荷兰国立博物馆的公有领域开放资源。
• 没有用的东西：博物馆品名没有当标签（只用来圈候选）；没有任何大模型生成的标签或说明；Qwen3.6 与 EmbeddingGemma 2 只在开发中作尺子，其判断不进训练材料。

Painting tiles were labelled by two people; 1,114 of them are verified negatives for all nine classes. A further 3,533 tiles carry labels derived from the 369 hand-boxed paintings used as the evaluation set in v1/v2, which is why that benchmark is no longer reported. Museum titles were used only to pick candidates, never as labels. No model-generated labels were used; vision-language models served only as independent yardsticks during development.

评测 Evaluation

画上验收 Painting hold-out（按画随机留出 20%：512 幅画、1,410 块，与训练材料不同画；三版在同一批上算；AP；「召回」为 v3 在准确率 ≥ 0.8 门槛下的召回，即发布的画上门槛）：

类 Class	验收正例	v2	第三版草稿（只重训头）	v3	v3 滑窗	v3 召回 @0.8	滑窗召回 @0.8
花	131	0.749	0.924	0.925	0.930	88%	89%
马	36	0.886	0.897	0.878	0.886	86%	89%
屋	325	0.780	0.859	0.877	0.883	85%	86%
人	357	0.691	0.854	0.879	0.887	78%	81%
鸟	42	0.700	0.743	0.777	0.794	60%	64%
舟	96	0.687	0.685	0.762	0.793	69%	74%
船	96	0.524	0.680	0.759	0.794	67%	75%
桥	84	0.573	0.657	0.752	0.757	60%	63%
月	25	0.611	0.652	0.601	0.619	36%	44%
亭	69	0.335	0.441	0.569	0.587	12%（不可用）	12%（不可用）
牛	6	0.306	0.434	0.490	0.490	—（未校准）	—（未校准）
mAP		0.622	0.712	0.752	0.766

验收集里有相当一部分是前几轮模型「拿不准」的难块，所以各类绝对值偏低。编码器微调带来的进步集中在舟船、桥、人、屋、鸟、亭；马、月、牛样本少，略有起伏。The hold-out deliberately contains many hard tiles. Fine-tuning the encoder helps most on boats, bridges, people, houses, birds and pavilions; horse, moon and ox (few examples) fluctuate slightly.

独立尺子 Independent yardstick：随机抽 480 块国画，由本机运行的开放权重 Qwen3.6 逐块判断七类物象有无（只作尺子，不进训练），再用各版发布件各自的门槛打标签。查到数／Qwen 判有的数（括号内为误报数）：

	人物	房屋	鸟	舟船	桥	亭子	月亮	mAP
v2	96/156 (34)	48/94 (15)	18/39 (0)	4/12 (0)	0/17 (0)	2/37 (1)	0/1	0.557
第三版草稿	92/156 (6)	52/94 (16)	15/39 (1)	6/12 (1)	5/17 (2)	0/37 (0)	0/1	0.611
v3	107/156 (8)	61/94 (14)	17/39 (0)	6/12 (0)	6/17 (1)	0/37 (0)	0/1	0.687
v3 滑窗	109/156 (7)	60/94 (12)	17/39 (0)	6/12 (0)	8/17 (1)	0/37 (0)	0/1	0.699

人物从 96 查到 107 且误报 34 降到 8；桥从不认到 6–8/17；舟船一半；亭仍为零（门槛关着）。On this yardstick v3 finds more people with far fewer false positives (34 → 8), bridges go from none to 6–8 of 17, boats reach half; pavilions stay at zero because their painting threshold is switched off.

与零样本多模态嵌入模型对照 vs. a zero-shot multimodal embedding model：EmbeddingGemma 2（Google，2026-10，Apache 2.0；视觉编码器 1.7 亿参数，网络数据训练、来源不明，只作对照）用中英文提示零样本打分，同一验收集、同一算法（10 类，舟船合一）：

	画上验收集 1,410 块 mAP	Qwen 480 块 mAP
EmbeddingGemma 2 零样本	0.658	0.673
看图识象第三版草稿	0.714	0.611
看图识象 v3	0.752	0.686

草稿时 Gemma 在舟船、亭上明显更强（舟船验收 0.81 对 0.72）；v3 微调编码器后舟船追到 0.76，亭 0.57 对 0.56 持平，人、鸟、花仍大幅领先。At the draft stage zero-shot EmbeddingGemma 2 was clearly stronger on boats and pavilions; after fine-tuning the encoder v3 closes the gap on boats and pavilions and keeps its lead on people, birds and flowers.

照片 Photos（本地留出 5,983 张有人写标签的 PD12M 照片，取正例 ≥ 20 的 20 类；三版同批）：mAP v2 0.399、草稿 0.393、v3 0.417；画种判对 92.8%、94.3%、93.9%。编码器微调后照片不但没退，还略升（树 0.34→0.39、鸟 0.39→0.44、湖 0.18→0.22、舟 0.25→0.28），人略降（0.40→0.37）。

画种 Medium：验收画块判为国画 v2 94.1% → v3 99.8%。

已知弱项 Known limitations

• 亭在画上不可用；牛在画上未校准；月只在画上、且门槛很严（验收召回 36%，滑窗 44%）。
• 舟船、桥在画上准确率 80% 时召回六到七成：小船、远桥仍会漏；开滑窗略好。
• 画上门槛只校准了上表的类；山、水、树等在画上沿用照片门槛，召回偏低，写说明时宜另靠馆方景物词。
• 马、月、牛三类比只重训头的草稿略低（样本 36、25、6 块，差异在噪声内）。
• 三种微调配方都顶在 0.75 左右：再往上要靠更多人判材料，尤其舟船、桥、亭、月。
• 其余与 v2 相同：仕女在照片上学成了「有女性」；英文标签歧义可能有漏网；不认现代物品、文字、人脸身份。

许可与署名 License & attribution

整包按 CC BY-SA 4.0 发布。使用时请署名：

看图识象 Kantu Shixiang v3 (SVOIC, CC BY-SA 4.0), a fine-tune of Mitsua Japanese CLIP ViT-B/16 by ELAN MITSUA Project / Abstract Engine (CC BY-SA 4.0). Labels from Wikimedia Commons contributors (CC BY-SA 4.0) and SVOIC annotators. Images from PD12M (public domain) and museum open-access collections.

This package is released under CC BY-SA 4.0. The image encoder is a fine-tuned derivative of Mitsua Japanese CLIP ViT-B/16 (CC BY-SA 4.0) and is released under the same licence, as that licence requires. Our additions (heads, thresholds, painting labels, lexicon) are CC BY-SA 4.0 as well. The model is provided as is; recognition can be wrong, and it is not suitable for any use requiring high accuracy.

本模型属 SVOIC「开放文化授权」系列：训练材料来源可查、可追溯、可核对。v1、v2 仍在本仓库的历史版本中可取用。