Xinference 电商搜索部署完整指南

使用 Qwen3-Embedding 和 Qwen3-Reranker 构建两阶段搜索系统（密集检索 + 精排）

📋 快速导航

• 快速开始
• 系统要求
• 完整安装步骤
• GPU 配置
• 模型部署
• 使用示例
• 故障排除

---

快速开始

最快 5 分钟上手（CPU 模式）

cd /data/tw/SearchEngine/third-party/xinference

# 1. 启动 Xinference 服务（自动 CPU 模式）
bash start.sh

# 2. 创建 Python 环境
bash setup_env.sh
bash setup_alias.sh
source ~/.bashrc

# 3. 激活环境
xinference-env

# 4. 部署模型（CPU 模式，慢但可用）
python deploy_models.py

# 5. 运行演示
python ecommerce_demo.py

注意：CPU 模式仅用于测试，生产环境请使用 GPU 模式。

---

系统要求

硬件配置

组件	最低配置	推荐配置
CPU	8核	16核+
内存	16GB	64GB+
GPU	无（CPU 模式）	NVIDIA Tesla T4 16GB+
存储	30GB	100GB+ SSD

GPU 显存需求：

• Qwen3-Embedding (4B): ~8GB
• Qwen3-Reranker (4B): ~8GB
• 两个模型同时运行: ~16GB+

软件要求

• 操作系统: Linux (Ubuntu 20.04+, CentOS 7+)
• Docker: 20.10+
• Docker Compose: v2.0+
• NVIDIA Driver: 525.0+ (GPU 模式)
• Conda: Miniconda3 或 Anaconda3
• Python: 3.10

---

完整安装步骤

步骤 1: 环境检查

# 检查系统信息
cat /etc/os-release

# 检查 GPU（如果有）
nvidia-smi

# 检查 Docker
docker --version
docker compose version

# 检查 Conda
conda --version

步骤 2: 启动 Xinference 服务

选项 A: CPU 模式（快速测试）

cd /data/tw/SearchEngine/third-party/xinference
bash start.sh

特点：

• ✅ 无需额外配置
• ✅ 快速启动
• ❌ 速度慢（10-50倍）
• ❌ 仅适合测试

选项 B: GPU 模式（生产环境）

自动安装 NVIDIA Container Toolkit：

cd /data/tw/SearchEngine/third-party/xinference
bash install_nvidia_container_toolkit.sh

脚本会自动：

1. 检测系统类型
2. 添加 NVIDIA 仓库
3. 安装 nvidia-container-toolkit
4. 配置 Docker 运行时
5. 重启 Docker 服务
6. 验证安装

手动安装（可选）：

# Ubuntu/Debian
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-docker.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

安装完成后，重新启动服务：

# 停止旧容器
sudo docker stop xinference
sudo docker rm xinference

# 重新启动（自动使用 GPU）
bash start.sh

验证 GPU 模式：

# 检查服务日志
sudo docker logs xinference | grep -i gpu

# 或者检查 GPU 使用
nvidia-smi

步骤 3: 配置 Python 环境

cd /data/tw/SearchEngine/third-party/xinference

# 自动创建环境
bash setup_env.sh

# 设置快捷别名
bash setup_alias.sh

# 使配置生效
source ~/.bashrc

环境信息：

• 环境名: xinference
• Python: 3.10.19
• 包: xinference-client 1.15.0, numpy 2.2.6

快捷命令：

xinference-env           # 激活环境并切换目录
xinference-activate     # 仅激活环境
xinference-cd          # 切换到 xinference 目录

步骤 4: 验证安装

# 检查 Xinference 服务
curl http://localhost:9997/v1/models

# 预期输出
{"object":"list","data":[]}

# 检查 Python 环境
xinference-env
python -c "from xinference_client import RESTfulClient; print('✅ 环境配置成功！')"

# 查看 Dashboard
open http://localhost:9998
# 或在浏览器访问

---

GPU 配置

检查 GPU 状态

# 检查 NVIDIA 驱动
nvidia-smi

# 检查 Docker GPU 支持
sudo docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

# 预期输出（成功）
+-----------------------------------------------------------------------------+
| NVIDIA-SMI 525.85.12    Driver Version: 525.85.12    CUDA Version: 11.0     |
|-------------------------------+----------------------+----------------------+
| GPU  Name        Persistence-M| Bus-Id        Disp.A | Volatile Uncorr. ECC |
| Fan  Temp  Perf  Pwr:Usage/Cap|         Memory-Usage | GPU-Util  Compute M. |
|===============================+======================+======================|
|   0  Tesla T4            On   | 00000000:00:1E.0 Off |                    0 |
| 34%   42C    P8    16W / 70W |      0MiB / 16384MiB |      0%      Default |
+-------------------------------+----------------------+----------------------+

GPU 可用性测试

# 测试 1: 检查 Xinference 是否能看到 GPU
curl http://localhost:9997/v1/models

