当前位置：首页 > news >正文

vLLM生产级部署实战：从Ollama迁移的稳定性优化全指南

news 2026/6/7 5:17:28

1. 项目概述：从 Ollama 切换到 vLLM 的真实动因与核心价值

我是在一个凌晨三点的 NAS 机柜前，盯着 Ollama 日志里那行“27 minute hang”决定换框架的。不是因为追求时髦，也不是被某篇技术白皮书说服，而是手头正在跑的 GraphRAG 流程——处理一批含 387 页 PDF、嵌套 14 层 JSON Schema 的客户合同文档——连续三天卡在知识图谱构建的第七步，每次重启后都从头开始，电费和耐心一起烧得滋滋作响。这背后没有宏大叙事，只有三个赤裸裸的现实问题：预算失控、响应失稳、运维崩溃。

Ollama 确实是本地 LLM 部署的“入门级瑞士军刀”：一行ollama run gemma:latest就能跑起来，Docker Compose 文件写得比咖啡配方还简洁，对 Hugging Face 模型的支持开箱即用，128K 上下文的宣传标语也足够诱人。但当你把它当成生产环境里的“主力发动机”，而不是周末玩具时，那些被简化掉的细节就会变成定时炸弹。比如它声称支持 128K 上下文，实际运行中却会随机截断成 35,567 token；比如它标榜“自动内存管理”，结果在双 GPU 场景下把显存当共享硬盘用，GPU0 被桌面显示进程占掉 1.2GB VRAM 后，整个推理服务直接报错退出；再比如那个默认 48 小时的超时设置——不是它忘了改，而是它的架构压根没设计“优雅降级”或“请求熔断”，挂就挂满 48 小时，期间所有新请求排队等死。

vLLM 不是来取代 Ollama 的，它是来接替“生产环境守夜人”这个岗位的。它不承诺“一键部署”，但保证“请求必达”；它不提供多模型热切换的便利，却用张量并行（Tensor Parallelism）把两块 RTX A2000 的 24GB 显存真正拧成一股绳；它放弃 GGUF 格式支持，换来的是 PagedAttention 内存管理机制——把 KV Cache 像操作系统管理物理内存一样切分成固定大小的页，按需加载、动态回收，彻底告别 OOM 崩溃。这篇文章要讲的，不是“vLLM 多好”，而是一个在 NAS 上自建 RAG 服务的实战者，如何用 72 小时踩坑、14 次配置迭代、3 个关键参数调整，把服务稳定性从“每天手动救火三次”提升到“能放心让它跑通宵”的全过程。关键词里的 “Towards AI” 并非指向某个平台，而是代表一种务实的技术判断取向：不迷信概念，只验证结果；不堆砌参数，只解决真问题。

2. 架构选型深度拆解：为什么是 vLLM，而不是 LiteLLM、Text Generation Inference 或自研方案？

选择 vLLM 不是一次灵光乍现，而是在 Ollama 崩溃后，对当前所有主流开源推理框架做的一次“生产环境适配度”压力测试。我把评估维度压缩成三个硬指标：单请求确定性、多请求吞吐密度、故障恢复成本。这三个指标直接对应着 GraphRAG 流程中最痛的三个环节：单次长文档解析的可靠性、批量知识图谱构建的并发效率、以及服务中断后重跑任务的时间损失。

先看 LiteLLM。它本质是个 API 网关层，把不同后端（OpenAI、Anthropic、Ollama）的接口统一成 OpenAI 格式。这在开发调试阶段很香，但一旦进入生产，它就成了性能瓶颈和故障放大器。举个例子：当 GraphRAG 需要并行发起 12 个子查询去检索不同知识节点时，LiteLLM 会把这些请求全部转发给底层 Ollama 实例。而 Ollama 的批处理能力极弱，12 个请求进来，它大概率会串行执行，或者因上下文计算错误导致其中 3 个请求超时失败。更致命的是，LiteLLM 自身不管理 GPU 显存，它只是个“传话筒”，底层 Ollama 挂了，它就跟着挂，且日志里只显示“Connection refused”，根本看不出是 GPU OOM 还是网络抖动。这种“黑盒叠加黑盒”的架构，在需要稳定性的场景里，风险系数直接拉满。

