一、速览

入门

FlexFlow Train 是一个用来训练深度学习模型的框架。所谓深度学习模型，可以理解为一个需要大量计算才能学会识别图片、文字等内容的数学程序。当模型规模变大或数据量增加时，单块 GPU（图形处理器，擅长并行计算）会不够用，就需要多块 GPU 或几台机器一起干活。

传统做法下，工程师要手动决定把模型和数据拆成几份、怎么分配到不同 GPU 上，这就像规划一条从北京到上海的高速路线，既要考虑哪段路堵车、哪段能开快，还要不断调整。FlexFlow Train 的作用，就是自动帮你搜索出当前硬件条件下最高效的拆分和计算方式，省去人工试错的麻烦。

它解决的核心运维痛点是：在多 GPU 环境下，训练脚本往往因为并行策略不合理而跑得很慢，而手动优化又非常耗时。使用 FlexFlow Train 后，你只需要启动训练，框架会自动尝试不同的数据切分和模型切分方案，找到更快的执行顺序。

这个仓库目前只负责训练（train），推理（serve）相关功能已经拆分到了另一个仓库 flexflow-serve。如果你只是想用训练好的模型做在线服务，需要关注另一个项目。

二、安装

进阶 · 推荐细读

安装 FlexFlow Train 之前，你需要一台能联网的 Linux 服务器，推荐 Ubuntu 20.04 或 22.04。如果要用 GPU 训练，服务器上还需要有 NVIDIA 显卡，并提前装好 CUDA 11.7 或兼容版本。CUDA 是 NVIDIA 提供的 GPU 编程平台，可以把它理解成显卡的驱动程序扩展，没有它显卡就无法被深度学习框架调用。

最省事的安装方式是使用官方预打包的 Docker 镜像。Docker 是一种把软件打包成“集装箱”后随处可运行的工具，你不需要手动配置编译环境。官方提供了两个镜像：flexflow-cuda 对应 NVIDIA GPU，flexflow-hip_rocm 对应 AMD GPU。对于大多数 N 卡服务器，直接拉取 CUDA 镜像即可：

docker pull ghcr.io/flexflow/flexflow-cuda:latest

拉取完成后，可以用下面的命令启动一个容器并进入命令行，验证镜像是否可用：

docker run --gpus all -it ghcr.io/flexflow/flexflow-cuda:latest bash

如果你不想用 Docker，也可以从源码编译。这种方式需要你在服务器上提前安装 CMake、C++ 编译器、Python 3.10 以上版本以及 CUDA、cuDNN 等依赖。编译流程请参考仓库内的 INSTALL.md 文件，因为不同系统环境的依赖版本略有差异，不建议新手第一次就尝试源码安装。

建议优先使用 Docker 镜像，把宝贵的运维时间留给训练任务本身，而不是和编译错误纠缠。

三、核心用法

进阶 · 推荐细读

FlexFlow Train 的特点是尽量兼容已有的 PyTorch 或 TensorFlow Keras 代码。对于普通用户，你的训练脚本不需要完全重写，只需要做少量修改：把原来导入 PyTorch/Keras 的语句替换成 FlexFlow 对应的接口，再在训练开始前初始化并行策略搜索器即可。

具体修改方式可以参考官方文档和 examples 目录中的示例。核心思路是：FlexFlow 会先自动尝试不同的并行化方案，比如把模型按层切开、把数据分批同时计算，然后对比每种方案的训练速度，选择吞吐量更高的那个用于正式训练。

运行训练脚本时，你仍然使用 Python 命令。以常见的 MNIST 手写数字分类任务为例，可以这样启动：

python train.py -e 10 -b 128 -p 20 -ll:gpu 2

这条命令表示：训练 10 个 epoch（把整个数据集完整过 10 遍），每个迭代的全局批量大小为 128（一次处理 128 张图片），每 20 个迭代打印一次训练进度，使用 2 个 GPU 进行计算。

如果你暂时没有真实数据集，可以不设置 -d 参数，FlexFlow 会自动生成合成数据来验证训练流程是否正常。这在测试硬件配置和脚本连通性时非常有用，相当于先跑一个空包确认整个管道没有漏水。

四、配置：命令行参数详解

深入 · 老手可选

