本地使用 Docker 部署和使用 Xinference

本地使用 Docker 部署和使用 Xinference

一、部署前准备

1. 环境要求

• 操作系统：Linux / macOS / Windows（WSL2）

• Docker：版本 ≥ 20.10

• GPU 支持（可选）：需安装 NVIDIA Container Toolkit

2. 验证 Docker 环境

bash复制

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

二、单机部署 Xinference

1. 拉取 Xinference 镜像

bash复制

docker pull xprobe/xinference:latest

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

• 仅 CPU 模式：

  bash复制

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

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

  bash复制

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

3. 验证部署状态

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

三、部署与使用模型

1. 通过命令行启动模型

进入容器内部操作：

bash复制

docker exec -it xinference bash

启动常用模型：

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 动态加载模型：

bash复制

# 启动 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. 查看已加载模型

bash复制

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

四、API 调用示例

1. Rerank 模型使用

Python复制

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())
# 输出示例：,]}

2. Embedding 模型使用

Python复制

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. 挂载自定义模型目录

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

bash复制

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

2. 限制 GPU 显存

为容器分配指定 GPU 资源：

bash复制

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

3. 调整容器资源限制

限制 CPU 和内存使用：

bash复制

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

六、常见问题解决

1. GPU 无法识别

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

bash复制

# 确保宿主机已安装 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 解决：

bash复制

# 手动下载模型到宿主机目录
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 解决：

bash复制

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

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

七、生产环境建议

使用 Docker Compose：

yaml复制

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

启用 HTTPS：

bash复制

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 系统中的多模型协作。