模型训练收工的那一刻，通常是最开心的；接下去要把模型送上线，才是最磨人的。手里一个小众模型，训练时用的自定义框架，checkpoint 命名随心所欲，架构和主流模型有那么点像又不完全一样。你想用 vLLM 上线，启动脚本直接报错“Model architectures are not supported”；换回原项目自带的推理脚本，单请求低吞吐，批处理调度、显存管理全得自己写。于是只好硬着头皮打开 vLLM 源码，研究怎么把一个自定义模型塞进去。

这篇文章就是完整记录这件事的做法。我会拿一个完全虚构、但结构上很典型的小众因果语言模型 MiniStream 作为例子，从权重转换、模型类编写、注册机制到启动验证，把“从零给 vLLM 添加自定义模型推理支持”的完整链路捋一遍。适合三类人：被“不支持的架构”卡住的部署工程师，想把自己训练的模型接入 vLLM 的算法同学，以及想搞懂 vLLM 模型适配机制的框架学习者。

1. 为什么“加模型支持”这件事绕不开

1.1 小众模型上线的两条死路

先说一个现实：vLLM 的高吞吐能力，本质上来自它对模型结构做了大量假设和预优化。连续批处理、paged KV cache、量化、算子融合，这些都是按主流 decoder-only 架构的规律去设计的。你的模型越是“长得像主流模型”，接入成本越低；越是个性化，越要自己动手补适配层。

小众模型常见的困境是两条路都不好走。

第一条路是用原项目自带推理脚本上线。论文代码也好、内部实验代码也好，大部分只保证“能跑”而不是“跑得快”。单条请求推理时，GPU 利用率经常只有个位数百分比；同时来十个请求，内存翻倍、速度骤降。想支持流式输出、多轮对话、并发排队，都得自己搭。最要命的是显存里的 KV cache 每次请求都要重新算，长对话根本扛不住。这条路对小模型或许能撑，模型一上亿参数就非常难受。

第二条路是用通用推理框架跑，但挑一个“看起来支持”的。很多框架只支持固定名单里的模型，要么你的模型压根不在列表里，要么得走 ONNX/TensorRT 导出，精度和算子覆盖又容易出问题。好不容易导出成功，模型里一个自定义位置编码可能就让整条链路废掉。折腾半天，最后还是回到原点。

相比之下，直接给 vLLM 写一个模型适配文件，一次性投入，之后就能吃到 vLLM 整套调度和显存管理红利，这是性价比最高的路径。只是这活儿有个门槛：你得先搞清楚 vLLM 到底是怎么“认识”一个模型的。

1.2 vLLM 认识模型的最小链条

很多人以为 vLLM 支持某个模型是靠“扫描模型文件自动识别”，其实完全不是。它内部维护了一张注册表，这张表把“模型架构名”映射到“模型类”。你调用 LLM(model=...) 时，引擎会走一条固定的识别链路：

1. 读取模型目录下的 config.json，拿到 architectures 字段，比如 ["MiniStreamForCausalLM"]。
2. 拿这个架构名去模型注册表里查，看有没有注册过对应的类。
3. 查到了，就用配置文件实例化这个模型类，然后调用它的 load_weights 方法把权重灌进去。
4. 查不到，直接抛“Model architectures are not supported”。

所以“给 vLLM 加一个模型”这个任务，拆开其实就是四件事：写一个模型类、把它注册到注册表、保证配置文件能被正确解析、实现权重加载逻辑。其中权重加载通常是最耗时的，因为你的 checkpoint 命名几乎一定和 vLLM 期望的不一样。

这个链路听起来简单，实际做起来处处是细节。下面把四个关键点一个个说清楚。

2. 动手前必须摸清的四个关键点

2.1 模型类长什么样

先看一个最小可用的模型类长什么样。以 vLLM 0.6.x 这个相对稳定的版本为例，模型类一般长这样：

import torch import torch.nn as nn from transformers import PretrainedConfig from vllm.model_executor.models.registry import ModelRegistry from vllm.model_executor.layers.linear import ColumnParallelLinear from vllm.model_executor.layers.sampler import Sampler @ModelRegistry.register_model("MiniStreamForCausalLM") class MiniStreamForCausalLM(nn.Module): def __init__(self, config: PretrainedConfig, cache_config=None): super().__init__() self.config = config self.model = MiniStreamModel(config) self.lm_head = ColumnParallelLinear( config.hidden_size, config.vocab_size, bias=False ) self.sampler = Sampler() def forward(self, input_ids, positions, kv_caches, attn_metadata, **kwargs): hidden_states = self.model(input_ids, positions, kv_caches, attn_metadata) return hidden_states def compute_logits(self, hidden_states, sampling_metadata): return self.lm_head(hidden_states) def sample(self, logits, sampling_metadata): return self.sampler(logits, sampling_metadata) def load_weights(self, weights): # 核心工作量都在这 pass

