vLLM 与 TGI 部署及接口特性对比

本文对照 vLLM 与 TGI 的部署入口、服务端口和接口能力，并说明 TGI 已进入维护模式后，如何完成环境准备、启动、验证与接口迁移检查。

先看结论：TGI 的 README 显示项目已进入维护模式，只接受小型错误修复、文档改进和轻量维护，同时列出了基于 SSE 的令牌流和 continuous batching。vLLM 的 OpenAI 兼容服务器文档则实现了 Completions API、Chat API 等接口，启动入口是 vllm serve。因此，迁移时不能只看“兼容 OpenAI”，还要逐项核对维护状态、部署条件、路由和请求参数。

部署前先确认系统条件

vLLM Quickstart 列出的基础环境是 Linux 和 Python 3.10 至 3.13。其 GPU 安装文档进一步说明，vLLM 不原生支持 Windows，Windows 用户应通过 WSL 和兼容的 Linux 发行版运行；NVIDIA GPU 需要 compute capability 7.5 或更高。准备 rented GPU 时，应先核对这一条件，而不是只确认机器型号。

部署 vLLM 并验证服务

按 Quickstart 的推荐流程，可先创建独立的 Python 3.12 环境，再安装并启动一个示例模型：

uv venv --python 3.12 --seed
source .venv/bin/activate
uv pip install vllm --torch-backend=auto
vllm serve Qwen/Qwen2.5-1.5B-Instruct

--torch-backend=auto 会检查已安装的 CUDA 驱动版本并选择相应的 PyTorch 索引。服务默认监听 http://localhost:8000，可通过 --host 和 --port 修改地址；当前一个服务进程一次承载一个模型。

启动后先请求模型列表：

curl http://localhost:8000/v1/models

该接口用于列出可用模型。若没有响应，应先检查启动日志和监听地址，不要直接改用其他接口路径。

部署 TGI 并验证服务

TGI README 说明，使用 NVIDIA GPU 需要 NVIDIA Container Toolkit，并建议采用 CUDA 12.2 或更高版本的 NVIDIA 驱动。替换模型和卷目录后，可按其 Docker 示例启动：

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

这里把宿主机 8080 映射到容器 80，--shm-size 1g 用于提供 NCCL 所需的共享内存。README 示例使用的镜像标签是 3.3.5，使用前仍应核对当前版本。服务启动后，可打开 http://localhost:8080/docs 查看 REST API 的 OpenAPI 文档。

如果必须不用 GPU，文档给出的调整是移除 --gpus all，并加入 --disable-custom-kernels，但 TGI 并不以 CPU 为目标平台。受限或私有模型还需要通过 HF_TOKEN 环境变量提供访问令牌。

接口特性：相同路由，不同约束

两者都提供 /v1/chat/completions，但具体约束并不完全相同。TGI 接口文档说明，该路由使用 POST，响应遵循 OpenAI Chat Completion 规范；传入 "stream": true 可获得令牌流。非对话场景则使用 /generate 和 /generate_stream。

vLLM 除了 /v1/chat/completions，还提供 /v1/completions，但不支持 suffix 参数；Chat API 需要模型具备 chat template，并忽略 user 参数。parallel_tool_calls 默认为 true，设为 false 时，每次请求返回零个或一个工具调用。其接口清单还包括 /v1/responses、/v1/embeddings、/v1/audio/transcriptions 和 /v1/chat/completions/batch。

迁移现有客户端时，应同时记录请求路径、HTTP 方法、流式开关、chat template 要求和特殊参数。像 top_k 这类不属于 OpenAI 接口的参数，需要通过客户端的 extra_body 传入，或直接合并进原始 JSON 请求体。

参数设置决定运行边界

根据 vllm serve 参数文档，--gpu-memory-utilization 是当前实例使用的 GPU 内存比例，默认值为 0.92。如果显式设置 --kv-cache-memory-bytes，它会覆盖 gpu_memory_utilization 的作用，两者不应被当作同一个开关理解。

--max-model-len 控制提示词和输出合计的上下文长度；未设置时从模型配置推导，设为 -1 或 auto 时会选择 GPU 内存能够容纳的最大长度。--max-num-seqs 限制单次迭代处理的序列数，--max-num-batched-tokens 限制单次迭代处理的 token 数。排查显存、上下文或并发问题时，应先确认这些边界，而不是只调整请求长度。

本文步骤均依据文中链接的官方文档整理，没有进行运行验证或性能测量；使用前应按当前版本重新核对。