xinference使用文档.md 7.43 KB
Edit Raw Blame History


根据搜索结果分析，Xinference从v1.7.0版本开始正式支持Qwen3-Embedding和Qwen3-Reranker模型。但需要注意早期版本存在一些部署问题，建议升级到最新稳定版。


一、支持情况确认
✅ 已支持（v1.7.0+）

Qwen3-Embedding：支持0.6B等规格，最大上下文8192 tokens，输出1024维向量
Qwen3-Reranker：支持0.6B等规格，Cross-Encoder架构用于精排

⚠️ 已知问题与解决方案

Batch Size限制：早期版本Qwen3-Reranker处理batch>1时报错no padding token defined


解决：升级到v1.7.0.post1或更高版本

GPU显存异常：vLLM引擎加载时显存占用过高


解决：升级到v1.7.1+，或使用--cpu-offload-gb参数


二、部署方案
方案1：Docker部署（推荐）
# 1. 拉取最新镜像（v1.7.1+）
docker pull xprobe/xinference:latest

# 2. 启动Xinference服务
docker run -d --name xinference \
  -p 9997:9997 -p 9998:9998 \
  --gpus all \
  -v /data/models:/data \
  -e XINFERENCE_HOME=/data \
  xprobe/xinference:latest xinference-local -H 0.0.0.0

# 3. 查看服务状态
curl http://localhost:9997/v1/models

方案2：pip部署
# 1. 安装最新版本（务必v1.7.1+）
pip install "xinference>=1.7.1"

# 2. 启动本地服务
xinference-local --host 0.0.0.0 --port 9997

# 3. 或启动集群模式
xinference-supervisor -H ${SUPERVISOR_HOST}
xinference-worker -e "http://${SUPERVISOR_HOST}:9997"


三、模型部署与使用
步骤1：部署Qwen3-Embedding模型
from xinference.client import Client

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

# 启动Qwen3-Embedding模型
model_uid = client.launch_model(
    model_name="qwen3-embedding",
    model_size_in_billions=0,  # 0表示自动选择可用版本
    model_type="embedding",
    engine="vllm",  # 推荐vLLM引擎
    gpu_idx="0",     # 指定GPU
)
print(f"Embedding模型UID: {model_uid}")

步骤2：部署Qwen3-Reranker模型
# 启动Qwen3-Reranker模型
reranker_uid = client.launch_model(
    model_name="qwen3-reranker",
    model_size_in_billions=0,
    model_type="rerank",  # 明确指定为reranker
    engine="vllm",
    gpu_idx="0",  # 可与embedding同卡，注意显存
)
print(f"Reranker模型UID: {reranker_uid}")

步骤3：电商搜索实战使用
# 获取模型实例
embedding_model = client.get_model(model_uid)
reranker_model = client.get_model(reranker_uid)

# 示例：电商搜索query和商品标题
query = "适合老人用的智能手机大屏幕长续航"
candidate_products = [
    "红米Note12 5000mAh大电量 6.67英寸大屏 老人模式",
    "iPhone 15 Pro Max 专业摄影旗舰",
    "华为畅享60 6000mAh超长续航 护眼大屏",
    "OPPO A1 5000mAh电池 简易模式适合长辈",
    "小米手环8 智能运动监测",
]

# 阶段1：密集检索召回Top-200
query_embedding = embedding_model.create_embedding(query)["data"][0]["embedding"]
# 使用Faiss或向量数据库批量检索（伪代码）
# candidate_embeddings = [embedding_model.create_embedding(p)["data"][0]["embedding"] for p in candidate_products]
# top200_ids = faiss_search(query_embedding, candidate_embeddings, k=200)

# 阶段2：精排Top-200为Top-50（实际场景）
# 为演示简化为精排全部5个
pairs = [(query, product) for product in candidate_products]
rerank_scores = reranker_model.rerank(pairs)

