Docker部署bge-m3/bge-reranker模型

安装与配置 NVIDIA Container Toolkit

确认前置条件
在开始之前，请确保系统已经安装了NVIDIA GPU驱动程序（NVIDIA 驱动≥535.86.10，支持 CUDA 12.2+），并且可以正常运行 nvidia-smi 命令。同时，Docker Engine（版本建议 Docker 24.0+）也需要被安装好。
安装 NVIDIA Container Toolkit
具体的安装命令会根据操作系统有所不同。以下是一些常见系统的安装方法，可以参考 NVIDIA Docker 安装指南：

对于Ubuntu或Debian系统：

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
apt-get update
apt-get install -y nvidia-container-toolkit

对于CentOS或RHEL系统：

curl -s -L https://nvidia.github.io/libnvidia-container/stable/rpm/nvidia-container-toolkit.repo | sudo tee /etc/yum.repos.d/nvidia-container-toolkit.repoyum clean expire-cacheyum install -y nvidia-container-toolkit

配置 Docker 运行时
安装完成后，需要配置Docker守护进程，使其默认使用NVIDIA Container Runtime。

nvidia-container-runtime --version
nvidia-ctk runtime configure --runtime=docker
systemctl restart docker

# 查看Docker Runtime配置
cat /etc/docker/daemon.json
{
    "default-runtime": "nvidia",
    "runtimes": {
        "nvidia": {
            "runtimeArgs": [],
            "path": "/usr/bin/nvidia-container-runtime"
        }
    },
    "insecure-registries": [
	  "xxx:5000"
    ]
}

验证 Docker GPU 支持

配置完成后，必须验证GPU是否真的可以在Docker容器中使用了。

运行测试容器：
使用一个标准的CUDA镜像启动一个容器，并执行 nvidia-smi 命令。如果容器内能正常显示出GPU信息，就说明配置成功了。

docker run --rm --gpus all nvidia/cuda:12.0-base nvidia-smi

这个命令会启动一个临时容器，并执行 nvidia-smi。如果配置正确，将看到与在宿主机上直接运行 nvidia-smi 类似的GPU状态信息。

部署bge-m3/bge-reranker模型

bge-m3/bge-reranker模型，TEI框架介绍参考常用AI模型介绍及多模型组合使用场景。

下载模型（推荐提前下载，避免容器内耗时）

通过 ModelScope 下载（推荐）

# 安装ModelScope工具
pip install modelscope

# 创建模型存储目录
mkdir -p /data/models

# 下载模型（国内源，速度快）
modelscope download --model BAAI/bge-m3 --local_dir /data/models/bge-m3
modelscope download --model BAAI/bge-reranker-v2-m3 --local-dir /data/models/bge-reranker-v2-m3

通过 Hugging Face 国内镜像下载（备用）

# 安装huggingface-cli
pip install huggingface-hub

# 设置国内镜像（hf-mirror）
export HF_ENDPOINT=https://hf-mirror.com

# 下载模型
huggingface-cli download --resume-download BAAI/bge-m3 --local-dir /data/models/bge-m3
huggingface-cli download --resume-download BAAI/bge-reranker-v2-m3 --local-dir /data/models/bge-reranker-v2-m3

text-embeddings-inference 国内镜像下载地址

模型部署

两个模型的核心部署命令对比：

特性	BGE-M3 嵌入模型	BGE-Reranker-V2-M3 重排序模型
核心功能	将文本转换为向量	对(query, document)对进行相关性打分
模型ID	`BAAI/bge-m3`	`BAAI/bge-reranker-v2-m3`
常用端口	`8080`	`8081`
验证方式	调用 `/embed` 端点	调用 `/rerank` 端点

NVIDIA GPU卡对应的text-embeddings-inference镜像：