几个容易被忽略的细节：

• forward 不直接返回 logits，而是返回最后一层 hidden states。后续的 logits 计算和采样由 compute_logits、sample 这两个方法负责，这是 vLLM 为了做采样处理、logits processor 而设计的拆分。
• init里那个 cache_config 参数，有的版本有，有的版本没有。保险写法是给它默认值 None，避免不同版本实例化时报参数数量不匹配。
• 注册装饰器里的字符串必须和 config.json 里 architectures[0] 完全一致，大小写、空格都得一样，否则注册了也找不到。

2.2 权重映射才是真正的重头戏

模型类说白了是个空壳，真正让一个模型跑起来的是权重映射。vLLM 加载权重时，会把 checkpoint 里的每个参数按名字喂给 load_weights，你要做的就是把 checkpoint 名字翻译成你的模型参数名，再把数据拷进去。

最朴素的写法是：

def load_weights(self, weights): params_dict = dict(self.named_parameters()) for item in weights: name = getattr(item, "name", item[0]) loaded_weight = getattr(item, "loaded_weight", item[1]) if name in params_dict: params_dict[name].data.copy_(loaded_weight)

为什么这里是重头戏？因为绝大多数自定义 checkpoint 不会按照“model.layers.0.self_attn.q_proj.weight”这种规范命名。我见过太多情况：

• QKV 是融合成一个 Wqkv.weight 矩阵，需要拆成 q_proj、k_proj、v_proj 三份；
• 门控 MLP 的两个权重拼在一起，需要拆成 gate_proj 和 up_proj；
• embedding 和 lm_head 是权重绑定的，checkpoint 里只存一份；
• 层编号从 1 开始而不是从 0 开始；
• 还有直接把 bias、scale 之类参数塞进同一个文件里的。

你每遇到一种情况，就要在 load_weights 里加一个分支去处理和翻译。如果模型有 30 多层，每一层都这样处理，分支代码会很长，但逻辑本身并不复杂。关键是先把 checkpoint 的键名和模型参数名两边都打印出来，做一次差集，心里有数再动手。

2.3 config.json 别靠猜

vLLM 读配置的方式是：先尝试用 transformers 生态的标准配置读取，再拿着里面的字段去实例化模型类。所以 config.json 里的字段质量直接决定后面是否顺利。

一份能用的 config.json 至少得包含这些：

{ "architectures": ["MiniStreamForCausalLM"], "model_type": "ministream", "hidden_size": 768, "num_hidden_layers": 8, "num_attention_heads": 12, "num_key_value_heads": 12, "head_dim": 64, "intermediate_size": 2048, "vocab_size": 32000, "max_position_embeddings": 2048, "rms_norm_eps": 1e-6, "rope_theta": 10000.0, "bos_token_id": 1, "eos_token_id": 2, "tie_word_embeddings": true }

我这里特别提醒三个坑。

第一个坑是 head_dim。很多模型 config 里不写 head_dim，而是靠 hidden_size 除以 num_attention_heads 去推算。如果你的模型里 head_dim 和这个除法结果不一致，就得显式写上，否则注意力计算会直接形状不匹配。

第二个坑是 architectures 字段。有些实验代码导出的 config 里，architectures 写的是训练脚本里的类名，比如 “MiniStreamTrainerModel”，跟推理模型类名完全对不上。vLLM 只会拿这个字段去注册表里查，名字对不上就是 not supported。

第三个坑是 tie_word_embeddings。如果你的模型 embedding 和 lm_head 是共享权重的，而 vLLM 模型实现里两者是独立参数，那么加载时要人为复制一份权重。这个处理不好，会出现“生成时第一个词概率异常”这类极难排查的问题。

2.4 注意力能不能复用，决定你后面省不省心

给 vLLM 写模型类，最大的性能分水岭在于注意力层怎么实现。

