[RFC]: Hidden States Extraction

快速结论：该报错场景发生在使用 vLLM 时，需要提取任意模型层的隐藏状态（hidden states）用于推测解码（如 Eagle3、DFlash）或强化学习（RL）训练。当前 vLLM 没有官方支持，现有解决方案要么丢失性能优化，要么需要大量侵入式修改。优先排查是否可以通过配置 --kv-transfer-config 和 --speculative_config 来启用隐藏状态提取功能。

问题场景

用户在使用 vLLM 进行模型推理时，需要获取中间层的隐藏状态（hidden states）用于以下目的：

Eagle3 / DFlash 等推测解码算法的“验证器”模型需要多层隐藏状态作为输入
强化学习（RL）训练，例如 VERL 项目
量化（quantization）研究
数据集生成：需要重新生成模型响应并同时返回隐藏状态

用户尝试的方案通常有以下问题：

使用 HuggingFace Transformers 生成：失去 vLLM 的性能优化、分布式支持等
对 vLLM 进行深度修改和打补丁：需要手动设置核心组件并访问内部 API，维护成本高，且可能禁用前缀缓存、自动批处理、异步服务器等功能

报错原文

[RFC]: Hidden States Extraction
Goal: Implement a solution for getting hidden states from any model layer out of vLLM in a performant way.

Speculative decoding algorithms such as Eagle3 and DFlash take "verifier" model hidden states (from multiple layers) as input.

Current vLLM provides no official approach to extracting these hidden states.

Previous attempts (#15434, #24288, #26686) have failed because they negatively impact hotpath performance or add too much complexity, or are limited in scope.

原因分析

vLLM 当前缺少一个性能高效、不影响热路径（hotpath）、且能处理多层的隐藏状态提取官方 API。现有方案要么性能损失大（如用 Transformers），要么需要大量侵入式修改（如打补丁访问内部 API），且这些修改会禁用 vLLM 的许多关键特性。

可能原因：vLLM 架构设计上，隐藏状态的计算和存储与 KV 缓存（KV cache）紧密相关，但一直没有稳定的外部接口来获取它们。过去的尝试（如 #15434）因影响热路径性能或增加过多复杂度而被拒绝。

环境排查

vLLM 版本：确认是否在 0.6.0+（支持 Eagle3 的 aux_hidden_states 系统）
模型架构：确认模型是否支持 Eagle3 或 DFlash 的推测解码（如 llama、mistral 等 transformer 类模型）
Python 版本：3.9+
PyTorch 版本：2.0+（vLLM 推荐版本）
CUDA 版本：11.8+
显卡：NVIDIA GPU 显存需足够容纳模型和隐藏状态
依赖：vllm-project/speculators 项目（如果使用现有方案）

解决步骤

检查现有方案：如果使用推测解码（如 Eagle3），确认 vLLM 版本是否支持 aux_hidden_states 系统。如果是 0.6.0+ 且模型支持 Eagle3，可先尝试通过 Eagle3 接口间接获取隐藏状态。
配置隐藏状态提取：根据 Issue 中的讨论，尝试以下配置参数（可优先尝试）：
- 启动 vLLM 时添加 --kv-transfer-config '{"kv_connector":"HiddenStatesConnector"}'
- 同时设置 --speculative_config '{"method": "extract_hidden_states"}'
使用演示插件：参考 @fynnsu 提供的基于 ExampleConnector 的演示代码（在 Issue #30672 中）。该插件通过创建一个虚拟 Eagle3 模型，将隐藏状态注入到 KV 缓存中，然后利用 KV Connector 接口高效提取。注意：该插件目前写入文件是同步的，性能仍有优化空间。
自定义扩展：如果模型不支持 Eagle3，可以考虑扩展 Eagle3 的模型支持列表，或者探索通过钩子（hooks）自动添加支持的方案。
社区参考：查看 vllm-project/speculators 项目中的 data_generation 模块，了解其现有方案（虽然会随 vLLM 内部更新而变迁）。

验证方法

运行一个测试脚本，配置好上述参数后，调用 vLLM 的推理接口。如果配置生效，通过 KV Connector 应该能获取到指定层的隐藏状态（如打印或保存到文件）。确认隐藏状态的形状与预期一致（与 token 序列一一对应），且推理性能没有显著下降（例如，在不启用该功能时速度不受影响）。

参考来源

vllm-project/vllm #33118

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

[RFC]: Hidden States Extraction