1. 环境说明

本文所有操作基于 Ubuntu 22.04 最小化安装（Minimal Install），主机 IP 固定为 192.168.1.10，工作负载运行在 NVIDIA GPU 上。我们将从零开始搭建 vLLM 推理服务，加载 qwen/Qwen2-7B（以 Qwen3.7 参数规模为例说明），并通过 Cherry Studio 客户端进行调用，同时针对 GPU 显存、吞吐量和延迟进行性能调优。

2. 基础环境准备

2.1 系统更新与基础工具

sudo apt update && sudo apt upgrade -y
sudo apt install -y wget curl git build-essential

2.2 固定 IP 地址

编辑 Netplan 配置文件，确保 IP 为 192.168.1.10：

sudo nano /etc/netplan/00-installer-config.yaml

写入以下内容：

network:
  version: 2
  renderer: networkd
  ethernets:
    eth0:
      dhcp4: no
      addresses:
        - 192.168.1.10/24
      routes:
        - to: default
          via: 192.168.1.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 8.8.4.4

应用配置：

sudo netplan apply

2.3 安装 NVIDIA 驱动与 CUDA

首先确认 GPU 型号，然后安装驱动：

lspci | grep -i nvidia
sudo apt install -y nvidia-driver-535   # 根据实际 GPU 选择版本
sudo reboot

重启后安装 CUDA Toolkit 12.x（vLLM 推荐）：

wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt update
sudo apt install -y cuda-toolkit-12-3   # 可能需要根据实际最新版本调整

设置环境变量：

echo 'export PATH=/usr/local/cuda-12.3/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.3/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
nvcc --version

3. 安装 vLLM

推荐使用 Python 虚拟环境，避免污染系统包：

sudo apt install -y python3.10-venv python3-pip
python3 -m venv ~/vllm_env
source ~/vllm_env/bin/activate

安装 vLLM（按 GPU 架构可能需要编译，直接 pip 安装预编译包通常可行）：

pip install vllm

验证安装：

python -c "import vllm; print(vllm.__version__)"

4. 下载 Qwen3.7 模型

Qwen2-7B 或同等参数量模型可直接从 ModelScope 或 HuggingFace 下载，推荐使用 huggingface_hub 缓存：

pip install huggingface_hub
huggingface-cli download Qwen/Qwen2-7B-Instruct --local-dir /data/models/Qwen2-7B-Instruct

如果网络受限，可设置镜像：

export HF_ENDPOINT=https://hf-mirror.com

5. 启动 vLLM 推理服务

以 OpenAI 兼容 API 方式启动，监听 192.168.1.10:8000：

python -m vllm.entrypoints.openai.api_server \
  --model /data/models/Qwen2-7B-Instruct \
  --host 192.168.1.10 \
  --port 8000 \
  --max-model-len 4096 \
  --gpu-memory-utilization 0.95 \
  --tensor-parallel-size 1

