DeepSeek-ViT权重分离与Timm加载实战

1. 为什么要把视觉塔权重拆给Timm——背景与动机

先说明一下这次要聊的具体场景。DeepSeek-V4.1 Flash 这个名字在社区里通常指 DeepSeek 系列里偏向多模态推理的 MoE 版本，它并不是单独发一个视觉模型，而是把语言主干和视觉编码器打包在同一份权重里。这份权重里的视觉编码器就是 DeepSeek-ViT，负责把图像转成视觉 token 序列，再交给语言模型去理解。真正动手做集成的时候，我们需要的往往只是 DeepSeek-ViT 这一块，而不是整套 MoE 权重。于是问题就来了：怎么从一整个大 checkpoint 里，把 DeepSeek-ViT 的权重干净地“抠”出来，并且让它能被 Timm 直接加载？

先说结论：这里不存在一个名为timm.create_model("deepseek_vit")的原生模型等你加载，至少到写这篇文章时还没有。Timm 官方仓库没有为 DeepSeek-ViT 单独注册过结构。所以“被 Timm 分离出来”并不是一件开箱即用的事，而是需要我们做三件事：第一，把 DeepSeek-ViT 的网络结构在 Timm 侧重建出来；第二，把官方 checkpoint 里带vision_model.前缀的键名重新映射成 Timm 模型内部使用的命名空间；第三，用非严格加载或者完全加载的方式，把权重灌进重建好的模型里，再做一次数值验证。整个过程做完之后，你就得到了一个可被 Timm 生态正常使用、可单独保存成state_dict的视觉塔权重文件。

那你可能要问，直接用官方仓库的 Vision Tower 类不就行了吗，为什么要绕道 Timm？我个人的看法是，Timm 的生态实在太方便了。不管是做图像分类的微调、接入检测分割模型，还是想跟社区里其他视觉模型做统一 baseline 对比，Timm 的模型工厂、预处理管线、EMA 和分类头工具都能直接复用。特别是当你想把 DeepSeek-ViT 和 SAM3、DINOv3 这类权重放在同一个 pipeline 里做特征对比时，统一走 Timm 接口可以少写一大堆适配代码。所以，把权重分离出来并转成 Timm 可加载的格式，不是说官方仓库不好，而是为了后面做工程实验更省事。

另外还有一个非常现实的问题：官方 repo 里的模型类通常和整套训练代码耦合，你加载 DeepSeek-ViT 的时候可能要连带拉起一堆依赖，比如特定的 tokenizer、特定的配置文件、特定的 transformer 版本。如果我们只关心视觉塔本身，把这些东西全部隔离掉才是最优解。把权重用 Timm 的标准格式重新保存，本质上就是做一次“结构解耦”，让视觉塔变成独立资产，之后无论接新任务还是做推理服务都干净利落。

1.1 先搞清楚“权重分离”的真实含义

所谓“权重分离”，不是拿个小刀把.safetensors文件切开，而是指：从一份完整的模型参数文件里，根据键名的前缀和网络块的边界，把属于视觉塔的那部分参数挑出来，再按照新的模型结构重新组织这些张量的名字和形状，最后另存为一份新的参数文件。这里有个容易被忽略的点：官方权重里的键名往往跟 Timm 模型的键名不完全一致，哪怕结构看起来差不多，也可能因为 Attention 层的 QKV 融合方式、LayerNorm 的 epsilon、甚至位置编码的实现细节，导致直接load_state_dict时出现一堆size mismatch和missing keys。

从工程经验来看，最稳妥的做法不是拿一个现成的 timm ViT 去硬套，而是先打印官方视觉塔的state_dict，把每一个 key 和对应的 tensor shape 列成一张表，再决定怎么映射。等这张表列清楚了，你会发现“分离权重”这件事本质上变成了“写一张键名映射表”。这也是我做这类转换时最核心的方法。

1.2 适合谁来读这篇文章

