安装与配置 NVIDIA Container Toolkit

1. 确认前置条件
   在开始之前，请确保系统已经安装了NVIDIA GPU驱动程序（NVIDIA 驱动≥535.86.10，支持 CUDA 12.2+），并且可以正常运行 nvidia-smi 命令。同时，Docker Engine（版本建议 Docker 24.0+）也需要被安装好。

2. 安装 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

3. 配置 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 国内镜像下载地址

模型部署

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

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

参数详细解释：

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}]

许多自部署的嵌入服务要求显式指定 model 字段，即使只有一个模型。如果是调用云服务，需要确认一下 Authorization 头格式是否正确，必须是 "Bearer YOUR_TOKEN" 这样的格式。

# OpenAI兼容格式
curl -X POST https://api.example.com/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "input": "你的测试文本",
    "model": "bge-m3"
  }'
  
curl -X POST https://api.example.com \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is Deep Learning?",
    "documents": ["Deep Learning is not...", "Deep learning is..."],
    "model": "bge-reranker"
  }'
  
# Ollama调用格式
curl http://api.example.com/api/embeddings -d '{
  "model": "bge-m3:latest",
  "prompt": "你的测试文本"
}'

# 调用云服务请求一般需要加上AK
-H "Authorization: Bearer YOUR_TOKEN"

问题排查

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 计算能力

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

2.curl测试模型调用400状态码报错，返回错误信息'msg': 'Field required', "type": "BadRequestError", "param": null, "code": 400 

错误信息 "Field required" 明确指出请求体中缺少了服务器所必需的字段。常见的自部署的服务（例如于 FlagEmbedding 或 FastAPI 自建的）可能期望的字段名与使用的不同。以下是几种可能的原因：

1. 字段名不匹配：服务器可能期望使用 documents 或 passages 而不是 texts 来接收待排序的文本列表。

2. 缺少必需字段：某些服务要求必须指定模型名称（model），即使只有一个模型。

3. 字段不被识别：请求的某些字段可能是非标准的，服务器解析时可能因多余字段而报错（虽然错误信息是“缺少字段”，但有时多余的字段也可能导致验证失败，不过通常会更明确地指出多余字段）。最可能还是缺少核心字段。

4. 字段名拼写错误：比如本应是 "texts"，写成了 "text"；或者 "mode" 写成了 "model"。字段名对不上，服务端会认为这个字段不存在。

5. JSON 格式不合法：特别是在 Windows 的命令行(cmd)中直接运行 curl，处理双引号时非常容易出错，导致整个 JSON 结构被破坏。

3.curl测试deepseek v3.2 function call功能返回400状态码报错

返回400报错，"function_call":null,"tool_calls":[]，tool_calls 没有数据。

解决：vllm部署deepseek加上支持function call配置参数：

vllm serve <model> --enable-auto-tool-choice --tool-call-parser deepseek_v3 --chat-template /path/to/tool_chat_template_deepseekvxx.jinja

正常function call 测试返回示例：

curl -s https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
  -H "Authorization: Bearer sk-0dd98xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v3.2",
    "messages": [
      {"role": "user", "content": "广州今天天气怎么样？"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "获取指定城市的实时天气",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "城市名称，例如 北京"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'
  
{"choices":[{"message":{"content":"我来帮您查询广州今天的天气情况。\n\n","role":"assistant","tool_calls":[{"function":{"arguments":"{\"location\": \"广州\", \"unit\": \"celsius\"}","name":"get_current_weather"},"id":"call_d786b74445f245b28151de2d","index":0,"type":"function"}]},"finish_reason":"tool_calls","index":0,"logprobs":null}],"object":"chat.completion","usage":{"prompt_tokens":335,"completion_tokens":70,"total_tokens":405,"prompt_tokens_details":{"cached_tokens":0}},"created":1773819775,"system_fingerprint":null,"model":"deepseek-v3.2","id":"chatcmpl-5d00f0d8-8e9f-9edb-ac9b-7104b5a6c126"}

相关参考：

• Native tool calls fail on DeepSeek 3.2
  

• https://docs.vllm.ai/en/latest/features/tool_calling/#deepseek-v3-models-deepseek_v3
  

• OpenManus项目对接自建LLM时的API 400错误解决方案
  

进一步排查建议

• 查看服务启动日志：当启动这个 localhost:8080 服务时，控制台通常会打印出可用的 API 路由和示例请求格式。检查日志中是否有类似 “Embeddings API is available at /v1/embeddings” 的信息，有时还会附带示例 curl 命令。

• 查阅服务的文档：如果使用的是特定框架（如 vLLM、LocalAI、FastChat 或 llama.cpp 的服务器模式），请查阅该框架的 OpenAI 兼容 API 文档，确认正确的字段名称和必要参数。

• 尝试访问 /v1/models：许多兼容 OpenAI API 的服务会提供 /v1/models 端点，列出可用的模型。运行以下命令看看返回什么：curl http://localhost:8080/v1/models。如果返回了模型列表，可以从中选取正确的模型名称填入 model 字段。

• 查看服务的 OpenAPI 文档（如果有）：许多基于 FastAPI 的服务会自动生成交互式文档。在浏览器中访问以下地址之一：

http://localhost:8080/docs

http://localhost:8080/redoc

参考：

• NVIDIA GPU架构演进及使用场景

• 英伟达GPU参数速查表

• 常用AI模型介绍及多模型组合使用场景

• CentOS、Ubuntu、Windows NVIDIA 显卡驱动安装

• 手把手教你离线安装 nvidia-docker以及docker (在线环境亦可)

• Docker容器中使用Nvidia GPU

安志合个人博客，版权所有 丨 如未注明，均为原创 丨 转载请注明转自：https://chegva.com/6572.html | ☆★★每天进步一点点,加油!★★☆ |