再看 Hugging Face 官方的 Text Generation Inference（TGI）。它确实比 Ollama 更接近生产标准，支持连续批处理（Continuous Batching）和量化。但它的设计哲学是“为 Hugging Face Hub 服务”，对本地私有化部署的友好度打了折扣。最典型的例子是模型加载：TGI 强制要求模型必须以 safetensors 格式存储，且对.bin文件支持不稳定。而我在 NAS 上缓存的 Gemma-3 模型，是通过huggingface-cli download直接拉下来的原始格式，里面混着.safetensors和.bin。TGI 在加载时会反复尝试解析，耗时长达 8 分钟，期间 GPU 显存占用飙升到 95%，最终因超时失败。我试过手动转换格式，但transformers库的convert脚本在 12GB 显存的 A2000 上会触发 CUDA Out of Memory，形成死循环。这种“为云优化，为本地设障”的体验，让我果断放弃。

至于自研方案？我用 PyTorch 写过一个最小可行版的推理服务，核心逻辑就是model.generate()加上简单的 HTTP 封装。它跑得飞快，但稳定性是灾难性的。当并发请求数超过 3 个，PyTorch 的 CUDA Context 就会开始争抢，出现“CUDA error: device-side assert triggered”这类底层错误，且无法捕获具体是哪个请求触发的。更麻烦的是，PyTorch 默认的内存分配器（cudaMalloc）在长时间运行后会产生严重碎片，一个原本只需 4GB 显存的请求，后期可能需要 6GB 才能成功分配，最终服务在第 17 小时必然崩溃。这印证了一个残酷事实：通用深度学习框架的推理能力，不等于高可用推理服务的能力。后者需要专门的内存管理、请求调度、错误隔离机制，这些正是 vLLM 的核心专利。

vLLM 的胜出点，恰恰在于它把这三个痛点都转化成了设计优势。它的 PagedAttention 机制，让 KV Cache 的内存占用变得可预测、可复用，彻底解决了显存碎片问题；它的 Continuous Batching 是真·动态批处理，能根据请求到达时间自动合并，把 12 个独立请求压缩成 2-3 个大批次，吞吐量直接翻倍；它的错误处理是“请求粒度”的，一个请求出错（比如 prompt 超长），不会影响其他请求，日志里会清晰标记Request ID: xxx failed due to ...，运维排查时间从小时级降到分钟级。这不是理论上的优势，而是我在把 GraphRAG 的文档解析模块从 Ollama 迁移到 vLLM 后，监控面板上看到的真实曲线：平均延迟从 42.3 秒降到 18.7 秒，P95 延迟波动范围从 ±25 秒收窄到 ±3.2 秒，服务月度宕机时间从 11.7 小时归零。选择 vLLM，本质上是选择了“用确定性换取复杂度”，而这个交换，在我的场景里，每一分钱都花在了刀刃上。

3. 核心参数精调指南：从 Docker Compose 到 GPU 显存的每一处关键配置

vLLM 的 Docker Compose 配置表面看只是一份 YAML 文件，但每一行参数背后，都是对 GPU 硬件特性、CUDA 运行时机制、以及 RAG 工作负载模式的深度理解。我把整个配置过程拆解成四个不可跳过的环节：容器基础环境、GPU 资源绑定、模型加载策略、推理行为控制。跳过任何一个环节，都可能在启动瞬间就失败，或者在运行数小时后悄然崩溃。

3.1 容器基础环境：IPC 模式与共享内存的生死线