FlexFlow Train 把运行配置分成两类：一类是 FlexFlow 训练相关的参数，另一类是 Legion runtime 底层资源参数。Legion 是 FlexFlow 使用的并行执行引擎，负责把任务调度到不同 GPU 和 CPU 上，可以理解成训练任务的“交通调度中心”。

训练常用参数如下：

-e, --epochs        总训练轮数，默认 1
-b, --batch-size    每次迭代的全局批大小，默认 64
-p, --print-freq    每多少次迭代打印一次进度，默认 10
-d, --dataset       训练数据集路径；不设置则使用合成数据

资源调度参数以 -ll: 开头，常用选项包括：

-ll:gpu            每个节点上使用的 GPU 数量，默认 0
-ll:fsize          每块 GPU 的显存大小，单位 MB
-ll:zsize          每节点的 zero-copy 内存大小，单位 MB
-ll:cpu            数据加载 worker 数量，默认 4

其中 -ll:gpu 非常重要，默认值是 0，如果不显式指定，FlexFlow 不会启用 GPU 训练，而是退回 CPU 模式，速度会慢几个数量级。-ll:fsize 用来告诉框架每块 GPU 有多少显存可分配，设置过大会导致显存溢出，设置过小会浪费算力。

-ll:zsize 指定 zero-copy 内存的大小，这种内存允许 GPU 直接访问主机内存中的数据，主要用于从磁盘预取训练图片。如果这个值设置得太小，数据加载会成为瓶颈，GPU 会经常空转等数据。

一个相对完整的命令行示例如下：

python train.py \
  -e 20 \
  -b 256 \
  -p 50 \
  -d /data/imagenet/train \
  -ll:gpu 4 \
  -ll:fsize 16000 \
  -ll:zsize 8192 \
  -ll:cpu 8

这条命令会在 4 块 GPU 上训练，每块 GPU 分配 16GB 显存，使用 8 个 CPU worker 从 /data/imagenet/train 目录加载数据，每 50 个迭代打印一次进度。

五、运维场景与避坑指南

深入 · 老手可选

在真实运维环境中，大多数团队会用 Docker 来启动 FlexFlow 训练任务。这样做的好处是环境可复现，不同工程师在不同机器上跑出来的结果更容易对齐。假设你的数据集放在宿主机的 /data 目录，可以这样挂载进容器：

docker run --gpus all \
  -v /data:/data \
  -v $(pwd)/train.py:/workspace/train.py \
  -it ghcr.io/flexflow/flexflow-cuda:latest \
  python /workspace/train.py -e 5 -b 128 -ll:gpu 4 -d /data/dataset

上面的命令把宿主机 /data 目录映射到容器内的 /data，把当前目录下的 train.py 挂载到容器内，然后用容器里预装好的环境执行训练。--gpus all 表示允许容器使用宿主机上的所有 GPU。

常见的问题集中在以下几个方面：

• CUDA 版本不匹配：官方预打包的 CUDA 镜像要求宿主机已经安装 CUDA 11.7。如果宿主机驱动或 CUDA 版本过低，容器启动后可能报错找不到 GPU 或库文件不兼容。建议先用 nvidia-smi 检查宿主机驱动版本，再决定用哪个镜像。
• 忘记设置 -ll:gpu：默认 GPU 数量为 0，训练会直接落在 CPU 上，速度极慢。每次启动命令务必检查这个参数。
• 数据路径错误却训练正常：因为 FlexFlow 在未检测到数据集时会自动使用合成数据，所以如果 -d 路径写错，程序仍然能跑，但训练结果完全没有意义。建议在正式训练前先设置 -e 1 跑一个 epoch 并观察日志中的数据来源。
• zero-copy 内存不足：如果训练时 GPU 利用率忽高忽低，而且日志显示数据加载时间很长，可以尝试增大 -ll:zsize 和 -ll:cpu 两个参数，给数据预取更多缓冲空间。

注意：不要在同一台宿主机上同时用多个 Docker 容器争抢全部 GPU，否则会出现显存溢出或频繁 OOM 错误。建议通过 -ll:gpu 和 --gpus 精确分配资源。

项目信息

参考链接

• GitHub 仓库
• 项目主页

延伸阅读

想继续探索？这些同领域的教程可能也适合你：

• 「Python」中文使用教程
• 「AI_NovelGenerator」中文使用教程
• 「snipe-it」中文使用教程