模型推理引擎 TGI 完全指南

什么是文本生成推理 (TGI)？

Text Generation Inference（TGI）是 Hugging Face 官方维护的、用于部署大语言模型（LLM）的高性能推理引擎。它专为生产环境设计，将模型优化、动态调度与高效网络服务融为一体，让你能够以最低延迟、最高吞吐量对外提供文本生成服务。

TGI 不仅是一个 HTTP 服务器，更是一套完整的推理栈：内置连续批处理、张量并行、量化推理、安全水印以及对 OpenAI API 的兼容，使模型从实验到上线的路径缩短到几分钟。

核心特性

高性能推理

基于 Rust 开发的核心调度器，结合 CUDA graph 预热、自定义 kernel 与算子融合，TGI 能在保持低抖动的同时榨干 GPU 的每一分算力。对于同一模型，其推理吞吐通常是朴素 vLLM 或自建 FastAPI 方案的 1.5～2 倍。

连续批处理

传统静态批处理会让早完成的请求等待慢的请求，造成 GPU 空闲。TGI 采用连续批处理：请求一旦结束就立即将其移出批次，并动态插入预处理完毕的新请求。这使得 GPU 利用率始终接近 100%，并发请求下的端到端延迟大幅下降。

张量并行与模型分片

面对 70B、130B 等超大模型，单张 GPU 显存无法容纳。TGI 支持自动将模型层切分到多个 GPU 上（张量并行），只需在启动命令中指定 --num-shard 即可。对于多节点集群，还可以配合 --sharded 实现跨主机推理。

量化支持

TGI 原生支持多种量化方案，在精度与显存之间取得平衡：

• GPTQ / AWQ：通过 --quantize gptq 或 --quantize awq 加载已在 Hub 上量化的模型。
• bitsandbytes：通过 --quantize bitsandbytes-nf4 动态量化，几乎不影响输出质量，显存减少约 75%。
• EETQ：针对特定模型的高速量化方案。

动态预热与自动缩放

首次推理需编译 CUDA graph，TGI 会在后台自动完成 warm-up，确保第一个实际请求不会因编译产生高延迟。配合 --max-total-tokens 和 --max-batch-prefill-tokens，引擎能根据当前负载自动调整批次大小，避免显存溢出。

水印 (Watermarking)

为防止 AI 生成文本被滥用，TGI 内置了基于哈希的文本水印功能。启用 --watermark-gamma 后，模型输出的 token 分布会嵌入可检测的签名，便于事后追踪文本来源，且肉眼不可见。

兼容 OpenAI API

无需修改现有前端代码。TGI 提供 /v1/chat/completions 等 OpenAI 标准端点，支持对话模板和函数调用。这意味着任何对接过 ChatGPT API 的应用都能无缝切换到本地部署的 TGI 服务。

快速入门

使用 Docker 运行 TGI

确保已安装 NVIDIA Container Toolkit，然后执行：

model=microsoft/Phi-3-mini-4k-instruct
volume=$PWD/data  # 模型缓存目录

docker run --gpus all --shm-size 1g -p 8080:80 \
  -v $volume:/data \
  ghcr.io/huggingface/text-generation-inference:latest \
  --model-id $model

服务启动后，可通过 http://localhost:8080 访问。若需指定量化或多卡，只需添加参数：

docker run ... ghcr.io/huggingface/text-generation-inference:latest \
  --model-id $model --num-shard 2 --quantize bitsandbytes-nf4

发送第一个推理请求

使用 curl 测试生成接口：

curl http://localhost:8080/generate \
  -X POST \
  -d '{"inputs":"What is Deep Learning?","parameters":{"max_new_tokens":128}}' \
  -H 'Content-Type: application/json'

返回的 JSON 中包含生成的文本与详细统计信息。流式响应只需添加 "stream": true。

配置详解

模型加载参数

推理参数

客户端在请求中通过 parameters 字段传递，常用参数包括：

