vLLM × Hugging Face Inference Endpoints：LLM 与多模态模型的托管部署完整指南

2026-09-04 11:07:17作者：柯茵沙

本篇基于 vLLM 官方文档 hf_inference_endpoints.md 整理，介绍如何将任意 vLLM 兼容模型部署到 Hugging Face Inference Endpoints 全托管推理平台：包括目录（Catalog）一键部署、Transformers 模型引导式部署、高级模型手动部署三种方法，并结合 vLLM 仓库源码剖析 Transformers 建模后端（modeling backend）是如何为任意 transformers 兼容模型提供 Day 0 支持、以及 vLLM 如何在其内部接管注意力计算的。

概览：全托管环境下的 vLLM 推理服务

所有与 vLLM 兼容的模型都可以部署到 Hugging Face Inference Endpoints，入口可以是 Hugging Face Hub 或 Inference Endpoints 界面本身。平台提供全托管环境，具备 GPU 加速、自动扩缩容和监控能力，无需自行管理底层基础设施。

其核心能力包括：

免运维：无需配置服务器、安装依赖或管理集群，端点从创建到就绪通常在分钟级完成；
多云支持：同一套端点可以在 AWS、Azure、GCP 等多家云厂商上部署，无需分别为各家注册账号；
与 Hub 深度集成：可直接部署任意 vLLM 或 transformers 兼容模型，追踪用量，并在线更新推理引擎；
引擎预配置：vLLM 引擎在端点容器中已预置，可在不改业务代码的情况下切换模型或引擎，端点自带监控与日志，简化生产部署。

文档将部署路径归纳为三种，按上手难度从低到高排列：

方法	适用模型	配置方式
方法 1：从 Catalog 部署	目录中已验证、已优化配置的模型	一键部署，零手动配置
方法 2：引导式部署	元数据中带 `transformers` library 标签的模型	Hub 模型卡 Deploy 按钮引导完成
方法 3：手动部署	使用自定义代码的 `transformers` 模型，或标准 `transformers` 无法运行但 vLLM 支持的模型	手动选择硬件与容器配置

方法 1：从 Catalog 一键部署

这是体验 vLLM on Inference Endpoints 最简单的方式。Hugging Face 维护了一个模型目录（catalog），其中模型的部署配置（GPU 设置、推理引擎参数等）已针对 vLLM 验证和优化，可以直接最大化性能。

操作步骤：

打开 Endpoints Catalog，在 Inference Server 选项中选择 vLLM，此时会展示当前已预置优化配置的模型列表；
选择目标模型，点击 Create Endpoint；
部署就绪后，使用控制台给出的 URL 调用端点——注意把 DEPLOYMENT_URL 替换为控制台提供的地址，并按需要补上 /v1 后缀：

# pip install openai
from openai import OpenAI
import os

client = OpenAI(
    base_url=DEPLOYMENT_URL,
    api_key=os.environ["HF_TOKEN"],
)

chat_completion = client.chat.completions.create(
    model="HuggingFaceTB/SmolLM3-3B",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "Give me a brief explanation of gravity in simple terms.",
                }
            ],
        }
    ],
    stream=True,
)

for message in chat_completion:
    print(message.choices[0].delta.content, end="")

几点说明：

Catalog 中的模型附带针对 vLLM 优化的 GPU 与推理引擎配置，是生产推荐的起点；
部署完成后，仍可在 Inference Endpoints UI 中监控端点，并随时更新容器或其配置（Container URI、Container Arguments），例如切换 vLLM 镜像版本；
端点通过标准 OpenAI 兼容 API 对外提供服务，因此任何 OpenAI SDK 客户端（包括上面的 openai 包）都可以直接对接，api_key 使用 Hugging Face 访问令牌（HF_TOKEN）。

方法 2：引导式部署（Transformers 标签模型）

该方法适用于模型元数据中带 transformers library 标签的模型，可以直接在 Hub UI 上完成部署，无需手动配置。判断依据是模型 README front matter 中 library: transformers 的标记。

文档以 ibm-granite/granite-docling-258M 模型为例：