Docker 默认的 IPC 模式是private，这意味着每个容器拥有自己独立的/dev/shm（POSIX 共享内存段），大小固定为 64MB。这在单 GPU 场景下够用，但在双 GPU 的 vLLM 张量并行（Tensor Parallelism）模式下，就是灾难的起点。vLLM 的 TP 模式要求两个 GPU 进程之间通过 NCCL（NVIDIA Collective Communications Library）进行高频通信，而 NCCL 默认使用/dev/shm作为通信缓冲区。实测数据显示，单个 A2000 GPU 在 TP 模式下，NCCL 初始化阶段就需要约 33MB 的共享内存空间。两个 GPU 同时启动，64MB 的默认值连初始化都撑不住，必然报错NCCL_SYSTEM_ERROR: System call failure，然后容器直接退出。

解决方案是强制使用ipc: host。这会让容器直接挂载宿主机的/dev/shm，其大小由宿主机内核参数kernel.shmmax决定（通常为 64MB * 1024 = 64GB，远超需求）。但这不是简单加一行就完事。ipc: host意味着容器与宿主机共享 IPC 命名空间，存在潜在的安全隔离风险。我的 NAS 宿主机上还运行着 Plex 媒体服务器和 Nextcloud，它们也依赖共享内存。为避免冲突，我在宿主机上执行了两步加固：第一，修改/etc/sysctl.conf，将kernel.shmmax和kernel.shmall设置为精确值68719476736（64GB），避免过大值被其他进程滥用；第二，在 Docker Compose 的command中，显式添加--nccl-socket-ifname=eth0，强制 NCCL 使用指定网卡通信，避免它误用宿主机的docker0网桥。这两步操作后，vLLM 的 NCCL 初始化成功率从 0% 提升到 100%，且 Plex 服务完全不受影响。

3.2 GPU 资源绑定：`NVIDIA_VISIBLE_DEVICES`与显存争夺战

NVIDIA_VISIBLE_DEVICES: "0,1"这行配置看似直白，但它触发了一场隐秘的显存资源争夺战。A2000 是专业卡，但我的 NAS 宿主机上，GPU0（PCIe Slot 1）同时承担着桌面显示输出任务（通过 HDMI 连接一台监控屏），而 GPU1（PCIe Slot 2）是纯粹的计算卡。Linux 内核会为 GPU0 分配一部分 VRAM 作为帧缓冲（Frame Buffer），这部分显存对 CUDA 应用是“不可见但不可用”的。实测发现，GPU0 的总显存为 12GB，但 CUDA 可用显存只有 10.8GB，被系统占用了 1.2GB。

如果对两块 GPU 使用相同的--gpu-memory-utilization 0.88参数，vLLM 会在 GPU0 上尝试分配10.8GB * 0.88 ≈ 9.5GB，在 GPU1 上尝试分配12GB * 0.88 = 10.56GB。问题在于，vLLM 的张量并行要求两块 GPU 的显存分配必须严格对称，否则会触发RuntimeError: Tensor parallel size must be divisible by number of GPUs。我的第一次失败，就是因为 GPU0 的可用显存不足，导致分配失败。

破局的关键在于差异化配置。我放弃了全局统一参数，改为在command中为每块 GPU 单独指定显存上限：

--tensor-parallel-size 2 \ --gpu-memory-utilization 0.85 \ --gpu-memory-utilization-gpu0 0.82 \ --gpu-memory-utilization-gpu1 0.88

vLLM 官方文档并未公开--gpu-memory-utilization-gpu0这个参数，它是我通过阅读 vLLM 源码vllm/entrypoints/openai/api_server.py发现的隐藏选项。这个参数允许你为特定 GPU ID 设置独立的显存利用率。经过 7 次微调，最终确定 GPU0 使用 0.82（即10.8GB * 0.82 ≈ 8.86GB），GPU1 使用 0.88（即12GB * 0.88 = 10.56GB），两者差值控制在 1.7GB 以内，完美满足张量并行的对称性要求。这个细节，是官方教程里绝不会写的，却是双 GPU 生产部署的生死线。

3.3 模型加载策略：量化方式、缓存路径与安全令牌

模型加载是 vLLM 启动最耗时的环节，也是最容易出错的环节。我的配置中包含三个关键决策点：

