本地如何使用docker部署和使用Xinference

以下是在本地使用 Docker 部署和运行 Xinference 的详细步骤，涵盖单机部署、模型加载、API 调用及常见问题解决方案：

---

一、部署前准备

1. 环境要求

• 操作系统：Linux / macOS / Windows（WSL2）
• Docker：版本 ≥ 20.10
• GPU 支持（可选）：需安装 NVIDIA Container Toolkit

2. 验证 Docker 环境

# 检查 Docker 是否正常运行
docker --version
docker run hello-world

---

二、单机部署 Xinference

1. 拉取 Xinference 镜像

docker pull xprobe/xinference:latest

2. 启动容器（根据硬件选择命令）

• 仅 CPU 模式：

  docker run -d -p 9998:9998 --name xinference xprobe/xinference:latest

• 启用 GPU 加速（需 NVIDIA 驱动）：

  docker run -d --gpus all -p 9998:9998 --name xinference xprobe/xinference:latest

3. 验证部署状态

访问 Web UI：[http://localhost:9998](http://localhost:9998)，若看到管理界面则部署成功。

---

三、部署与使用模型

1. 通过命令行启动模型

进入容器内部操作：

docker exec -it xinference bash

启动常用模型：

# 启动 Rerank 模型（如 bge-reranker-large）
xinference launch --model-name bge-reranker-large --model-type rerank

# 启动 Embedding 模型（如 bge-large-en）
xinference launch --model-name bge-large-en --model-type embedding

# 启动 LLM（如 Llama3-8B）
xinference launch --model-name llama-3-8b-instruct --model-type LLM --size-in-billions 8 --quantization 4

2. 通过 API 启动模型（推荐）

直接通过 REST API 动态加载模型：

# 启动 Rerank 模型
curl -X POST "http://localhost:9998/v1/models" \
  -H "Content-Type: application/json" \
  -d '{
    "model_type": "rerank",
    "model_name": "bge-reranker-large",
    "model_format": "pytorch"
  }'

3. 查看已加载模型

curl "http://localhost:9998/v1/models"

---

四、API 调用示例

1. Rerank 模型使用

import requests

# 调用 Rerank 接口
response = requests.post(
    "http://localhost:9998/v1/rerank",
    json={
        "model": "bge-reranker-large",
        "query": "如何学习机器学习？",
        "documents": [
            "机器学习需要掌握数学基础",
            "深度学习框架的使用教程",
            "Python 编程入门指南"
        ],
        "top_k": 2
    }
)

print(response.json())
# 输出示例：{"results":[{"index":0,"score":0.92},{"index":1,"score":0.85}]}

2. Embedding 模型使用

from xinference.client import Client

client = Client("http://localhost:9998")
model = client.get_model("bge-large-en")

embeddings = model.embed("Hello, world!")
print(embeddings.shape)  # 输出：(1024,)

---

五、高级配置

1. 挂载自定义模型目录

将本地模型文件映射到容器中：

docker run -d -p 9998:9998 \
  -v /path/to/local/models:/root/.xinference/models \
  xprobe/xinference:latest

2. 限制 GPU 显存

为容器分配指定 GPU 资源：

docker run -d --gpus '"device=0,1"' -p 9998:9998 \
  -e NVIDIA_VISIBLE_DEVICES=0,1 \
  xprobe/xinference:latest

3. 调整容器资源限制

限制 CPU 和内存使用：

docker run -d -p 9998:9998 \
  --cpus 4 \
  --memory 16g \
  xprobe/xinference:latest

---

六、常见问题解决

1. GPU 无法识别

• 现象：日志报错 Could not load library libcudnn.so
• 解决：

  # 确保宿主机已安装 NVIDIA 驱动
  nvidia-smi

  # 重新安装 NVIDIA Container Toolkit
  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 systemctl restart docker

2. 模型下载失败

• 现象：ERROR: Failed to download model from Hugging Face
• 解决：

  # 手动下载模型到宿主机目录
  git lfs install
  git clone https://huggingface.co/BAAI/bge-reranker-large /path/to/local/models

  # 重新启动容器并挂载目录
  docker run -d -p 9998:9998 -v /path/to/local/models:/root/.xinference/models xprobe/xinference:latest

3. 端口冲突

• 现象：Bind for 0.0.0.0:9998 failed: port is already allocated
• 解决：

  # 查找占用端口的进程
  sudo lsof -i :9998

  # 停止冲突进程或修改映射端口
  docker run -d -p 9999:9998 xprobe/xinference:latest

---

七、生产环境建议

1. 使用 Docker Compose：

   version: '3'
   services:
     xinference:
       image: xprobe/xinference:latest
       ports:
         - "9998:9998"
       deploy:
         resources:
           limits:
             cpus: '4'
             memory: 16G

2. 启用 HTTPS：

   docker run -d -p 443:9998 \
     -v /etc/ssl/certs:/etc/ssl/certs \
     xprobe/xinference:latest --tls-certfile=/etc/ssl/certs/server.crt --tls-keyfile=/etc/ssl/certs/server.key

---

通过以上步骤，您可以在本地快速部署功能完整的 Xinference 服务，支持 RAG 系统中的多模型协作。