• temperature：控制随机性，值越低越确定，典型范围 0.1 ~ 1.0。
• top_p：核心采样，限制累计概率超过 p 的最小 token 集合。
• max_new_tokens：生成的最大 token 数。
• stop：停止词列表，遇到任何 stop token 立即终止。
• repetition_penalty：重复惩罚因子，1.0 表示无惩罚。

批处理与调度

• --max-waiting-tokens：允许等待队列中的总 token 数，限制显存占用以平衡延迟与吞吐。
• 连续批处理由 Rust 调度器自动管理，无需手动调参。通常只需根据 GPU 显存设置 --max-batch-prefill-tokens 和 --max-total-tokens。

量化和优化

• --quantize：接受 bitsandbytes-nf4、bitsandbytes-fp4、gptq、awq、eetq 等选项。
• 启用 --cuda-graphs 可捕获重复计算图（默认开启），提升小 batch 场景性能。
• --max-concurrent-requests：硬性并发限制，保护服务不被过载，超过限制会返回 503。

高级特性：并发与可扩展性

张量并行

对于超大模型，使用 --num-shard 将模型切分到多块 GPU。引擎会自动分配层，并插入必要的通信操作。例如，在 4xA100 80GB 上运行 70B 模型：

docker run --gpus all --shm-size 10g -p 8080:80 \
  ... \
  --model-id meta-llama/Meta-Llama-3-70B-Instruct \
  --num-shard 4 --quantize bitsandbytes-nf4

动态批处理策略

TGI 的调度器会同时管理 prefill 和 decode 阶段：prefill 计算密集型，decode 访存密集型。通过 --max-batch-prefill-tokens 和 --max-batch-total-tokens 可在二者之间取得平衡。在典型聊天机器人场景中，将 max-batch-prefill-tokens 设为 4096 即可满足 90% 的交互式负载。

部署方案

单 GPU 部署

最简单的部署方式：拉取官方镜像，传递模型 ID，暴露端口即可。适用于 7B 及以下模型，使用量化后甚至可运行 13B 模型。

多 GPU 部署

在一台机器内使用多个 GPU，只需通过 --num-shard 或 --sharded 指定。Docker 运行时必须挂载所有 GPU（--gpus all），并为主机通信分配足够大的共享内存（--shm-size 建议为总 GPU 数 × 16GB）。

在 Kubernetes 上部署

Hugging Face 提供 Helm Chart，支持基于 nodeSelector 的 GPU 调度、HPA 弹性伸缩和 Prometheus 指标暴露。一个典型的生产级部署会结合 Ingress，并开启 GRPC 以提高内部服务间通信效率。

关键配置片段：

replicaCount: 2
resources:
  limits:
    nvidia.com/gpu: 4
args:
  - --model-id=mistralai/Mixtral-8x7B-Instruct-v0.1
  - --num-shard=4
  - --max-input-length=4096
  - --max-total-tokens=8192

常见问题

问：TGI 与 vLLM 有什么区别？
答：两者都实现了连续批处理，但 TGI 在量化支持（尤其是 bitsandbytes 动态量化）、水印、安全过滤、Hugging Face Hub 生态集成以及 OpenAI API 兼容性方面更胜一筹。性能差异因模型和硬件而异，建议针对具体场景测试。

问：如何监控推理性能？
答：TGI 暴露了标准化的 Prometheus 指标端点 /metrics，包括请求数量、延迟分布、batch 大小、token 吞吐等。可以直接接入 Grafana 仪表盘。

问：推理请求体过大导致超时怎么办？
答：可通过环境变量 MAX_INPUT_LENGTH 设置服务端最大输入长度，同时客户端应做好重试与降级逻辑。另外，增加 --max-waiting-tokens 可缓解排队压力。

问：如何加载微调后的 LoRA 适配器？
答：TGI 当前版本原生支持推理时动态加载 LoRA 权重，只需将适配器放在 Hugging Face Hub 或本地目录，启动时通过 LORA_ADAPTERS 环境变量或 --lora-adapters 参数指定即可。

开始使用 Hugging Face TGI，让你的大语言模型推理服务从“能用”跃升为“好用”。更多高级用法和参数说明请查阅 官方文档。