如果你的模型用的是标准 RoPE + MHA/GQA，直接复用 vLLM 的 Attention 层就好，paged KV cache、前缀缓存、滑动窗口这些能力全部自动生效。这是最理想的情况。

如果你的模型有特殊的位置编码、特殊 attention mask 或者需要往 attention score 里加额外的 bias，就得斟酌了。vLLM 的 Attention 层封装了下层各种后端，不是所有自定义行为都支持。有人选择回到 PyTorch 原生实现，比如 F.scaled_dot_product_attention，这样功能上没问题，模型照样能跑，但你会失去 paged KV cache 的优势，KV cache 显存占用和推理延迟都会明显变差。

我的建议是分两步走：第一版先保证能跑通，哪怕用原生注意力实现；跑通之后再回过头来，看能不能把特殊注意力行为改造到 vLLM Attention 支持的范围内。别一上来就追求完美性能，先让整条链路活起来。

3. 实操：把一个非标准 checkpoint 接进 vLLM

3.1 样例模型：MiniStream 与原始权重结构

现在进入实战。假设我们手里有个内部训练的小模型 MiniStream，参数量约 1.3 亿，结构不复杂：standard decoder-only，8 层 Transformer，hidden size 768，12 个注意力头，SwiGLU 激活，RMSNorm，RoPE 位置编码。结构上一点都不特殊，但 checkpoint 格式非常“实验风”。

原始 checkpoint 是单个 model.pt 文件，键名长这样：

• embedding.weight：形状 [32000, 768]
• blocks.0.attn.Wqkv.weight：形状 [2304, 768]，Q、K、V 按行顺序拼在一起
• blocks.0.attn.out_proj.weight：形状 [768, 768]
• blocks.0.mlp.w12.weight：形状 [4096, 768]，SwiGLU 的两个门控矩阵拼在一起
• blocks.0.mlp.w3.weight：形状 [768, 2048]
• blocks.0.norm1.weight、blocks.0.norm2.weight：形状 [768]
• 没有独立的 lm_head，embedding 与输出头共享权重

也就是说，训练框架导出时完全按“角色”命名，不关心 transformers 生态的命名规范。我们要做的第一件事，就是写个脚本把它翻译成 vLLM 能消化的 HF 风格权重。

3.2 第一步：写权重转换脚本

转换脚本的逻辑很简单：逐个键名做映射。需要特别注意的是 Wqkv 融合矩阵和 w12 融合矩阵的处理方式。

import torch from safetensors.torch import save_file raw = torch.load("mini-stream-132m/model.pt", map_location="cpu") raw = raw["model"] if "model" in raw else raw mapped = {} mapped["model.embed_tokens.weight"] = raw["embedding.weight"] mapped["lm_head.weight"] = raw["embedding.weight"] # tied 权重，存两份 hidden_size = 768 mid = hidden_size # 因为 MiniStream 是 MHA，Q/K/V 各占 hidden_size intermediate = 2048 for i in range(8): src = f"blocks.{i}" dst = f"model.layers.{i}" fused_qkv = raw[f"{src}.attn.Wqkv.weight"] # [2304, 768] q, k, v = torch.split(fused_qkv, [hidden_size, hidden_size, hidden_size], dim=0) mapped[f"{dst}.self_attn.q_proj.weight"] = q mapped[f"{dst}.self_attn.k_proj.weight"] = k mapped[f"{dst}.self_attn.v_proj.weight"] = v mapped[f"{dst}.self_attn.o_proj.weight"] = raw[f"{src}.attn.out_proj.weight"] w12 = raw[f"{src}.mlp.w12.weight"] # [4096, 768]，对应 gate_up_proj mapped[f"{dst}.mlp.gate_up_proj.weight"] = w12 mapped[f"{dst}.mlp.down_proj.weight"] = raw[f"{src}.mlp.w3.weight"] mapped[f"{dst}.input_layernorm.weight"] = raw[f"{src}.norm1.weight"] mapped[f"{dst}.post_attention_layernorm.weight"] = raw[f"{src}.norm2.weight"] save_file(mapped, "mini-stream-hf/model.safetensors")

转完之后别急着进 vLLM，先把 config.json 和 tokenizer 相关文件准备好，目录结构如下：

mini-stream-hf/ ├── config.json ├── model.safetensors ├── tokenizer.json └── tokenizer_config.json

这一步完成后，最好先用 transformers 生态的参考实现把转换后的权重跑一遍，生成一个 greedy 结果存下来。这叫“黄金输出”，后面验证 vLLM 接入是否正确就用它对比。

