Skip to content

vLLM安装与使用 ​

vLLM安装 ​

介绍 ​

vLLM 是一个专注于大语言模型推理与服务的高性能库,它的核心价值在于解决“模型能跑”之后“怎么跑得快、跑得省”的问题。

  • ROCm 最底层的“地基”:ROCm 是 AMD 的 GPU 计算平台,作用等同于 NVIDIA 的 CUDA。
  • PyTorch 中间的“通用计算引擎”:PyTorch 是深度学习框架,提供了张量计算和自动求导等基础能力。vLLM 本身不直接与 GPU 驱动对话,它依赖 PyTorch 作为计算后端。
  • vLLM 最上层的“推理服务框架”:vLLM 构建在 PyTorch 之上,利用 PyTorch 提供的算子来实现自己的核心优化逻辑(如 PagedAttention 的显存管理、连续批处理调度)。

Python方式安装 ​

vLLM安装:查看预构建 Wheel版本:https://wheels.vllm.ai/rocm/vllm

  • 根据预构建版本信息,安装ROCm版本
  • 例如:vllm-0.32.0+rocm723-cp312-cp312-manylinux_2_39_x86_64.whl
    • 安装ROCm 7.2.3 版本
    • 创建 Python 3.12环境

vLLM inference and serving on ROCm

Pytorch ROCm 7.2.3 安装包

bash
# 创建 Python 3.12 环境
mkdir /opt/my-vllm
cd /opt/my-vllm
uv python pin 3.12.13
uv init
uv venv

# 安装 vLLM (预计需要半小时)
source .venv/bin/activate
uv pip install vllm --extra-index-url https://wheels.vllm.ai/rocm/ --upgrade
uv pip install orjson
  
# 安装验证
python -c "import vllm; print(vllm.__version__)"
uv pip list # 显示:
# vllm                                     0.32.0+rocm723

Docker方式安装(可选) ​

下载镜像

bash
# 约11GB
docker pull vllm/vllm-openai-rocm:latest
# 或 docker pull vllm/vllm-openai-rocm:nightly

运行

bash
docker run --rm \
    --group-add=video \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --device /dev/kfd \
    --device /dev/dri \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai-rocm:<tag> \
    --model Qwen/Qwen3-0.6B

vLLM使用 ​

bge-m3模型 ​

使用 ModelScope 下载模型。BAAI/bge-m3 模型说明

  • 权重文件:pytorch_model.bin(这是核心的 PyTorch 模型权重)。

  • 模型结构配置:config.json 和 configuration.json(定义了模型的架构和参数)。

  • 分词器文件:tokenizer.json、tokenizer_config.json、sentencepiece.bpe.model 和 special_tokens_map.json(用于将文本转换为模型能理解的 token)。

  • 池化配置:1_Pooling/config.json(非常重要,它告诉模型如何正确地将 token 向量聚合成最终的句子向量,bge-m3 依赖这里的 CLS pooling)。

  • 句子变换器配置:config_sentence_transformers.json 和 sentence_bert_config.json(这些是 sentence-transformers 库的配置文件,vLLM 在加载时会参考它们)。

  • 以下文件是可选:

    • 稀疏/多向量权重:sparse_linear.pt 和 colbert_linear.pt。如果你需要 bge-m3 的稀疏检索(lexical matching)或 ColBERT 多向量功能,则需要它们;如果只做稠密向量检索,则不需要。

    • 说明文档:README.md 等,可以下载备用。

bash
# 安装modelscope
uv pip install modelscope

# 下载模型
mkdir bge-m3
uv run modelscope download --model BAAI/bge-m3 \
  1_Pooling/config.json \
  config.json \
  config_sentence_transformers.json \
  configuration.json \
  pytorch_model.bin \
  sentence_bert_config.json \
  sentencepiece.bpe.model \
  special_tokens_map.json \
  tokenizer.json \
  tokenizer_config.json \
  --local_dir ./bge-m3