# 测试 2: 尝试部署一个小模型测试 GPU
xinference-env
python -c "
from xinference_client import RESTfulClient
client = RESTfulClient('http://localhost:9997')
# 列出支持的 GPU 模型
# 如果成功，说明 GPU 可用
"

多 GPU 配置

# 使用 GPU 0
python deploy_models.py --gpu 0

# 使用 GPU 1
python deploy_models.py --gpu 1

# 使用多个 GPU
python deploy_models.py --gpu 0,1

---

模型部署

部署 Qwen3 4B 模型

完整部署（Embedding + Reranker）

xinference-env

# 部署所有模型
python deploy_models.py

预期输出：

============================================================
  Qwen3 模型自动部署
============================================================

🔗 连接到 Xinference 服务: http://localhost:9997
✅ 连接成功！

============================================================
  部署 Qwen3-Embedding 模型 (4B)
============================================================

⏳ 正在部署，首次运行需要下载模型，请耐心等待...
   模型大小: ~8GB
   上下文长度: 8192 tokens
   向量维度: 1024

✅ Qwen3-Embedding 部署成功！
   模型 UID: qwen3-embedding-4b

============================================================
  部署 Qwen3-Reranker 模型 (4B)
============================================================

✅ Qwen3-Reranker 部署成功！
   模型 UID: qwen3-reranker-4b

============================================================
  🎉 模型部署完成！
============================================================

预计时间（GPU 模式）：

• 首次下载: 5-15 分钟（取决于网络）
• 模型加载: 2-5 分钟

单独部署

# 仅部署 Embedding
python deploy_models.py --embedding-only

# 仅部署 Reranker
python deploy_models.py --reranker-only

# 指定 GPU
python deploy_models.py --gpu 1

查看已部署模型

# 使用脚本
python deploy_models.py --list

# 使用 API
curl http://localhost:9997/v1/models | python -m json.tool

测试模型

测试 Embedding

xinference-env
python -c "
from xinference_client import RESTfulClient

client = RESTfulClient('http://localhost:9997')
model = client.get_model('qwen3-embedding-4b')

result = model.create_embedding('测试文本')
vector = result['data'][0]['embedding']

print(f'✅ 向量维度: {len(vector)}')
print(f'✅ 前5维: {vector[:5]}')
"

测试 Reranker

xinference-env
python -c "
from xinference_client import RESTfulClient

client = RESTfulClient('http://localhost:9997')
model = client.get_model('qwen3-reranker-4b')

query = '适合老人用的智能手机'
docs = ['华为畅享60 6000mAh', '小米手环8']

results = model.rerank([(query, doc) for doc in docs])

for doc, score in zip(docs, results):
    print(f'[{score[\"relevance_score\"]:.4f}] {doc}')
"

---

使用示例

电商搜索两阶段架构

用户查询: "适合老人用的智能手机大屏幕长续航"
    ↓
┌──────────────────────────────────────┐
│ 阶段1: 密集检索 (Dense Retrieval)     │
│ Qwen3-Embedding (4B)                 │
│ 召回 Top-200                         │
└──────────────────────────────────────┘
    ↓
┌──────────────────────────────────────┐
│ 阶段2: 精排 (Reranking)              │
│ Qwen3-Reranker (4B)                  │
│ Top-200 → Top-10                     │
└──────────────────────────────────────┘
    ↓
最终结果

运行演示

xinference-env

# 完整演示
python ecommerce_demo.py

# 简单演示
python ecommerce_demo.py --simple

# 指定模型 UID
python ecommerce_demo.py --embedding qwen3-embedding-4b --reranker qwen3-reranker-4b

输出示例：

======================================================================
  🛒 电商搜索实战演示 - Qwen3 双塔架构
======================================================================

🔗 连接到 Xinference 服务...
✅ 连接成功！

⏳ 加载模型...
✅ 模型加载完成

======================================================================
🔍 搜索查询: 适合老人用的智能手机大屏幕长续航
======================================================================

📊 阶段1: 密集检索（召回 Top-200）
----------------------------------------------------------------------
⏱️  密集检索耗时: 0.23秒
✅ 召回 200 个候选商品

🎯 阶段2: 精排（Cross-Encoder 打分）
----------------------------------------------------------------------
⏱️  精排耗时: 0.15秒

🎯 搜索结果 (Top 5):
----------------------------------------------------------------------
1. [0.9876] 华为畅享60 6000mAh超长续航 护眼大屏 鸿蒙系统
2. [0.9654] OPPO A1 5000mAh电池 简易模式适合长辈
3. [0.9432] vivo Y78 5000mAh大电池 120Hz高刷屏
4. [0.9210] 荣耀Play7T 6000mAh巨量电池 双卡双待
5. [0.8976] 诺基亚C31 5050mAh电池 耐用三防

代码示例

Python SDK

from xinference_client import RESTfulClient

# 连接服务
client = RESTfulClient("http://localhost:9997")

# 获取模型
embedding_model = client.get_model("qwen3-embedding-4b")
reranker_model = client.get_model("qwen3-reranker-4b")

# 1. 生成 Embedding
query = "高端智能手机"
query_vector = embedding_model.create_embedding(query)["data"][0]["embedding"]