第一，量化方式选择--quantization bitsandbytes。vLLM 支持 AWQ、GPTQ、SqueezeLLM 等多种量化，但bitsandbytes是唯一支持在加载时动态进行 4-bit 量化的方式。这意味着我不需要提前下载一个已经量化的 GGUF 模型（Ollama 的强项），而是可以直接加载 Hugging Face 上的原生unsloth/gemma-3-4b-it模型。好处是灵活性极高：如果后续想换回 8-bit 或 16-bit，只需改一个参数，无需重新下载数 GB 的模型文件。坏处是首次加载会慢 2-3 分钟，因为它要在 GPU 上实时执行量化计算。我接受这个代价，因为我的 GraphRAG 服务是“启动后长期运行”，而非“按需启停”。

第二，Hugging Face 缓存路径的挂载。volumes: - ~/.cache/huggingface:/root/.cache/huggingface这行配置，表面是路径映射，实则关乎磁盘 IO 性能。NAS 的硬盘是 SATA SSD，顺序读写速度约 550MB/s，但随机小文件读写（Hugging Face 缓存的特点）只有 40K IOPS。如果让 vLLM 在容器内新建缓存，它会把数千个.safetensors分片文件写入容器的 overlay2 文件系统，IO 延迟飙升。通过挂载宿主机已有的缓存目录，vLLM 直接复用之前huggingface-cli download下载好的完整模型，启动时间从 8 分钟缩短到 2 分钟 17 秒。

第三，Hugging Face Token 的安全注入。HUGGING_FACE_HUB_TOKEN: "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"这种明文写法在生产环境是重大安全隐患。我实际采用的是 Docker Secrets。在docker-compose.yml中，我移除了 environment 行，改为：

secrets: - hf_token secrets: hf_token: file: ./secrets/hf_token.txt

并在容器启动命令中，通过--hf-token-file /run/secrets/hf_token参数传递。这样，Token 文件只存在于内存中的 tmpfs 文件系统，容器销毁后自动消失，彻底杜绝了密钥泄露风险。这个细节，是很多教程忽略的“生产级安全底线”。

3.4 推理行为控制：从`--max-model-len`到`--enforce-eager`的全链路调优

推理参数是 vLLM 稳定性的最后一道闸门。我花了整整两天时间，用ab（Apache Bench）工具对每个参数做压力测试，最终锁定以下组合：

--max-model-len 56000：这是最反直觉的参数。Gemma-3 官方支持 128K 上下文，Ollama 也宣称支持。但我发现，当--max-model-len设为 128000 时，vLLM 在处理一个 85,000 token 的长文档时，KV Cache 的内存页分配会出现大量碎片，导致 P95 延迟飙升至 65 秒。通过nvidia-smi dmon -s u监控显存使用，我发现碎片率高达 37%。将该值降至 56000 后，碎片率稳定在 8% 以下，且完全覆盖了我的 GraphRAG 最大文档长度（实测最长为 49,231 tokens）。这个数字不是拍脑袋定的，而是基于公式Optimal Length = (GPU Total VRAM * Utilization) / (2 * Model Size in GB)计算得出：(12GB * 0.88 * 2) / (2 * 2.4GB) ≈ 44,000，再向上取整留出 25% 余量，得到 56,000。这是一个在“能力边界”和“稳定裕度”之间找到的黄金平衡点。

--enable-chunked-prefill：这个参数开启了“分块预填充”（Chunked Prefill）。GraphRAG 的典型请求是“请基于以下 50 页合同文本，提取所有甲方义务条款”，prompt 长度往往超过 30,000 tokens。传统预填充会一次性将整个 prompt 加载进 KV Cache，导致显存瞬时峰值过高。启用此参数后，vLLM 会将长 prompt 切分成多个 4096-token 的块，逐块处理，显存占用曲线变得平滑，OOM 风险降低 92%。

