ARTICLE · 1077186

本地大模型部署指南- vLLM(含源码)

发布时间：2026-09-25 18:57:29 最近访问：2026-09-25 18:57:01

面向 Linux/NVIDIA GPU 的高吞吐推理服务，提供连续批处理与 OpenAI 兼容 API。

推荐环境：Ubuntu/Linux + NVIDIA GPU；Windows 建议 WSL2 或容器化 Linux

模型格式：Hugging Face Transformers 模型、量化模型及 vLLM 支持的格式

示例接口：http://127.0.0.1:8000/v1/chat/completions

示例模型：Qwen/Qwen3-8B

安全提示：开发环境先绑定 127.0.0.1。生产环境不要将未鉴权服务直接暴露到公网，应先配置 TLS、认证、限流与访问审计。

一、部署前先确认这几件事

先明确使用目标：个人离线问答、桌面演示、内网 API，还是高并发生产服务。框架选择要同时考虑硬件、模型格式、并发需求与运维能力。

• 个人电脑或原型：优先选择 7B-14B 的量化 instruct 模型，重点确认内存、显存、SSD 空间和中文模板。

• 单 GPU 服务：重点确认显存、上下文长度、KV Cache 和并发数；模型参数量并不等于实际可承载的业务并发。

• 多 GPU 或多用户服务：通常选用 vLLM 或 SGLang，并提前设计网关、监控、鉴权和容量压测。

• CPU 或低显存设备：优先考虑 llama.cpp 与 GGUF 量化模型，验收指标是 tokens/s、内存占用和回答质量。

• 所有场景：模型、提示词、输入和输出都可能包含敏感数据；下载前阅读模型卡与许可证，定义数据保留和访问权限。

重要边界：本文给出部署流程，不代表当前机器已经安装或运行了模型。部署当天仍需重新核对框架版本、GPU 兼容性和模型许可证。

二、安装与启动

Windows 11 路径

1. 原生 Windows 不作为本指南的生产路径；使用 WSL2 Ubuntu 或远程 Linux GPU 主机。

2. 在 WSL2 中先验证 `nvidia-smi` 与 CUDA 可见性，再按 Linux 路径建立虚拟环境。

3. 若采用 Docker，确认 Docker Desktop 已启用 WSL2 集成和 NVIDIA Container Toolkit 支持。

Ubuntu/Linux + NVIDIA GPU 路径

4. 确认 NVIDIA 驱动、CUDA 兼容性和 `nvidia-smi` 输出，再建立隔离环境：`python3 -m venv .venv && source .venv/bin/activate`。

5. 安装前按 vLLM 官方安装矩阵核对 Python、PyTorch、CUDA 与 GPU 架构；常见起点为 `pip install vllm`。

6. 需要受限模型时，使用最小权限的 Hugging Face Token，并通过环境变量或秘密管理器传入。

版本提示：GPU 推理框架会受到 Python、PyTorch、CUDA、NVIDIA 驱动和模型架构的共同影响。升级前应在隔离环境验证，并保留可回滚版本。

启动服务

vllm serve Qwen/Qwen3-8B --host 127.0.0.1 --port 8000 --dtype auto --gpu-memory-utilization 0.90

出现监听地址或模型加载完成日志后，还要继续执行下一节的模型列表检查和对话请求，不能只看进程是否启动。

三、接口验证与 Python 调用

请求流程：业务程序发起 HTTP 请求 -> 推理服务排队与调度 -> 模型加载权重并推理 -> 服务返回 JSON 或流式响应。生产环境应把公网入口、TLS、认证和限流交给网关，模型服务本身仅监听私网或回环地址。

先做健康检查或模型发现

curl http://127.0.0.1:8000/v1/models

预期结果是能列出已加载模型，或收到与框架文档一致的健康响应。若此步骤失败，先排查端口、服务进程、监听地址和防火墙。

最小 Python 客户端

下面仅使用 Python 标准库。启动服务后，将 `model` 字段替换为服务实际暴露的模型标识；业务代码还需要补充超时、重试边界、请求日志和敏感信息处理。