# 2. 搜索商品（假设有预计算的向量）
# products_with_vectors = [...]

# 3. 精排
results = reranker_model.rerank([
    (query, "华为 Mate 60 Pro 卫星通信"),
    (query, "iPhone 15 Pro Max 钛金属"),
    (query, "小米14 Pro 徕卡光学")
])

for result in results:
    print(f"[{result['relevance_score']:.4f}] {result['index']}")

REST API

# Embedding API
curl -X POST http://localhost:9997/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding-4b",
    "input": ["测试文本"]
  }'

# Reranker API
curl -X POST http://localhost:9997/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-reranker-4b",
    "query": "适合老人用的手机",
    "documents": [
      "华为畅享60 6000mAh",
      "小米手环8"
    ],
    "top_n": 5
  }'

---

故障排除

问题 1: GPU 不可用

症状：

Worker can only see these GPUs: [].

解决方案：

# 1. 安装 NVIDIA Container Toolkit
bash install_nvidia_container_toolkit.sh

# 2. 重启服务
sudo docker stop xinference
sudo docker rm xinference
bash start.sh

# 3. 验证
nvidia-smi

问题 2: 模型下载失败

症状：

Failed to download model

解决方案：

# 使用国内镜像
export HF_ENDPOINT=https://hf-mirror.com
python deploy_models.py

问题 3: 显存不足

症状：

CUDA out of memory

解决方案：

# 只部署一个模型
python deploy_models.py --embedding-only

# 或使用不同的 GPU
python deploy_models.py --gpu 1

问题 4: 导入错误

症状：

ModuleNotFoundError: No module named 'xinference'

解决方案：

# 激活正确的环境
xinference-env

# 重新安装依赖
pip install xinference-client --force-reinstall

问题 5: 服务连接失败

解决方案：

# 检查服务状态
curl http://localhost:9997/v1/models

# 查看日志
sudo docker logs -f xinference

# 重启服务
sudo docker restart xinference

---

进阶配置

性能优化

1. 离线向量预计算
2. 向量数据库集成（Milvus/Pinecone）
3. Redis 缓存
4. 批量处理

生产部署

                    ┌─────────────┐
                    │   负载均衡   │
                    └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
         ┌────▼────┐  ┌───▼────┐  ┌───▼────┐
         │Xinference│ │Xinference│ │Xinference│
         │ Instance1│ │ Instance2│ │ Instance3│
         └────┬────┘  └───┬────┘  └───┬────┘
              │            │            │
              └────────────┼────────────┘
                           │
                    ┌──────▼──────┐
                    │   向量数据库   │
                    │   (Milvus)   │
                    └─────────────┘

监控指标

metrics = {
    "latency_p50": "< 100ms",
    "latency_p99": "< 300ms",
    "qps": "100+",
    "gpu_utilization": "< 80%",
    "cache_hit_rate": "> 60%"
}

---

附录

常用命令

# 服务管理
bash start.sh                      # 启动服务
sudo docker logs -f xinference     # 查看日志
sudo docker restart xinference     # 重启服务
sudo docker stop xinference        # 停止服务

# 环境管理
xinference-env                     # 激活环境
conda deactivate                   # 退出环境

# 模型管理
python deploy_models.py            # 部署模型
python deploy_models.py --list     # 列出模型
curl http://localhost:9997/v1/models  # API 查询

# 演示示例
python ecommerce_demo.py           # 运行演示
python ecommerce_demo.py --simple  # 简单示例

目录结构

xinference/
├── README.md                              # 本文档
├── QUICKSTART.md                          # 快速开始
├── ENV_SETUP.md                           # 环境配置详解
├── start.sh                               # 服务启动脚本
├── install_nvidia_container_toolkit.sh    # NVIDIA Toolkit 安装
├── setup_env.sh                           # Conda 环境创建
├── setup_alias.sh                         # Shell 别名配置
├── activate.sh                            # 环境激活脚本
├── deploy_models.py                       # 模型部署脚本
├── ecommerce_demo.py                      # 电商搜索示例
├── docker-compose.yml                     # Docker Compose 配置
└── models/                                # 模型存储目录

参考资源

• Xinference 官方文档
• Qwen3 模型介绍
• Docker 部署指南
• NVIDIA Container Toolkit

---

总结

本文档提供了 Xinference 电商搜索系统的完整部署指南：

✅ 环境准备: Docker + Conda + GPU 驱动 ✅ 服务安装: CPU/GPU 两种模式 ✅ 环境配置: 自动化脚本 + 快捷命令 ✅ 模型部署: Qwen3-Embedding 4B + Qwen3-Reranker 4B ✅ 使用示例: 两阶段搜索架构 ✅ 故障排除: 常见问题及解决方案

下一步：

1. 根据需求选择 CPU 或 GPU 模式
2. 部署模型并运行演示
3. 根据实际数据集调整参数
4. 集成向量数据库进行优化

---

文档版本: v1.0 最后更新: 2025-12-25 维护者: Search Engine Team