--enforce-eager：这是调试阶段的救命稻草。vLLM 默认使用 PyTorch 的torch.compile进行动态图优化，能提升 15% 吞吐，但错误信息极其晦涩。开启此参数后，它退回到传统的 eager mode，虽然性能略降 5%，但所有 CUDA 错误都会精准定位到 Python 代码行，配合--log-level DEBUG，我能快速判断是模型权重加载问题，还是 attention mask 构造错误。在生产环境稳定后，我依然保留它，因为“可预测的 5% 性能损失”，远胜于“不可预测的 100% 服务中断”。

4. 实操全流程详解：从零开始搭建、验证到上线的每一步

把一份配置文件写对，和让一个服务真正稳定运行，是两回事。我把整个迁移过程拆解成六个严格按序执行的阶段，每个阶段都有明确的成功标志和失败回滚方案。这不是理想化的流程图，而是我在 NAS 机柜前，用键盘和日志文件一步步踩出来的血泪路径。

4.1 阶段一：宿主机环境预检（耗时 15 分钟）

在任何 Docker 操作前，必须确保宿主机“地基”牢固。我执行了四条命令，缺一不可：

GPU 驱动与 CUDA 版本校验：
```
nvidia-smi --query-gpu=name,driver_version,cuda_version --format=csv
```
输出必须显示RTX A2000、驱动版本>= 535.104.05、CUDA 版本>= 12.2。A2000 对 CUDA 12.4 有兼容性问题，如果检测到12.4，必须降级到12.2。这是无数人卡住的第一步，因为nvidia-docker会静默失败。
共享内存容量检查：
```
df -h /dev/shm cat /proc/sys/kernel/shmmax
```
/dev/shm必须挂载且容量>= 1GB，shmmax必须>= 1073741824（1GB）。如果不符合，执行sudo sysctl -w kernel.shmmax=1073741824并写入/etc/sysctl.conf。
Docker Engine 配置验证：
```
docker info | grep -i "runtimes\|nvidia"
```
输出必须包含nvidiaruntime。如果缺失，说明nvidia-container-toolkit未正确安装，需按 NVIDIA 官方文档重装。
Hugging Face 缓存完整性扫描：
```
ls -la ~/.cache/huggingface/hub/models--unsloth--gemma-3-4b-it/snapshots/
```
必须看到一个以长哈希值命名的子目录，且其内部包含config.json,model.safetensors,tokenizer.model等核心文件。如果目录为空或缺失，立即执行huggingface-cli download unsloth/gemma-3-4b-it --local-dir ~/.cache/huggingface/hub/models--unsloth--gemma-3-4b-it。

提示：这四个检查项，任何一个失败，都必须当场修复。我曾因跳过第 2 步，在启动后 3 小时才遇到 NCCL 错误，白白浪费了调试时间。

4.2 阶段二：最小化 Docker Compose 启动（耗时 8 分钟）

创建一个极简的docker-compose.min.yml，只包含最核心的三行：

services: vllm: image: vllm/vllm-openai:latest command: >- --model unsloth/gemma-3-4b-it --max-model-len 56000 --tensor-parallel-size 2 ports: - "28888:8000" volumes: - ~/.cache/huggingface:/root/.cache/huggingface environment: NVIDIA_VISIBLE_DEVICES: "0,1"

执行docker compose -f docker-compose.min.yml up -d。成功标志：docker ps显示容器状态为Up X minutes，且docker logs vllm | tail -20中没有ERROR或FATAL字样，结尾是INFO: Uvicorn running on http://0.0.0.0:8000。失败回滚：如果容器立即退出，执行docker logs vllm，90% 的概率是 NCCL 共享内存不足，此时立即执行docker compose -f docker-compose.min.yml down，然后进入阶段一重新检查。

4.3 阶段三：API 连通性与基础功能验证（耗时 5 分钟）

用curl直接调用 vLLM 的 OpenAI 兼容 API，发送一个最简请求：

curl -X POST "http://localhost:28888/v1/chat/completions" \ -H "Content-Type: application/json" \ -d '{ "model": "unsloth/gemma-3-4b-it", "messages": [{"role": "user", "content": "Hello"}], "max_tokens": 10 }'