在 Hugging Face Hub 上打开目标模型页，确认其 README front matter 中 library 标记为 transformers，即可判定兼容；
在模型卡右上角找到 Deploy 按钮（仅对带 transformers 标签的模型显示）；
点击 Deploy > HF Inference Endpoints，进入 Inference Endpoints 配置界面；
选择硬件（示例选择 AWS > GPU > T4）与容器配置，容器类型选 vLLM，点击 Create Endpoint 完成部署；
部署就绪后调用端点，同样需要把 DEPLOYMENT_URL 替换为控制台 URL 并补上 /v1。由于这是一个文档解析（docling）模型，示例请求携带了一张图片：

# pip install openai
from openai import OpenAI
import os

client = OpenAI(
    base_url=DEPLOYMENT_URL,
    api_key=os.environ["HF_TOKEN"],
)

chat_completion = client.chat.completions.create(
    model="ibm-granite/granite-docling-258M",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": {
                        "url": "https://huggingface.co/ibm-granite/granite-docling-258M/resolve/main/assets/new_arxiv.png",
                    },
                },
                {
                    "type": "text",
                    "text": "Convert this page to docling.",
                },
            ]
        }
    ],
    stream=True,
)

for message in chat_completion:
    print(message.choices[0].delta.content, end="")

需要注意：该方法采用的是平台最佳猜测的默认配置（best-guess defaults），对推理质量、显存占用敏感的模型，可能需要后续在端点 UI 中手动调整容器参数以匹配具体需求。

方法 3：手动部署（高级模型）

以下两类模型无法通过模型卡上的 Deploy 按钮部署，需要走手动流程：

带 transformers 标签但依赖自定义代码（custom code / trust_remote_code）的模型；
标准 transformers 无法运行、但已被 vLLM 原生支持的模型。

文档以 rednote-hilab/dots.ocr（一个集成进 vLLM 的 OCR 模型）为例，演示手动部署流程：

打开 Inference Endpoints 界面，点击 New 发起新部署；
在弹出对话框中切换到 Hub 页签，搜索目标模型并选中；
在配置页选择云厂商与硬件，示例选择 AWS + L4 GPU，实际按硬件需求调整；
滚动到 Container Configuration，容器类型选择 vLLM；
点击 Create Endpoint 完成部署。端点就绪后即可通过 OpenAI Completion API、cURL 或其他 SDK 调用（同样注意 URL 是否需要补 /v1）。

部署后常见的运维操作：

调整容器配置：在 UI 中修改 Container URI、Container Arguments 后点击 Update Endpoint，端点会按新容器配置重新部署。例如对于自定义代码模型，可能需要把镜像换成 nightly 版本（vllm/vllm-openai:nightly）并在容器参数中追加 --trust-remote-code 标志；
更换模型：修改模型本身需要创建新端点，或换一个模型重新部署，不能仅靠更新容器配置完成。

仓库侧可以看到，dots.ocr 对应的模型实现确实已注册进 vLLM 模型注册表：registry.py 中有 "DotsOCRForCausalLM": ("dots_ocr", "DotsOCRForCausalLM") 的映射，实现位于 dots_ocr.py，这正是文档将该模型选为手动部署示例的原因——它不依赖标准 transformers 加载路径，需要 vLLM 自身的模型实现。

源码深潜：Transformers 建模后端如何实现 Day 0 支持

文档的 "Advanced Deployment Details" 一节指出：借助 Transformers modeling backend 集成，vLLM 对任意 transformers 兼容模型提供 Day 0 支持——即新模型无需等待 vLLM 社区编写专门的模型实现，即可在 vLLM 引擎上运行并获得其优化推理能力。下面结合源码说明这一机制在 vLLM 仓库中的落地。

后端类族：按任务组合的 Mixin

vLLM 在 transformers/init.py 中定义了一组后端包装类，通过 Mixin 组合覆盖不同任务形态：

TransformersForCausalLM（文本生成）、TransformersMoEForCausalLM（MoE 文本生成）；
TransformersMultiModalForCausalLM、TransformersMultiModalMoEForCausalLM（多模态生成，同时注册了 MultiModalProcessor / MultiModalProcessingInfo / MultiModalDummyInputsBuilder 处理器，保证多模态输入走 vLLM 的标准预处理管线）；
TransformersEmbeddingModel、TransformersMultiModalEmbeddingModel（embedding 池化任务）；
TransformersForSequenceClassification 及 MoE / 多模态变体（分类池化任务）。

