vLLM embed.py 扩展：添加非 EngineArgs 自定义参数

Mon, 01 Jun 2026 11:30:00 +0800

背景

vLLM 官方示例 examples/basic/offline_inference/embed.py 展示了一个标准的 Embedding 推理流程，其参数解析采用如下模式：

parser = FlexibleArgumentParser()
parser = EngineArgs.add_cli_args(parser)
args = parser.parse_args()
llm = LLM(**vars(args))

核心流程是：

创建 FlexibleArgumentParser
通过 EngineArgs.add_cli_args(parser) 将 EngineArgs 的所有字段注册为 CLI 参数
解析参数后通过 LLM(**vars(args)) 直接解包传给 LLM 构造函数

这种模式对纯 EngineArgs 场景工作良好，但当你需要添加业务相关的自定义参数（如 --batch-size、--input-file）时，就会遇到一个问题：非 EngineArgs 的参数会被一起传给 LLM()，导致 TypeError。

问题所在

LLM.__init__ 只接受 EngineArgs 中定义的字段。如果在 parser 上添加了额外的自定义参数，vars(args) 会包含这些多余字段，直接解包传入 LLM() 会导致类似这样的错误：

TypeError: LLM.__init__() got an unexpected keyword argument 'custom_param'

解决方案的核心思路是：在将参数传给 LLM() 之前，把自定义参数剥离出来。

三种解决方案

方法一：手动按字段过滤（最直观）

def parse_args():
 parser = FlexibleArgumentParser()
 parser = EngineArgs.add_cli_args(parser)
 parser.add_argument("--custom-param", type=str, default=None)
 parser.add_argument("--batch-size", type=int, default=32)
 return parser.parse_args()

def main(args: Namespace):
 engine_args = {k: v for k, v in vars(args).items()
 if k in EngineArgs.__dataclass_fields__}
 llm = LLM(**engine_args)

 print(f"Custom param: {args.custom_param}")
 print(f"Batch size: {args.batch_size}")

原理：EngineArgs 是一个 dataclass，__dataclass_fields__ 包含所有声明字段的元信息。遍历 vars(args) 字典，只保留 key 存在于 __dataclass_fields__ 中的条目即可。

开发 on Richelieu's Blog

vLLM embed.py 扩展：添加非 EngineArgs 自定义参数

背景

问题所在

三种解决方案

方法一：手动按字段过滤（最直观）