企业官网建设流程全解析

简介：面向大语言模型部署实践者的一份完整项目资料，以通义千问Qwen为对象，基于vLLM框架介绍服务化部署的关键方法。压缩包内共收集9个文件，包括6个Python脚本、2张运行效果图、1份说明文档，整体大小仅为433KB，轻量易用。6个脚本各司其职，分别用于启动vLLM服务、通过客户端发起请求、执行离线推理、封装模型调用、构建提示词处理工具，以及启动基于Gradio的可视化交互页面，基本覆盖从模型加载、接口定义到服务启停的完整部署链路。两张截图直观展示Web界面与Qwen的运行效果，说明文档则对依赖安装、模型配置、接口测试和性能调优等步骤给出详细指引，兼顾高并发请求与系统稳定性等实际场景。资料已有1491人学习下载，适合具备一定Python基础、希望通过源码与教程快速上手大模型服务部署的开发者。

1. 用 vLLM 部署 Qwen：为什么这是目前最稳的私有化部署路线

当你要在企业内网跑通通义千问 Qwen 大模型时，第一件事不是写提示词，而是选对部署引擎。vLLM 是目前社区用得最多、也最不容易翻车的选择：它用 PagedAttention 把显存利用率拉高了一个数量级，QPS 吞吐在同类开源方案里长期排第一梯队，而且对外暴露 OpenAI 兼容接口，意味着你现有调用 ChatGPT 的业务代码几乎不用改就能切换过来。这篇实战笔记要做的，就是把「装环境 → 拉模型 → 起服务 → 调参数 → 避坑 → 接业务」这条链路完整走一遍，对应标题里那个项目实战包的落地路径。适合手里有带 NVIDIA 显卡的 Linux 服务器、想在企业内部做本地部署大语言模型的工程师——看完你可以照着命令一把跑通，也能知道上线前哪些参数必须动。

2. 部署前的环境准备：CUDA、Python 与 vLLM 安装的三个匹配点

2.1 先用一张表搞清楚选型：为什么不是 Ollama，不是 Text Generation Inference

开始动手前，先说清楚为什么整个方案锁定 vLLM。市面上常见的本地部署大语言模型工具有几个：Ollama 胜在安装简单，适合个人笔记本；SGLang 和 vLLM 类似，都是高性能推理引擎；TGI 是 Hugging Face 家的，部署起来配置项更多。vLLM 之所以在企业大模型私有化部署场景里最常用，核心是两点：一是显存效率，PagedAttention 把 KV Cache 分页管理，长上下文场景下显存浪费明显少；二是接口兼容，原生提供 /v1/chat/completions，和 OpenAI 格式一致，接入 FastGPT、Dify 这类前端平台几乎零改造。

我总结过一张简单的对比表，供选型时参考：

如果目标很明确是企业内网做服务、对接上层应用，vLLM 是第一选择。如果是给同事做本地体验工具，Ollama 也可以，但并发和吞吐上来以后，Ollama 的排队策略和显存管理就没 vLLM 从容了。

2.2 CUDA 版本和 vLLM wheel 的匹配：先查再装，避免玄学报错

vLLM 安装遇到的大部分翻车现场，都出在 CUDA 版本和 PyTorch 版本对不上。我的做法是先在服务器上确认三件事：显卡驱动版本、CUDA 运行时版本、Python 版本。

# 查看显卡和驱动 nvidia-smi # 查看 Python 版本 python3 --version # 查看当前 CUDA 运行时版本（如果已装） nvcc --version

需要说明的是，nvidia-smi 显示的 CUDA Version 是驱动支持的最高 CUDA 版本，不代表当前环境里实际装了哪个 CUDA Toolkit。vLLM 的 pip 包在安装时会校验 PyTorch 编译时用的 CUDA 版本，如果你本机没有对应版本的 CUDA Toolkit，但 PyTorch 自带的 CUDA runtime 是完整的，也能跑——前提是驱动版本足够新。

常见做法是新建一个干净的 conda 环境，直接用 PyTorch 官方索引装对应 CUDA 版本的 PyTorch，再装 vLLM：