# 按重排序分数排序
sorted_results = sorted(
    zip(candidate_products, rerank_scores),
    key=lambda x: x[1]["relevance_score"],
    reverse=True
)

# 输出结果
for product, score in sorted_results:
    print(f"相似度: {score['relevance_score']:.4f} | 商品: {product}")

# 预期输出：
# 相似度: 0.9234 | 商品: 华为畅享60 6000mAh超长续航 护眼大屏
# 相似度: 0.8912 | 商品: OPPO A1 5000mAh电池 简易模式适合长辈
# 相似度: 0.8567 | 商品: 红米Note12 5000mAh大电量 6.67英寸大屏 老人模式
# 相似度: 0.2345 | 商品: iPhone 15 Pro Max 专业摄影旗舰
# 相似度: 0.1234 | 商品: 小米手环8 智能运动监测


四、REST API调用方式
Embedding API（兼容OpenAI格式）
# 实时生成query向量
curl -X POST http://localhost:9997/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding",
    "input": ["适合老人用的智能手机大屏幕长续航"]
  }'

# 批量生成商品向量（离线任务）
curl -X POST http://localhost:9997/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-embedding",
    "input": ["商品标题1", "商品标题2", ..., "商品标题10000"]
  }'

Reranker API
# 精排候选商品
curl -X POST http://localhost:9997/v1/rerank \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-reranker",
    "query": "适合老人用的智能手机大屏幕长续航",
    "documents": [
      "红米Note12 5000mAh大电量 6.67英寸大屏 老人模式",
      "华为畅享60 6000mAh超长续航 护眼大屏"
    ],
    "top_n": 10
  }'


五、关键参数与优化
1. 显存配置建议
# 对于显存有限的场景，使用CPU卸载
reranker_uid = client.launch_model(
    model_name="qwen3-reranker",
    model_type="rerank",
    engine="vllm",
    cpu_offload_gb=16,  # 将部分计算卸载到CPU
    gpu_memory_utilization=0.6,  # 限制显存使用
)

2. 性能调优
# Embedding批量处理优化
embedding_model.create_embedding(
    input_texts, 
    batch_size=100,  # 增大批量提升吞吐
    normalize=True   # 归一化向量用于余弦相似度
)

# Reranker并发控制（避免OOM）
reranker_model.rerank(
    pairs,
    batch_size=8,  # 根据显存调整，A10G建议8-16
    max_length=512 # 限制输入长度
)

3. 电商搜索最佳实践

离线批量：每天凌晨全量重新生成2亿商品embedding，存入向量数据库（Milvus/Pinecone）
在线实时：用户query实时embedding，召回Top-1000
精排阶段：对Top-1000使用Qwen3-Reranker打分，取Top-50返回
缓存策略：TOP 10000热搜query的embedding和rerank结果缓存Redis，QPS提升10倍
混合检索：结合BM25关键词召回，提升头部Query准确率


六、版本兼容性矩阵


Xinference版本
Qwen3-Embedding
Qwen3-Reranker
推荐度


❌ 不支持
❌ 不支持
必须升级


v1.7.0
✅ 支持
⚠️ 有batch bug
慎用


v1.7.0.post1
✅ 支持
✅ 基本支持
可用


≥ v1.7.1
✅ 完美支持
✅ 完美支持
强烈推荐


建议：生产环境务必使用 v1.7.1或更高版本


七、监控与运维
# 查看模型运行状态
curl http://localhost:9997/v1/models

# 监控GPU显存（推荐部署Prometheus+Grafana）
nvidia-smi -l 1

# 日志排查
docker logs -f xinference --tail 100


总结
Xinference + Qwen3-Embedding + Qwen3-Reranker是完全可行且已生产可用的组合，特别适合电商搜索场景。只需注意：


版本必须≥1.7.1
Reranker建议单独部署以避免显存争抢
两阶段检索（海选+精排）是最佳实践


如需具体压测数据或故障排查，可进一步咨询！