TGI（Text Generation Inference）部署指南：Hugging Face 推理服务器
TGI（Text Generation Inference）是 Hugging Face 官方开源的推理服务器，专为生产级文本生成场景设计。如果你的工作流已经深度整合了 Hugging Face Hub——模型从 Hub 下载、用 transformers 做评测、用 Spaces 做演示——那么 TGI 是最自然的生产部署延伸，无需额外的格式转换，直接对接 Hub 上的原始权重。
我见过不少团队走的弯路是：先用 transformers 的 generate() 起了个 Flask 服务，压测跑到 20 并发就开始排队、显存爆掉，最后才回头看 TGI 或 vLLM 这类专门的推理服务器。问题不在代码写得差，而在于原生 generate() 是为单次调用设计的——它不知道怎么把十几个不同长度的请求塞进同一批 GPU 计算里，也不知道怎么在显存紧张时动态调度。TGI 解决的正是这个”怎么把 GPU 喂饱又不喂爆”的工程问题，下面从原理层面拆开讲。
TGI 的核心特性
| 特性 | 说明 |
|---|---|
| Flash Attention 2 | 注意力计算优化，减少显存占用并提升速度 |
| 连续批处理（Continuous Batching） | 动态合并请求，提升 GPU 利用率 |
| Token 流式输出 | SSE 流式响应，首 token 延迟低 |
| 量化支持 | GPTQ、AWQ、bits-and-bytes INT8/INT4 |
| 多卡张量并行 | 支持 --num-shard 多 GPU |
| OpenAI 兼容 API | /v1/chat/completions 端点 |
| Paged Attention | 较新版本已支持 |
这几个特性不是孤立的优化点，它们其实是一套连贯的解题思路，值得展开讲讲背后的逻辑，不然你调参数的时候容易调错方向。
**Flash Attention 2 省的是显存带宽，不是显存容量。**标准注意力实现需要先算出完整的 QK^T 矩阵再做 softmax，这个中间矩阵会被物理写入显存再读出来，序列越长这块开销越大。Flash Attention 2 用分块计算的方式，把 QK^T 和 softmax 的中间结果留在 GPU 的高速缓存（SRAM）里算完再写回，不落地那个大矩阵，所以省的其实是显存带宽和 IO 时间，副作用是长序列场景下速度提升明显，短对话场景提升不那么显著。如果你的业务全是几十 token 的短问答，别指望开了 Flash Attention 2 就能翻倍提速，它的收益和序列长度是正相关的。
**连续批处理（Continuous Batching）解决的是”请求到达时间不对齐”的问题。**传统静态批处理要等一批请求凑齐了才一起送进 GPU 计算，如果有个请求已经生成完了但同批次的其他请求还没结束，它得干等着，GPU 算力就这么被浪费了。TGI 的连续批处理是在 token 级别做调度：每生成完一个 token 就检查一遍，谁结束了就立刻把它踢出批次、腾出空位塞下一个排队的请求进来，而不是等整批都结束。这就是为什么线上高并发场景下开了连续批处理之后，GPU 利用率能从松散的六七成顶到九成以上——本质是把”批次”这个静态边界打破了，变成了动态滑动窗口。
**Paged Attention 管的是显存碎片。**每个请求的 KV Cache 大小取决于它已经生成的 token 数，长度不固定，如果按最大长度预分配显存，短请求会浪费大量空间；如果按实际长度动态分配，显存又会产生大量碎片，导致明明总显存够用，却分配不出连续的一块给新请求。Paged Attention 借鉴了操作系统虚拟内存分页的思路，把 KV Cache 切成固定大小的小块（page），按需分配、按需回收，从根上消灭了碎片问题。这个机制最早是 vLLM 团队提出并证明有效的，TGI 后来跟进实现，所以你会看到两边在这块的技术路线其实是趋同的。
Docker 快速部署
TGI 官方推荐用 Docker 部署，镜像内置了所有依赖，是最干净的方式：
# 拉取 TGI 最新镜像
docker pull ghcr.io/huggingface/text-generation-inference:latest
# 部署 Qwen2.5-7B（需要先设置 HF_TOKEN 环境变量）
docker run --gpus all \
-e HF_TOKEN=$HF_TOKEN \
-p 8080:80 \
-v $HOME/.cache/huggingface:/data \
ghcr.io/huggingface/text-generation-inference:latest \
--model-id Qwen/Qwen2.5-7B-Instruct \
--max-concurrent-requests 64 \
--max-input-length 4096 \
--max-total-tokens 8192
调用示例（curl）：
curl http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "tgi",
"messages": [{"role": "user", "content": "你好"}],
"stream": false
}'
**你应该看到什么：**容器启动后先跑一段模型加载日志，最后一行大概率是类似 Connected 或 Ready 的提示，同时监听端口开始响应。你可以先用 docker logs -f <container_id> 盯着日志，看到日志里出现 Warming up model on GPU 之后再等一会儿——TGI 会用几个不同长度的假请求预热一遍，把常见 batch size 下的算子先跑通、避免第一个真实请求踩到编译延迟。预热完成前调用接口大概率会超时或排队很久，这不是 bug，是正常的冷启动过程，生产环境建议在健康检查里加个预热等待期，不要让负载均衡在容器刚起来那几十秒就把流量导过来。
关键启动参数
| 参数 | 作用 | 建议 |
|---|---|---|
--model-id | HF Hub 模型 ID 或本地路径 | 必填 |
--num-shard | 张量并行 GPU 数量 | 等于使用的 GPU 数 |
--quantize | 量化：gptq / awq / bitsandbytes-nf4 | 显存紧张时启用 |
--max-concurrent-requests | 最大并发请求数 | 按显存调整，默认 128 |
--max-input-length | 最大输入 token 数 | 不超过模型支持的上下文长度 |
--max-total-tokens | 输入 + 输出总 token 上限 | 影响 KV Cache 显存分配 |
--dtype | 权重精度：float16 / bfloat16 | A100/H100 用 bfloat16 更稳 |
这几个参数里最容易踩坑的是 --max-total-tokens 和 --max-concurrent-requests 的组合关系，很多人第一次调的时候会单独调其中一个，结果不是显存爆掉就是并发上不去。原理是这样的：TGI 启动时会按 --max-total-tokens × --max-concurrent-requests 这个量级去预估 KV Cache 需要的显存上限（实际计算比这个更精细，还要看模型的层数、注意力头数，但量级关系是对的），如果你把并发数和单请求 token 上限都往大了调，显存需求是乘法关系而不是加法关系，很容易一下子就把显存打爆。
实际调参的顺序建议反过来：先确定你的业务场景里单个请求的输入输出大概会用掉多少 token（比如客服问答场景输入 500、输出 300，--max-total-tokens 设 1024 留点余量足够），再拿这个数去试并发上限，从 16 开始往上加，边加边看显存占用，直到接近但不超过显存上限的 85% 左右（留出余量给显存碎片和突发请求），这样调出来的配置才是贴合你实际业务的，而不是抄一个网上的通用配置然后线上炸显存。
量化怎么选：GPTQ / AWQ / bitsandbytes 到底用哪个
这三种量化方案都能把模型压到 INT4/INT8，省显存的效果差不多，但适用场景和代价不一样，别看到”量化”两个字就随便选一个：
| 方案 | 量化方式 | 精度损失 | 适用场景 |
|---|---|---|---|
| GPTQ | 离线校准量化，需要提前跑一遍校准数据集 | 较小，校准数据代表性够的话几乎无感 | 模型固定不变、追求推理速度的生产部署 |
| AWQ | 离线量化，保留对激活值影响大的权重通道精度 | 通常比 GPTQ 略优，尤其是长文本场景 | 同上，社区新模型的量化版本更新更快 |
| bitsandbytes (nf4/int8) | 运行时动态量化，无需提前校准 | 略高于前两者，但胜在即开即用 | 快速验证、显存实在不够用但又懒得走校准流程的场景 |
我自己的经验是：如果只是想先跑起来看看效果，--quantize bitsandbytes-nf4 最省心，不用额外准备校准数据集，改一个参数重启容器就行；但如果这套服务要长期跑在生产环境、对吞吐和精度都有要求，值得花时间用 GPTQ 或者直接去 HF Hub 上找模型作者或社区已经量化好的 AWQ 版本（很多热门模型都有现成的 -AWQ 或 -GPTQ 后缀仓库），省得自己校准。
TGI vs vLLM：选型对比
两者都是生产级推理框架，核心差异在于生态定位和优化方向：
| 维度 | TGI | vLLM |
|---|---|---|
| 主要维护方 | Hugging Face 官方 | 社区（加州大学等） |
| 部署方式 | Docker 优先 | pip 优先，也有 Docker |
| HF Hub 集成 | 原生无缝 | 兼容但非原生 |
| PagedAttention | 较新版支持 | 原创实现，更成熟 |
| 模型支持广度 | 以 HF 生态为主 | 略广，社区贡献更活跃 |
| Serverless 场景 | HuggingFace Inference Endpoints | 需自建 |
| 吞吐量（同等配置） | 接近，略低于 vLLM 极限 | 通常略高 |
选 TGI 的信号：你的团队已重度依赖 HF Hub、用 transformers 做实验、希望 Docker 化部署、或者要对接 HuggingFace Inference Endpoints 托管服务。
选 vLLM 的信号：你更关注极致吞吐、需要更成熟的 PagedAttention 实现、或团队更熟悉 pip 部署方式。
本地模型部署（不依赖 Hub）
如果模型权重已下载到本地：
docker run --gpus all \
-p 8080:80 \
-v /path/to/local/model:/model \
ghcr.io/huggingface/text-generation-inference:latest \
--model-id /model
生产环境这几个坑我踩过，报错原文贴出来给你对照
线上跑 TGI 遇到的问题，十次有八次能从报错文案里直接定位根因，剩下两次是显存和网络的隐性问题。整理几个高频的：
报错：Input validation error: inputs tokens + max_new_tokens must be <= 4096
这个不是显存问题，是你请求里传的 max_new_tokens 加上输入长度超过了启动时 --max-total-tokens 设的上限。修法有两个方向：要么在启动参数里把 --max-total-tokens 调大（前提是显存够），要么在客户端请求里动态计算输入长度、把 max_new_tokens 设小一点，别无脑给个固定的大值。我见过有团队直接把 max_new_tokens 写死成 2048，结果长输入的请求全报这个错，改成”根据输入长度动态算剩余可用 token 数”之后问题就没了。
报错：CUDA out of memory. Tried to allocate X MiB
这是真显存不够了，常见于并发数或 --max-total-tokens 调太高，或者同一张卡上还跑着别的进程。排查顺序：先 nvidia-smi 看显存占用是不是被别的容器/进程占了一部分；确认没有的话，就把 --max-concurrent-requests 往下调一半再试；如果模型本身就大（比如 70B 用单卡跑 fp16），那该上量化或者上 --num-shard 多卡分摊，硬调参数解决不了模型本身放不下的问题。
请求偶发超时或卡住，日志里没有明显报错 这种最烦人，通常是预热没做完、或者某个异常长的请求把批次里其他请求的调度都拖慢了（连续批处理虽然能动态调度，但极端长的单个请求还是会占用较多算力份额）。建议在网关层面对单个请求的最大等待时间设个超时（比如 30 秒），超时后走重试或者降级到备用模型，别让一个慢请求拖垮整个批次的用户体验。重试的时候要注意加指数退避（比如首次重试等 1 秒，第二次等 2 秒，第三次等 4 秒），不要立刻重试，不然相当于给本就吃紧的 GPU 又加了一层瞬时压力，容易造成雪崩。
多卡部署时 --num-shard 设了但吞吐没提升甚至更差
张量并行不是卡越多越快，它要求卡间通信（比如通过 NVLink）足够快，否则每一层计算完都要做一次跨卡的数据同步，通信开销会把并行带来的收益吃掉。如果你的多卡环境走的是 PCIe 而不是 NVLink，两卡张量并行的收益可能远低于预期，这种情况下换成”每张卡独立跑一个 TGI 实例、前面挂负载均衡”的水平扩展方式，往往比硬上张量并行更划算——数据并行不需要卡间频繁同步，通信开销小得多。
并发压测与成本怎么估
调完参数别急着上线，先自己压一遍。用 locust 或者简单点用 ab（Apache Bench）modelling 真实业务的请求分布，重点看两个指标：P99 延迟（而不只是平均延迟，平均值会掩盖长尾卡顿）和达到 P99 延迟明显恶化之前能扛住的并发数，这个并发数就是你这套配置的实际承载能力，别信启动参数里 --max-concurrent-requests 写的理论值。
成本估算上，按 GPU 小时单价 × 部署所需卡数 × 运行时长来算是最直接的，但容易漏算的是”为了扛住峰值预留的冗余算力”——如果你按平均并发配置显卡数量，遇到流量高峰就会大面积超时。经验做法是按 P95 并发（而不是平均并发）来定容量，平时的空闲算力用来跑批处理任务或者干脆缩容，云上按量计费的实例可以配合自动伸缩来省这部分冗余成本，具体单价请以你所在云厂商当前的官方计费页面为准，不同区域、不同 GPU 型号价格差异很大，这里不列具体数字免得过时误导你。
常见问题
TGI 启动时一直显示”Loading model”不动怎么回事？
首次启动会从 HF Hub 下载权重（70B 模型可能超过 100GB），确保网络通畅，或提前下载权重后映射本地目录。国内网络建议配置 HF 镜像站（HF_ENDPOINT=https://hf-mirror.com）。
TGI 支持流式输出吗？
支持。在请求体中设置 "stream": true，TGI 会返回 SSE（Server-Sent Events）格式的流式 token，前端可直接消费。
TGI 和 vLLM 能同时运行吗？
可以，它们是独立进程，分别监听不同端口。你可以先两者都部署，用 ab 或 locust 做并发压测，选吞吐更高的方案用于生产。
延伸阅读：
- 算力基础全景：大模型算力基础指南
- 高并发吞吐框架：vLLM 部署高并发推理
- 量化方案详解：模型量化 GGUF/AWQ/GPTQ 怎么选
- GPU 选型指南：推理 GPU 选型：4090/A100/H100
- 算力专题 Hub：算力专题
- 不想自维护推理服务器？加入候补，直接调 API