conda create -n vllm-qwen python=3.10 -y conda activate vllm-qwen # 以 CUDA 12.1 为例，先装 PyTorch pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121 # 再装 vLLM，pip 会自动拉取配套的依赖 pip install vllm

这里有几个参数值得解释一下。Python 版本我通常选 3.10，因为 vLLM 对 3.10 和 3.11 的支持最成熟，3.12 在有些版本上会遇到编译依赖缺失的问题。CUDA 版本的选择要看 vLLM 官方发布页里对应版本支持的 CUDA 列表，一般 12.1 和 12.4 是覆盖面最广的；如果你用的是较新的显卡架构，建议优先考虑 CUDA 12.x 的较新小版本，配套的驱动也更全。

提示：如果公司内网不能直连 PyTorch 官方源，可以先配好 pip 的镜像源，再执行同样的命令。vLLM 本身优先用 pip 装预编译 wheel，不要一上来就源码编译，源码编译非常耗时且容易踩内核编译的坑。

2.3 模型文件从哪拿：ModelScope 下载 Qwen 的步骤

模型权重来源是第二个大坑。Hugging Face 在国内访问不稳定，企业内网环境尤其麻烦。我一般直接用 ModelScope 拉 Qwen 权重，它在国内有镜像，速度和下载稳定性都好得多。用 modelscope 的 Python SDK 下载模型：

# 安装 modelscope pip install modelscope # 下载 Qwen2.5-7B-Instruct 到本地目录 modelscope download --model Qwen/Qwen2.5-7B-Instruct --local_dir /data/models/qwen2.5-7b-instruct

这段命令的逻辑是：--model 指定模型仓库 ID，--local_dir 指定下载到本机的绝对路径。下载完成后会在目录里看到 config.json、tokenizer.json 以及多个 .safetensors 分片文件。值得注意的一点是，vLLM 加载模型时要求目录里包含完整的 tokenizer 文件，很多下载工具默认会跳过部分文件，导致启动时才报“缺少 tokenizer_config.json”。所以下载完先确认这几个关键文件都在：

ls /data/models/qwen2.5-7b-instruct

正常应该能看到 config.json、generation_config.json、tokenizer_config.json、tokenizer.json、chat_template.json 和若干 .safetensors 文件。如果缺文件，重新用 modelscope download 补拉一次，不要手动从别的机器拷贝，容易混入版本不一致的文件。

关于模型版本选择，也在这里多说一句。如果服务器显存不大，优先选 Instruct 版本而不是 Base 版本，因为 Base 版本没有经过对话指令微调，直接接 OpenAI 兼容接口时回答质量会明显差一个档次。量化版本（比如 AWQ 或 GPTQ）建议先跑通 FP16 再考虑，排错时少一个变量。

3. 跑通第一个 vLLM 服务：启动命令、参数含义与验证请求

3.1 最小启动命令：从 FP16 开始

环境就绪、模型下载完成后，就可以启动 vLLM。第一步不要加任何花哨的优化参数，先用最朴素的命令跑起来，确认链路是通的。

conda activate vllm-qwen # 用 vLLM 启动 Qwen2.5-7B-Instruct 的 OpenAI 兼容服务 python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-7b-instruct \ --served-model-name qwen2.5-7b \ --port 8000 \ --host 0.0.0.0 \ --gpu-memory-utilization 0.85 \ --max-model-len 8192

逐项拆一下这几个参数的意义。--model 指定的是本地模型目录绝对路径，这样 vLLM 不会尝试从远端拉权重。--served-model-name 是暴露给客户端的模型名，你可以随意起名，客户端请求时这个值要和它一致。--host 0.0.0.0 表示监听所有网卡，这样内网其他机器可以访问；如果只本机调试，改成 127.0.0.1 更安全。--gpu-memory-utilization 控制显存使用上限，0.85 表示最多用 85% 显存，留一点余量给 CUDA context 和驱动开销。--max-model-len 是输入输出历史的总 token 上限，这里设 8192 意味着单轮对话上下文最长为 8192 tokens。

启动日志里重点关注两行：一行是模型权重加载完成的提示，另一行会打印出当前显存配置下能支撑的最大并发数。如果看到显存不足的报错，优先调低 --gpu-memory-utilization，而不是急着换小模型。

