一、前言
近期业务需要搭建私有化大模型推理服务,选用Xinference作为统一模型调度平台,服务器硬件:8 张 NVIDIA L20 46GB显存GPU,驱动版本595.71.05,nvidia-smi最高支持CUDA12.5,本地nvcc编译工具是CUDA13.3。
环境前置说明:系统Ubuntu 22.04,Python 3.12,8卡L20多卡推理场景,部署参考官方文档:https://inference.readthedocs.io/zh-cn/latest/getting_started/installation.html
部署流程概览
以下是 Xinference 部署的核心步骤流程图,涵盖了从环境准备到模型加载的全过程,并标注了关键决策点:
关键决策点说明:
- CUDA 版本对齐:必须根据
nvidia-smi显示的驱动上限(CUDA 12.5)选择对应的 PyTorch cu124 版本,避免安装 cu130/cu133 导致libcudart.so.13缺失。 - 后端选择:根据实际需求选择推理后端:
- vLLM 后端:高性能,适合大模型(7B/13B/34B),但对驱动/CUDA 版本要求严格。
- transformers 后端:兼容性好,规避 CUDA/驱动版本问题,适合轻量 embedding/rerank 任务。
二、服务器硬件 & 环境信息
1. GPU驱动信息
nvidia-smi
# Driver Version: 595.71.05
# CUDA Version(驱动上限): 13.2 → 实际驱动仅支持CUDA12.5 Runtime
# GPU:8 × NVIDIA L20 46GB
2. 本地CUDA编译工具
nvcc -V
# CUDA compilation tools, release 13.3, V13.3.33
核心大坑:nvcc编译工具CUDA 13.3 ≠ 驱动支持的CUDA Runtime上限12.5,一旦安装CUDA 13系列PyTorch/vLLM,直接报
libcudart.so.13找不到。
三、标准部署流程
3.1 前置系统依赖安装
# Ubuntu / Debian
sudo apt update
sudo apt install -y python3 python3-pip python3-venv git build-essential libopenmpi-dev
3.2 创建独立隔离虚拟环境
绝对不要使用系统全局Python! 全局环境会残留各种版本的 torch、CUDA 包,必然出现依赖打架。
# 创建工作目录
mkdir -p /opt/xinference && cd /opt/xinference
# 新建专属虚拟环境
python3 -m venv venv-xinference
# 激活环境(后续所有安装、启动命令必须先执行这行)
source venv-xinference/bin/activate
# 升级基础pip,清理缓存
pip install --upgrade pip setuptools wheel -i https://pypi.tuna.tsinghua.edu.cn/simple
pip cache purge
激活成功后终端前缀显示 (venv-xinference)。
3.3 国内清华源加速安装全套依赖(解决 pip 下载慢)
步骤 1:安装固定兼容版本 PyTorch(cu124,适配驱动 CUDA 12.5 上限)
拒绝 cu130/cu133 版本 torch,否则 libcudart.so.13 报错:
pip3 install torch==2.4.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 -i https://pypi.tuna.tsinghua.edu.cn/simple
# 验证torch CUDA可用
python -c "import torch; print('torch版本:', torch.__version__); print('GPU可用:', torch.cuda.is_available())"
# 输出True即正常
步骤2:安装匹配torch 2.4.1的vLLM 0.6.3高性能推理后端
vLLM 官方预编译包国内下载慢,搭配 vLLM 官方镜像源加速:
pip install vllm==0.6.3 \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
--extra-index-url https://wheels.vllm.ai
# 验证vllm安装成功(该版本无__version__属性,改用version子模块)
python -c "import vllm.version; print('vLLM 版本:',vllm.version.__version__)"
# 校验CUDA底层扩展无报错
python -c "from vllm import _C; print('vLLM CUDA 扩展加载正常')"
步骤 3:统一降级 numpy<2.0,解决 outlines 依赖冲突
之前安装 numpy 2.x 会触发 outlines 0.0.46 requires numpy<2.0.0 报错:
pip install "numpy<2.0" -i https://pypi.tuna.tsinghua.edu.cn/simple
步骤4:完整安装 Xinference 全套组件
pip install "xinference[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple
# 全局依赖冲突自检,无报错即环境完美
pip check
3.4 后台常驻启动 Xinference 服务
坑点提醒:禁止加sudo启动!
sudo 会重置环境变量 PATH,脱离虚拟环境,系统全局找不到 xinference-local 命令,直接提示 没有那个文件或目录。
后台启动命令(输出日志、允许内网所有机器访问)
# 杀掉残留进程
pkill -f xinference-local
rm -f xinference.log
# 后台常驻启动
nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &
# 验证服务进程
ps aux | grep xinference-local
# 验证 API 接口是否通
curl http://127.0.0.1:9997/v1/models
3.5 加载模型两种方案(区分vLLM/transformers后端)
方案 A:vLLM 后端(高性能,适合大模型 7B/13B/34B)
# 加载rerank模型bge-reranker-v2-m3
xinference run bge-reranker-v2-m3 --backend vllm
方案B:transformers后端(规避CUDA/驱动版本报错,轻量embedding/rerank首选)
当 vLLM 持续报驱动、CUDA 版本错误时,直接切换该后端,无任何 CUDA 底层依赖冲突:
xinference run bge-reranker-v2-m3 --backend transformers
验证模型加载成功
执行模型加载命令后,需要验证模型是否成功加载并可通过 API 调用。以下是验证步骤:
1. 检查模型加载日志
模型加载过程中,终端会输出加载进度。成功加载的标志是看到类似以下输出:
# 使用 vLLM 后端加载
xinference run bge-reranker-v2-m3 --backend vllm
# 成功加载输出示例
[INFO] Loading model bge-reranker-v2-m3...
[INFO] Model bge-reranker-v2-m3 loaded successfully with vLLM backend.
[INFO] Model UID: model-xxxxxx
[INFO] Endpoint: http://127.0.0.1:9997/v1/models/model-xxxxxx
2. 通过 curl 调用 API 验证模型状态
模型加载完成后,可以通过 Xinference 的 REST API 验证模型状态:
# 查看所有已加载模型
curl http://127.0.0.1:9997/v1/models
# 预期输出示例(JSON格式)
{
"models": [
{
"model_uid": "model-xxxxxx",
"model_name": "bge-reranker-v2-m3",
"model_type": "rerank",
"backend": "vllm",
"status": "ready",
"size_in_bytes": 1342177280,
"loaded_at": "2024-01-01T12:00:00Z"
}
]
}
3. 测试模型推理接口
确认模型状态为 "ready" 后,可以测试推理接口:
# 测试 rerank 模型(以 bge-reranker-v2-m3 为例)
curl http://127.0.0.1:9997/v1/rerank \
-H "Content-Type: application/json" \
-d '{
"model": "model-xxxxxx",
"query": "什么是人工智能?",
"documents": [
"人工智能是计算机科学的一个分支",
"机器学习是人工智能的实现方式之一",
"深度学习是机器学习的一个子领域"
],
"top_n": 3
}'
# 预期输出示例
{
"results": [
{
"index": 0,
"relevance_score": 0.95,
"document": "人工智能是计算机科学的一个分支"
},
{
"index": 1,
"relevance_score": 0.87,
"document": "机器学习是人工智能的实现方式之一"
},
{
"index": 2,
"relevance_score": 0.76,
"document": "深度学习是机器学习的一个子领域"
}
],
"model": "bge-reranker-v2-m3",
"usage": {
"total_tokens": 45
}
}
4. 监控服务日志
实时查看服务日志,确认无错误信息:
# 查看实时日志
tail -f xinference.log
# 成功日志示例
[INFO] Model bge-reranker-v2-m3 is ready for inference.
[INFO] API server listening on http://0.0.0.0:9997
验证要点总结:
- 模型状态:通过
/v1/models接口确认模型状态为"ready" - API 连通性:通过
/v1/rerank或/v1/completions等接口测试推理功能 - 日志无报错:
xinference.log中无ERROR或WARNING级别错误 - 进程存活:
ps aux | grep xinference-local显示进程正常运行
如果以上验证都通过,说明模型已成功加载并可以正常提供服务。
四、部署全流程踩坑实录
坑 1:执行 pip install “xinference[all]” 依赖冲突报错
完整报错日志
ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
outlines 0.0.46 requires numpy<2.0.0, but you have numpy 2.3.5 which is incompatible.
vllm-flash-attn 2.6.1 requires torch==2.4.0, but you have torch 2.11.0 which is incompatible.
xformers 0.0.27.post2 requires torch==2.4.0, but you have torch 2.11.0 which is incompatible.
根因分析
- numpy版本过高(2.x),Outlines包强制要求numpy<2.0;
- 安装了不匹配的高版本torch,vLLM-Flash-Attn、Xformers仅适配Torch 2.4系列;
- 多套CUDA/torch包共存,pip依赖解析冲突。
一键修复命令
# 卸载冲突组件
pip uninstall -y vllm-flash-attn xformers numpy torch torchvision torchaudio
# 重装兼容全套
pip install torch==2.4.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install xformers==0.0.27.post2 -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install "numpy<2.0" -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install vllm==0.6.3 -i https://pypi.tuna.tsinghua.edu.cn/simple --extra-index-url https://wheels.vllm.ai
pip install "xinference[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple
pip check
坑 2:sudo nohup xinference-local 启动提示命令不存在
完整报错
[1]+ 退出 127 sudo nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1
nohup: 无法运行命令 'xinference-local': 没有那个文件或目录
根因
sudo执行命令会清空当前shell的虚拟环境PATH变量,系统全局Python未安装Xinference,因此找不到脚本。
修复方案
全程不加 sudo,9997 是高位端口,无需 root 权限监听:
nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &
坑 3:vLLM 引擎启动报错:NVIDIA driver is too old (found version 12050)
完整报错
RuntimeError: The NVIDIA driver on your system is too old (found version 12050). Please update your GPU driver by downloading and installing a new version from the URL: http://www.nvidia.com/Download/index.aspx Alternatively, go to: https://pytorch.org to install a PyTorch version that has been compiled with your version of the CUDA driver.
根因
12050对应CUDA Driver API 12.5,新版vLLM v1 引擎对驱动下限要求抬高,当前驱动版本无法满足vLLM底层校验。
两套修复方案
方案1(推荐,无需升级驱动):卸载vLLM,只用transformers后端
pip uninstall -y vllm vllm-flash-attn
pip install xinference -i https://pypi.tuna.tsinghua.edu.cn/simple
# 加载模型强制指定transformers后端
xinference run bge-reranker-v2-m3 --backend transformers
方案 2(保留 vLLM):锁定 torch 2.4.1 cu124 全套兼容包,上文标准安装流程已适配。
坑 4:模型加载崩溃,OSError: libcudart.so.13: cannot open shared object file: No such file or directory
完整报错日志
OSError: libcudart.so.13: cannot open shared object file: No such file or directory
RuntimeError: Start sub pool failed, returncode: 1
模型启动失败,接口返回500
核心根因(最致命大坑)
- 本地 nvcc 是 CUDA 13.3,误安装了
torch==2.13.0+cu130、cuda-toolkit==13.0.3.0; - 服务器 NVIDIA 驱动最高仅支持 CUDA 12.5 Runtime,系统仅存在 libcudart.so.12,不存在 13 版本库文件;
- PyTorch 编译时绑定 CUDA 13 运行时库,启动 GPU 推理直接找不到 so 文件,子进程崩溃。
完整根治修复命令
# 1. 停止所有 Xinference 进程
pkill -f xinference
rm -f xinference.log
# 2. 彻底卸载所有 CUDA 13 相关包
pip uninstall -y torch torchvision torchaudio cuda-toolkit nvidia-cublas nvidia-cudnn-cu13 nvidia-cusparselt-cu13 nvidia-nccl-cu13 nvidia-nvjitlink triton numpy
# 3. 重装适配驱动上限 CUDA 12.4 的稳定全套
pip3 install torch==2.4.1 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 -i https://pypi.tuna.tsinghua.edu.cn/simple
pip install "numpy<2.0" packaging setuptools wheel -i https://pypi.tuna.tsinghua.edu.cn/simple
# 方案 A:不用 vLLM(推荐,彻底规避 CUDA 版本问题)
pip install xinference -i https://pypi.tuna.tsinghua.edu.cn/simple
# 方案 B:需要 vLLM 高性能推理则执行下面一行
pip install vllm==0.6.3 -i https://pypi.tuna.tsinghua.edu.cn/simple --extra-index-url https://wheels.vllm.ai
pip check
# 4. 重启服务
nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &
关键避坑总结
不要安装 cu130/cu133 版本 PyTorch,驱动上限仅 CUDA 12.5,只能使用 cu124 编译的 torch 包。
五、生产环境优化补充
5.1 系统托管systemd服务(开机自启、异常自动重启)
创建 /etc/systemd/system/xinference.service
[Unit]
Description=Xinference Model Inference Service
After=network.target
[Service]
User=root
WorkingDirectory=/opt/xinference
Environment="PATH=/opt/xinference/venv-xinference/bin"
Environment="XINFERENCE_MODEL_DIR=/data/xinference-models"
ExecStart=/opt/xinference/venv-xinference/bin/xinference-local --host 0.0.0.0 --port 9997
Restart=on-failure
RestartSec=5
[Install]
WantedBy=multi-user.target
执行生效命令:
sudo systemctl daemon-reload
sudo systemctl start xinference
sudo systemctl enable xinference
sudo systemctl status xinference
5.2 国内模型下载加速(魔搭ModelScope源)
启动服务前配置环境变量,优先从国内阿里云魔搭下载模型,避免HuggingFace访问超时:
export XINFERENCE_MODEL_SRC=modelscope
nohup xinference-local --host 0.0.0.0 --port 9997 > xinference.log 2>&1 &
5.3 8卡L20多卡张量并行加载大模型示例
以Qwen2-72B大模型为例,8卡张量并行分摊显存:
xinference run qwen2:72b-instruct-v1.5 --backend vllm --tensor-parallel-size 8
六、环境彻底崩坏重建方案
当依赖彻底混乱、多种CUDA/torch版本残留,无需手动卸载排查,直接删除虚拟环境重建,最快解决所有版本冲突:
cd /opt/xinference
# 删除损坏的虚拟环境
rm -rf venv-xinference
# 重新从【3.2 创建隔离虚拟环境】开始完整安装一遍
七、总结
- 环境隔离是核心:必须使用独立venv虚拟环境,杜绝系统全局Python;
- CUDA版本严格对齐:驱动上限CUDA12.5,仅能使用cu124的PyTorch,cu13系列包直接触发so文件缺失崩溃;
- 依赖版本一一匹配:torch2.4.1 ↔ vllm0.6.3 ↔ numpy<2.0,任意版本错位都会产生冲突报错;
- 两种推理后端灵活切换:追求吞吐量用vLLM;驱动/CUDA版本不兼容时,直接切换transformers后端零报错;
- 禁止sudo启动服务:会丢失虚拟环境PATH,找不到xinference命令。

2592

被折叠的 条评论
为什么被折叠?



