# Xinference 电商搜索部署完整指南

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

## 📋 快速导航

- [快速开始](#快速开始)
- [系统要求](#系统要求)
- [完整安装步骤](#完整安装步骤)
- [GPU 配置](#gpu-配置)
- [模型部署](#模型部署)
- [使用示例](#使用示例)
- [故障排除](#故障排除)

---

## 快速开始

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

```bash
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: 环境检查

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

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

# 检查 Docker
docker --version
docker compose version

# 检查 Conda
conda --version
```

### 步骤 2: 启动 Xinference 服务

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

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

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

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

**自动安装 NVIDIA Container Toolkit**：

```bash
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. 验证安装

**手动安装（可选）**：

```bash
# 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
```

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

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

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

**验证 GPU 模式**：

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

# 或者检查 GPU 使用
nvidia-smi
```

### 步骤 3: 配置 Python 环境

```bash
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

**快捷命令**：
```bash
xinference-env           # 激活环境并切换目录
xinference-activate     # 仅激活环境
xinference-cd          # 切换到 xinference 目录
```

### 步骤 4: 验证安装

```bash
# 检查 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 状态

```bash
# 检查 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 可用性测试

```bash
# 测试 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 配置

```bash
# 使用 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）

```bash
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 分钟

#### 单独部署

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

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

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

#### 查看已部署模型

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

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

### 测试模型

#### 测试 Embedding

```bash
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

```bash
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                     │
└──────────────────────────────────────┘
    ↓
最终结果
```

### 运行演示

```bash
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

```python
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

```bash
# 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: [].
```

**解决方案**：

```bash
# 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
```

**解决方案**：

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

### 问题 3: 显存不足

**症状**：
```
CUDA out of memory
```

**解决方案**：

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

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

### 问题 4: 导入错误

**症状**：
```
ModuleNotFoundError: No module named 'xinference'
```

**解决方案**：

```bash
# 激活正确的环境
xinference-env

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

### 问题 5: 服务连接失败

**解决方案**：

```bash
# 检查服务状态
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)   │
                    └─────────────┘
```

### 监控指标

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

---

## 附录

### 常用命令

```bash
# 服务管理
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 官方文档](https://inference.readthedocs.io/)
- [Qwen3 模型介绍](https://github.com/QwenLM/Qwen3)
- [Docker 部署指南](https://docs.docker.com/)
- [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/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