Architecture    Image
CPU ghcr.io/huggingface/text-embeddings-inference:cpu-1.6
Volta   NOT SUPPORTED
Turing (T4, RTX 2000 series, …) ghcr.io/huggingface/text-embeddings-inference:turing-1.6 (experimental)
Ampere 80 (A100, A30)   ghcr.io/huggingface/text-embeddings-inference:1.6
Ampere 86 (A10, A40, A4000, …)  ghcr.io/huggingface/text-embeddings-inference:86-1.6
Ada Lovelace (RTX 4000 series, …)   ghcr.io/huggingface/text-embeddings-inference:89-1.6
Hopper (H20, H100)  ghcr.io/huggingface/text-embeddings-inference:hopper-1.6 (experimental)

1.部署 BGE-M3 嵌入模型
此命令会拉取本地镜像、加载本地模型并启动服务，使用NVIDIA L20卡部署。

docker run -d \
  --name bge-m3 \
  --runtime nvidia \
  --gpus '"device=0"' \
  --ipc=host \
  -v /data/models/bge-m3:/mnt/models\
  -p 8080:8080 \
  --entrypoint=text-embeddings-router \
  ghcr.io/huggingface/text-embeddings-inference:1.6 \
  --model-id /mnt/models \
  --port 8080 \
  --max-batch-tokens 16384 \
  --max-concurrent-requests 512 \
  --max-client-batch-size 32

参数详细解释：

参数组	参数	解释说明
Docker基础配置	`docker run -d`	启动一个新容器并在后台 (`-d`，即 `detached` 模式) 运行。
	`--name bge-m3`	为容器指定一个名称 (`bge-m3`)，便于后续通过名称进行管理（如查看日志、停止容器）。
	`-p 8080:8080`	端口映射，格式为 `宿主机端口:容器内端口`。此处将宿主机`8080`端口映射到容器内应用的`8080`端口，以便通过 `http://主机IP:8080` 访问服务。
	`-v /data/models/bge-m3:/mnt/models`	数据卷挂载，将宿主机目录 `/data/models/bge-m3` 挂载到容器内的 `/mnt/models` 路径。容器内的应用可直接读取此处的模型文件。
GPU与运行时配置	`--runtime nvidia`	指定使用 NVIDIA 容器运行时，这是容器能够访问宿主GPU驱动的基础（需提前安装`nvidia-container-toolkit`）。
	`--gpus '"device=0"'`	精确指定容器可使用的GPU设备。`"device=0"` 表示仅使用系统中的第一块GPU（索引为0）。引号的嵌套是语法要求。
	`--ipc=host`	让容器使用宿主机的进程间通信（IPC）命名空间。对于需要大量共享内存的GPU应用（如大模型推理），此配置能显著提升性能并避免内存问题。
镜像与入口点	`--entrypoint=text-embeddings-router`	覆盖Docker镜像默认的启动命令，直接指定容器启动时运行 `text-embeddings-router` 这个程序。
镜像与入口点	`ghcr.io/huggingface/text-embeddings-inference:1.6`	指定要拉取和运行的Docker镜像地址及标签。这里是Hugging Face官方提供的文本嵌入推理服务，版本为 `1.6`。
模型推理服务参数	`--model-id /mnt/models`	指定模型加载的路径。这里的 `/mnt/models` 对应上面 `-v` 参数挂载的目录，容器会从此路径读取模型文件。
	`--port 8080`	指定容器内的推理服务监听在 `8080` 端口。此端口必须与 `-p` 参数中映射的容器侧端口一致。
	`--max-batch-tokens 16384`	限制单个批处理中所有文本的token总数上限。是控制显存消耗和批处理效率的核心参数。
	`--max-concurrent-requests 512`	设置服务的最大并发请求数。用于控制服务负载，超过此数量的新请求需要排队等待。
	`--max-client-batch-size 32`	限制单个客户端请求中最多能包含的文本数量（即批大小）。与`max-batch-tokens`共同作用。

2.部署 BGE-Reranker-V2-M3 重排序模型