启动

  • vllm serve:启动 vLLM 的 OpenAI 兼容 API 服务器。只要启动了它,你就可以通过 HTTP 请求(如 /v1/embeddings)来调用模型。
  • /opt/my-vllm/bge-m3:指定模型的位置。这里你填的是本地绝对路径。vLLM 会自动读取该目录下的 config.json、pytorch_model.bin 等文件
  • --runner pooling:告诉 vLLM 切换到 pooling 模式。这会触发 vLLM 去读取模型目录下的 1_Pooling/config.json
  • --served-model-name bge-m3:给模型起个“别名”。在发送 API 请求时,请求体里的 "model": "bge-m3"
  • --dtype float16:指定模型权重的计算精度为 FP16(半精度浮点数)。这是 GPU 推理的默认且推荐的设置。它在几乎不损失精度的前提下,比 FP32(单精度)节省一半显存,并提升计算速度。
  • --gpu-memory-utilization 0.4:显存利用率上限。0.4 表示 vLLM 最多使用显卡 40% 的显存
bash
cd /opt/my-vllm
source .venv/bin/activate

# 启动
vllm serve /opt/my-vllm/bge-m3 \
  --runner pooling \
  --served-model-name bge-m3 \
  --dtype float16 \
  --port 8500 \
  --gpu-memory-utilization 0.4 \
  --max-model-len 8192 \
  --max-num-seqs 256

测试

bash
curl http://localhost:8500/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-m3",
    "input": "Hello world"
  }'

bge-reranker模型 ​

BGE-M3 对应的重排模型是 BAAI/bge-reranker-v2-m3。下载地址

  • --max-model-len:模型最大上下文长度
bash
# 下载模型
cd /opt/my-vllm
source .venv/bin/activate
mkdir bge-reranker-v2-m3
modelscope download --model BAAI/bge-reranker-v2-m3 --local_dir ./bge-reranker-v2-m3


# 启动服务
vllm serve /opt/vllm2/bge-reranker-v2-m3 \
  --runner pooling \
  --served-model-name bge-reranker-v2-m3 \
  --dtype float16 \
  --port 8700 \
  --gpu-memory-utilization 0.4 \
  --max-model-len 4096
  --max-num-seqs 256

测试

bash
curl http://localhost:8700/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "什么是量子纠缠?",
    "documents": [
      "量子纠缠是一种量子力学现象,两个粒子状态相互关联。",
      "苹果富含维生素C和膳食纤维。",
      "今天天气晴朗,适合户外运动。"
    ],
    "top_n": 3
  }'

vLLM参数 ​

核心/基础配置(必知)

参数作用 / 示例
--model模型路径或 HF ID。vllm serve <model> 其实等同于 vllm serve --model <model>
--served-model-name定义 API 调用的模型别名,例如 --served-model-name bge-m3
--dtype数据类型。常用 auto(自动匹配)、float16、bfloat16
--trust-remote-code允许加载自定义代码。某些模型(带自定义架构)必须加此参数才能启动
--max-model-len限制输入的最大 token 长度。例如 --max-model-len 8192。强烈建议设置它来防止超长文本撑爆显存(bge-m3 上限是 8192)

显存与并发调优(性能关键)

参数作用 / 示例
--gpu-memory-utilization显存占用比例。默认 0.9。双服务共卡时,务必设置为 0.4 / 0.45 等
--max-num-seqs最大并发序列数(Batch Size 的基础)。调大能提升吞吐量,但会增加显存占用。默认通常为 256
--enforce-eager强制禁用 CUDA/HIP Graph 优化。如果你遇到 ROCm 相关的内核报错或启动卡死,加上这个参数可以降级运行(牺牲部分吞吐换稳定)
--block-sizeKV Cache 的块大小。默认 16。不要轻易改

Pooling/Reranker 专用参数(非常关键)