如果你正在做这三类事情，这篇文章会比较对味：一是想把 DeepSeek 系列多模态模型里的视觉编码器单独拎出来做特征提取；二是想在 Timm 生态里统一管理多个视觉塔，把 DeepSeek-ViT 和社区里的其他 ViT 做对比实验；三是刚刚接触权重转换，想搞明白 checkpoint 里那些长串键名到底对应网络里的哪一块。文章会尽量少堆术语，但涉及结构定义和键名映射的地方必须给到细节，因为这些细节才是实际操作时真正卡人的地方。

2. DeepSeek-ViT 的骨架结构与官方 checkpoint 的键名规律

开始写映射脚本之前，你需要对两部分内容心里有数：DeepSeek-ViT 的网络结构长什么样，以及官方权重文件里的键名命名规律是什么。缺了任何一块，后面都会变成盲人摸象。

DeepSeek-ViT 整体上是一个标准的 Vision Transformer，带 patch embedding、若干层 Transformer block、LayerNorm 和额外的位置编码。从 DeepSeek-VL 系列开源代码来看，它的视觉塔结构跟 SigLIP 那一路比较接近，patch size 是 16，输入分辨率常见的是 384 或 448，输出的是 patch token 序列。不同版本在层数、隐层维度和注意力头上会有差异，所以不建议在代码里写死参数，最好从官方配置里读取。

最关键的一点是，DeepSeek-ViT 的 Transformer block 里，Attention 部分通常把 Q、K、V 的投影拆成三个独立的线性层，而不是像常见 timm ViT 那样直接把三个矩阵拼成一个 fused QKV。这个差异直接决定了键名映射的难度。如果你把官方权重强行灌进 timm 默认的 fused QKV 结构里，q_proj.weight跟qkv.weight根本对不上，一个 768x768 的张量和一个 2304x768 的张量不可能直接复制过去。

2.1 官方权重的键名骨架

我以某个常见 DeepSeek-VL 版本为例，打印出一部分视觉塔的键名（具体版本会有差异，但规律一致）：

vision_model.embed_tokens.weight vision_model.embed_positions.weight vision_model.encoder.layers.0.input_layernorm.weight vision_model.encoder.layers.0.input_layernorm.bias vision_model.encoder.layers.0.self_attn.q_proj.weight vision_model.encoder.layers.0.self_attn.k_proj.weight vision_model.encoder.layers.0.self_attn.v_proj.weight vision_model.encoder.layers.0.self_attn.out_proj.weight vision_model.encoder.layers.0.post_attention_layernorm.weight vision_model.encoder.layers.0.mlp.gate_proj.weight vision_model.encoder.layers.0.mlp.up_proj.weight vision_model.encoder.layers.0.mlp.down_proj.weight vision_model.encoder.layers.1.input_layernorm.weight ...

看到这个结构，你基本就明白为什么不能直接加载了。vision_model是外层包裹，encoder.layers.N是 Transformer 层，input_layernorm是 Attention 前的 norm，post_attention_layernorm是 MLP 前的 norm。self_attn里 QKV 三个投影分开，MLP 是 gate/up/down 三层的 SwiGLU 结构。这套命名明显更接近大语言模型的惯例，而不是经典 ViT 的命名。

2.2 位置编码与 Embedding 的形态

embed_tokens.weight不是通常意义上的 text embedding，它是 patch embedding 的卷积权重，形状一般是(hidden_size, in_channels, patch_size, patch_size)。这个跟 timm 里patch_embed.proj.weight的形状一致。而embed_positions.weight是位置编码表，形状是(num_positions, hidden_size)，num_positions 等于 patch 数加一还是不加一，取决于官方实现里有没有预留 cls token。

这些细节会在映射时决定很多东西。比如，你可以选择直接把位置编码表重命名后塞给 Timm 的pos_embed，但如果官方在位置编码里做了插值或特殊处理，直接塞过去可能会让效果打折扣。稳妥的做法是：把位置编码表拿出来，用同样的方式重新初始化并复制数值，确保不丢失信息。

2.3 分离前先做一次“结构归一化”