from __future__ import annotationsimport jsonfrom urllib.request import Request, urlopenurl = "http://127.0.0.1:8000/v1/chat/completions"payload = { "model": "Qwen/Qwen3-8B", "messages": [{"role": "user", "content": "请用一句话说明本地部署的意义。"}], "temperature": 0.2}request = Request( url, data=json.dumps(payload).encode("utf-8"), headers={"Content-Type": "application/json"}, method="POST",)with urlopen(request, timeout=60) as response: result = json.loads(response.read().decode("utf-8"))print(result["choices"][0]["message"]["content"])

四、生产化部署建议

• 生产部署明确设置 `--tensor-parallel-size`、最大模型长度、GPU 内存利用率和并发上限；先压测再提高并发。

• 优先通过 Nginx/Envoy/API Gateway 提供 TLS、鉴权、限流和访问日志，vLLM 实例通常只监听私网。

• Docker 镜像、vLLM、PyTorch、CUDA 和驱动必须作为一个兼容矩阵锁定版本。

可用性：使用进程托管和健康检查，观察存活、就绪、重启次数与模型加载时长。

性能：设置连接/读取超时、请求大小上限和并发边界，监控首 token 延迟、tokens/s、P50/P95 与队列长度。

资源：限制 CPU、内存、显存和磁盘；持续观察 GPU 利用率、显存、KV Cache 与磁盘余量。

安全：模型服务仅私网监听或置于网关保护之后；审计认证失败、限流命中和异常请求。

Linux systemd 服务模板

[Unit]Description=vLLM local LLM serviceAfter=network-online.target[Service]User=llmWorkingDirectory=/opt/llmEnvironment=HOME=/var/lib/llmExecStart=/bin/bash -lc 'vllm serve Qwen/Qwen3-8B --host 127.0.0.1 --port 8000 --dtype auto --gpu-memory-utilization 0.90'Restart=on-failureRestartSec=5[Install]WantedBy=multi-user.target

模板说明：这是结构示例，不应原样直接用于生产。必须替换实际的虚拟环境或二进制绝对路径、模型目录、用户权限、日志路径、环境变量和网关策略。

五、常见问题排查

7. 1. 端口无法访问

常见原因：服务只监听回环地址、进程未启动，或防火墙阻断

建议动作：先在服务主机执行健康检查；确认监听地址、入站规则和反向代理配置。

8. 2. 首次响应很慢

常见原因：模型首次加载、CUDA 内核编译或磁盘缓存尚未就绪

建议动作：预热一条短请求；把模型放在 SSD；观察显存和磁盘占用。

9. 3. 显存不足

常见原因：模型、KV Cache、上下文长度和并发总量超过显存

建议动作：换小模型或量化版本；降低上下文/并发；调整 GPU 内存参数。

10. 4. 返回 401/403

常见原因：网关或服务启用了鉴权，但客户端未提供正确密钥

建议动作：检查反向代理与服务端鉴权策略；从环境变量读取密钥，不要写入代码。

11. 5. 模型下载失败

常见原因：网络、代理、磁盘空间或模型仓库权限问题

建议动作：核对网络与代理；预留足够磁盘；先用浏览器或 CLI 验证模型仓库访问。

12. 6. 中文输出异常

常见原因：模型模板、编码或客户端请求体不一致

建议动作：使用 UTF-8 JSON；选择明确支持中文的 instruct/chat 模型；检查 chat template。

13. 7. 启动时 CUDA/PyTorch 不匹配

常见原因：驱动、CUDA、PyTorch wheel 或 GPU 架构不匹配

建议动作：按 vLLM 官方兼容矩阵重建环境；不要混用系统 PyTorch 和旧虚拟环境。

六、官方资料

部署当天请再次核对官方发布版本、安装方式、兼容矩阵和模型许可。不要把本文示例中的版本或模型名视为永久不变。

• https://docs.vllm.ai/en/stable/

• https://docs.vllm.ai/en/stable/getting_started/quickstart/

相关学习资料