成功标志：返回 JSON 中包含"choices": [{"message": {"content": "Hello! How can I help you today?"}}]，且响应时间< 3秒。失败排查：如果返回503 Service Unavailable，说明模型加载失败，检查docker logs vllm中是否有OSError: Unable to load weights；如果返回400 Bad Request，检查 JSON 格式是否合法；如果超时，检查nvidia-smi是否显示 GPU 利用率为 0%，说明 vLLM 进程未真正启动。

4.4 阶段四：压力测试与参数微调（耗时 45 分钟）

使用ab工具模拟 GraphRAG 的典型负载：

ab -n 100 -c 10 -p chat_request.json -T "application/json" http://localhost:28888/v1/chat/completions

其中chat_request.json是一个包含 2000 token prompt 的真实请求样本。记录Requests per second和Time per request (mean)。然后，每次只修改一个参数，重复测试：

将--max-model-len从 56000 改为 64000，观察延迟变化；
将--gpu-memory-utilization从 0.85 改为 0.88，观察是否出现CUDA out of memory；
添加--enable-chunked-prefill，观察 P95 延迟是否下降。

注意：每次修改后，必须执行docker compose down && docker compose up -d重建容器，因为 vLLM 的参数在启动时固化，热更新无效。

4.5 阶段五：GraphRAG 集成与端到端验证（耗时 2 小时）

将 vLLM 的 API 地址http://host_ip:28888/v1替换掉原有 GraphRAG 代码中的 Ollama 地址。重点验证三个场景：

单文档解析：上传一个 15,000 token 的 PDF，确认知识图谱节点生成无遗漏；
多文档并发：同时提交 5 个不同文档，确认所有请求均成功返回，无超时；
长上下文检索：在一个已构建的知识图谱上，执行一个需要跨 3 个文档关联的复杂查询，确认召回率和响应时间达标。

成功标志：所有场景下，GraphRAG 的日志中不再出现Connection reset by peer或Read timeout，且最终生成的 Neo4j 图谱数据完整，与 OpenAI 版本对比，关键节点覆盖率差异< 2%。

4.6 阶段六：生产环境守护与监控部署（耗时 30 分钟）

服务上线不等于结束，而是运维的开始。我部署了三层守护：

Docker 自愈：在docker-compose.yml的vllm服务下添加：

restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost:8000/health"] interval: 30s timeout: 10s retries: 3

GPU 显存监控脚本：创建gpu_monitor.sh，每 5 分钟执行nvidia-smi --query-gpu=memory.used,memory.total --format=csv,noheader,nounits，并将结果写入gpu_usage.log。当memory.used连续 3 次> 95%，自动触发docker restart vllm。
日志轮转配置：在docker-compose.yml中添加logging配置，限制单个日志文件大小为 10MB，最多保留 5 个文件，防止日志撑爆 NAS 存储。

至此，一个从零开始、经受过真实 GraphRAG 工作负载考验的 vLLM 服务，才算真正落地。整个过程耗时约 4 小时，但换来的是此后三个月零宕机的稳定运行。

5. 常见问题与独家避坑指南：那些文档里不会写的实战教训

在把 vLLM 推上生产环境的 92 天里，我记录了 37 个具体问题。这里精选 5 个最具代表性、最易踩坑的案例，附上根因分析和我的独家解决方案。这些不是教科书答案，而是我在凌晨两点对着nvidia-smi和docker logs反复推演后，刻进肌肉记忆里的经验。

5.1 问题：vLLM 启动后，`nvidia-smi`显示 GPU 利用率 0%，但`curl`请求一直超时

现象描述：容器状态为Up 5 minutes，日志里没有 ERROR，但所有 API 请求都卡在pending状态，curl最终返回Failed to connect to localhost port 28888: Connection refused。

根因分析：这不是网络问题，而是 vLLM 的--host参数默认绑定到了127.0.0.1（localhost），而 Docker 容器内的127.0.0.1指向的是容器自身，不是宿主机。当外部请求发到宿主机的28888端口时，Docker 的端口映射（"28888:8000"）会将流量转发到容器的8000端口，但 vLLM 只监听127.0.0.1:8000，拒绝来自0.0.0.0的连接。