考虑到不同版本的 DeepSeek-ViT 配置可能不一样，我强烈建议你写一个简单的脚本，先把官方 checkpoint 里所有vision_model.开头的键打印出来另存为 JSON，然后对着 JSON 人工校对一遍结构。这一步虽然枯燥，但能省掉后面大量的调试时间。特别是你换一个版本的时候，键名可能从vision_model改成vision_tower，从self_attn改成attention，不校对直接写映射函数等于埋雷。

结构归一化还包含一层意思：你要决定好目标模型用什么样的 block 布局。我的建议是优先保留官方结构，也就是 QKV 分离、SwiGLU MLP 这种写法，然后通过自定义模型的方式把它注册进 Timm，而不是强行向 timm 默认配置靠拢。后者虽然写起来少，但等效性验证会非常痛苦。

3. 在 Timm 侧构造一个与 DeepSeek-ViT 几何一致的视觉塔

搞清楚官方结构之后，下一步是在 Timm 侧拿到一个“键名空间对齐”的模型。这里不需要重新发明轮子，Timm 本身提供了模型工厂和注册机制，我们只需要按官方结构写一个自定义类，然后把它注册进 Timm 的模型表里。

3.1 Timm 的模型工厂到底做了什么

timm.create_model并不是魔法，它的本质是根据模型名字去一个全局注册表里查找对应的构造函数，然后传入参数并返回模型实例。注册表的键就是模型名。所以要让 Timm 认识 DeepSeek-ViT，我们只需要做两件事：第一步，定义模型类；第二步，用timm.models.registry.register_model给它起一个名字，例如deepseek_vit_timm。之后你就可以像调用内置模型一样调用它，timm.create_model("deepseek_vit_timm", ...)。

这里有一个推荐的做法是继承timm.models.vision_transformer.VisionTransformer，然后重写 Attention 和 MLP 部分，让它们匹配官方结构。我最初是直接从零写了一个完整的 ViT 类，后来发现维护成本太高，跟 timm 预处理和 feature map 接口接不上。参考 timm 已有代码风格做继承改造，是最省力的。

3.2 写一个匹配官方结构的自定义 Attention

因为官方把 QKV 拆开，我们的自定义 Attention 也拆开。核心代码如下（示意）：

import torch import torch.nn as nn from timm.models.vision_transformer import VisionTransformer class DeepSeekViTAttention(nn.Module): def __init__(self, dim, num_heads=16, qkv_bias=True): super().__init__() self.num_heads = num_heads head_dim = dim // num_heads self.scale = head_dim ** -0.5 self.q_proj = nn.Linear(dim, dim, bias=qkv_bias) self.k_proj = nn.Linear(dim, dim, bias=qkv_bias) self.v_proj = nn.Linear(dim, dim, bias=qkv_bias) self.out_proj = nn.Linear(dim, dim, bias=True) def forward(self, x): B, N, C = x.shape q = self.q_proj(x).reshape(B, N, self.num_heads, C // self.num_heads).permute(0, 2, 1, 3) k = self.k_proj(x).reshape(B, N, self.num_heads, C // self.num_heads).permute(0, 2, 1, 3) v = self.v_proj(x).reshape(B, N, self.num_heads, C // self.num_heads).permute(0, 2, 1, 3) attn = (q @ k.transpose(-2, -1)) * self.scale attn = attn.softmax(dim=-1) x = (attn @ v).transpose(1, 2).reshape(B, N, C) x = self.out_proj(x) return x

对应的 MLP 也要改成 SwiGLU 结构：

class DeepSeekViTMLP(nn.Module): def __init__(self, dim, hidden_dim): super().__init__() self.gate_proj = nn.Linear(dim, hidden_dim, bias=False) self.up_proj = nn.Linear(dim, hidden_dim, bias=False) self.down_proj = nn.Linear(hidden_dim, dim, bias=True) def forward(self, x): return self.down_proj(nn.functional.silu(self.gate_proj(x)) * self.up_proj(x))

