FlagEmbedding 容器化部署详解从 Docker 镜像到 GPU 微调的完整路径【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbeddingFlagEmbedding 是一套面向文本嵌入Embedding把文本转成向量与重排序Reranker对候选结果精排的一站式工具包推理、微调、评估覆盖了 RAG 场景的完整链路。新同学拿到一台 GPU 服务器通常要手动装 torch、对 CUDA 版本、编 deepspeed环境经常折腾半天。我们用容器把这套流程固化成镜像让 FlagEmbedding 容器化部署变成一次性的构建、反复的复用。一、先把装环境这件事的痛苦摆出来torch 与 deepspeed 是最大的两个变量FlagEmbedding 的核心依赖 torch 必须与机器上的 CUDA 驱动匹配装错成 CPU 版torch.cuda.is_available()直接返回 False而 setup.py 中定义的[finetune]额外依赖deepspeed、flash-attn又要求针对特定 torch 版本安装差一个小版本就是一堆报错。手动装的顺序永远是 CUDA 相关库 → torch → 其余包每一步都可能卡住。把安装过程固化成镜像容器镜像打包了运行所需依赖、可直接启动的文件包本质上就是修好的环境存档把安装步骤写进 Dockerfile执行一次docker build之后任何机器拉取镜像即可运行。修复环境的成本从每台机器一次变成改 Dockerfile 重新构建一次。最小示例——宿主机上的两项前置检查# 宿主机 GPU 驱动是否可用应输出一张或多张卡的信息 nvidia-smi # 验证 Docker 能否把 GPU 透传进容器需宿主机已装 NVIDIA Container Toolkit docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi二、两种安装方式对应两种镜像先决定镜像装什么推理还是微调setup.py 把依赖分成两档pip install .满足推理与评估pip install .[finetune]额外引入 deepspeed 与 flash-attn服务训练。把全部依赖塞进同一个镜像推理服务会平白多出好几个 GB 的体积。我们的做法是拆成两枚推理镜像保持精简训练镜像单独构建FlagEmbedding Docker 镜像构建时按用途二选一。DockerfileCOPY 源码进镜像再安装# 基础镜像选 CUDA runtime 版自带 GPU 运行库容器内无需装驱动 FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04 WORKDIR /app # 先装系统依赖与 torchPyPI 默认版本即 CUDA 构建保证后续包对着正确的 torch 安装 RUN apt-get update apt-get install -y --no-install-recommends \ python3 python3-pip python3-venv \ ln -s /usr/bin/python3 /usr/bin/python \ pip3 install --no-cache-dir torch # 把本地源码拷入镜像并安装项目依赖训练镜像改为 .[finetune] COPY . . RUN pip3 install --no-cache-dir . # 指定模型缓存路径与宿主机挂载点保持一致避免重复下载权重 ENV HF_HUB_CACHE/root/.cache/huggingface/hub要点用COPY把构建上下文当前目录的源码带进镜像构建期不依赖网络克隆torch 必须在项目包之前安装否则后者可能拉入不匹配的 CPU 版 torch。三、构建镜像用一行命令验证 GPU构建并留意耗时# 构建推理镜像-f 指定 Dockerfile末尾的 . 表示构建上下文为当前目录 docker build -f Dockerfile -t flagembedding-infer:latest .首次构建需要拉取数 GB 的 CUDA 基础镜像并下载依赖耗时在十几分钟到半小时之间属正常现象。后续修改 Dockerfile 时缓存会自动复用不必每次全量重来。GPU 环境一行验证⚠️ 带 GPU 的镜像验收标准只有一条容器里nvidia-smi能看到卡且 torch 识别 CUDA。两条命令都通过才算交付# 容器内执行 nvidia-smi能回显卡列表说明 GPU 透传链路正常 docker run --rm --gpus all flagembedding-infer:latest nvidia-smi # 再确认 torch 是否可用 CUDA应打印 True docker run --rm --gpus all flagembedding-infer:latest \ python -c import torch; print(torch.cuda.is_available())如果第一条命令直接报错问题在宿主机侧Toolkit 未装或驱动过旧不必继续排查镜像本身。四、GPU 环境下跑通推理服务挂两样东西GPU 与模型缓存推理时模型权重从 HuggingFace Hub 下载到本地缓存。缓存目录不落盘的话每次起容器都要重新下载几个 GB 的权重。把宿主机目录挂进容器的缓存路径缓存就能跨容器、跨镜像复用# 挂载宿主机 HF 缓存目录并用 --gpus device0 只分配第一张卡 docker run --rm -it --gpus device0 \ -v $HOME/.cache/huggingface:/root/.cache/huggingface \ flagembedding-infer:latest容器里跑单卡推理示例仓库自带单卡推理脚本适合直接当容器验收用例它加载 bge-small-en-v1.5对两条 query 和两条 passage 计算余弦相似度末尾还附了期望输出供比对# 在容器内运行单卡推理示例仓库挂载到 /workspace 供脚本读取 docker run --rm --gpus device0 \ -v $HOME/.cache/huggingface:/root/.cache/huggingface \ -v $PWD:/workspace -w /workspace \ flagembedding-infer:latest \ python examples/inference/embedder/encoder_only/base_single_device.py输出数值与脚本内标注的期望值一致说明模型、CUDA、代码链路全部正常。更多推理 API 用法可参考 单卡推理示例 与 README 的 Quick Start 部分。五、微调任务进容器多卡与 DeepSpeed微调入口是一条 torchrun 命令examples/finetune/ 下的脚本本质是包装torchrun的 bash 文件。以 encoder_only/base.sh 为例它通过num_gpus控制卡数并引用 ds_stage0.json 作为 DeepSpeed 配置。进容器后脚本无需改动卡数分配交给环境变量# -e 传入可见 GPU 列表容器内 torchrun 只能看到这两张卡 -e CUDA_VISIBLE_DEVICES0,1挂好数据与输出目录一次跑通微调脚本里训练数据是相对路径../example_data/...相对脚本目录解析所以只需把仓库整体挂进容器输出目录单独挂载容器退出不丢 checkpoint# 在训练镜像内直接执行微调脚本挂载仓库、模型缓存与输出目录 docker run --rm -it --gpus all \ -e CUDA_VISIBLE_DEVICES0,1 \ -v $PWD:/workspace -w /workspace \ -v $HOME/.cache/huggingface:/root/.cache/huggingface \ -v $PWD/output:/workspace/output \ flagembedding-ft:latest \ bash examples/finetune/embedder/encoder_only/base.sh这个示例用的是仓库自带样例数据可以直接作为冒烟测试正式训练时把脚本中train_data换成自己的 jsonl 目录即可。六、生产环境调优与排障让镜像瘦身体积大头是 CUDA 基础镜像与 pip 缓存三个动作够用全程--no-cache-dir上方 Dockerfile 已包含apt 与 pip 放在同一条RUN里减少层数基础镜像选 runtime 而非 develdevel 附带完整编译工具链多占 5GB 以上。做完这些推理镜像主要由 torch 与 CUDA 运行库构成十几 GB 属正常区间。常见故障模式对照torch.cuda.is_available()为 Falsetorch 装成了 CPU 版或运行时漏了--gpus参数。微调启动即 OOM调小per_device_train_batch_size或确认gradient_checkpointing已开启示例脚本 中默认已开可直接改参数。模型反复下载、拉取慢宿主机的 HF 缓存没挂对路径挂载点必须与镜像内HF_HUB_CACHE指向的位置一致。训练镜像 import deepspeed 失败构建时用了基础安装需按pip install .[finetune]重新构建。部署前自检清单检查点命令 / 动作期望结果宿主机 GPUnvidia-smi卡列表正常GPU 透传docker run --rm --gpus all 镜像 nvidia-smi与宿主机一致torch 认卡容器内执行python -c import torch; print(torch.cuda.is_available())True模型缓存查看宿主机缓存目录权重已存在重启容器不重复下载微调卡数容器内echo $CUDA_VISIBLE_DEVICES与计划使用的卡一致仓库配套的 Tutorials 覆盖相似度指标、Faiss 索引、RAG 流水线等主题快速入门教程 可以当作镜像构建完成后的验收脚本跑一遍。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/14 16:20:55 · 阅读 1.2k FlagEmbedding 容器化部署详解：从 Docker 镜像到 GPU 微调的完整路径
FlagEmbedding 容器化部署详解从 Docker 镜像到 GPU 微调的完整路径【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbeddingFlagEmbedding 是一套面向文本嵌入Embedding把文本转成向量与重排序Reranker对候选结果精排的一站式工具包推理、微调、评估覆盖了 RAG 场景的完整链路。新同学拿到一台 GPU 服务器通常要手动装 torch、对 CUDA 版本、编 deepspeed环境经常折腾半天。我们用容器把这套流程固化成镜像让 FlagEmbedding 容器化部署变成一次性的构建、反复的复用。一、先把装环境这件事的痛苦摆出来torch 与 deepspeed 是最大的两个变量FlagEmbedding 的核心依赖 torch 必须与机器上的 CUDA 驱动匹配装错成 CPU 版torch.cuda.is_available()直接返回 False而 setup.py 中定义的[finetune]额外依赖deepspeed、flash-attn又要求针对特定 torch 版本安装差一个小版本就是一堆报错。手动装的顺序永远是 CUDA 相关库 → torch → 其余包每一步都可能卡住。把安装过程固化成镜像容器镜像打包了运行所需依赖、可直接启动的文件包本质上就是修好的环境存档把安装步骤写进 Dockerfile执行一次docker build之后任何机器拉取镜像即可运行。修复环境的成本从每台机器一次变成改 Dockerfile 重新构建一次。最小示例——宿主机上的两项前置检查# 宿主机 GPU 驱动是否可用应输出一张或多张卡的信息 nvidia-smi # 验证 Docker 能否把 GPU 透传进容器需宿主机已装 NVIDIA Container Toolkit docker run --rm --gpus all nvidia/cuda:12.1.1-base-ubuntu22.04 nvidia-smi二、两种安装方式对应两种镜像先决定镜像装什么推理还是微调setup.py 把依赖分成两档pip install .满足推理与评估pip install .[finetune]额外引入 deepspeed 与 flash-attn服务训练。把全部依赖塞进同一个镜像推理服务会平白多出好几个 GB 的体积。我们的做法是拆成两枚推理镜像保持精简训练镜像单独构建FlagEmbedding Docker 镜像构建时按用途二选一。DockerfileCOPY 源码进镜像再安装# 基础镜像选 CUDA runtime 版自带 GPU 运行库容器内无需装驱动 FROM nvidia/cuda:12.1.1-cudnn8-runtime-ubuntu22.04 WORKDIR /app # 先装系统依赖与 torchPyPI 默认版本即 CUDA 构建保证后续包对着正确的 torch 安装 RUN apt-get update apt-get install -y --no-install-recommends \ python3 python3-pip python3-venv \ ln -s /usr/bin/python3 /usr/bin/python \ pip3 install --no-cache-dir torch # 把本地源码拷入镜像并安装项目依赖训练镜像改为 .[finetune] COPY . . RUN pip3 install --no-cache-dir . # 指定模型缓存路径与宿主机挂载点保持一致避免重复下载权重 ENV HF_HUB_CACHE/root/.cache/huggingface/hub要点用COPY把构建上下文当前目录的源码带进镜像构建期不依赖网络克隆torch 必须在项目包之前安装否则后者可能拉入不匹配的 CPU 版 torch。三、构建镜像用一行命令验证 GPU构建并留意耗时# 构建推理镜像-f 指定 Dockerfile末尾的 . 表示构建上下文为当前目录 docker build -f Dockerfile -t flagembedding-infer:latest .首次构建需要拉取数 GB 的 CUDA 基础镜像并下载依赖耗时在十几分钟到半小时之间属正常现象。后续修改 Dockerfile 时缓存会自动复用不必每次全量重来。GPU 环境一行验证⚠️ 带 GPU 的镜像验收标准只有一条容器里nvidia-smi能看到卡且 torch 识别 CUDA。两条命令都通过才算交付# 容器内执行 nvidia-smi能回显卡列表说明 GPU 透传链路正常 docker run --rm --gpus all flagembedding-infer:latest nvidia-smi # 再确认 torch 是否可用 CUDA应打印 True docker run --rm --gpus all flagembedding-infer:latest \ python -c import torch; print(torch.cuda.is_available())如果第一条命令直接报错问题在宿主机侧Toolkit 未装或驱动过旧不必继续排查镜像本身。四、GPU 环境下跑通推理服务挂两样东西GPU 与模型缓存推理时模型权重从 HuggingFace Hub 下载到本地缓存。缓存目录不落盘的话每次起容器都要重新下载几个 GB 的权重。把宿主机目录挂进容器的缓存路径缓存就能跨容器、跨镜像复用# 挂载宿主机 HF 缓存目录并用 --gpus device0 只分配第一张卡 docker run --rm -it --gpus device0 \ -v $HOME/.cache/huggingface:/root/.cache/huggingface \ flagembedding-infer:latest容器里跑单卡推理示例仓库自带单卡推理脚本适合直接当容器验收用例它加载 bge-small-en-v1.5对两条 query 和两条 passage 计算余弦相似度末尾还附了期望输出供比对# 在容器内运行单卡推理示例仓库挂载到 /workspace 供脚本读取 docker run --rm --gpus device0 \ -v $HOME/.cache/huggingface:/root/.cache/huggingface \ -v $PWD:/workspace -w /workspace \ flagembedding-infer:latest \ python examples/inference/embedder/encoder_only/base_single_device.py输出数值与脚本内标注的期望值一致说明模型、CUDA、代码链路全部正常。更多推理 API 用法可参考 单卡推理示例 与 README 的 Quick Start 部分。五、微调任务进容器多卡与 DeepSpeed微调入口是一条 torchrun 命令examples/finetune/ 下的脚本本质是包装torchrun的 bash 文件。以 encoder_only/base.sh 为例它通过num_gpus控制卡数并引用 ds_stage0.json 作为 DeepSpeed 配置。进容器后脚本无需改动卡数分配交给环境变量# -e 传入可见 GPU 列表容器内 torchrun 只能看到这两张卡 -e CUDA_VISIBLE_DEVICES0,1挂好数据与输出目录一次跑通微调脚本里训练数据是相对路径../example_data/...相对脚本目录解析所以只需把仓库整体挂进容器输出目录单独挂载容器退出不丢 checkpoint# 在训练镜像内直接执行微调脚本挂载仓库、模型缓存与输出目录 docker run --rm -it --gpus all \ -e CUDA_VISIBLE_DEVICES0,1 \ -v $PWD:/workspace -w /workspace \ -v $HOME/.cache/huggingface:/root/.cache/huggingface \ -v $PWD/output:/workspace/output \ flagembedding-ft:latest \ bash examples/finetune/embedder/encoder_only/base.sh这个示例用的是仓库自带样例数据可以直接作为冒烟测试正式训练时把脚本中train_data换成自己的 jsonl 目录即可。六、生产环境调优与排障让镜像瘦身体积大头是 CUDA 基础镜像与 pip 缓存三个动作够用全程--no-cache-dir上方 Dockerfile 已包含apt 与 pip 放在同一条RUN里减少层数基础镜像选 runtime 而非 develdevel 附带完整编译工具链多占 5GB 以上。做完这些推理镜像主要由 torch 与 CUDA 运行库构成十几 GB 属正常区间。常见故障模式对照torch.cuda.is_available()为 Falsetorch 装成了 CPU 版或运行时漏了--gpus参数。微调启动即 OOM调小per_device_train_batch_size或确认gradient_checkpointing已开启示例脚本 中默认已开可直接改参数。模型反复下载、拉取慢宿主机的 HF 缓存没挂对路径挂载点必须与镜像内HF_HUB_CACHE指向的位置一致。训练镜像 import deepspeed 失败构建时用了基础安装需按pip install .[finetune]重新构建。部署前自检清单检查点命令 / 动作期望结果宿主机 GPUnvidia-smi卡列表正常GPU 透传docker run --rm --gpus all 镜像 nvidia-smi与宿主机一致torch 认卡容器内执行python -c import torch; print(torch.cuda.is_available())True模型缓存查看宿主机缓存目录权重已存在重启容器不重复下载微调卡数容器内echo $CUDA_VISIBLE_DEVICES与计划使用的卡一致仓库配套的 Tutorials 覆盖相似度指标、Faiss 索引、RAG 流水线等主题快速入门教程 可以当作镜像构建完成后的验收脚本跑一遍。【免费下载链接】FlagEmbeddingRetrieval and Retrieval-augmented LLMs项目地址: https://gitcode.com/GitHub_Trending/fl/FlagEmbedding创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考