FlagEmbedding Docker 容器部署完整指南3 个阶段跑通镜像构建与 GPU 推理【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbeddingFlagEmbeddingBAAI 的 BGE 系列是目前检索与检索增强生成RAG场景下使用最广的开源嵌入/重排工具包之一。本文带你完成 FlagEmbedding 容器化部署的完整闭环从环境自检、Docker 镜像构建到 GPU 推理服务运行与微调训练最终得到一套可复现、可挂缓存、可调优的容器化环境。你将得到什么读完本文你的机器上会运行一个满足以下三点能力的flagembedding容器即插即用的推理环境容器内import FlagEmbedding即可加载bge-*嵌入与重排模型跑通官方推理示例可复现的微调环境直接执行仓库自带的torchrun训练脚本无需再装 DeepSpeed可缓存、可换卡、可限资源的运行配置模型缓存挂载到宿主机GPU 指定与资源限制一行参数搞定。容器在 RAG 链路中的位置如下——嵌入模型负责召回重排模型负责精排而你要做的就是把这两类能力封装进同一个镜像✅ 完成标志脑海中形成「宿主机 → 镜像 → 容器 → 挂载缓存」四层映射后续每一步都在填充这四层。部署前自检清单本阶段目标10 分钟确认机器满足要求避免构建到一半才发现缺依赖。检查项最低要求验证命令CPU / 内存8 核 / 16GB微调建议 16 核 / 32GBnproc free -hGPU1 块 NVIDIA GPU≥8GB 显存bge-large微调建议 16GBnvidia-smiDocker20.10docker versionNVIDIA Container Toolkit已安装--gpus all可用的前提docker run --rm --gpus all nvidia/cuda:11.8.0-base nvidia-smi模型仓库访问能连通 HuggingFace或已配置镜像缓存预下载一个bge-small模型试速度⚠️ 第二条验证命令是关键它同时验证了 Docker 和 NVIDIA Container Toolkit 两个组件。如果它跑不通后面所有--gpus参数都会直接报错。✅ 完成标志上表中「GPU 验证」命令能打印出显卡列表其余项全部通过。阶段一构建 FlagEmbedding Docker 镜像本阶段目标产出一个同时覆盖「推理 微调」两个用途的镜像。1.1 写 Dockerfile项目根目录没有requirements.txt依赖统一声明在 setup.pytorch、transformers4.44.2、datasets、sentence_transformers 等所以最稳的装法是直接pip install -e .让 setup.py 替你钉版本。把下面这份 Dockerfile 放在仓库任意空目录不要动仓库本身# 运行期基础镜像Ubuntu 22.04 CUDA 11.8兼顾体积与兼容性 FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04 WORKDIR /workspace # 系统依赖git 拉代码python3 跑推理 RUN apt-get update apt-get install -y --no-install-recommends \ git python3 python3-pip \ rm -rf /var/lib/apt/lists/* # 拉取项目源码内网构建可改为 COPY . . 去掉本行 RUN git clone https://gitcode.com/GitHub_Trending/fl/FlagEmbedding . # setup.py 声明的核心依赖 微调所需的 DeepSpeed # flash-attn 需编译环境不全时可省略不影响推理 RUN pip3 install --no-cache-dir -e . \ pip3 install --no-cache-dir deepspeed # 模型缓存集中到固定目录方便挂载卷复用 ENV HF_HOME/workspace/.cache/huggingface \ WANDB_MODEdisabled \ PYTHONPATH/workspace CMD [bash]三个关键决策对应 Dockerfile 里三处-e .而不是-r requirements.txt版本由 setup.py 统一维护未来升级项目只需重建镜像HF_HOME固定路径官方脚本如 examples/finetune/embedder/encoder_only/base.sh会读取HF_HUB_CACHE环境变量固定缓存路径后模型只下载一次deepspeed单独装它是 setup.py 中finetune附加依赖之一推理用户不装也完全没问题。1.2 构建并验证在项目根目录执行构建镜像名带上版本号方便多版本共存docker build -t flagembedding:1.4 . # 首次构建约 10~20 分钟接下来用最小脚本验证环境——容器内直接import并确认 GPU 可见docker run --gpus all -it --rm flagembedding:1.4 \ python -c import torch, FlagEmbedding; print(OK, torch.cuda.is_available()) # 期望输出OK True✅ 完成标志命令输出OK True说明镜像内 PyTorch、CUDA、FlagEmbedding 三者链路全部打通。阶段二运行 GPU 推理服务本阶段目标把官方推理示例放进容器跑通并让模型缓存在宿主机上持久化。2.1 挂载缓存启动容器-v参数把宿主机目录挂到容器的HF_HOME模型文件从此只下载一次docker run --gpus all -it --rm \ -v $PWD/hf_cache:/workspace/.cache/huggingface \ flagembedding:1.42.2 跑通官方嵌入推理示例容器内执行仓库自带的单卡推理示例examples/inference/embedder/encoder_only/base_single_device.py它加载bge-small-en-v1.5并对 query/passage 编码、计算余弦相似度python examples/inference/embedder/encoder_only/base_single_device.py看到脚本尾部打印的期望输出约[[0.7944 0.4492] ...]且与实际值吻合就说明推理链路正确。想要多卡仓库同样提供了base_multi_devices.py与 M3 系列的m3_*.py示例都在 examples/inference/embedder/encoder_only/ 目录下。2.3 跑通重排模型重排Reranker是 RAG 精排环节推理入口与嵌入不同参考 examples/inference/reranker/encoder_only/ 下的bge-reranker-v2示例python examples/inference/reranker/encoder_only/bge_reranker_v2.py✅ 完成标志嵌入与重排两个官方示例都在容器内跑通且hf_cache/目录在宿主机上生成了模型文件。阶段三容器内运行微调训练本阶段目标复用同一个镜像执行仓库自带的官方微调脚本验证训练链路。3.1 了解脚本在做什么官方脚本 examples/finetune/embedder/encoder_only/base.sh 做三件事用torchrun启动双卡进程、加载bge-large-en-v1.5、在retrieval/sts/classification/clustering四类示例数据上做对比学习微调并启用deepspeedstage0 与 fp16。这也是镜像里必须预装 deepspeed 的原因。3.2 启动训练容器微调比推理多吃两块资源共享内存和输出目录对应--shm-size与额外的-vdocker run --gpus all -it --rm \ --shm-size16g \ -v $PWD/hf_cache:/workspace/.cache/huggingface \ -v $PWD/output:/workspace/output \ flagembedding:1.4 \ bash examples/finetune/embedder/encoder_only/base.sh--shm-size16g是多卡torchrun的常见坑共享内存不足会导致 dataloader 随机挂掉。输出目录挂到宿主机后checkpoint 可直接取走部署。✅ 完成标志日志出现 loss 持续下降且./test_encoder_only_base_bge-large-en-v1.5/生成 checkpoint。生产级调优本阶段目标把「能跑」变成「跑得省」四个维度各给一条可直接用的手段。精度与显存FP16 半精度推理侧不想要 fp32 的显存开销时加载后直接转半精度即可无需任何参数from FlagEmbedding import FlagModel import os model FlagModel( BAAI/bge-large-en-v1.5, query_instruction_for_retrievalRepresent this sentence for searching relevant passages: , cache_diros.getenv(HF_HOME, None), ) model model.half() # 整个模型转 fp16显存约减半训练侧官方脚本已默认--fp16不需要额外配置。模型缓存只下载一次的三条命令宿主机预先拉好模型容器内复用避免每次冷启动都走网络# 1. 宿主机预下载任意有 Python 环境的机器 python -c from huggingface_hub import snapshot_download; snapshot_download(BAAI/bge-large-en-v1.5, cache_dir./hf_cache) # 2. 容器运行时挂载见阶段二 2.1 # -v $PWD/hf_cache:/workspace/.cache/huggingface # 3. 完全离线环境挂载后加 --network none验证零网络依赖批处理与 GPU 分配限制指定卡--gpus all改为--gpus device0多卡机器上把大模型固定到特定卡批大小微调时改 base.sh 中的per_device_train_batch_size默认 2是测试值显存充裕时调到 8~16--gradient_checkpointing已默认开启两者配合可再压 20% 显存并发容器本身无状态同一镜像起 N 个容器各挂一份只读缓存即可水平扩展。资源限制给容器加上 CPU/内存硬顶防止批量编码任务拖垮宿主机docker run --gpus device0 -it --rm \ --cpus8 \ --memory16g \ -v $PWD/hf_cache:/workspace/.cache/huggingface \ flagembedding:1.4✅ 完成标志nvidia-smi里看到的显存占用与 CPU 占用均不超过你设定的上限且推理/训练结果与不设限时一致。高频排障本阶段目标覆盖 80% 实际会踩的坑每条给「现象 → 定位 → 解法」。Q1容器内torch.cuda.is_available()为 False或--gpus all直接报错定位宿主机 NVIDIA Container Toolkit 未装或 Docker 未重载。解法安装 toolkit 后sudo systemctl restart docker用「部署前自检清单」里的nvidia/cuda:11.8.0-base nvidia-smi命令复验。这是全部 GPU 问题中占比最高的一条。Q2微调时训练进程随机崩溃报RuntimeError: ... shared memory或 segfault解法加--shm-size16g阶段三 3.2 已覆盖仍崩溃则调小per_device_train_batch_size脚本中--gradient_checkpointing保持开启。Q3镜像构建到pip install deepspeed或 flash-attn 时编译失败定位运行期基础镜像缺少编译链。解法纯推理场景直接从 Dockerfile 删掉 deepspeed 安装行镜像更小、构建更快需要微调时改用nvidia/cuda:*-devel镜像或预装好工具的私有基础镜像。Q4模型下载极慢导致容器首跑卡住解法按「生产级调优」中的三步预下载流程把模型放进hf_cache/再挂载进容器彻底离线时可加--network none做验收测试。✅ 完成标志四条问答对应的命令你都能在 30 秒内复述出修复动作。继续深入本阶段目标给出容器跑起来之后的「下一步学习地图」全部指向仓库内真实路径。官方教程Tutorials/ 覆盖从嵌入基础、MTEB/BEIR 评估、Faiss 索引到 RAG 与微调的 7 大模块其中 Tutorials/7_Fine-tuning/7.1.2_Fine-tune.ipynb 与本文阶段三一一对应更多模型入口推理侧 FlagEmbedding/inference/ 提供FlagAutoModel/FlagAutoReranker自动路由支持 BGE-M3、ICL、Pseudo-MoE 等变体评估管线examples/evaluation/ 内置 MS MARCO、BEIR、MTEB、MIRACL 等基准脚本镜像不改动换一条bash命令即可在容器内跑评估回归测试tests/test_infer_embedder_basic.py 可作为镜像验收脚本每次重建镜像后跑一遍即可确认环境未漂移中文文档README_zh.md 与 docs/ 目录提供完整的中文说明。容器视角下的仓库模块分布可作为你规划「哪些目录进镜像、哪些目录挂卷」的参照✅ 完成标志你能指出任意一个官方示例脚本在容器里的绝对路径如/workspace/examples/finetune/...。下一步建议先用bge-small-en-v1.5按阶段一到阶段二走一遍最小编码链路全程约 30 分钟确认缓存挂载与 GPU 分配无误后再在同一镜像中把 base.sh 的--model_name_or_path换成你的业务模型开跑微调——这一条链路打通你就拥有了可版本化、可交接的 FlagEmbedding 容器化环境。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 FlagEmbedding Docker 容器部署完整指南：3 个阶段跑通镜像构建与 GPU 推理
FlagEmbedding Docker 容器部署完整指南3 个阶段跑通镜像构建与 GPU 推理【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbeddingFlagEmbeddingBAAI 的 BGE 系列是目前检索与检索增强生成RAG场景下使用最广的开源嵌入/重排工具包之一。本文带你完成 FlagEmbedding 容器化部署的完整闭环从环境自检、Docker 镜像构建到 GPU 推理服务运行与微调训练最终得到一套可复现、可挂缓存、可调优的容器化环境。你将得到什么读完本文你的机器上会运行一个满足以下三点能力的flagembedding容器即插即用的推理环境容器内import FlagEmbedding即可加载bge-*嵌入与重排模型跑通官方推理示例可复现的微调环境直接执行仓库自带的torchrun训练脚本无需再装 DeepSpeed可缓存、可换卡、可限资源的运行配置模型缓存挂载到宿主机GPU 指定与资源限制一行参数搞定。容器在 RAG 链路中的位置如下——嵌入模型负责召回重排模型负责精排而你要做的就是把这两类能力封装进同一个镜像✅ 完成标志脑海中形成「宿主机 → 镜像 → 容器 → 挂载缓存」四层映射后续每一步都在填充这四层。部署前自检清单本阶段目标10 分钟确认机器满足要求避免构建到一半才发现缺依赖。检查项最低要求验证命令CPU / 内存8 核 / 16GB微调建议 16 核 / 32GBnproc free -hGPU1 块 NVIDIA GPU≥8GB 显存bge-large微调建议 16GBnvidia-smiDocker20.10docker versionNVIDIA Container Toolkit已安装--gpus all可用的前提docker run --rm --gpus all nvidia/cuda:11.8.0-base nvidia-smi模型仓库访问能连通 HuggingFace或已配置镜像缓存预下载一个bge-small模型试速度⚠️ 第二条验证命令是关键它同时验证了 Docker 和 NVIDIA Container Toolkit 两个组件。如果它跑不通后面所有--gpus参数都会直接报错。✅ 完成标志上表中「GPU 验证」命令能打印出显卡列表其余项全部通过。阶段一构建 FlagEmbedding Docker 镜像本阶段目标产出一个同时覆盖「推理 微调」两个用途的镜像。1.1 写 Dockerfile项目根目录没有requirements.txt依赖统一声明在 setup.pytorch、transformers4.44.2、datasets、sentence_transformers 等所以最稳的装法是直接pip install -e .让 setup.py 替你钉版本。把下面这份 Dockerfile 放在仓库任意空目录不要动仓库本身# 运行期基础镜像Ubuntu 22.04 CUDA 11.8兼顾体积与兼容性 FROM nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04 WORKDIR /workspace # 系统依赖git 拉代码python3 跑推理 RUN apt-get update apt-get install -y --no-install-recommends \ git python3 python3-pip \ rm -rf /var/lib/apt/lists/* # 拉取项目源码内网构建可改为 COPY . . 去掉本行 RUN git clone https://gitcode.com/GitHub_Trending/fl/FlagEmbedding . # setup.py 声明的核心依赖 微调所需的 DeepSpeed # flash-attn 需编译环境不全时可省略不影响推理 RUN pip3 install --no-cache-dir -e . \ pip3 install --no-cache-dir deepspeed # 模型缓存集中到固定目录方便挂载卷复用 ENV HF_HOME/workspace/.cache/huggingface \ WANDB_MODEdisabled \ PYTHONPATH/workspace CMD [bash]三个关键决策对应 Dockerfile 里三处-e .而不是-r requirements.txt版本由 setup.py 统一维护未来升级项目只需重建镜像HF_HOME固定路径官方脚本如 examples/finetune/embedder/encoder_only/base.sh会读取HF_HUB_CACHE环境变量固定缓存路径后模型只下载一次deepspeed单独装它是 setup.py 中finetune附加依赖之一推理用户不装也完全没问题。1.2 构建并验证在项目根目录执行构建镜像名带上版本号方便多版本共存docker build -t flagembedding:1.4 . # 首次构建约 10~20 分钟接下来用最小脚本验证环境——容器内直接import并确认 GPU 可见docker run --gpus all -it --rm flagembedding:1.4 \ python -c import torch, FlagEmbedding; print(OK, torch.cuda.is_available()) # 期望输出OK True✅ 完成标志命令输出OK True说明镜像内 PyTorch、CUDA、FlagEmbedding 三者链路全部打通。阶段二运行 GPU 推理服务本阶段目标把官方推理示例放进容器跑通并让模型缓存在宿主机上持久化。2.1 挂载缓存启动容器-v参数把宿主机目录挂到容器的HF_HOME模型文件从此只下载一次docker run --gpus all -it --rm \ -v $PWD/hf_cache:/workspace/.cache/huggingface \ flagembedding:1.42.2 跑通官方嵌入推理示例容器内执行仓库自带的单卡推理示例examples/inference/embedder/encoder_only/base_single_device.py它加载bge-small-en-v1.5并对 query/passage 编码、计算余弦相似度python examples/inference/embedder/encoder_only/base_single_device.py看到脚本尾部打印的期望输出约[[0.7944 0.4492] ...]且与实际值吻合就说明推理链路正确。想要多卡仓库同样提供了base_multi_devices.py与 M3 系列的m3_*.py示例都在 examples/inference/embedder/encoder_only/ 目录下。2.3 跑通重排模型重排Reranker是 RAG 精排环节推理入口与嵌入不同参考 examples/inference/reranker/encoder_only/ 下的bge-reranker-v2示例python examples/inference/reranker/encoder_only/bge_reranker_v2.py✅ 完成标志嵌入与重排两个官方示例都在容器内跑通且hf_cache/目录在宿主机上生成了模型文件。阶段三容器内运行微调训练本阶段目标复用同一个镜像执行仓库自带的官方微调脚本验证训练链路。3.1 了解脚本在做什么官方脚本 examples/finetune/embedder/encoder_only/base.sh 做三件事用torchrun启动双卡进程、加载bge-large-en-v1.5、在retrieval/sts/classification/clustering四类示例数据上做对比学习微调并启用deepspeedstage0 与 fp16。这也是镜像里必须预装 deepspeed 的原因。3.2 启动训练容器微调比推理多吃两块资源共享内存和输出目录对应--shm-size与额外的-vdocker run --gpus all -it --rm \ --shm-size16g \ -v $PWD/hf_cache:/workspace/.cache/huggingface \ -v $PWD/output:/workspace/output \ flagembedding:1.4 \ bash examples/finetune/embedder/encoder_only/base.sh--shm-size16g是多卡torchrun的常见坑共享内存不足会导致 dataloader 随机挂掉。输出目录挂到宿主机后checkpoint 可直接取走部署。✅ 完成标志日志出现 loss 持续下降且./test_encoder_only_base_bge-large-en-v1.5/生成 checkpoint。生产级调优本阶段目标把「能跑」变成「跑得省」四个维度各给一条可直接用的手段。精度与显存FP16 半精度推理侧不想要 fp32 的显存开销时加载后直接转半精度即可无需任何参数from FlagEmbedding import FlagModel import os model FlagModel( BAAI/bge-large-en-v1.5, query_instruction_for_retrievalRepresent this sentence for searching relevant passages: , cache_diros.getenv(HF_HOME, None), ) model model.half() # 整个模型转 fp16显存约减半训练侧官方脚本已默认--fp16不需要额外配置。模型缓存只下载一次的三条命令宿主机预先拉好模型容器内复用避免每次冷启动都走网络# 1. 宿主机预下载任意有 Python 环境的机器 python -c from huggingface_hub import snapshot_download; snapshot_download(BAAI/bge-large-en-v1.5, cache_dir./hf_cache) # 2. 容器运行时挂载见阶段二 2.1 # -v $PWD/hf_cache:/workspace/.cache/huggingface # 3. 完全离线环境挂载后加 --network none验证零网络依赖批处理与 GPU 分配限制指定卡--gpus all改为--gpus device0多卡机器上把大模型固定到特定卡批大小微调时改 base.sh 中的per_device_train_batch_size默认 2是测试值显存充裕时调到 8~16--gradient_checkpointing已默认开启两者配合可再压 20% 显存并发容器本身无状态同一镜像起 N 个容器各挂一份只读缓存即可水平扩展。资源限制给容器加上 CPU/内存硬顶防止批量编码任务拖垮宿主机docker run --gpus device0 -it --rm \ --cpus8 \ --memory16g \ -v $PWD/hf_cache:/workspace/.cache/huggingface \ flagembedding:1.4✅ 完成标志nvidia-smi里看到的显存占用与 CPU 占用均不超过你设定的上限且推理/训练结果与不设限时一致。高频排障本阶段目标覆盖 80% 实际会踩的坑每条给「现象 → 定位 → 解法」。Q1容器内torch.cuda.is_available()为 False或--gpus all直接报错定位宿主机 NVIDIA Container Toolkit 未装或 Docker 未重载。解法安装 toolkit 后sudo systemctl restart docker用「部署前自检清单」里的nvidia/cuda:11.8.0-base nvidia-smi命令复验。这是全部 GPU 问题中占比最高的一条。Q2微调时训练进程随机崩溃报RuntimeError: ... shared memory或 segfault解法加--shm-size16g阶段三 3.2 已覆盖仍崩溃则调小per_device_train_batch_size脚本中--gradient_checkpointing保持开启。Q3镜像构建到pip install deepspeed或 flash-attn 时编译失败定位运行期基础镜像缺少编译链。解法纯推理场景直接从 Dockerfile 删掉 deepspeed 安装行镜像更小、构建更快需要微调时改用nvidia/cuda:*-devel镜像或预装好工具的私有基础镜像。Q4模型下载极慢导致容器首跑卡住解法按「生产级调优」中的三步预下载流程把模型放进hf_cache/再挂载进容器彻底离线时可加--network none做验收测试。✅ 完成标志四条问答对应的命令你都能在 30 秒内复述出修复动作。继续深入本阶段目标给出容器跑起来之后的「下一步学习地图」全部指向仓库内真实路径。官方教程Tutorials/ 覆盖从嵌入基础、MTEB/BEIR 评估、Faiss 索引到 RAG 与微调的 7 大模块其中 Tutorials/7_Fine-tuning/7.1.2_Fine-tune.ipynb 与本文阶段三一一对应更多模型入口推理侧 FlagEmbedding/inference/ 提供FlagAutoModel/FlagAutoReranker自动路由支持 BGE-M3、ICL、Pseudo-MoE 等变体评估管线examples/evaluation/ 内置 MS MARCO、BEIR、MTEB、MIRACL 等基准脚本镜像不改动换一条bash命令即可在容器内跑评估回归测试tests/test_infer_embedder_basic.py 可作为镜像验收脚本每次重建镜像后跑一遍即可确认环境未漂移中文文档README_zh.md 与 docs/ 目录提供完整的中文说明。容器视角下的仓库模块分布可作为你规划「哪些目录进镜像、哪些目录挂卷」的参照✅ 完成标志你能指出任意一个官方示例脚本在容器里的绝对路径如/workspace/examples/finetune/...。下一步建议先用bge-small-en-v1.5按阶段一到阶段二走一遍最小编码链路全程约 30 分钟确认缓存挂载与 GPU 分配无误后再在同一镜像中把 base.sh 的--model_name_or_path换成你的业务模型开跑微调——这一条链路打通你就拥有了可版本化、可交接的 FlagEmbedding 容器化环境。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考