这个结构就是照着官方权重键名来的。之后把这两个模块嵌进一个 ViT 主类，注册给 Timm，目标模型就准备好了。注意这里的dim、num_heads、depth等参数不要自己猜，直接从官方配置读取，如果找不到配置文件，就根据权重 shape 反推。比如q_proj.weight.shape == (D, D)，那dim就是 D；gate_proj.weight.shape == (M, D)，那 hidden_dim 就是 M。

3.3 注册进 Timm 并检查键名

把模型定义好后，注册代码如下：

import timm from timm.models.registry import register_model @register_model def deepseek_vit_timm(pretrained=False, **kwargs): model = DeepSeekViTForTimm(**kwargs) if pretrained: load_custom_state_dict(model, kwargs.get("checkpoint_path", "")) return model model = timm.create_model("deepseek_vit_timm", img_size=384, patch_size=16, depth=24, embed_dim=1024, num_heads=16)

然后立刻打印一遍model.state_dict().keys()，跟官方视觉塔的键名做 diff。如果只是前缀不同，后面都好办；如果出现结构差异，比如键名数量对不上、某个层多了 bias 而官方没有，那就现在修模型定义，不要拖到加载阶段再处理。这一步的核心目标是让两份state_dict在键级别上完全对齐，最多只差前缀和顺序。

4. 权重重映射的完整实操流程

模型构造好了，接下来就是最硬核的环节：写重映射函数，把官方权重转成 Timm 权重。这一步我会给出一个通用的流程，并强调几个容易出错的地方。

4.1 明确映射关系表

先手工整理一份映射关系，举个例子：

官方键 Timm 键 vision_model.embed_tokens.weight patch_embed.proj.weight vision_model.embed_positions.weight pos_embed vision_model.encoder.layers.{i}.input_layernorm.weight blocks.{i}.norm1.weight vision_model.encoder.layers.{i}.input_layernorm.bias blocks.{i}.norm1.bias vision_model.encoder.layers.{i}.self_attn.q_proj.weight blocks.{i}.attn.q_proj.weight vision_model.encoder.layers.{i}.self_attn.k_proj.weight blocks.{i}.attn.k_proj.weight vision_model.encoder.layers.{i}.self_attn.v_proj.weight blocks.{i}.attn.v_proj.weight vision_model.encoder.layers.{i}.self_attn.out_proj.weight blocks.{i}.attn.out_proj.weight vision_model.encoder.layers.{i}.post_attention_layernorm.weight blocks.{i}.norm2.weight vision_model.encoder.layers.{i}.post_attention_layernorm.bias blocks.{i}.norm2.bias vision_model.encoder.layers.{i}.mlp.gate_proj.weight blocks.{i}.mlp.gate_proj.weight vision_model.encoder.layers.{i}.mlp.up_proj.weight blocks.{i}.mlp.up_proj.weight vision_model.encoder.layers.{i}.mlp.down_proj.weight blocks.{i}.mlp.down_proj.weight

注意，这张表里norm1和norm2的对应关系是假设官方结构里input_layernorm在 attention 前、post_attention_layernorm在 MLP 前。如果你打印出的配置文件不是这个顺序，一定要以自己的打印结果为准。

4.2 重映射函数代码

下面这段函数是我实际用的映射逻辑，可以作为一个起点。它的思路很简单：遍历旧 state_dict，用正则把带vision_model前缀的键替换成新前缀，同时处理embed_tokens、embed_positions这样特殊的键。

import re import torch def remap_deepseek_vit_state_dict(src_state: dict) -> dict: dst_state = {} for key, value in src_state.items(): if not key.startswith("vision_model."): continue new_key = None # 处理 embedding 部分 if key == "vision_model.embed_tokens.weight": new_key = "patch_embed.proj.weight" elif key == "vision_model.embed_positions.weight": new_key = "pos_embed" else: # 处理 encoder 内部 m = re.match( r"vision_model\.encoder\.layers\.(\d+)\.(.*)", key ) if m: layer_idx = int(m.group(1)) rest = m.group(2) rest = rest.replace("input_layernorm", "norm1") rest = rest.replace("post_attention_layernorm", "norm2") rest = rest.replace("self_attn.q_proj", "attn.q_proj") rest = rest.replace("self_attn.k_proj", "attn.k_proj") rest = rest.replace("self_attn.v_proj", "attn.v_proj") rest = rest.replace("self_attn.out_proj", "attn.out_proj") rest = rest.replace("mlp.gate_proj", "mlp.gate_proj") rest = rest.replace("mlp.up_proj", "mlp.up_proj") rest = rest.replace("mlp.down_proj", "mlp.down_proj") new_key = f"blocks.{layer_idx}.{rest}" else: continue dst_state[new_key] = value return dst_state