下面详细讲解各参数的含义与实践调优建议：

  • --model：模型路径或 HuggingFace 仓库 ID。可以指定本地路径（如 /data/models/Qwen2-7B-Instruct）或直接使用 HuggingFace 上的模型名（如 Qwen/Qwen2-7B-Instruct）。使用 HuggingFace ID 时 vLLM 会自动从缓存或远程下载模型文件。

  • --host：服务绑定的 IP 地址。设为 0.0.0.0 表示监听所有网络接口，允许外部访问；设为具体 IP 则仅监听该地址。生产环境建议绑定内网 IP 或配合防火墙使用。

  • --port：服务监听的端口号，默认 8000。可根据实际需求修改，注意不要与其他服务冲突。

  • --max-model-len：模型支持的最大上下文长度（输入 + 输出 token 总数）。该值直接影响显存占用——每增加 1K 上下文，KV Cache 的显存开销会显著上升。Qwen2-7B 原生支持 32768 token，但单卡 24GB 显存下建议设为 4096~8192 以避免 OOM。注意：这个值不能超过模型配置文件中的 max_position_embeddings，否则 vLLM 会报错。

  • --gpu-memory-utilization：GPU 显存利用率，取值范围 0~1。vLLM 会根据该比例预分配 KV Cache 使用的显存池。设为 0.90 表示预留 10% 显存给 CUDA 上下文、PyTorch 临时变量等开销。单卡场景推荐 0.90~0.95；如果同时运行其他 GPU 进程（如监控、训练），应适当降低该值。

  • --tensor-parallel-size：张量并行数，用于将模型切分到多张 GPU 上。单卡环境必须设为 1；2 卡可设为 2，4 卡可设为 4，以此类推。注意张量并行要求 GPU 之间通过 NVLink 或高速 PCIe 互联，否则通信瓶颈会抵消并行收益。数据并行可用 --pipeline-parallel-size 配合实现更复杂的分布式策略。

  • --max-num-batched-tokens（未在上方命令中出现，但极关键）：控制每次迭代批处理的最大 token 总数。较大的值（如 8192）可提高吞吐量，但会增加单次迭代延迟。默认值通常为 max-model-len，建议根据并发量与延迟要求调整，范围通常在 2048~16384 之间。

  • --max-num-seqs：同时处理的最大序列（请求）数。超过该值的请求会排队等待。增大该值可提升并发处理能力，但会增加显存压力。单卡 7B 模型通常设为 32~256。

  • --quantization：量化方法，可选 awq、gptq、squeezellm、fp8 等。量化可大幅降低显存占用（如 AWQ 可使 7B 模型从 14GB 降至约 4GB），但会轻微影响生成质量。启用前需确保模型已经按对应量化方法转换，否则启动会失败。

  • --dtype：模型推理时的数据类型，可选 auto、float16、bfloat16、float32。默认 auto 会自动选择模型配置文件中的最佳类型，一般无需手动修改。

5.1 配置 systemd 服务（开机自启）

为使 vLLM 在系统重启后自动运行，建议将其注册为 systemd 服务。创建服务单元文件：

sudo nano /etc/systemd/system/vllm.service

写入以下内容（注意替换模型路径、IP 和参数为你的实际值）：

[Unit]
Description=vLLM Inference Service (Qwen2-7B)
After=network.target remote-fs.target
[Service]
Type=simple
User=root
WorkingDirectory=/root
Environment="PATH=/usr/local/cuda-12.3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
ExecStartPre=/bin/bash -c 'source /root/vllm_env/bin/activate'
ExecStart=/root/vllm_env/bin/python -m vllm.entrypoints.openai.api_server 
--model /data/models/Qwen2-7B-Instruct
--host 0.0.0.0
--port 8000
--max-model-len 4096
--gpu-memory-utilization 0.92
--tensor-parallel-size 1
--max-num-batched-tokens 4096
--max-num-seqs 64
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target

关键字段说明：

  • After=network.target：确保网络就绪后再启动服务，避免模型下载或 API 监听失败。
  • User：运行服务的用户。建议使用非 root 用户（如 vllm）以提高安全性，但需确保该用户有 GPU 访问权限（加入 video 和 render 组）。
  • ExecStartPre：在主进程启动前执行的命令，这里用于激活 Python 虚拟环境（实际因 systemd 隔离性，改用 ExecStart 直接调用虚拟环境中的 Python 解释器）。
  • Restart=always：进程意外退出时自动重启，保证服务高可用。
  • RestartSec=10：重启间隔 10 秒，避免频繁崩溃时占用资源。

保存后执行以下命令启用并启动服务：

sudo systemctl daemon-reload          # 重新加载 systemd 配置
sudo systemctl enable vllm.service    # 设置开机自启
sudo systemctl start vllm.service     # 立即启动服务
sudo systemctl status vllm.service    # 查看运行状态

查看实时日志：

sudo journalctl -u vllm.service -f   # -f 表示持续跟踪最新日志

服务启动后可通过 curl 测试：

curl http://192.168.1.10:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "/data/models/Qwen2-7B-Instruct",
    "prompt": "你好",
    "max_tokens": 50
  }'

6. 配置 Cherry Studio 调用

Cherry Studio 支持 OpenAI 兼容的 API 端点。打开 Cherry Studio，进入「设置」-「API 提供商」，添加自定义提供方：

  • API 基础 URL：http://192.168.1.10:8000/v1
  • API 密钥：可留空或填写任意字符串（vLLM 默认不验证）
  • 模型：填入本地模型路径（如 /data/models/Qwen2-7B-Instruct）

