Xinference部署bge-reranker-v2-m3模型完整指南（WSL）

一、环境准备与基础依赖安装

1.1 安装git-lfs

# 下载git-lfs
wget https://github.com/git-lfs/git-lfs/releases/download/v3.5.1/git-lfs-linux-amd64-v3.5.1.tar.gz

# 解压安装包
tar -zxvf git-lfs-linux-amd64-v3.5.1.tar.gz

# 进入安装目录
cd git-lfs-3.5.1

# 执行安装脚本
sudo ./install.sh

# 配置git-lfs
git lfs install

# 验证安装
git lfs version

1.2 安装uv并配置Python环境

# 下载并安装uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 配置环境变量（根据实际安装路径调整）
export PATH="$HOME/.local/bin:$PATH"

# 使用uv锁定Python 3.11版本
uv python install 3.11

二、安装Xinference

2.1 安装Xinference核心组件

# 使用uv安装Xinference
uv pip install xinference -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装模型依赖
uv pip install --upgrade transformers peft -i https://pypi.tuna.tsinghua.edu.cn/simple

2.2 配置系统服务

# 创建systemd服务文件
sudo tee /etc/systemd/system/xinference.service << EOF
[Unit]
Description=Xinference Service
After=network.target

[Service]
Type=simple
User=king
WorkingDirectory=/home/king
ExecStart=/home/king/.local/bin/xinference-local -H 0.0.0.0
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# 启动服务
sudo systemctl daemon-reload
sudo systemctl start xinference.service
sudo systemctl enable xinference.service

三、模型下载与准备

3.1 使用git-lfs下载模型

# 克隆模型仓库
git clone https://www.modelscope.cn/AI-ModelScope/bge-reranker-v2-m3.git

# 移动模型到指定目录
mv bge-reranker-v2-m3 /home/king/ai_model/

3.2 验证模型文件

# 检查模型文件完整性
ls -lh /home/king/ai_model/bge-reranker-v2-m3/
# 确认model.safetensors文件大小约为2.2GB

四、模型部署与启动

4.1 启动重排序模型

# 启动bge-reranker-v2-m3模型（gpu）
xinference launch \
  --model-name bge-reranker-v2-m3 \
  --model-type rerank \
  --gpu-idx 0 \
  --model-path /home/king/ai_model/bge-reranker-v2-m3

4.2 常见错误解决方案

ModuleNotFoundError: No module named ‘transformers’

# 安装缺失的依赖
uv pip install --upgrade transformers peft -i https://pypi.tuna.tsinghua.edu.cn/simple

CrossEncoder.init() got an unexpected keyword argument ‘engine’

# 启动时不要添加--engine参数
# 正确用法如上所示，无需指定engine

五、模型验证与测试

5.1 检查模型状态

# 查看当前运行的模型
xinference list

5.2 API功能测试

# 发送测试请求
curl -X POST http://localhost:9997/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "如何做西红柿炒鸡蛋",
    "documents": [
      "西红柿炒鸡蛋是一道经典的家常菜，做法简单。",
      "今天天气真好，适合出去散步。",
      "准备两个鸡蛋打散，西红柿切块，热锅凉油先炒鸡蛋。"
    ]
  }'

5.3 预期结果分析

正常返回结果应包含：

• index: 2 - 具体操作步骤，相关度最高（约0.997）
• index: 0 - 背景介绍，相关度次之（约0.987）
• index: 1 - 无关内容，相关度极低（约0.00001）

六、进阶配置建议

6.1 性能优化

• 确保GPU驱动和CUDA环境配置正确
• 根据GPU显存大小调整批处理参数
• 监控系统资源使用情况

七、故障排查指南

7.1 服务状态检查

# 查看服务状态
sudo systemctl status xinference.service

# 查看服务日志
sudo journalctl -u xinference.service -f

7.2 网络连接测试

# 测试API端口
curl http://localhost:9997/health

7.3 常见问题汇总

• 权限问题：确保用户对模型目录有读写权限
• 依赖冲突：使用虚拟环境隔离依赖
• GPU不可用：检查CUDA和cuDNN版本兼容性