这里有几条经验值得分享。一是千万不要试图一句代码解决所有映射，不同版本的前缀改动非常隐蔽，最稳妥的是写完后打印一份新字典的键，跟目标模型逐行对比。二是如果发现pos_embed的形状不一致，比如官方位置编码表是(num_patches + 1, hidden)而 timm 是(1, num_patches + 1, hidden)，需要手动 reshape 并补上 batch 维，这步不能省略。三是如果目标模型参数里没有 bias 而原权重里有，或者反过来，说明模型定义和官方不一致，要回到第 3 章改模型结构，而不是在这里偷懒丢弃参数。

4.3 从完整 checkpoint 里抽取视觉塔

很多情况下你手头不是一个单独视觉塔权重文件，而是整个 DeepSeek-V4.1 Flash 的合并权重。这时需要先按前缀抽取，再映射。抽取代码很简单：

full_state = torch.load("DeepSeek-V4.1-Flash.safetensors", map_location="cpu") # 如果用的是 safetensors，建议用 safe_open 按 key 读取，避免一次性占满内存 vision_keys = [k for k in full_state.keys() if k.startswith("vision_model.")] vision_state = {k: full_state[k] for k in vision_keys} mapped_state = remap_deepseek_vit_state_dict(vision_state)

这里额外提一个细节：如果整个 checkpoint 特别大，比如几十个 GB，用torch.load直接读进来内存会爆。这种场景下建议用safetensors的safe_open流式读取，只挑vision_model.开头的张量读入，其他全部跳过。工程上这是很关键的一步，不要等到 OOM 了才后悔。

4.4 清洗掉不参与加载的辅助键

官方权重里经常会有num_batches_tracked、running_mean、running_var这类 BN 统计量，以及一些loss、global_step之类的元数据。ViT 里如果没有 BN 层，这些东西都要过滤掉。我的做法是在映射函数末尾加一行：

dst_state = {k: v for k, v in dst_state.items() if not k.endswith("num_batches_tracked")}

另外有些官方权重会带module.前缀（如果是训练脚本用了 DataParallel），这一步也要在映射前剥掉。判断方式是先打印任意一个 key，如果看到module.vision_model.，就在startswith判断前先统一去掉module.。

5. 从“能加载”到“真的对”——验证与常见坑

权重转换最怕的就是“能跑但不对”：模型能加载、能前向，但输出特征跟官方实现差一截。这种问题往往不是加载环节出错，而是结构等效性没做到位。

5.1 数值验证方法

拿到映射后的权重并成功load_state_dict之后，不要直接拿去微调，先做一次数值验证。验证方法很简单：准备一张相同尺寸的输入图（或者相同 shape 的随机张量），分别用官方视觉塔和 Timm 侧模型跑 forward，对比最后一层输出的 mean、std 和最大绝对误差。如果最大绝对误差在 1e-4 量级以内，基本可以认为对齐了；如果在 1e-1 量级，那就要查一些隐蔽差异。

有一个偷懒但非常高效的验证技巧：不需要真的跑一整个模型，可以只对比第一层 block 的输出，把误差定位得更细。比如加载完权重后，把官方模型和 timm 模型的blocks.0.norm1输出分别打印出来，看看是 embedding 阶段就歪了，还是 attention 阶段才歪。

5.2 那些让人血压飙升的坑