3.3 第二步：写模型类并注册

模型类的完整代码会包含三个部分：基础模块（注意力、MLP、层）、顶层模型、以及注册入口。MiniStream 结构不特殊，注意力可以直接用 vLLM 的 Attention 层。下面是完整实现思路。

from vllm.model_executor.layers.activation import SiluAndMul from vllm.model_executor.layers.layernorm import RMSNorm from vllm.model_executor.layers.linear import ColumnParallelLinear, RowParallelLinear from vllm.model_executor.layers.vocab_parallel_embeddings import VocabParallelEmbedding from vllm.attention.layer import Attention class MiniStreamAttention(nn.Module): def __init__(self, config): super().__init__() self.hidden_size = config.hidden_size self.num_heads = config.num_attention_heads self.head_dim = config.head_dim self.q_proj = ColumnParallelLinear(self.hidden_size, self.hidden_size, bias=False) self.k_proj = ColumnParallelLinear(self.hidden_size, self.hidden_size, bias=False) self.v_proj = ColumnParallelLinear(self.hidden_size, self.hidden_size, bias=False) self.o_proj = RowParallelLinear(self.hidden_size, self.hidden_size, bias=False) self.attn = Attention(self.num_heads, self.head_dim) def forward(self, hidden_states, positions, kv_cache, attn_metadata): q, _ = self.q_proj(hidden_states) k, _ = self.k_proj(hidden_states) v, _ = self.v_proj(hidden_states) q = q.view(-1, self.num_heads, self.head_dim) k = k.view(-1, self.num_heads, self.head_dim) v = v.view(-1, self.num_heads, self.head_dim) out = self.attn(q, k, v, kv_cache, attn_metadata) out = out.view(-1, self.hidden_size) out, _ = self.o_proj(out) return out class MiniStreamMLP(nn.Module): def __init__(self, config): super().__init__() self.gate_up_proj = ColumnParallelLinear( config.hidden_size, 2 * config.intermediate_size, bias=False ) self.act_and_mul = SiluAndMul() self.down_proj = RowParallelLinear( config.intermediate_size, config.hidden_size, bias=False ) def forward(self, x): x, _ = self.gate_up_proj(x) x = self.act_and_mul(x) x, _ = self.down_proj(x) return x class MiniStreamDecoderLayer(nn.Module): def __init__(self, config): super().__init__() self.input_layernorm = RMSNorm(config.hidden_size, eps=config.rms_norm_eps) self.self_attn = MiniStreamAttention(config) self.post_attention_layernorm = RMSNorm(config.hidden_size, eps=config.rms_norm_eps) self.mlp = MiniStreamMLP(config) def forward(self, hidden_states, positions, kv_cache, attn_metadata): residual = hidden_states hidden_states = self.input_layernorm(hidden_states) hidden_states = self.self_attn(hidden_states, positions, kv_cache, attn_metadata) hidden_states = residual + hidden_states residual = hidden_states hidden_states = self.post_attention_layernorm(hidden_states) hidden_states = self.mlp(hidden_states) hidden_states = residual + hidden_states return hidden_states class MiniStreamModel(nn.Module): def __init__(self, config): super().__init__() self.embed_tokens = VocabParallelEmbedding( config.vocab_size, config.hidden_size ) self.layers = nn.ModuleList([ MiniStreamDecoderLayer(config) for _ in range(config.num_hidden_layers) ]) self.norm = RMSNorm(config.hidden_size, eps=config.rms_norm_eps) def forward(self, input_ids, positions, kv_caches, attn_metadata): hidden_states = self.embed_tokens(input_ids) for i, layer in enumerate(self.layers): hidden_states = layer(hidden_states, positions, kv_caches[i], attn_metadata) hidden_states = self.norm(hidden_states) return hidden_states

现在把最关键的 load_weights 补上。因为转换脚本已经把 fused 的 Wqkv 拆成了 q/k/v 三份，所以 load_weights 里大部分情况是直接拷贝，只有两个地方需要特殊处理：lm_head 是 tied 的，embedding 和 lm_head 用同一份权重；还有 gate_up_proj 这个参数名要认出来。

