Transformers 对接 vLLM 推理引擎model_impltransformers 加载与 PagedAttention 源码解析【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers本篇指南基于 Transformers 官方文档 vLLM 集成说明讲解如何在 vLLM 高吞吐推理引擎中通过model_impltransformers使用 Transformers 建模后端离线LLMAPI 与在线vllm serve两种用法的完整命令vLLM 与 Transformers 的加载流程AutoConfig→AutoModel.from_config→AutoTokenizer并结合仓库源码解读 vLLM 风格 PagedAttention 在 Transformers 连续批处理路径中的实现帮助读者在部署 LLM 服务时理解为什么 vLLM 要用 Transformers 建模后端、以及两边在 KV cache 分页上如何对齐。vLLM 是什么以及为什么需要 Transformers 建模后端vLLM 是一个面向大规模 LLM 服务的高吞吐推理引擎它持续地对请求做批处理continuous batching并用 PagedAttention 保持 KV cache 内存紧凑。Transformers 文档在 vLLM 集成页 中给出的核心思路是设置model_impltransformers即可让 vLLM 使用 Transformers 建模后端来加载模型。这意味着当某个模型还没有被 vLLM 自身的模型注册表覆盖时你可以直接借 Transformers 的模型实现跑在 vLLM 的调度与内核之上而不必等待 vLLM 侧逐个移植模型。这也是本文档存在的主要价值——它是一条零移植的服务化通路。离线推理LLM API 用法Transformers 官方文档给出的最简离线生成示例可直接复制运行前提是本机已安装 vLLMfrom vllm import LLM llm LLM(modelmeta-llama/Llama-3.2-1B, model_impltransformers) print(llm.generate([The capital of France is]))各要素说明modelmeta-llama/Llama-3.2-1BHub 模型 IDvLLM 会按后文流程拉取config.json与 safetensors 权重model_impltransformers跳过 vLLM 模型注册表直接从 Transformers 加载模型实现。这是本文档中最重要的开关llm.generate(...)vLLM 的离线批量生成接口输入 prompt 列表输出带生成文本的对象列表。在线服务vllm serve 命令对于在线API server部署把同样的开关以命令行参数形式传给vllm servevllm serve meta-llama/Llama-3.2-1B \ --task generate \ --model-impl transformers参数说明meta-llama/Llama-3.2-1B要服务的 Hub 模型--task generate声明该模型执行文本生成任务--model-impl transformers与离线 API 的model_impltransformers等价让服务使用 Transformers 建模后端。命令启动后vLLM 会以 OpenAI 兼容接口的形式对外提供生成服务适合直接接入现有网关。Transformers 集成四步加载流程文档中 Transformers integration 一节完整描述了 vLLM 与 Transformers 的加载协议以下四步必须完整理解它是排障时的主线配置加载AutoConfig.from_pretrained从 Hub或本地 Hugging Face 缓存读取模型的config.json。vLLM 会用architectures字段对照自己的内部模型注册表决定使用哪个 vLLM 模型类注册表未命中时回落到 Transformers如果模型不在 vLLM 注册表中vLLM 会调用AutoModel.from_config加载 Transformers 的模型实现——这正是model_impltransformers所走的路径分词器加载AutoTokenizer.from_pretrained加载分词器文件。vLLM 会缓存部分分词器内部状态tokenizer internals以降低推理时的每步开销权重下载模型权重以 safetensors 格式从 Hub 下载。一个值得强调的机制文档原文设置model_impltransformers会绕过 vLLM 的模型注册表直接从 Transformers 加载模型。vLLM 会保留 Transformers 的模型结构但用自有的优化版本替换大部分模型模块MoE、注意力、线性层等。换句话说落到 vLLM 里运行时你看到的仍然是 Transformers 定义的网络结构层数、注意力类型、MoE 路由等全部来自config.json和 Transformers 的建模代码但计算热点被换成了 vLLM 的优化内核。这解释了为什么零移植也能获得 vLLM 级别的吞吐。源码佐证一vLLM 风格 PagedAttention 在 Transformers 中的实现文档提到 vLLM用 PagedAttention 保持 KV cache 内存紧凑。这个机制在 Transformers 仓库内同样有一等实现且两处设计明确相互对齐——PagedAttentionCache 的类文档字符串直接写道它 inspired by VLLMs hybrid allocator受 vLLM 混合分配器启发。其核心是三级缓存层级引自 cache.py 源码注释Page页最小缓存单元大小为[num_heads, head_size]即一层对一个 token 的 K 或 V 所需空间。只有全注意力层的模型存一个 token 的 KV cache 需要2 * num_layers个页Block块block_size个页的集合是实际分配单位按块分配而非按页分配以降低管理复杂度与碎片。每个块分配给一个层组——组内层只有同一种注意力类型full-attention 或 sliding-attention。全模型只有一种注意力类型时只有一个组混合注意力的模型如 full sliding 混合会拆成多个组Cache tensor物理缓存张量每个层组内有与层数等量的物理张量形状为[num_blocks * block_size, num_heads, head_size]。源码注释中的示例值得细读一个有两个层组各 3 层全注意力组与滑窗注意力组、共 8 个块的模型在滑窗窗口填满后只需给全注意力组分配新块滑窗组的块可以不再增长——这在单一组设计下做不到因为滑窗组的块也会被白白占掉。这正是 vLLM 混合分配器思想在 Transformers 连续批处理路径中的落地。源码佐证二paged attention 前向计算与 block table真正把分页变成高效内核调用的是 paged_attention_forward。它接收PagedAttentionCache与一个block_table按两条路径分派无 block_tableprefill / 变长路径用cache.update配合read_index/write_index更新缓存再调用flash_attn_varlen_funcflash-attn 的 varlen 内核完成注意力计算有 block_tabledecode 快速路径进入 _paged_decode_forward调用flash_attn_with_kvcache做缓存就地更新 注意力的融合计算。block_table的语义见 flash_paged.py 的参数文档与 vLLM 完全同构形状为(num_groups, batch_size, max_blocks_per_seq)的 int32 张量每个请求的块表是一个物理块索引向量内核结合该请求的cache_seqlens知道要读/写多少缓存并通过块表把逻辑位置映射到物理位置未分配的块以-1填充。此外源码还处理了两个工程细节MLA 等v_head_dim q_head_dim的模型需要把 V 零填充到 query 头维度再计算L43-L47、L95-L96以及 vLLM 的 FA3 内核与 Tri Dao 内核的 block table 参数名不同需通过cache.get_block_table_key(...)动态解析L129-L130。这套实现位于transformers的src/transformers/generation/continuous_batching/目录含 scheduler.py、cache_manager.py、model_runner.py 等模块对应文档 连续批处理说明 与 PagedAttention 指南。从源码结构看Transformers 与 vLLM 在请求调度 分页 KV cache 融合 attention 内核三件套上保持了设计一致性这也让模型在两边之间迁移时行为更可预期。适用前提与排障要点适用前提model_impltransformers适用于 vLLM 注册表未覆盖、或你希望直接用 Transformers 建模实现运行的场景若模型已有 vLLM 原生实现走注册表路径不设置该参数通常也完全可用。权重以 safetensors 从 Hub 拉取首次运行需要网络或本地缓存排障主线加载异常时按四步流程定位——config.json的architectures字段决定走哪条路径→ 模型实现加载 → 分词器 → 权重文件。AutoConfig.from_pretrained能读通但第二步失败多为该架构在 Transformers 侧无对应实现文档局限官方 vLLM 集成页 面向如何接入未涵盖量化配置、张量并行等 vLLM 侧高级参数这些以 vLLM 自身的文档为准延伸阅读仓库内KV cache 分页的设计细节见 paged_attention.md请求级连续调度的架构见 continuous_batching_architecture.md。小结vLLM 用 continuous batching PagedAttention 支撑大规模 LLM 服务model_impltransformers离线 API或--model-impl transformersvllm serve两个开关即可让 vLLM 直接使用 Transformers 建模后端绕开 vLLM 模型注册表加载协议为四步AutoConfig.from_pretrained读配置 → 注册表未命中时AutoModel.from_config加载 Transformers 实现 →AutoTokenizer.from_pretrained加载分词器vLLM 会缓存其内部状态→ safetensors 权重下载落到 vLLM 后Transformers 模型结构被保留MoE / attention / linear 等热点模块被替换为 vLLM 优化版本Transformers 仓库内的 PagedAttentionCache 与 paged_attention_forward 实现了与 vLLM 同构的块表 融合 KV-cache 内核路径是理解两边如何对齐的最佳源码入口。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考