参数作用 / 示例
--runner poolingEmbedding 模型专用,触发 CLS Pooling。你当前必填
--task scoreReranker 模型专用,即 Cross-Encoder 打分模式。启动 bge-reranker 时使用
--task embed部分版本下用于生成 embedding(与 runner pooling 等价)
--hf-overrides如果 vLLM 无法识别模型,可强制覆盖配置,例如 --hf-overrides '{"architectures": ["BgeM3EmbeddingModel"]}'

服务与网络配置

参数作用 / 示例
--host监听地址。默认 0.0.0.0(所有网卡)。如果你只想本机访问,可设为 127.0.0.1
--port监听端口。默认 8000
--api-key设置 API 密钥。例如 --api-key mysecret,客户端请求头需带 Authorization: Bearer mysecret
--uvicorn-log-level日志级别。常用 info、debug、warning

vLLM排错 ​

错误描述:vLLM空负载时,CPU 占用 100%

解决方案:未解决

bash
# 查找原因
uv pip install py-spy -i https://pypi.tuna.tsinghua.edu.cn/simple
py-spy top --pid 7378

strace -p 9818 -c -f

# 限制硬件队列数量
export HSA_ENABLE_YIELDING_POLL=1
export GPU_MAX_HW_QUEUES=1
export VLLM_SLEEP_WHEN_IDLE=1  # 可以保留,以确保Python层也正确休眠
# 然后启动 vLLM 服务

运维 ​

systemd服务 ​

系统级 systemd 服务,简单说就是由系统初始化进程(PID 1)直接管理的后台服务。它不依赖任何用户登录,随操作系统启动而启动,适合托管服务器上需要长期运行的核心应用。

与“用户级服务”的根本区别在于作用范围和生命周期。系统级服务属于整个操作系统,无论有没有人登录,它都在后台运行。

典型应用场景

  • 服务器常驻服务:Web 服务、数据库、API 后端、推理引擎等
  • 需要特定启动顺序的任务:服务之间常有依赖关系(例如先有网络,再有应用)。systemd 能通过 After、Wants 等字段精确控制启动顺序和依赖,避免因启动过早而失败。
  • 需要崩溃自愈的进程:通过 Restart=on-failure 配置,进程异常退出时 systemd 会自动拉起。

systemd使用方法 ​

编写单元文件:在 /etc/systemd/system/ 目录下创建以 .service 结尾的文件。

  • [Unit]:描述服务,定义启动顺序(After)和依赖(Wants)。
  • [Service]:定义如何运行。关键指令包括 ExecStart(必须绝对路径)、User(指定非 root 的运行用户)、Restart(重启策略)。
  • [Install]:定义如何开机自启。通常写 WantedBy=multi-user.target,表示在多用户模式下启动。

重载配置:每次新建或修改单元文件后,必须执行:

bash
# 告诉 systemd 重新读取磁盘上的配置文件
sudo systemctl daemon-reload

启用并启动

  • 设置开机自启:sudo systemctl enable 服务名
  • 立即启动并设置自启:sudo systemctl enable --now 服务名。--now 省去了单独执行 start 的步骤。

日常管理

  • 查状态:systemctl status 服务名
  • 看日志:journalctl -u 服务名 -f(实时跟踪),日志由 journald 统一收集,无需再去翻找零散的文件。
  • 停止/禁用:sudo systemctl stop 服务名 / sudo systemctl disable 服务名

创建vllm服务 ​

创建文件:/etc/systemd/system/vllm-bge-m3.service

bash
# 详见 devops\docker\vllm\vllm-bge-m3.service

启用并启动服务

bash
# 重新加载 systemd 配置
sudo systemctl daemon-reload

# 设置开机自启
sudo systemctl enable vllm-bge-m3.service

# 立即启动服务
sudo systemctl start vllm-bge-m3.service

# 查看服务状态
systemctl status vllm-bge-m3.service

# 实时跟踪日志输出
journalctl -u vllm-bge-m3.service -f