def load_weights(self, weights): params_dict = dict(self.named_parameters()) for item in weights: name = getattr(item, "name", item[0]) loaded_weight = getattr(item, "loaded_weight", item[1]) if name == "model.embed_tokens.weight": params_dict["model.embed_tokens.weight"].data.copy_(loaded_weight) params_dict["lm_head.weight"].data.copy_(loaded_weight) continue if name in params_dict: params_dict[name].data.copy_(loaded_weight)

为什么可以这么简单？因为我们在转换脚本里已经把命名统一成了 vLLM 模型类里的参数名。这是最推荐的做法：能通过转换脚本解决的问题，就不要在 load_weights 里堆分支。

注册方式有两种。一种是直接把 ministream.py 放进 vLLM 源码目录 vllm/model_executor/models/ 下，并在该目录的init.py 里加一行 import。这个办法最省事，但每次升级 vLLM 都要重新打补丁。另一种是写成独立的 Python 包，在调用 LLM 之前的启动脚本里先 import 你的模型模块，让 @ModelRegistry.register_model 装饰器在引擎启动前完成注册。第二种更干净，我后来一直用这种。

3.4 第三步：启动推理与正确性验证

代码写完之后，直接用 vLLM 启动：

from vllm import LLM, SamplingParams llm = LLM( model="./mini-stream-hf", dtype="bfloat16", max_model_len=2048, enforce_eager=True, # 调试阶段先关掉 CUDA Graph gpu_memory_utilization=0.8, ) prompts = ["请用一句话介绍你自己。", "解释一下什么是 KV Cache。"] outputs = llm.generate(prompts, SamplingParams(max_tokens=64, temperature=0.2)) for o in outputs: print(o.outputs[0].text)

如果这里能正常输出，恭喜，最难的 90% 已经过了。但“能输出”不等于“输出正确”。我强烈建议做一次黄金输出对比：拿转换后的 model.safetensors 加载进参考实现，用同一个 prompt、同样的采样参数（最好 temperature=0 的 greedy）生成一份结果，再和 vLLM 的输出逐 token 对比。

我第一次接入模型时，输出看起来通顺，但首 token 命中率只有七成左右。后来发现是注意力缩放系数里用了 hidden_size 的平方根，而原模型用的是 head_dim 的平方根。这类问题靠肉眼几乎不可能发现，只能靠机械对比。

4. 验证跑通之后：性能与版本差异

4.1 性能表现怎么看

正确性过了之后，把 enforce_eager 关掉，恢复 CUDA Graph，再重新跑一遍。这时候你会看到吞吐明显提升。再检查几个点：

第一，确认你的注意力层确实走到了 vLLM 的 Attention。MiniStream 是标准 MHA，所以 paged KV cache、前缀缓存都能直接用。如果你的模型用了 SDPA 兜底，性能会差一大截，那就得回头想想怎么把特殊结构标准化。

第二，看 KV cache 显存占用。vLLM 启动时会自动计算 KV cache 大小，但如果你的 max_model_len 设得很大，KV cache 会吃掉大量显存。可以从 gpu_memory_utilization、max_num_seqs、max_model_len 三个参数入手调整。

第三，想上多卡张量并行的话，load_weights 的写法要升级。上面的例子在单卡下没问题，多卡时 ColumnParallelLinear 的参数会被切分，你需要处理每个 rank 拿到对应分片。最简单的方式是参考同版本 vLLM 官方模型文件里对 weight_loader 的处理，把每个参数的加载交给 weight_loader，而不是直接对 param.data 整体 copy。这里我建议直接抄同版本 LLaMA 类模型的做法，别自己发明。

4.2 不同 vLLM 版本的适配差异

vLLM 迭代速度快得离谱，不同版本的接口差异是我踩过最多坑的地方。核心思想是：你的模型文件最好基于你部署版本里某个现成模型文件做“差分”，而不是拿着老博客的代码直接套。

不管哪个版本，load_weights 的“语义”从来没变过：上游把 checkpoint 权重一个接一个传给你，你负责翻译成模型参数并拷贝。只要抓住这个核心，版本升级对你来说只是换接口写法，不是换思路。

5. 常见问题与排查实录

5.1 注册了还是 not supported

这是第一个容易翻车的点。排查顺序如下：

先确认 config.json 里 architectures 的值，和注册时的字符串一字不差，包括大小写。再确认你的模型模块确实被 import 了。如果你用的是自定义包的方式，很常见的情况是启动脚本里忘了 import，装饰器根本没执行，注册表里自然没有。最后确认 vLLM 的模型注册表是否已经包含你的类，可以在代码里临时打印出来看一眼。

5.2 权重加载各种 mismatch

权重相关报错是最常见的，本质都是“vLLM 模型参数名”和“checkpoint 键名”对不上。解决手段是写一个小脚本，同时打印两边的键名：

# 打印 checkpoint 键名 from safetensors import safe_open with safe_open("mini-stream-hf/model.safetensors", framework="pt") as f: print("\n".join(sorted(f.keys()))) # 打印模型参数名 model = MiniStreamForCausalLM(config) print("\n".join(sorted(dict(model.named_parameters()).keys())))

对着两份名单做差集，哪个名字少、哪个名字多，一目了然。如果你看到 size mismatch 而不是 name mismatch，那通常是某个维度算错了，比如 QKV 拆分的 hidden_size 写错，或者词表大小因 padding 和实际权重不一致。

5.3 显存爆了与生成变慢

如果是加载阶段就爆显存，优先怀疑 dtype。默认加载 fp32 很容易爆，改成 bfloat16 或 float16 会让显存直接减半。如果加载没问题，一跑生成就爆，重点查 max_model_len 和 gpu_memory_utilization。调试阶段还可以加上 enforce_eager，把 CUDA Graph 的显存开销省掉。

如果是生成速度越来越慢，而不是一开始就慢，大概率是 KV cache 没有被正确复用。检查你的注意力实现是不是每次 forward 都重新计算了历史 token。如果模型用了自定义 attention 兜底，这个问题尤其常见。

5.4 输出和原模型对不上

输出不一致时，按这个优先级排查：

1. dtype 不一致，比如原模型是 fp32，vLLM 里用了 bf16，某些层会有一点点漂移，但不会离谱。
2. RMSNorm 的 eps。很多模型这个值是 1e-6 或 1e-5，差一个数量级，小概率出现明显偏差。
3. RoPE 相关参数，包括 rope_theta、rope_scaling，甚至 max_position_embeddings。位置编码类的 bug 往往在长序列才暴露，短 prompt 看不出问题。
4. 注意力缩放系数。检查注意力分数乘的是 head_dim 的倒数平方根，还是 hidden_size 的倒数平方根。
5. 词表 padding。如果你的词表大小不是 32 的倍数，某些实现会 padding 到对齐，导致 lm_head 的权重形状和 embedding 对不上。

以上都排完了，还有一个大招：在模型类里加一个临时 debug 钩子，把每一层的 hidden states 导出成文件，和参考实现逐层做余弦相似度。哪一层开始分叉，问题就定位在哪一层。

6. 我踩过的坑与几个保命习惯

最后说几句实在的，都是真金白银踩出来的经验。

第一个习惯：动手写模型类之前，先到你的 vLLM 版本里找结构最接近的官方模型文件，复制一份，然后基于这份拷贝去改。版本接口再怎么变化，你手里的官方文件就是最准确的“标准答案”。网上教程再详细，也不如你自己差分一份真实代码来得靠谱。我第一次升级 vLLM 版本后，旧模型文件直接跑不起来，就是靠这个习惯救回来的。

第二个习惯：权重转换脚本一定要保留，而且要像对待核心代码一样对待它。很多模型发布新版本后，权重结构会微调，你必然要重跑转换。没有脚本就等着哭吧。转完立刻做一次端到端小规模验证：用参考实现加载转换后的权重，跑一个 greedy 输出，存成黄金文件。后面 vLLM 接入、参数调整都以这个黄金文件为基准。

第三个习惯：调试阶段永远先把 enforce_eager 打开。CUDA Graph 捕获失败、形状不一致这类问题，开了 eager 之后错误信息会清晰得多。等一切正常了再关掉，不要一开始就纠结性能。

最后一个小技巧，我觉得比什么都实用：给模型类留一个 debug 开关，把前向过程里的中间 hidden states 导出来，跟参考实现逐层对比。位置编码、mask、缩放系数这些 bug，靠看最终输出根本发现不了，逐层相似度一对比，差异出在哪一层立刻现形。这一招帮我省掉的排查时间，比写模型类本身还多。

给 vLLM 加一个自定义模型，本质上就是把“训练时的假设”翻译成“推理引擎的假设”。这个翻译过程没有太多魔法，就是一个又一个参数、一层又一层的核对。只要流程清晰、验证到位，小众模型也能吃上工业级推理引擎的红利。