Xinference 完整部署及踩坑指南

一、前言

近期业务需要搭建私有化大模型推理服务,选用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 12.5

误装 CUDA 13 系列

无冲突

有冲突

高性能需求

CUDA/驱动兼容问题

环境准备
Ubuntu 22.04 + Python 3.12

硬件环境检查
nvidia-smi / nvcc -V

CUDA 版本对齐决策
驱动上限 CUDA 12.5

选择 PyTorch cu124 版本
避免 libcudart.so.13 缺失

触发致命错误
OSError: libcudart.so.13

回退修复
卸载 cu13 包,重装 cu124

创建虚拟环境
venv-xinference

安装依赖
清华源加速

PyTorch 2.4.1 cu124

vLLM 0.6.3

numpy<2.0

Xinference[all]

依赖冲突检测
pip check

启动 Xinference 服务
nohup xinference-local

执行一键修复命令

后端选择决策

vLLM 后端
适合 7B/13B/34B 大模型

transformers 后端
轻量 embedding/rerank

模型加载成功
服务就绪

关键决策点说明:

  1. CUDA 版本对齐:必须根据 nvidia-smi 显示的驱动上限(CUDA 12.5)选择对应的 PyTorch cu124 版本,避免安装 cu130/cu133 导致 libcudart.so.13 缺失。
  2. 后端选择:根据实际需求选择推理后端:
    • 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 中无 ERRORWARNING 级别错误
  • 进程存活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.
根因分析
  1. numpy版本过高(2.x),Outlines包强制要求numpy<2.0;
  2. 安装了不匹配的高版本torch,vLLM-Flash-Attn、Xformers仅适配Torch 2.4系列;
  3. 多套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
核心根因(最致命大坑)
  1. 本地 nvcc 是 CUDA 13.3,误安装了 torch==2.13.0+cu130cuda-toolkit==13.0.3.0
  2. 服务器 NVIDIA 驱动最高仅支持 CUDA 12.5 Runtime,系统仅存在 libcudart.so.12,不存在 13 版本库文件
  3. 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 创建隔离虚拟环境】开始完整安装一遍

七、总结

  1. 环境隔离是核心:必须使用独立venv虚拟环境,杜绝系统全局Python;
  2. CUDA版本严格对齐:驱动上限CUDA12.5,仅能使用cu124的PyTorch,cu13系列包直接触发so文件缺失崩溃;
  3. 依赖版本一一匹配:torch2.4.1 ↔ vllm0.6.3 ↔ numpy<2.0,任意版本错位都会产生冲突报错;
  4. 两种推理后端灵活切换:追求吞吐量用vLLM;驱动/CUDA版本不兼容时,直接切换transformers后端零报错;
  5. 禁止sudo启动服务:会丢失虚拟环境PATH,找不到xinference命令。
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值