保存后即可在对话界面选择该模型进行交互。如果 Cherry Studio 与服务器不在同一网段，请确保防火墙开放 8000 端口：

sudo ufw allow 8000/tcp

7. 性能调优实践

7.1 显存与批次控制

vLLM 的核心优势在于 PagedAttention 和连续批处理。调优关键参数：

--gpu-memory-utilization 0.92    # 留少量显存给系统开销
--max-num-batched-tokens 4096    # 限制每批次 token 数，平衡吞吐与延迟
--max-num-seqs 256               # 最大并发请求数

7.2 KV Cache 与量化

若显存紧张，可启用 FP8 量化或 AWQ 量化版本（需预先转换模型）。例如使用 FP8：

--quantization fp8

7.3 推测解码与投机采样

对于较小模型可尝试推测解码，但 Qwen2-7B 规模下通常不开启。关注 vLLM 版本更新引入的优化即可。

7.4 操作系统层面调优

  • 关闭 GPU 的持久模式以减少延迟波动：sudo nvidia-smi -pm 1
  • 调整系统 swappiness 为 10：sudo sysctl vm.swappiness=10
  • 固定 CPU 频率为性能模式：sudo cpupower frequency-set -g performance

7.5 监控与压测

使用 vLLM 自带的 benchmark 工具进行吞吐测试：

python -m vllm.entrypoints.openai.run_batch \
  --model /data/models/Qwen2-7B-Instruct \
  --request-rate 10 \
  --num-prompts 500

通过 nvidia-smi 和 vLLM 的 Prometheus 指标接口监控 GPU 利用率与 token 生成速率。

8. 常见问题与排查

在部署 vLLM 和通过 Cherry Studio 调用的过程中，可能会遇到一些典型问题。下面列出最常见的四种错误，并提供排查步骤和解决方案。

8.1 CUDA 版本不兼容

错误现象：启动 vLLM 时报错 CUDA driver version is insufficient、cublas error 或 CUDA_HOME not set。

排查步骤：

  • 检查驱动版本：nvidia-smi 顶部显示的 CUDA Version 为驱动支持的最高 CUDA 版本。
  • 检查 CUDA Toolkit 版本：nvcc --version 或 cat /usr/local/cuda/version.txt。
  • 检查 PyTorch 编译的 CUDA 版本：python -c "import torch; print(torch.version.cuda)"。

解决方案：

  • 确保驱动版本 >= CUDA Toolkit 版本。如果驱动低于所需版本，请升级 NVIDIA 驱动（如 sudo apt install -y nvidia-driver-535）。
  • vLLM 推荐使用 CUDA 12.x，如果使用 apt 安装了 cuda-toolkit-12-3，请确认 /usr/local/cuda 软链接指向正确版本。
  • 如果 pip 安装的预编译包与系统 CUDA 版本不匹配，尝试从源码安装：pip install vllm --no-binary vllm。

8.2 模型加载失败

错误现象：启动服务时报错 OSError: Can't load model ... No such file or directory 或 huggingface_hub.utils._errors.LocalEntryNotFoundError。

排查步骤：

  • 检查模型路径是否存在：ls -l /data/models/Qwen2-7B-Instruct，确认目录下有 config.json 和权重文件。
  • 如果使用 HuggingFace ID 下载，检查网络和镜像设置：echo $HF_ENDPOINT。
  • 确认有读取权限：sudo chown -R $USER:$USER /data/models/Qwen2-7B-Instruct。

解决方案：

  • 重新下载模型：huggingface-cli download Qwen/Qwen2-7B-Instruct --local-dir /data/models/Qwen2-7B-Instruct，建议配合镜像。
  • 如果需要认证的模型（如 Llama），先登录 HuggingFace：huggingface-cli login 输入 token。
  • 检查 systemd 服务文件中 ExecStart 的模型路径是否与本地路径一致。

8.3 端口占用

错误现象：启动 vLLM 时报错 Address already in use 或 OSError: [Errno 98] Address already in use。

排查步骤：

  • 查看端口 8000 占用情况：sudo lsof -i :8000 或 ss -tlnp | grep 8000。
  • 如果使用 systemd 启动，检查是否有旧进程残留：sudo systemctl status vllm.service。