独家解决方案：在command中显式添加--host 0.0.0.0。完整的启动命令应为：

--model unsloth/gemma-3-4b-it \ --max-model-len 56000 \ --host 0.0.0.0 \ --port 8000 \ ...

这个参数在 vLLM 文档中被列为“高级选项”，但对 Docker 部署是刚需。我花了 3 小时才意识到，docker ps显示的端口映射0.0.0.0:28888->8000/tcp，并不意味着 vLLM 自动监听0.0.0.0，它依然固执地只认127.0.0.1。

5.2 问题：GraphRAG 执行到知识图谱构建环节，vLLM 报错`ValueError: Input length (X) exceeds maximum context length (Y)`

现象描述：单个curl请求正常，但 GraphRAG 流程中，当它把多个文档的摘要拼接成一个超长 prompt 时，vLLM 返回Input length exceeds maximum context length，而X的值（如 62,341）明显大于我配置的--max-model-len 56000。

根因分析：vLLM 的--max-model-len控制的是模型能处理的最大总长度（prompt + generated tokens），而 GraphRAG 代码在拼接 prompt 时，并未预留max_tokens的生成空间。例如，我设置了--max-model-len 56000，但 GraphRAG 的请求中max_tokens=2048，那么实际允许的 prompt 长度上限是56000 - 2048 = 53952。当拼接后的 prompt 达到 54,000 时，就超限了。

独家解决方案：在 GraphRAG 的客户端代码中，增加一个动态长度校验函数：

def safe_truncate_prompt(prompt: str, max_model_len: int, max_tokens: int = 2048) -> str: """根据 vLLM 的 max-model-len 和请求的 max_tokens，安全截断 prompt""" tokenizer = AutoTokenizer.from_pretrained("unsloth/gemma-3-4b-it") prompt_tokens = len(tokenizer.encode(prompt)) available_prompt_len = max_model_len - max_tokens if prompt_tokens > available_prompt_len: # 截断到 available_prompt_len，保留末尾重要信息 truncated = tokenizer.decode(tokenizer.encode(prompt)[-available_prompt_len:]) logger.warning(f"Prompt truncated from {prompt_tokens} to {available_prompt_len} tokens") return truncated return prompt

这个函数必须在每次向 vLLM 发送请求前调用。它不是粗暴地按字符截断，而是按 token 精确计算，确保语义完整性。这是我从 Ollama 的“随机截断”血泪史中总结出的最实用技巧。

5.3 问题：服务运行 12 小时后，`nvidia-smi`显示 GPU 显存占用 100%，但`docker stats`显示容器内存使用率仅 45%

现象描述：服务看起来一切正常，但响应时间越来越慢，P95 延迟从 20 秒爬升到 85 秒。nvidia-smi显示GPU-0和GPU-1的Memory-Usage都是12288MiB / 12288MiB，而docker stats却显示vllm容器的MEM USAGE / LIMIT是8.2GiB / 18GiB。

根因分析：这是典型的 CUDA 显存泄漏（CUDA Memory Leak）。vLLM 的 PagedAttention 机制本身不会泄漏，但当它与某些特定的 PyTorch 版本（如 2.3.0）和 CUDA 12.2 组合时，torch.compile的动态图优化会在长时间运行后，导致部分 KV Cache 页无法被 GC 回收。docker stats只统计 CPU 内存，不统计 GPU 显存，所以产生巨大误导。

独家解决方案：有两个层面的应对：

短期急救：执行nvidia-smi --gpu-reset -i 0,1（需 root 权限），强制重置 GPU，立竿见影。但这只是治标。
长期根治：在command中添加--disable-custom-all-reduce和--enforce-eager。前者禁用 vLLM 的自定义 NCCL 优化，后者关闭torch.compile。虽然会损失约 8% 的吞吐，但换来的是 7x24 小时的绝对稳定。我在生产环境中，永远优先选择“可预测的性能”，而非“理论上的峰值”。