AnandaSky是一个面向历史汉语文档逐行转写的视觉语言模型（ViT 编码器 + Qwen3 解码器，约 6.26 亿参数）。由于它没有内置在transformers的官方模型列表中，加载时必须开启trust_remote_code，并依赖config.json里的auto_map字段把AutoModelForCausalLM、AutoProcessor等入口路由到仓库自带的 modeling_anandasky.py 与 inference_processor.py。本文完整拆解这套自定义模型加载机制：trust_remote_code为什么必需、auto_map如何工作、以及AnandaProcessor从图片到文本的完整推理流程。

一、为什么 AnandaSky 必须开启 trust_remote_code？

大多数开源模型（如Qwen2、Llama）的建模代码直接由transformers库内置，AutoModelForCausalLM.from_pretrained(...)能"认得"它们。

但 AnandaSky 的架构是全新的自定义结构：

• 视觉侧：AnandaEncoder（ViT）+AnandaVisionPrefixAdapter
• 文本侧：基于 Qwen3 的自回归解码器Qwen3Model
• 顶层模型类：AnandaForCausalLM（见 modeling_anandasky.py）

这些代码全部写在仓库内的modeling_anandasky.py里，transformers官方并不认识它们。因此：

⚠️ 加载时必须传入trust_remote_code=True，让transformers允许从模型仓库下载并执行自定义 Python 代码。

from transformers import AutoModelForCausalLM model = AutoModelForCausalLM.from_pretrained( "badianeai/AnandaSky", trust_remote_code=True, # 关键：启用仓库内置的自定义建模代码 torch_dtype="auto", device_map="auto", )

小提示：trust_remote_code=True会执行模型仓库内的代码，请只对你信任的仓库开启（本模型由 BnF DataLab 发布，见 README.md）。

二、auto_map：自定义加载的"路由表"

auto_map是transformers提供的类名映射表——它告诉Auto*系列工厂类："遇到这个仓库时，请使用仓库里的这些自定义类，而不是内置实现。"

在 AnandaSky 的 config.json 中：

"auto_map": { "AutoConfig": "modeling_anandasky.AnandaHFConfig", "AutoModelForCausalLM": "modeling_anandasky.AnandaForCausalLM", "AutoProcessor": "inference_processor.AnandaProcessor" }

三个入口一一对应：

工作机制非常直观：

1. 你调用AutoModelForCausalLM.from_pretrained(...)；
2. transformers读取仓库的config.json，发现architectures是未知的AnandaForCausalLM，再查auto_map；
3. 按modeling_anandasky.AnandaForCausalLM的定位规则，动态 import 仓库中的modeling_anandasky.py并实例化该类。

📌 这正是"自定义模型"与"内置模型"加载路径的分水岭：没有auto_map，Auto*类根本不知道该用哪个实现。

同样的映射也出现在 processor_config.json 中，用于AutoProcessor的解析：

"processor_class": "AnandaProcessor", "auto_map": { "AutoProcessor": "inference_processor.AnandaProcessor" }

三、AnandaProcessor：从古籍行图到文本的完整工作流

AnandaProcessor 是一个ProcessorMixin，把两件事粘合在一起：

• AnandaImageProcessor（图像预处理）
• AutoTokenizer（Qwen3 词表分词，支持纯文本输入）

1. 图像预处理流水线

AnandaImageProcessor（inference_processor.py）对每一张"文档行图片"依次执行 6 步：

1. 转 RGB 3 通道（灰度图自动扩展为 3 通道）
2. 转为 CHW 格式的 float32 张量，归一化到[0, 1]
3. 用训练时的均值/标准差标准化（image_mean≈ [0.5218, 0.5218, 0.5235]，image_std≈ [0.3383, 0.3394, 0.3391]，见 processor_config.json）
4. 将 H/W 补齐到patch_size=10的整数倍
5. 再补齐到patch_size × merge_factor的整数倍，同时生成patch_attention_mask（标记哪些 patch 是真实内容、哪些是填充）
6. 输出pixel_values+patch_attention_mask

💡patch_attention_mask很关键：AnandaSky 依赖 FlashAttention 的 varlen 接口做变长注意力，该掩码告诉模型"哪些 patch 位置是填充"，从而保证不同尺寸的行图可以组成一个 batch。

2. 文本侧：只给一个"开始"提示

做纯转写时通常不传text，此时AnandaProcessor.__call__会自动为每张图构造一个仅含BOS token（bos_token_id=151645）的input_ids，表示"从这里开始生成"（见 inference_processor.py）。

3. 最终输出

processor(images=image, return_tensors="pt")返回一个BatchFeature，包含 4 个字段，正好对应模型需要的全部输入：

input_ids, attention_mask, pixel_values, patch_attention_mask

四、快速上手：最小推理流程

把前面三节串起来，完整跑通 AnandaSky 只需四步（完整示例见 README.md 的 "Minimal Inference Example"）：

from PIL import Image import torch from transformers import AutoModelForCausalLM, AutoProcessor DEVICE = torch.device("cuda") DTYPE = torch.bfloat16 # 1. 加载模型（trust_remote_code 触发 auto_map 路由） model = AutoModelForCausalLM.from_pretrained( "badianeai/AnandaSky", trust_remote_code=True, torch_dtype=DTYPE ).to(DEVICE) # 2. 加载自定义 Processor（同样走 auto_map） processor = AutoProcessor.from_pretrained( "badianeai/AnandaSky", trust_remote_code=True ) # 3. 图像 → 4 个输入张量 image = Image.open("line_image.png") inputs = processor(images=image, return_tensors="pt") # 4. 生成并解码 with torch.no_grad(): output = model.generate(**inputs, use_cache=True) text = processor.decode(output[0, 1:], skip_special_tokens=True).strip() print(text)

其中processor.decode(...)会透传到内部 tokenizer（inference_processor.py），skip_special_tokens=True去掉特殊标记，得到干净的转写文本。

五、常见问题与最佳实践

🧭 新手记忆口诀

1. config.json里的auto_map= 路由表：决定Auto*用哪个自定义类；
2. trust_remote_code=True= 开关：允许transformers执行仓库内代码；
3. AnandaProcessor= 胶水层：把图片标准化/切 patch + 补齐、把文本转 token，产出模型generate()需要的全部张量。

掌握这三点，你不仅可以加载 AnandaSky，也具备了理解和迁移任何基于trust_remote_code机制发布的自定义视觉语言模型的能力。