注意：--max-model-len 不是越长越好。7B 模型在 FP16 下权重约占 14GB 显存，剩余显存要同时容纳 KV cache。设成 32768 后，并发一上来很容易提示 KV cache 空间不足，日志会直接报错。

3.2 用 curl 验证服务的三个关键字段

服务启动后，先在服务器本地验证。不要急着接业务系统，先用一个最小请求确认模型推理正常：

curl http://127.0.0.1:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "model": "qwen2.5-7b", "messages": [ {"role": "user", "content": "用一句话介绍你自己"} ], "max_tokens": 256, "temperature": 0.7 }'

如果返回内容里有 choices[0].message.content 字段，说明服务已经正常对外提供大模型推理能力了。这里要特别确认的是请求里的 model 字段，必须和启动命令里的 --served-model-name 一致，否则会返回 model not found。很多第一次用 vLLM 的同事在这里翻车，明明服务起来了，客户端一直报错，就是因为模型名没对上。

3.3 接入 Python 业务代码：用 openai 库替换调用

服务验证通过后，业务侧接入就非常简单。因为 vLLM 暴露的是 OpenAI 兼容接口，Python 端直接用 openai 库，只需把 base_url 指向 vLLM：

from openai import OpenAI client = OpenAI( base_url="http://你的内网IP:8000/v1", api_key="sk-空值即可" # vLLM 默认不校验 api key，但字段必须传 ) resp = client.chat.completions.create( model="qwen2.5-7b", messages=[{"role": "user", "content": "简述 RAG 的原理"}], max_tokens=512, temperature=0.3, ) print(resp.choices[0].message.content)

这段代码的价值在于：如果之前业务对接的是 OpenAI 官方接口，迁移到本地只改 base_url 一行，其余代码全部不动。vLLM 在接收到请求时会自动做 tokenize、推理和 detokenize，响应结构也和 OpenAI 保持一致的字段命名。api_key 传一个字符串即可，vLLM 默认不校验，但 openai 库会要求非空，否则请求发不出去。

4. 上线前必调的四个参数：显存、上下文长度、并发与量化

4.1 gpu-memory-utilization：先算权重占用量，再定值

很多人在这一步喜欢凭感觉填 0.9 或 0.95，结果启动即崩溃。正确的做法是先算一下模型权重的显存占用。FP16 格式下，每 10 亿参数约占用 2GB 显存。Qwen2.5-7B 约 7.6B 参数，权重约 14.5GB；如果是 14B 模型，约 29GB。再加上 CUDA context、激活值、以及推理过程中产生的临时张量，剩余显存才是 KV cache 的可用空间。

我一般分两种场景定这个值。场景一：单卡 24GB（如 RTX 3090 或 4090），跑 Qwen2.5-7B FP16。权重已经占掉 14.5GB，剩下的 9GB 多全给 KV cache 也不够长上下文，所以 --gpu-memory-utilization 设 0.9，--max-model-len 控制在 4096 或 8192，并发压到个位数。场景二：单卡 80GB（如 A100 或 H100），跑 Qwen2.5-14B FP16。权重约 29GB，剩余空间充足，可以给 KV cache 分配 40GB 以上，此时 --gpu-memory-utilization 可以设 0.85，--max-model-len 开到 16384 甚至 32768，并发能支撑几十路。

经验值是 --gpu-memory-utilization 不要超过 0.9。留 10% 余量是给驱动和 CUDA context 的，设到 0.95 或 1.0 之后，服务偶发报错会变得很随机，属于典型的“查不出原因的玄学问题”。

4.2 max-model-len：按业务最坏情况算，别按平均值算

max-model-len 决定的是 KV cache 能支撑的最大单请求上下文长度。很多人把它理解为“输入长度限制”，其实是错的。它约束的是单次请求中，prompt tokens 加上生成的 max_tokens 的总和。假设业务里用户可能一次性传入一篇 4000 token 的文档并期望生成 1000 token 回答，那 max-model-len 至少要设 6000 以上，而不是按平均输入长度来设。

设置太短的直接后果是长文档请求直接报 length 错误；设置太长又会把 KV cache 占满，并发一高就开始排队甚至 OOM。调整时观察启动日志里打印的那行信息：当前配置下最大并发数是多少。这个数字就是当前显存配置下，最坏情况能并行承载的请求数。如果这个数字远低于业务预期，优先调小 --gpu-memory-utilization 看看是否冲突，或者换 AWQ 量化版本给权重“减重”。

4.3 量化怎么选：AWQ vs GPTQ vs FP16

我的建议是：如果是 7B 模型且 24G 显存，直接 FP16，效果最好且排错最简单。如果要在 24G 卡上跑 14B 或 32B，选 AWQ 预量化版本，启动时加 --quantization awq。Qwen 官方在 ModelScope 上提供了多个量化版本，文件名里一般带 awq 或 gptq 字样，下载对应目录即可。

4.4 tensor-parallel-size 与并发配置

多卡场景下，tensor-parallel-size 控制模型切分到几张卡上。规则很简单：用 N 张卡，就设 N；前提是这几张卡必须通过 NVLink 或 PCIe 连接，否则通信开销会把收益吃掉。显存 24G 跑 14B 权重的 FP16 不够时，可以 2 卡并行：

python -m vllm.entrypoints.openai.api_server \ --model /data/models/qwen2.5-14b-instruct \ --tensor-parallel-size 2 \ --gpu-memory-utilization 0.85 \ --max-model-len 8192

还有两个容易被忽略的参数。--max-num-seqs 控制单批次最大序列数，默认 256，在长上下文场景下调到 32 或 64 能降低延迟波动；--enforce-eager 关闭 CUDA graph 模式，虽然首 token 延迟会略高，但显存占用更可预测，调试阶段建议开启，上线后关掉。

5. 部署避坑：CUDA 不匹配、显存翻车和模型加载失败的 5 条排查记录

5.1 现象：pip 装好 vLLM，启动即报缺少 CUDA 相关符号

这个问题几乎是“二进宫”级别的常见。现象是启动命令执行后几秒，日志直接报 Error loading shared library libcudart.so 或找不到 libcupti.so。原因很简单：pip 安装的 vLLM 是预编译包，它要求的 CUDA runtime 和当前系统环境不一致。比如装的是基于 CUDA 12.4 编译的 vLLM，但机器里只有 CUDA 11.8 的库。解决方法是不要碰系统级的 CUDA 软链接，而是在 conda 环境内重装匹配版本的 PyTorch 和 vLLM：

# 在 vllm-qwen 环境内卸载后重装 pip uninstall vllm -y pip install vllm --index-url https://download.pytorch.org/whl/cu124

更稳妥的做法是启动前先打印当前环境下 CUDA 可见版本：python -c "import torch; print(torch.version.cuda)"，如果输出和 vLLM 要求不一致，就按上面的方法重装。不要尝试手动拷贝 CUDA 库文件，那样往往导致更多版本冲突。

5.2 现象：启动时提示 CUDA out of memory，但 nvidia-smi 显示显存占用不到一半

这个现象极具迷惑性。显存占用不高却报 OOM，原因是 vLLM 在初始化阶段会尝试为整个模型权重和 KV cache 一次性分配显存。如果你设置了 --gpu-memory-utilization 0.9，但模型权重加上 KV cache 的预估总量已经超过 90% 显存，vLLM 的预分配就会失败。此时 nvidia-smi 看起来占用低，是因为分配失败后直接退出，显存被释放了。

解决分三步：第一步把 --max-model-len 调小一半，减少 KV cache 预估；第二步把 --gpu-memory-utilization 从 0.9 降到 0.8；第三步如果还不行，检查是否有其他进程占用显存：

nvidia-smi # 查找占用显存的进程 fuser -v /dev/nvidia*

看到有残留的训练脚本或另一个推理服务，先结束掉。这类“假空显存”是最容易让人走弯路的情况。

5.3 现象：请求长文本时返回 context length exceeded

这是 max-model-len 设短的典型症状。现象是短文本一切正常，一传长文档立刻报错。原因不是模型不承认长输入，而是 KV cache 的预分配上限在那里，vLLM 在 tokenize 阶段就会拒绝超长请求。解决方式是动态调整。这里有个经验值：如果业务里 95% 的请求在 4000 token 以内，但偶尔有 8000 token 的文档，不必把 max-model-len 拉到 16384（这会显著降低并发上限），而是可以在应用层先做截断或分块，把过长内容交给 RAG 流程处理，而不是硬塞给模型。在 API 网关层做一个 max length 校验，比在模型层硬扛更经济。

5.4 现象：下载完模型后启动，报 tokenizer 相关文件缺失

前面提到过，ModelScope 下载有时会漏文件。报错信息一般是 tokenizer_config.json not found 或 chat_template.json missing。原因是下载过程中断或部分子文件没有下载完整。解决方式是回到 ModelScope 页面核对文件清单，然后重新拉取。注意不要在已有目录里重复执行导致文件混杂，建议下载时单独建目录，完成后核对文件再决定是否替换原目录。检查文件总数可以看一下目录里 safetensors 分片的索引文件 model.safetensors.index.json，它列出的分片文件名都应该实际存在。

5.5 现象：服务能启动，但并发一高响应越来越慢，甚至全部超时

这个现象意味着不是 vLLM 挂了，而是并发参数和硬件不匹配。常见原因有两个：一是 --max-num-seqs 太大，单个 batch 里挤入了太多不同长度的请求，导致最长序列拖慢整批；二是连续批处理调度把长请求和短请求混在一个批次，短请求的等待时间被拉长。解决方式是把 --max-num-seqs 降到 16 或 32，同时把 --max-model-len 收敛到业务实际需要的长度。如果还是慢，就要考虑提升 --gpu-memory-utilization 让 KV cache 有更多空间，或者减少同时接入的客户端并发。做压测时固定住请求长度分布，否则测出来的数据不具备参考意义。

提示：多卡场景下如果 tensor-parallel-size 大于实际显卡数量，vLLM 会在启动时直接报错，不会等到请求才暴露。日志里如果出现 NCCL 相关报错，优先检查卡间通信和驱动版本。

6. 进阶验证与接入上层平台：压测吞吐和对接 FastGPT 的最后一公里

6.1 用一段 Python 脚本做并发压测，拿到第一手 QPS

服务上线前，至少做一轮简单的并发压测，别等到业务方反馈再补救。这段脚本用 ThreadPoolExecutor 模拟 10 个并发请求，统计成功率、平均延迟和 QPS：

import time from concurrent.futures import ThreadPoolExecutor from openai import OpenAI client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="sk-test") def chat_once(prompt): t0 = time.time() resp = client.chat.completions.create( model="qwen2.5-7b", messages=[{"role": "user", "content": prompt}], max_tokens=128, temperature=0.7, ) return time.time() - t0 prompts = ["介绍一下 CPU 和 GPU 的区别"] * 20 with ThreadPoolExecutor(max_workers=10) as pool: results = list(pool.map(chat_once, prompts)) avg = sum(results) / len(results) print(f"平均延迟: {avg:.2f}s, 吞吐: {len(results)/sum(results):.2f} QPS")

