3、配置类定义：为自定义模型编写 ModelConfig
好，咱们进入第三个关键环节——配置类定义。说白了，就是告诉 vLLM：「我这个模型长什么样，内存怎么管，精度怎么设」。
我个人习惯把 ModelConfig 比作模型的「身份证」。你想想看，vLLM 要调度你的模型，总得知道它有几斤几两吧？配置类就是干这个的。
3.1 配置类的基本结构
先看一个最简的配置类骨架。我直接上代码，你感受一下：
from vllm.config import ModelConfig
class MyCustomModelConfig(ModelConfig):
"""我的自定义模型配置"""
def __init__(self, **kwargs):
super().__init__(**kwargs)
# 这里放你的专属参数
self.my_param = kwargs.get("my_param", "default_value")
嗯，这里要注意：必须继承 ModelConfig。我在项目中遇到过有人直接写了个普通类，结果 vLLM 死活不认——因为它内部会做类型检查。
3.2 核心参数定义
配置类里要定义哪些参数？我列个清单，都是实战中绕不开的：
| 参数名 | 类型 | 说明 | 我的建议 |
|---|---|---|---|
model |
str | 模型名称或路径 | 用 HuggingFace 的命名规范 |
tokenizer |
str | 分词器名称或路径 | 通常和模型一致 |
dtype |
str | 数据类型（float16/bfloat16/float32） | 优先用 bfloat16 |
max_model_len |
int | 最大序列长度 | 根据显存来定 |
trust_remote_code |
bool | 是否信任远程代码 | 自定义模型建议设为 True |
为什么我建议优先用 bfloat16？因为它在训练和推理中表现更稳定。我曾经踩过一个坑：用 float16 跑一个深层模型，梯度直接炸了——后来换成 bfloat16 就稳了。你想想看，同样的显存开销，换来更少的数值问题，何乐而不为？
3.3 dtype 设置的细节
dtype 这块值得单独拎出来说。vLLM 支持三种设置方式：
- 字符串形式：
"float16"、"bfloat16"、"float32" - torch 类型：
torch.float16、torch.bfloat16 - 自动检测：
"auto"（从模型权重推断）
我个人习惯用字符串形式，因为配置文件里写起来方便。但要注意：如果你的模型权重是混合精度的，用 "auto" 可能会出问题。我记得有一次，一个同事的模型权重里既有 float32 又有 float16，结果 "auto" 模式直接报错——最后手动指定了 bfloat16 才搞定。
核心原则：dtype 的选择要权衡精度和性能。推理场景下，bfloat16 是甜点；训练场景下，混合精度（AMP）更常见。
3.4 内存管理参数
内存管理是 vLLM 的强项，但配置不当也会翻车。这里有几个关键参数：
gpu_memory_utilization：GPU 显存利用率，默认 0.9。我一般设 0.85 留点余量。swap_space：CPU 交换空间大小，默认 4GB。如果你的模型很大，建议调高。max_num_batched_tokens：单次批处理的最大 token 数，影响吞吐量。
我曾经在 24GB 显存的卡上跑一个 13B 模型，gpu_memory_utilization 设了 0.95，结果 OOM 了。后来降到 0.85，配合 swap_space 8GB，稳如老狗。你想想看，留点余量不是怂，是成熟。
3.5 完整配置类示例
来，看一个完整的实战例子。这是我为一个自定义对话模型写的配置类：
from vllm.config import ModelConfig
from typing import Optional, Dict, Any
class ChatModelConfig(ModelConfig):
"""对话模型配置"""
def __init__(
self,
model: str = "my-org/my-chat-model",
tokenizer: Optional[str] = None,
dtype: str = "bfloat16",
max_model_len: int = 4096,
gpu_memory_utilization: float = 0.85,
swap_space: int = 8,
**kwargs
):
super().__init__(
model=model,
tokenizer=tokenizer or model,
dtype=dtype,
max_model_len=max_model_len,
gpu_memory_utilization=gpu_memory_utilization,
swap_space=swap_space,
trust_remote_code=True,
**kwargs
)
# 自定义参数
self.chat_template = kwargs.get("chat_template", "default")
self.system_prompt = kwargs.get("system_prompt", "")
def to_dict(self) -> Dict[str, Any]:
"""转为字典，方便序列化"""
base = super().to_dict()
base.update({
"chat_template": self.chat_template,
"system_prompt": self.system_prompt,
})
return base
小技巧：重写 to_dict() 方法是个好习惯。vLLM 在保存和加载配置时会用到它，不写的话自定义参数就丢了。
3.6 避坑指南
最后，分享几个我踩过的坑：
- 参数名冲突：不要用 vLLM 内部保留的关键字做自定义参数名。比如别用
block_size、cache_config这些。 - 类型检查：vLLM 会对参数做类型校验。我遇到过传了字符串
"4096"而不是整数4096，结果报错半天。 - 默认值陷阱：自定义参数的默认值要谨慎。我曾经设了个
None，结果下游代码没做空值检查，直接崩了。
警告：配置类定义好后，一定要跑一遍 vllm.entrypoints.llm.LLM 的初始化流程做验证。别问我怎么知道的——有一次我改了参数名但忘了更新注册逻辑，排查了整整一个下午。
3.7 知识体系图
下面这张图总结了配置类定义的核心脉络，我手绘的 SVG，你感受一下：
嗯，配置类这块就这些。记住：好的配置类，是模型稳定运行的基石。别嫌麻烦，多花 10 分钟把参数定义清楚，能省下后面 10 小时的排查时间。
公众号:蓝海资料掘金营，微信deep3321