外观
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
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+rocm723Docker方式安装(可选)
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.6BvLLM使用
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-size | KV Cache 的块大小。默认 16。不要轻易改 |
Pooling/Reranker 专用参数(非常关键)
| 参数 | 作用 / 示例 |
|---|---|
--runner pooling | Embedding 模型专用,触发 CLS Pooling。你当前必填 |
--task score | Reranker 模型专用,即 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