简介这份PDF面向零基础开发者与研究人员讲解如何用Docker与vLLM在本地部署BGE-M3文本嵌入模型。BGE-M3由北京智源人工智能研究院推出支持稠密、稀疏与多向量三种检索模式适用于跨语言语义匹配与信息检索。资源围绕容器化环境搭建、vLLM高效推理框架配置、GPU与共享内存参数设置展开并给出从modelscope下载模型、运行OpenAI兼容服务的完整脚本最后通过LangChain完成文档加载、切分、向量存储与相似度查询的测试。压缩包仅1个PDF文件约1.35MB内容紧凑涵盖Docker安装、镜像源配置、vLLM镜像使用及文本嵌入验证等关键环节。已有644人学习适合希望快速验证BGE-M3能力、将其集成到本地NLP pipeline或关注隐私保护、定制化与成本可控的读者参考同时提醒注意脚本细节调整与识别误差。1. 为什么要在本地用 Docker vLLM 跑 BGE-M3如果你正在做 RAG、语义检索或者知识库问答大概率绕不开文本嵌入模型。BGE-M3 是目前中文场景里综合表现很稳的一个多语言嵌入模型支持稠密、稀疏、多向量三种检索方式长文本能吃到 8192 token。但真到落地的时候很多人卡在第一步模型怎么跑起来、怎么稳定对外提供 HTTP 接口、怎么和业务代码解耦。我见过太多团队直接用 transformers 写个 Flask 服务结果并发一上来就崩显存管理一塌糊涂。用 Docker 把运行环境封起来再用 vLLM 做推理后端是目前比较省心的组合。vLLM 的 PagedAttention 和连续批处理能把吞吐拉起来Docker 保证换台机器也能复现。这篇笔记就是把这个组合从零跑通的完整路径包括镜像怎么选、参数怎么调、接口怎么测、坑在哪。适合有基本 Linux 命令基础、想自己搭一套嵌入服务的工程师新手照着敲也能跑通。2. 环境准备Docker 与 vLLM 镜像选型2.1 为什么不用 pip 直接装 vLLM先说一个血泪经验vLLM 对 torch、CUDA、Python 版本极其敏感。你在宿主机上 pip install vllm很可能把已经装好的 torch 版本改掉导致其他项目直接跑不起来。热搜词里「安装vllm会改变已经安装好的torch」就是这个坑。Docker 的核心价值在这里就体现出来了——把 vLLM 和它的依赖全部锁在容器里宿主机环境一点不动。另一个原因是驱动兼容。vLLM 官方镜像已经预编译好了对应 CUDA 版本的 kernel你只需要宿主机装好 NVIDIA 驱动和 nvidia-container-toolkit容器里就能直接用 GPU。自己 pip 装的话还得折腾 flash-attn 编译没个半小时下不来。2.2 安装 Docker 与 NVIDIA Container ToolkitUbuntu 下安装 Docker 的常见做法# 卸载旧版本避免冲突 sudo apt-get remove docker docker-engine docker.io containerd runc # 安装依赖 sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg # 添加 Docker 官方 GPG key sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \ sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg # 添加仓库 echo deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null # 安装 Docker Engine sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin # 把当前用户加入 docker 组避免每次 sudo sudo usermod -aG docker $USER newgrp docker装完 Docker 后还需要装 NVIDIA Container Toolkit否则容器里看不到 GPU# 添加 NVIDIA 容器工具仓库 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 sudo apt-get update sudo apt-get install -y nvidia-container-toolkit sudo nvidia-ctk runtime configure --runtimedocker sudo systemctl restart docker验证 GPU 是否能在容器里用docker run --rm --gpus all nvidia/cuda:12.1.0-base-ubuntu22.04 nvidia-smi能打印出显卡信息就说明通了。如果报permission denied while trying to connect to the Docker API说明当前用户没在 docker 组里重新登录或者执行newgrp docker即可。2.3 vLLM 镜像版本怎么选vLLM 官方在 Docker Hub 上维护了vllm/vllm-openai镜像直接用它最省事。选版本时注意两点一是 CUDA 版本要和宿主机驱动匹配驱动版本 525 以上基本能跑 CUDA 12.1二是镜像 tag 里的 vLLM 版本建议选近几个月的稳定版太老的版本对 BGE-M3 的支持可能不完整。拉镜像docker pull vllm/vllm-openai:latest如果国内拉取慢可以配置镜像加速器在/etc/docker/daemon.json里加 registry-mirrors然后sudo systemctl restart docker。这一步不是必须的但能省不少等待时间。3. 用 vLLM 拉起 BGE-M3 服务3.1 模型下载与目录规划BGE-M3 在 Hugging Face 上的模型 ID 是BAAI/bge-m3。有两种方式拿到模型文件一是让容器启动时自动从 HF 下载二是提前下载到宿主机再挂载进容器。生产环境我一般选第二种因为容器重启不用重新下载也方便做版本管理。提前下载可以用 huggingface-clipip install -U huggingface_hub export HF_ENDPOINThttps://hf-mirror.com # 国内加速可选 huggingface-cli download BAAI/bge-m3 \ --local-dir /data/models/bge-m3 \ --local-dir-use-symlinks False下载完检查一下目录应该有config.json、pytorch_model.bin或 safetensors、tokenizer.json这些文件。模型大小大概 2.2GB 左右FP16 精度。3.2 启动命令与关键参数vLLM 从某个版本开始支持 embedding 模型启动时要加--task embed。完整命令docker run -d --name bge-m3-server \ --gpus all \ --shm-size 8g \ -p 8000:8000 \ -v /data/models/bge-m3:/models/bge-m3 \ vllm/vllm-openai:latest \ --model /models/bge-m3 \ --task embed \ --dtype float16 \ --max-model-len 8192 \ --gpu-memory-utilization 0.85 \ --port 8000 \ --served-model-name bge-m3逐个说参数含义--gpus all把宿主机所有 GPU 暴露给容器。如果只想用某几张卡用--gpus device0,1。--shm-size 8g共享内存大小。vLLM 多进程通信会用到默认 64MB 太小容易报错。-v把宿主机模型目录挂进容器避免重复下载。--task embed告诉 vLLM 这是嵌入模型不是生成模型。不加这个参数会按生成模型加载直接报错。--dtype float16推理精度。BGE-M3 用 FP16 就够了显存紧张可以试bfloat16但老卡可能不支持。--max-model-len 8192最大序列长度。BGE-M3 支持 8192但设太大显存占用高按业务实际文本长度调。一般检索场景 512 或 1024 就够。--gpu-memory-utilization 0.85GPU 显存使用上限比例。留 15% 给其他进程避免 OOM。--served-model-name bge-m3对外暴露的模型名调用时要对应。启动后看日志确认docker logs -f bge-m3-server看到Application startup complete和Uvicorn running on http://0.0.0.0:8000就说明起来了。如果卡在加载模型或者报 CUDA 错误往下看避坑章节。3.3 接口调用与返回结构vLLM 的 embedding 接口兼容 OpenAI 格式路径是/v1/embeddings。用 curl 测一下curl http://localhost:8000/v1/embeddings \ -H Content-Type: application/json \ -d { model: bge-m3, input: [什么是文本嵌入, BGE-M3 支持多语言] }返回结构里data数组每项有embedding字段是一个 1024 维的浮点数组。注意 BGE-M3 的稠密向量维度是 1024不是 768。如果你之前用别的模型建过索引维度对不上会直接报错这点要提前确认。Python 调用示例import requests def get_embeddings(texts, urlhttp://localhost:8000/v1/embeddings): resp requests.post(url, json{ model: bge-m3, input: texts }, timeout30) resp.raise_for_status() data resp.json() # 按 index 排序保证和输入顺序一致 items sorted(data[data], keylambda x: x[index]) return [item[embedding] for item in items] vecs get_embeddings([测试文本一, 测试文本二]) print(len(vecs), len(vecs[0])) # 2 1024这里有个细节批量请求时返回的index字段不一定和输入顺序一致尤其是并发高的时候。稳妥做法是按index排序后再用。另外input可以传字符串数组也可以传 token 数组但传 token 数组需要自己处理 padding一般不建议。4. 性能调优与批量推理参数4.1 批处理大小与吞吐的关系vLLM 的核心优势是连续批处理但 embedding 模型和生成模型的调度逻辑不太一样。embedding 请求通常是「来一批文本返回一批向量」没有自回归解码过程所以吞吐主要受限于 GPU 计算和显存带宽。实测下来单张 A100 80G 跑 BGE-M3--max-model-len 512时batch size 开到 64 左右吞吐比较理想再往上收益递减。消费级卡比如 4090 24Gbatch size 建议控制在 16 到 32 之间具体看文本长度。vLLM 启动时有个--max-num-seqs参数控制并发序列数默认 256。embedding 场景可以适当调低到 64 或 128减少显存碎片。这个参数不是越大越好设太大反而会因为调度开销导致延迟上升。4.2 长文本处理的截断策略BGE-M3 虽然支持 8192 token但实际业务里超过 512 token 的文本占比通常不高。如果无脑把--max-model-len设成 8192vLLM 会按最大长度预分配 KV cache显存浪费严重。我的做法是分两档主服务设--max-model-len 1024覆盖绝大多数请求超长文本单独走一个--max-model-len 8192的实例或者在上游做切分。切分时注意不要从句子中间断开按标点或段落切否则嵌入质量会下降。如果请求文本超过max-model-lenvLLM 默认会报错而不是截断。可以在客户端做长度检查from transformers import AutoTokenizer tokenizer AutoTokenizer.from_pretrained(/data/models/bge-m3) def safe_truncate(text, max_tokens1024): ids tokenizer.encode(text, add_special_tokensFalse) if len(ids) max_tokens: return text # 截断后解码可能有乱码但比报错好 return tokenizer.decode(ids[:max_tokens], skip_special_tokensTrue)4.3 显存不够时的降级方案显存不够是最常见的问题。几个降级方向一是降--gpu-memory-utilization但降太低会导致 vLLM 无法分配 KV cache 直接启动失败二是降--max-model-len这个最有效三是用--dtype bfloat16替代 float16显存占用一样但数值稳定性更好四是量化vLLM 支持 AWQ 和 GPTQ但 BGE-M3 的量化版本需要自己转不是所有版本都现成。如果只有 8G 显存建议--max-model-len 512、--gpu-memory-utilization 0.9、--max-num-seqs 32这样能跑起来但吞吐有限。真要上量还是得换卡或者多卡。5. 避坑与常见问题排查5.1 容器启动报 CUDA out of memory现象容器日志里出现torch.cuda.OutOfMemoryError服务起不来。原因--gpu-memory-utilization设太高或者--max-model-len太大导致 KV cache 预分配超出显存。解决先把--max-model-len降到 512--gpu-memory-utilization降到 0.8确认能起来后再逐步往上加。另外检查是不是有其他进程占着 GPUnvidia-smi看一眼。5.2 请求返回 400 错误说 model not found现象curl 调用时返回{error: The model xxx does not exist}。原因请求体里的model字段和启动时的--served-model-name不一致。解决要么请求里用启动时指定的名字要么启动时不加--served-model-namevLLM 会用模型路径作为默认名。建议显式指定避免路径变化导致调用方要改代码。5.3 批量请求时向量顺序错乱现象传了 10 条文本返回的向量和输入对不上。原因vLLM 内部并发处理返回的index字段才是真实顺序直接按数组下标取会错。解决如 3.3 节代码所示按index排序后再返回。这个坑很隐蔽单条测试时发现不了批量时才暴露。5.4 容器重启后模型重新下载现象每次docker restart都要等很久日志显示在下载模型。原因模型没有挂载到宿主机容器内下载的文件在容器删除后就没了。解决按 3.1 节提前下载到宿主机启动时用-v挂载。另外确认挂载路径和--model参数一致。5.5 多卡启动时只用到一张卡现象--gpus all启动了但nvidia-smi看只有一张卡在跑。原因vLLM 默认单卡推理多卡需要加--tensor-parallel-size参数。解决比如 2 张卡就加--tensor-parallel-size 2。注意 tensor parallel 要求卡数能整除注意力头数BGE-M3 一般 2 卡或 4 卡没问题。另外多卡通信走 NVLink 还是 PCIe 对性能影响很大PCIe 下加速比可能不到 1.5 倍。6. 进阶把嵌入服务接进检索链路服务跑起来只是第一步真正产生价值是接进检索链路。我一般会做三件事一是加一层缓存相同文本不重复请求二是做健康检查服务挂了能自动摘除三是把向量归一化方便用余弦相似度。缓存用 Redis 最简单key 用文本的 md5value 存向量序列化后的 bytes。注意缓存要设过期时间模型更新后旧向量就失效了。健康检查直接请求/health端点vLLM 自带这个接口返回 200 就是正常。向量归一化在客户端做import numpy as np def normalize(vec): arr np.array(vec, dtypenp.float32) norm np.linalg.norm(arr) if norm 0: return arr.tolist() return (arr / norm).tolist()归一化后内积就等于余弦相似度检索时用 FAISS 的IndexFlatIP就行比IndexFlatL2快一点。验证服务是否值得上生产我通常压测一轮用 1000 条真实业务文本并发 10看 P99 延迟和吞吐。A100 单卡、max-model-len 512 的情况下P99 大概在 50ms 以内吞吐能到 2000 token/s 以上。如果延迟超过 200ms先查是不是 batch size 太小或者网络往返开销大。最后说个习惯每次改完启动参数我都会把docker run命令存成一个start.sh脚本连同模型版本号一起记在 README 里。这样过三个月回头看能准确知道当时跑的是什么配置不用去翻聊天记录。这个习惯帮我省过好几次「后悔药」。希望帮到你。本文还有配套的精品资源点击获取