这套类族正是文档中"引导式部署可部署任意 transformers 标签模型"的底层支撑：平台只需把模型权重交给容器，vLLM 引擎在加载时就能用对应的包装类接管推理。

自动选择：model_impl 与回退链

从源码结构看，后端选择逻辑由 model_impl 配置项驱动，默认为 auto，见 config/model.py。当模型注册表中没有目标架构时，注册表会尝试解析该架构的 transformers 实现，并按 registry.py 中的回退逻辑处理：

若能解析出兼容的 transformers 模型模块，且 model_impl != "transformers"（即用户显式指定了其他实现），返回 None 让调用方走其他路径；
若模块声明与 vLLM 后端不兼容，抛出 ValueError: The Transformers implementation of ... is not compatible with vLLM；
否则返回 model_config._get_transformers_backend_cls()，即选中 transformers 后端。

具体选中哪个后端类由 _get_transformers_backend_cls 决定：以 Transformers 为前缀，若 hf_config 与 hf_text_config 不一致（嵌套配置，即多模态）则追加 MultiModal，若模型是 MoE 则追加 MoE，再根据 runner 类型追加 EmbeddingModel / ForSequenceClassification / ForCausalLM 后缀。using_transformers_backend 则用于判断当前模型是否确实运行在该后端上，后续若干代码路径（如 LoRA 的 batch 维度处理）会据此做分支。相关的加载路径还可在 model_loader/utils.py 中看到：当解析出的架构正是 transformers 后端类时，走专门的权重加载逻辑。

注意力接管：把朴素 Attention 换成 vLLM 实现

Day 0 支持并不意味着放弃 vLLM 的性能优势。transformers/init.py 中实现了两个注意力转发函数并向 transformers 的 ALL_ATTENTION_FUNCTIONS 注册：

vllm_attention_forward（注册名 vllm）：取出该层的 vLLM Attention 实例，对 Q/K/V 做形状整理后调用 self_attn.forward，并对 MLA 中 value 头维小于 qk 头维的情况做了 pad 处理；
vllm_mla_attention_forward（注册名 vllm_mla）：面向 MLA 注意力，处理 kv_c_normed 与 k_pe 的 reshape 后交给 MLAAttention。

也就是说，transformers 模型在 vLLM 内执行时，注意力内核仍由 vLLM 的 PagedAttention 体系承担，KV cache 管理、批处理调度等推理优化照常生效。后端机制的测试见 tests/models/transformers/test_backend.py，基础层实现在 base.py。

调用端点：统一通过 OpenAI 兼容 API

三种部署方法最终都收敛到同一调用契约，可以归纳为三点：

URL 处理：使用控制台给出的端点 URL，需要按 API 路径要求补 /v1 后缀；
认证：api_key 使用 Hugging Face 访问令牌（环境变量 HF_TOKEN）；
请求形态：标准 OpenAI Chat Completions 请求，model 字段填 Hub 上的模型仓库名（如 HuggingFaceTB/SmolLM3-3B、ibm-granite/granite-docling-258M），支持流式输出，多模态模型可携带 image_url 等富媒体内容块。

这也解释了文档强调的"无需改代码切换模型或引擎"：只要端点保持 OpenAI 兼容接口，业务侧客户端代码在换模型、换引擎之间无需修改。

小结与延伸阅读

三种部署方法的选择标准：有现成优化配置选 Catalog；transformers 标签的普通模型用 Deploy 按钮引导式部署；自定义代码或 vLLM 专属模型（如 DotsOCRForCausalLM）走手动部署，并预留"换 nightly 镜像 + --trust-remote-code"这类容器参数调整空间；
Day 0 支持的实现证据集中在 vllm/model_executor/models/transformers/ 目录与 registry.py 的回退链中，后端类选择规则见 config/model.py；
文档内引用的全部截图位于 docs/assets/deployment/ 目录（hf-inference-endpoints-*.png），便于对照 UI 步骤；
同一主题可结合仓库中的其他部署文档继续深入，如 docker.md、k8s.md，以及框架集成文档目录 docs/deployment/frameworks/ 下的其他平台指南。