TGI 基于 vLLM 后端启动时提示 “no available memory for cache”，不是 TGI 服务本身崩溃，而是 vLLM 在初始化阶段为 KV cache 预留显存失败。这个错误发生在模型权重加载之后、服务真正接收请求之前，直接原因是显存中可用且连续的空间不够，通常与 max-model-len、tensor-parallel-size、gpu-memory-utilization 等参数有关。排查时不要只盯着“加大显存”或“多卡并行”，先按下面的顺序确认当前占用和配置。

该错误的核心原因是 vLLM 为 KV cache 分配显存时，可用空间不足或碎片化。只要暂时调低模型最大 token 长度、限制单请求输入长度，或调小显存利用率参数，通常能恢复启动。注意这只能缓解当前启动失败，真正的容量上限仍取决于 GPU 总显存和模型权重大小。

先确认显存占用和 GPU 分配

运行 nvidia-smi 查看 GPU 的 memory-used 和 memory-free。检查是否有其他进程占用了同一块 GPU，尤其当 TGI 指定了 CUDA_VISIBLE_DEVICES 时，被指定的卡必须处于可支配状态。建议使用以下命令获得干净数据：

nvidia-smi `--query-gpu`=index,memory.total,memory.used,memory.free `--format`=csv

如果 free 显存很小，比如只有几百 MB，那么即便调小参数，KV cache 也可能无法分配。此时需要先停掉占用显存的其他服务，或者换一块更大的 GPU。特别要注意某些嵌入模块、多进程推理会占用显存，启动 TGI 前要确认 GPU 完全空闲。

降低 KV cache 的 token 上限

vLLM 的 KV cache 大小与模型允许的最大序列长度强相关。TGI 通过启动参数控制这一上限。可以先设置一个保守值，确认能启动后再逐步扩大。例如：

text-generation-launcher `--model-id` meta-llama/Llama-2-7b-chat-hf `--backend` vllm `--max-total-tokens` 2048 `--max-batch-prefill-tokens` 1024

如果你的 TGI 版本不接受这两个参数，请通过 `--help` 查看实际的参数名。关键是把 max-total-tokens 设置为比预期请求长度稍大的值，而不是使用默认的 4096 或更高。调整后如果启动成功，说明之前的失败确实与 token 上限过大有关。

注意：降低 max-total-tokens 会限制单条请求的最大长度，同时可能降低并发时的显存占用。这是一个取舍，但不是恢复性能的方案。如果业务需要长上下文，应继续检查下面的显存利用率参数。

调整显存利用率和碎片策略

vLLM 会在显存中预分配模型权重和 KV cache。如果剩余显存不够，可以通过环境变量调低利用率。例如设置：

export VLLM_GPU_MEMORY_UTILIZATION=0.6

这个值表示 vLLM 最多使用的显存比例。调低后缓存分配会留出更多余量，但并发能力会下降。部分 vLLM 版本还支持通过 PYTORCH_CUDA_ALLOC_CONF 降低显存碎片影响：

export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True

设置后再启动 TGI。这个环境变量对 PyTorch 显存分配器生效，能降低“显存总量够但连续块不够”的概率。如果调低后仍失败，说明当前 GPU 总显存确实无法满足模型加最小 cache 的需求，需要换更大的 GPU，或改用更小的模型。

检查张量并行和 GPU 卡配置

如果启动命令里带着 tensor-parallel-size 且大于 1，vLLM 需要把模型和缓存分散到多张卡，每张卡都必须有足够独立显存。可以先强制改成 1 试一次：

text-generation-launcher `--model-id` meta-llama/Llama-2-7b-chat-hf `--backend` vllm `--tensor-parallel-size` 1

能启动后再回退到原并行数，并分别检查每张卡的 memory-free。多卡并行时，建议用 CUDA_VISIBLE_DEVICES 固定参与计算的 GPU 编号，避免选到被其他任务占用的卡。

验证并确认启动是否正常

参数调整后，不能只看“能启动”三个字。启动日志中应出现 vLLM 成功为 KV cache 分配空间的提示，然后向 /generate 发送一个短请求，确认输出正常。如果只是启动成功但生成时报错，说明显存仍然紧张，应继续降低 token 长度或并发数。验证时输入长度要小于 max-total-tokens，并观察 nvidia-smi 中 memory-usage 是否稳定在预期范围内。

综合来看，这个启动失败大概率是显存容量与缓存预留参数不匹配。按“确认空闲显存、降低 token 上限、调低显存利用率、减少并行数”的次序逐项排查，可以避免无谓的重启和模型切换。