解决方案：

  • 终止占用进程：sudo kill -9 <PID>，或停止旧的 vLLM 实例。
  • 修改 vLLM 监听端口：增加 --port 8080 或其他空闲端口。
  • 确保防火墙未阻止端口（已在第 6 节中提及），必要时临时关闭防火墙测试：sudo ufw disable（测试完记得开启）。

8.4 显存不足（OOM）

错误现象：vLLM 启动过程中或处理请求时报错 CUDA out of memory 或 torch.cuda.OutOfMemoryError。

排查步骤：

  • 查看当前显存使用：nvidia-smi，确认是否有其他进程占用显存。
  • 检查 vLLM 启动参数：--gpu-memory-utilization 值是否过高（例如设为 0.95 可能仍 OOM）。
  • 检查 --max-model-len 是否设置得过大，例如 8192 在 24G 显存下可能导致 OOM。
  • 查看 vLLM 启动日志中是否有显存分配警告。

解决方案：

  • 降低 --gpu-memory-utilization 至 0.85 或更低，为系统留足空间。
  • 减少 --max-model-len 至 4096 或 2048。
  • 降低 --max-num-batched-tokens 和 --max-num-seqs。
  • 启用量化（如 FP8 或 AWQ）以大幅降低显存占用，注意模型需要提前量化。
  • 如果单卡显存实在不足，考虑使用多卡张量并行（--tensor-parallel-size 2）或升级硬件。

9. 总结

本文完成了 Ubuntu 22.04 最小化环境下的 vLLM 部署全流程：从基础环境、NVIDIA 驱动、CUDA 安装，到 vLLM 服务启动与 Qwen3.7 模型加载，最终通过 Cherry Studio 调用并实现性能调优。关键调优点在于显存利用率、批处理参数和操作系统层面的配合，帮助在单卡环境下获得最佳推理性能。后续可根据业务负载进一步调整模型量化策略或扩展为多卡推理。

10. 关键生成参数详解

在使用 vLLM 的 OpenAI 兼容 API 或通过 Cherry Studio 调用时，除了服务端启动参数，客户端请求中的生成参数同样对输出质量、多样性和性能有重要影响。以下是几个核心参数的详细解释：

10.1 System Prompt（系统提示词）

作用：System Prompt 用于设定 AI 助手的角色、行为规范和对话上下文。它会在用户输入之前被注入到对话历史中，引导模型以特定身份或风格进行回复。

使用方式：在 OpenAI 格式的请求中，通过 messages 数组的第一个元素设置，其 role 为 "system"。

{
  "model": "/data/models/Qwen2-7B-Instruct",
  "messages": [
    {
      "role": "system",
      "content": "你是一个专业的 Linux 系统运维专家，回答应简洁、准确，优先提供可执行的命令。"
    },
    {
      "role": "user",
      "content": "如何查看当前系统的 GPU 使用情况？"
    }
  ],
  "max_tokens": 100
}

最佳实践：

  • 保持简洁：过长的 System Prompt 会占用宝贵的上下文窗口。
  • 明确指令：清晰定义助手的角色、知识范围和回答风格。
  • 对于 Qwen2-7B-Instruct 这类经过指令微调的模型，System Prompt 效果显著，能有效约束模型输出。

10.2 Temperature（温度）

作用：控制生成文本的随机性（创造性）。值越高，输出越多样、不可预测；值越低，输出越确定、保守。

  • 范围：通常为 0.0 到 2.0，vLLM 默认值一般为 1.0。
  • 低温度（如 0.1-0.3）：适用于需要事实准确、代码生成、翻译等任务，输出稳定、重复性高。
  • 中等温度（如 0.7-1.0）：平衡创意与一致性，适用于一般对话、内容创作。
  • 高温度（如 1.2-1.5）：适用于创意写作、头脑风暴，输出更具探索性，但也可能包含无关或不合逻辑的内容。

建议：对于技术文档生成或代码辅助，建议设置为 0.2-0.5；对于开放域聊天，可设置为 0.7-1.0。

10.3 Top-P（核采样）

作用：另一种控制随机性的方法，也称为“核采样”。它从累积概率超过阈值 P 的最小候选词集合中随机采样。

  • 范围：0.0 到 1.0。默认值常为 0.7 或 1.0。
  • 低 Top-P（如 0.5）：仅从概率最高的少量词汇中采样，输出更加集中和可预测。
  • 高 Top-P（如 0.9-1.0）：从更广泛的词汇中采样，增加多样性。