这个压测脚本建议留存，每次调参后重跑同一组数据，形成对比记录，别凭感觉判断优化是否有效。如果并发一高出现超时，回到上一章按排查顺序处理。

6.2 接入 FastGPT 这类平台：Base URL 和模型名对齐

模型服务和业务中间还差一层编排。FastGPT、Dify 这类平台都很成熟，它们支持自定义 OpenAI 兼容模型地址。配置时把 Base URL 填成 vLLM 的 http://内网IP:8000/v1，密钥填任意非空值，模型名填 vLLM 启动时的 served-model-name。如果公司同时管理多套模型，也可以加一层网关统一管理，这样无论上层换成 DeepSeek 还是别的模型，vLLM 作为底座只改模型路径，上层接口完全不动。

就这个实战包而言，项目源码的价值不在于代码本身，而在于把环境、下载、启动、调参、接入串成了一条可复现的路径。跑通之后我建议你自己再改三处：换业务 prompt、用 P95 请求长度重设 max-model-len、补上压测脚本。这样才能把模板变成你环境里稳定运行的服务。

最后说个教训：刚上手 vLLM 时总想一次配满所有参数，出错就得同时排查四五个变量。后来改成“最简配置跑通，逐项加参数，每次只改一个变量”的节奏，翻车率直线下降。希望帮到你。

本文还有配套的精品资源，点击获取