一次搞定：vLLM 部署 bge-m3 + reranker 全踩坑记录（含 404 / connection refused 终极解决方案）

大家好我是舒一笑不秃头，喜欢写作和分享，更多精彩内容～

最近在用 vLLM 部署 BGE 向量模型（bge-m3）+ reranker（bge-reranker-v2-m3） ，做 RAG 检索增强。

本来以为就是两条 docker run，结果实际踩了一堆坑：

❌ connection refused
❌ embedding 接口 404
❌ model 不存在
❌ reranker 接口参数不对

这篇文章直接帮你 一次性填平所有坑，让你 10 分钟跑通。

🧱 一、整体架构

我们跑两个服务：

服务	端口	作用
bge-m3	8000	embedding
reranker	8001	重排

🐳 二、正确的 Docker 启动方式（非常关键）

✅ embedding 服务

lua 复制代码

docker run -d \
  --name bge-m3-vllm \
  --gpus all \
  -p 8000:8000 \
  -v /data/models_bge-m3/bge-m3:/model \
  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/vllm/vllm-openai:v0.9.2 \
  --host 0.0.0.0 \
  --port 8000 \
  --model /model \
  --served-model-name bge-m3 \
  --task embed \
  --api-key sk-xxx

✅ reranker 服务

lua 复制代码

docker run -d \
  --name bge-reranker-v2-m3 \
  --gpus all \
  -p 8001:8000 \
  -v /data/bge-reranker-v2-m3:/model \
  swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/vllm/vllm-openai:v0.9.2 \
  --host 0.0.0.0 \
  --port 8000 \
  --model /model \
  --served-model-name bge-reranker-v2-m3 \
  --task score \
  --api-key sk-xxx

⚠️ 三、最容易踩的 4 个大坑（重点！！！）

❌ 坑 1：connection refused

现象

vbnet 复制代码

curl: (7) Failed to connect ... port 8001

原因

服务还没 ready（最常见）
没监听 0.0.0.0
防火墙没开

解决

先用本机测：

bash 复制代码

curl http://127.0.0.1:8001/v1/models

再看日志：

复制代码

docker logs -f bge-reranker-v2-m3

必须看到：

复制代码

Application startup complete

❌ 坑 2：embedding 返回 404（你遇到的核心问题）

你的日志👇

bash 复制代码

embedding接口HTTP状态 : 404
baseUrl=http://IP:8000/v1/embeddings

❗核心原因

👉 baseUrl 写错了层级

你填的是：

bash 复制代码

http://IP:8000/v1/embeddings ❌

但很多系统会自动拼 /embeddings，最终变成：

bash 复制代码

/v1/embeddings/embeddings ❌

所以 404！

✅ 正确写法

ini 复制代码

baseUrl = http://IP:8000/v1

❌ 坑 3：模型名不一致（非常隐蔽）

你系统里用的是：

复制代码

bge-m3-vllm

但实际服务返回：

json 复制代码

"id": "bge-m3"

👉 这会直接导致：

模型找不到
接口异常

✅ 解决方案（二选一）

方案 A（推荐）

改平台：

ini 复制代码

modelName = bge-m3

方案 B（强制一致）

启动时加：

css 复制代码

--served-model-name bge-m3-vllm

❌ 坑 4：reranker 接口参数错误

你写的是：

json 复制代码

"query": "xxx"

但 /v1/score 要：

json 复制代码

"queries": "xxx"

✅ 正确写法

方法 1：用 score

arduino 复制代码

curl http://IP:8001/v1/score \
  -d '{
    "model": "bge-reranker-v2-m3",
    "queries": "什么是人工智能",
    "documents": ["AI是...", "机器学习是..."]
  }'

方法 2（推荐）：用 rerank

arduino 复制代码

curl http://IP:8001/v1/rerank \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "什么是人工智能",
    "documents": ["AI是...", "机器学习是..."]
  }'

🧪 四、最终验证（一定要做）

1️⃣ 看模型

bash 复制代码

curl http://127.0.0.1:8000/v1/models

2️⃣ 测 embedding

arduino 复制代码

curl http://127.0.0.1:8000/v1/embeddings \
  -d '{
    "model": "bge-m3",
    "input": "测试"
  }'

3️⃣ 测 reranker

arduino 复制代码

curl http://127.0.0.1:8001/v1/rerank \
  -d '{
    "model": "bge-reranker-v2-m3",
    "query": "什么是AI",
    "documents": ["AI是...", "机器学习是..."]
  }'

🧠 五、一句话总结（精华）

👉 你所有问题的本质就 3 个：

baseUrl 不要写到 /embeddings，只写 /v1
modelName 必须和 /v1/models 返回一致
reranker 接口参数要用 queries 或直接用 /rerank

🎯 六、进阶建议（加分项）

如果你做 RAG，推荐组合：

复制代码

bge-m3（向量） + reranker（重排）

流程：

erlang 复制代码

query → embedding → 向量检索 → rerank → LLM

效果会明显提升。

🚀 结尾

如果你也在用：

vLLM
BGE
RAG
向量数据库

这套组合是目前性价比极高的一套开源方案。