与 Temperature 的关系：通常两者配合使用。Temperature 调整整个概率分布的平滑程度，Top-P 动态限制采样池的大小。设置 top_p=0.9 并搭配适当的 temperature 是常见的平衡策略。

10.4 Frequency Penalty（频率惩罚）

作用：降低模型重复使用已出现词汇的概率，惩罚重复用词，使生成内容用词更丰富。

  • 范围：通常为 -2.0 到 2.0。正值表示惩罚，负值表示鼓励重复。默认值为 0.0（无惩罚）。
  • 正值（如 0.5-1.5）：有效减少重复短语和词汇，使长文本更流畅自然。
  • 过高值（如 >2.0）：可能导致用词过于生僻或语句不通顺。

建议：在生成长篇内容（如文章、故事）或需要避免循环重复时，可设置为 0.5 到 1.0。

10.5 Max Tokens（最大生成长度）

作用：限制模型单次响应生成的最大 token 数量。注意，此限制是针对本次生成的输出部分，不包括输入的 prompt tokens。

  • 影响：直接影响响应长度和生成时间。设置过小可能导致回答被截断；设置过大会浪费资源，并可能因超出模型上下文窗口而失败。
  • 与 max-model-len 的关系：服务端启动参数 --max-model-len 定义了模型能处理的输入+输出的总 token 上限。客户端的 max_tokens 必须满足：len(prompt_tokens) + max_tokens <= max-model-len。

建议：根据实际需求设置。对于简短问答，50-200 足够；对于长文生成，可设为 500-1000。同时需确保服务端的 --max-model-len 设置足够大。

10.6 参数组合建议

以下是一些常见场景的参数组合参考：

  • 技术问答/代码生成： temperature=0.2, top_p=0.9, frequency_penalty=0.1, max_tokens=500
  • 创意写作/故事生成： temperature=0.8, top_p=0.95, frequency_penalty=0.5, max_tokens=1000
  • 日常对话： temperature=0.7, top_p=0.9, frequency_penalty=0.0, max_tokens=300
  • 摘要/翻译（确定性高）： temperature=0.1, top_p=0.5, frequency_penalty=0.0, max_tokens=400

在实际使用 Cherry Studio 时，可以在对话设置或每次请求的“高级参数”中调整这些值，观察输出变化以找到最适合当前任务的配置。

# ubuntu # linux # 运维 # AI
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

3分钟掌握Codex技能安装：一键部署你的AI助手工具库

想要为你的Codex AI助手安装新技能？不用再手动复制文件了！skill-installer为你提供了一套完整的解决方案，让你能够从GitHub仓库快速获取和安装各种实用的Codex技能。无论你是AI开发新手还是经验丰富的开发者，这个工具都能让你在几分钟内扩展Codex的功能边界。## 为什么选择skill-installer？ 🤔在AI辅助编程的时代，Codex技能已经成为提升开发效

avatar AI编程社区

DB-GPT分布式AI数据引擎：企业级智能分析平台架构解析

DB-GPT作为新一代AI数据助手，通过分布式架构和智能代理引擎重构了传统数据分析范式。该平台将大型语言模型的自然语言理解能力与企业级数据处理需求深度融合，构建了面向生产环境的可扩展AI数据平台。其核心价值在于将复杂的SQL生成、数据分析和可视化任务转化为简单的自然语言交互，同时确保系统安全性、可追溯性和企业级可靠性。## 技术定位与生态分析在当前数据智能生态中，DB-GPT填补了传统BI

avatar AI编程社区

如何用Awesome Claude Skills将AI助手打造成你的全能创作伙伴和职业顾问

你是否曾想过，如果有一个AI伙伴能帮你完成从专业文章撰写到完美简历定制的所有工作，工作效率会提升多少倍？Awesome Claude Skills正是这样一个神奇的AI技能宝库，它汇集了1000+个精心筛选的Claude技能，覆盖内容创作、职业发展、文档处理等各个方面，让你在AI的帮助下轻松应对各种工作挑战。## 痛点分析：传统工作流程的三大瓶颈在内容创作和职业发展中，我们常常面临这样的困

avatar AI编程社区