第一个高频坑是 LayerNorm 的 epsilon 不同。官方唐代实现经常用 1e-5 或 1e-6，而 timm 个别默认配置可能不一样。这个差异平时看不出来，但在对比宽松模型时，误差会叠加到不可忽略的程度。解决办法很简单：在模型配置里显式传入norm_eps，并且在加载前打印官方模型vision_model.encoder.layers[0].input_layernorm.eps，确保两边一致。

第二个高频坑是 attention bias。DeepSeek 系列某些视觉塔会在 self-attention 里加上 attention bias 或者相对位置 bias，这些 bias 可能存在于self_attn的额外参数里，也可能由位置编码动态生成。如果你在官方 state_dict 里看到类似self_attn.relative_attention_bias.weight或self_attn.attention_bias的键，而你的 Timm 模型里没有对应参数，那就是结构还没对齐。不要简单丢弃这些权重，应该在 Attention 模块里补上对应逻辑，否则长序列输入时位置信息会丢失。

第三个高频坑是 dtype 问题。官方权重可能以 bf16 精度存储，而你的加载脚本默认用 float32 创建模型。直接加载对数值影响不大，但如果之后要跟官方推理结果做精确对比，务必在验证时保持同一 dtype。我的建议是验证脚本里统一用model.to(torch.bfloat16)，再做对比，避免 dtype 带来的尾差干扰判断。

5.3 手动逐层对比的检查清单

如果加载后数值对不上，我一般按这个顺序排查：

1. 检查映射表本身：把官方 key 和 timm key 逐行打印，确认没有漏映射。
2. 检查pos_embed是否需要插值：输入分辨率不同会导致位置编码数量不同，这时需要做 position interpolation。
3. 检查patch_embed的卷积 stride 和 padding：如果官方是padding=0而 timm 默认是padding=1，那输出序列长度直接不同。
4. 检查 attention 里是否存在use_fused_attn的数值分支，不同的 kernel 实现可能有微小差异。
5. 最后才怀疑权重数值本身写错了：可以随机取某层权重，用torch.equal对比原始值和新保存的值。

这个排查顺序能帮你避免在错误方向上浪费时间。

6. 分离后的权重文件怎么保存和组织

当验证通过后，剩下的问题就是如何把分离出来的权重保存成一个持久化的资产文件，方便后续复用。

推荐格式仍然是safetensors。保存代码：

from safetensors.torch import save_file save_file(mapped_state, "deepseek_vit_timm.safetensors")

同时建议把一份 JSON 格式的模型配置一起保存，里面至少包含img_size、patch_size、depth、embed_dim、num_heads、mlp_hidden_dim、norm_eps、qkv_bias这些字段。这样以后加载时不需要再去翻官方 repo，直接读配置就能重建模型。如果你打算注册成 timm 的预训练模型，可以在register_model里头处理一份pretrained_cfg，指向这个 safetensors 文件，这样timm.create_model("deepseek_vit_timm", pretrained=True)就能直接用了。这种做法也是社区里加载 DINOv3、SAM3 权重时的常见路径。

还有一个小建议：保存的时候顺手把权重里所有 key 的 shape 打印到日志里留档。这个 shape 清单在你日后换机器、升级库、对比不同版本时非常有用，相当于给权重做了一份“X 光片”。

7. 一点实际操作上的体会

最后分享一个我个人的感受。权重转换这类工作并不复杂，真正的难度在“细心”二字。你写的映射函数可能只有两三行，但真正花时间的永远是核对结构、核对键名、核对数值。我做过好多次转换，最后发现数值不对，往往不是因为代码写错，而是因为一开始没有把官方模型和 Timm 模型的参数列表并排打印出来，全靠眼睛脑补结构。

所以如果你也想做这件事，我的建议是不要跳步。第一步打印官方 state_dict，第二步打印 timm state_dict，第三步写映射脚本，第四步数值验证。每一步都留下日志。只要你严格按照这个节奏走，DeepSeek-ViT 的权重分离不会成为卡住你的问题。把这套方法跑通之后，你会发现它不光适用于 DeepSeek-ViT，任何结构差异较大的权重转换都可以照搬这个流程。