docker run -d \
  --name bge-reranker \
  --runtime nvidia \
  --gpus '"device=1"' \
  --ipc=host \
  -v /data/models/bge-reranker-v2-m3:/mnt/models\
  -p 8081:8080 \
  --entrypoint=text-embeddings-router \
  ghcr.io/huggingface/text-embeddings-inference:1.6 \
  --model-id /mnt/models \
  --port 8080 \
  --max-batch-tokens 16384 \
  --max-concurrent-requests 512 \
  --max-client-batch-size 32

执行 nvidia-smi 命令查看模型运行进程：

服务验证与问题排查

部署后，请按顺序验证服务状态。

1.检查容器状态

docker ps | grep -E "bge-m3|bge-reranker"

确认两个容器的状态（STATUS）均为 Up。

2.查看容器日志

# 查看BGE-M3日志
docker logs bge-m3 --tail 50

# 查看BGE-Reranker日志
docker logs bge-reranker --tail 50

关注日志末尾，确认出现类似 "Server started on 0.0.0.0:8080" 、"Ready"的成功信息，并且没有显存的报错。

3.发送测试请求

测试 BGE-M3 (嵌入)：成功会返回一个浮点数向量。

curl -X POST "http://localhost:8080/embed" \
  -H "Content-Type: application/json" \
  -d '{"inputs": "Hello, world!"}'

# 预期结果：
[[-0.015909059,0.026837891,...,-0.03666923,0.0015528625]]

测试 BGE-Reranker (重排序)：

text-embeddings-inference 服务的 /rerank 端点通常期望一个包含query和texts列表的JSON。成功会返回一个相关性分数列表。

curl -X POST "http://localhost:8081/rerank" \
      -H 'Content-Type: application/json' \
    -d '{"query":"What is Deep Learning?", "texts": ["Deep Learning is not...", "Deep learning is..."], "raw_scores": false}'

# 预期结果：
[{"index":1,"score":0.9976404},{"index":0,"score":0.12527926}]

问题排查

1.CUDA计算能力兼容性错误

docker run 启动模型容器报错：ERROR text_embeddings_backend: backends/src/lib.rs:388: Could not start Candle backend: Could not start backend: Runtime compute cap 89 is not compatible with compile time compute cap 90

这是问题原因是CUDA计算能力（90）与目前部署的GPU的实际计算能力（89）不匹配。确认使用的GPU具体型号和计算能力：

nvidia-smi --query-gpu=name,compute_cap --format=csv

常见计算能力对应表：详见 CUDA GPU 计算能力

计算能力	GPU架构	典型GPU型号
9.0	Hopper	NVIDIA H20，H100，H200
8.9	Ada Lovelace	RTX 40系列
8.6	Ampere	A100, A30, RTX 30系列
7.5	Turing	RTX 20系列, T4
6.1	Pascal	P100, GTX 10系列

解决方案：替换适配NVIDIA L20卡的镜像，Nvidia L20使用 ghcr.io/huggingface/text-embeddings-inference:1.6 镜像，H20使用 text-embeddings-inference:hopper-1.6 镜像

参考：

CHEGVA

让我们面对现实让我们忠于理想

Docker部署bge-m3/bge-reranker模型

安装与配置 NVIDIA Container Toolkit

验证 Docker GPU 支持

部署bge-m3/bge-reranker模型

下载模型（推荐提前下载，避免容器内耗时）

模型部署

服务验证与问题排查

问题排查

您可能还感兴趣的文章！

发表评论取消回复

安装与配置 NVIDIA Container Toolkit

验证 Docker GPU 支持

部署bge-m3/bge-reranker模型

下载模型（推荐提前下载，避免容器内耗时）

模型部署

服务验证与问题排查

问题排查

<img src="/static/book.png" width=20 height=20> 您可能还感兴趣的文章！

发表评论 取消回复

您可能还感兴趣的文章！

发表评论取消回复