1. 为什么还要聊 tf.flags 这个老古董

如果你最近两三年才接触深度学习框架，大概率没怎么见过tf.flags。现在大家写配置要么用argparse，要么用Hydra、OmegaConf，再或者干脆上click、typer这类命令行工具。但只要你翻一翻 2018 到 2020 年之间的 TensorFlow 项目代码，尤其是那些经典的图像分类、目标检测、序列建模的官方示例，tf.flags出现的频率高得吓人。它本质上就是 TensorFlow 对 Python 标准库argparse的一层薄封装，把命令行参数解析、默认值管理、帮助信息生成这几件事打包成了一个FLAGS对象，让训练脚本可以同时支持“命令行传参”和“代码里直接改默认值”两种玩法。

我之所以想专门写一篇关于tf.flags的用法总结，是因为在实际维护老项目和做模型复现时，这个组件踩坑的概率远比想象中高。比如你从某个开源仓库 clone 下来一份代码，里面写着tf.app.flags.DEFINE_string('data_dir', '/tmp/data', 'path to dataset')，然后你在命令行里敲python train.py --data_dir=/my/data，结果发现程序读到的还是/tmp/data。又或者你在 Jupyter Notebook 里想临时改一个超参数，直接给FLAGS.learning_rate赋值，却发现怎么都不生效。这些问题的根源都在于tf.flags的解析时机、命名空间和默认值覆盖逻辑，跟很多人直觉里的argparse并不完全一样。

这篇文章适合三类人看：第一类是需要维护或复现早期 TensorFlow 项目的工程师，你得看懂这些DEFINE_xxx到底在干什么；第二类是想把自己手头脚本从tf.flags迁移到argparse或absl.flags的开发者，你需要知道哪些行为可以平滑替换、哪些地方会埋雷；第三类是对“配置管理”这件事本身感兴趣的人，tf.flags虽然老，但它对“默认值 + 命令行覆盖 + 代码内覆盖”这三层优先级的处理方式，放到今天依然有参考价值。下面我会从整体设计思路开始拆，然后逐层讲核心 API、实操流程、常见坑和迁移方案，尽量把每个“为什么”都讲透。

2. tf.flags 的整体设计与核心思路拆解

2.1 它到底解决了什么问题

在没有tf.flags之前，一个典型的训练脚本大概长这样：文件开头硬编码一堆路径和超参数，比如BATCH_SIZE = 32、LR = 0.001、DATA_DIR = './data'。想换个数据集？改代码。想调个学习率？改代码。想同时跑两组实验？复制一份文件改一改。这种做法在实验阶段极其低效，而且容易把不同实验的配置搞混。argparse当然能解决这个问题，但argparse的写法比较啰嗦：你要先创建parser = argparse.ArgumentParser()，然后一个个add_argument，最后parse_args()，再手动把结果塞进一个全局变量或者传给各个函数。tf.flags把这套流程压缩成了“定义即注册、解析即全局可用”的模式，写起来更短，读起来也更集中。

更关键的一点是，tf.flags的FLAGS对象是一个全局单例。你在文件 A 里DEFINE_integer('batch_size', 32, 'batch size')，在文件 B 里只要import了 TensorFlow 并拿到FLAGS，就能直接读FLAGS.batch_size。这种“一处定义、处处可读”的特性，对于那种由十几个模块拼起来的大型训练框架来说，确实省掉了大量参数传递的样板代码。你可以把它理解成一个“带命令行接口的全局配置字典”，只不过这个字典的键必须在程序启动时通过DEFINE_xxx注册好，不能随便新增。

2.2 三层优先级的覆盖逻辑

tf.flags最核心的设计，是它对参数来源的优先级处理。理解这三层优先级，基本就理解了这个库一半的行为。第一层是代码内默认值，也就是你在DEFINE_string、DEFINE_integer这些调用里写的第二个参数。第二层是命令行参数，也就是用户在终端里敲的--batch_size=64。第三层是代码内显式赋值，比如你在某个函数里写FLAGS.batch_size = 128。这三层的生效顺序并不是简单的“后来居上”，而是跟parse_flags的调用时机强相关。

默认情况下，tf.flags会在第一次访问FLAGS的某个属性时触发解析，把命令行参数合并进来。也就是说，如果你在parse_flags之前就手动给FLAGS.batch_size赋了值，那么命令行参数会覆盖掉你的赋值；反过来，如果你在parse_flags之后赋值，那么你的赋值会覆盖命令行参数。这个细节非常容易踩坑，尤其是在 Notebook 环境里，因为 Notebook 的代码执行顺序和脚本不一样，你很难保证“解析”到底发生在哪一步。我个人的经验是：永远不要在业务代码里依赖“赋值时机”这种隐式行为，要么统一走命令行，要么在解析完成后显式覆盖，并且加注释说明。

2.3 为什么它后来被弃用了

tf.flags在 TensorFlow 2.x 里被标记为弃用，官方推荐用absl.flags替代。原因主要有两个。第一，tf.flags和argparse的兼容性不好，如果你的项目里同时用了argparse和tf.flags，两者会争抢sys.argv，导致参数解析混乱。第二，tf.flags的全局单例设计在大型项目里会带来“隐式依赖”问题：一个函数读了FLAGS.xxx，但你在函数签名里完全看不出来它依赖这个配置，测试和重构都很麻烦。absl.flags虽然也是全局的，但它在解析行为、类型检查和帮助信息生成上更规范，而且不绑定 TensorFlow，所以适用范围更广。不过话说回来，理解tf.flags依然有价值，因为大量存量代码还在用它，而且它的设计思路——集中定义、全局读取、命令行覆盖——在很多配置管理方案里都能看到影子。

3. 核心 API 与参数定义细节解析

3.1 五种基础类型的定义方式

tf.flags提供了五种最常用的参数类型，分别是DEFINE_string、DEFINE_integer、DEFINE_float、DEFINE_boolean和DEFINE_enum。它们的函数签名基本一致：第一个参数是参数名，第二个是默认值，第三个是帮助信息，后面还可以跟一些可选参数比如flag_values（用于 enum）和required（是否必填）。下面这张表把五种类型的写法和取值示例列出来，方便你对照记忆。

这里有几个细节值得单独拎出来说。第一，DEFINE_boolean的命令行行为跟其他类型不一样。对于布尔参数，--use_gpu表示设为True，--nouse_gpu表示设为False，你也可以写--use_gpu=True或--use_gpu=False，但--use_gpu False这种带空格的写法是不行的，会被解析成两个独立的 token。第二，DEFINE_enum的默认值必须在flag_values列表里，否则会在定义时就报错。第三，所有DEFINE_xxx调用都会往一个全局注册表里写东西，如果你重复定义同一个参数名，后定义的会覆盖先定义的，而且不会报错，这一点非常危险，后面讲常见问题时会展开。

3.2 参数名的命名规范与访问方式

tf.flags对参数名的要求比较宽松，你可以用下划线、数字、字母，但建议统一用蛇形命名法（snake_case），比如learning_rate、num_epochs、data_dir。访问的时候直接通过FLAGS.参数名读取，比如FLAGS.learning_rate。这里有一个容易忽略的点：FLAGS对象在访问不存在的参数时会直接抛AttributeError，而不是返回None或默认值。这意味着你不能像用字典那样用FLAGS.get('xxx', default)，必须先确保参数已经定义过。在实际项目里，我习惯把所有DEFINE_xxx集中放在一个config.py或者脚本最开头，这样能一眼看出整个程序有哪些可配置项，避免“读到一半发现某个参数没定义”的尴尬。

另外，FLAGS对象支持FLAGS.__dict__或者FLAGS.flag_values_dict()来查看所有已定义的参数和当前值，调试的时候很好用。比如你在训练脚本里打印print(FLAGS.flag_values_dict())，就能看到所有参数的最终取值，快速确认命令行有没有生效。不过要注意，flag_values_dict()返回的是一个普通字典，修改它不会影响FLAGS本身，它只是快照。

3.3 解析时机的三种控制方式

tf.flags的参数解析并不是在DEFINE_xxx时发生的，而是在你第一次访问FLAGS属性、或者显式调用FLAGS(sys.argv)、tf.app.run()时发生的。这三种方式对应三种不同的使用场景。第一种是“懒解析”，也就是你不主动调用解析，直接读FLAGS.xxx，库会在背后自动解析一次sys.argv。这种方式在简单脚本里能用，但在 Notebook 或者被其他脚本 import 的场景下很容易出问题，因为sys.argv可能包含你不想要的参数。第二种是显式调用FLAGS(sys.argv)，把命令行参数传进去，解析完成后FLAGS就固定下来了。第三种是tf.app.run()，它内部会先解析参数，再调用你指定的main函数，这是官方示例里最常见的写法。

我个人的建议是：在脚本里永远用tf.app.run()或者显式FLAGS(sys.argv)，不要依赖懒解析。原因很简单，懒解析的触发点不明确，你可能在某个工具函数里读了一下FLAGS，结果解析提前发生了，后面再传命令行参数就不生效了。显式解析虽然多写一行，但行为可预测，调试起来也方便。

4. 实操流程与完整代码示例

4.1 最小可运行示例

先来看一个最基础的例子，把定义、解析、使用三个环节串起来。这个脚本模拟一个训练入口，支持通过命令行指定数据集路径、批次大小和学习率。

import tensorflow as tf # 定义参数 tf.app.flags.DEFINE_string('data_dir', '/tmp/data', '数据集根目录') tf.app.flags.DEFINE_integer('batch_size', 32, '训练批次大小') tf.app.flags.DEFINE_float('learning_rate', 0.001, '初始学习率') tf.app.flags.DEFINE_boolean('use_gpu', True, '是否使用 GPU 训练') FLAGS = tf.app.flags.FLAGS def main(_): print('data_dir =', FLAGS.data_dir) print('batch_size =', FLAGS.batch_size) print('learning_rate =', FLAGS.learning_rate) print('use_gpu =', FLAGS.use_gpu) if __name__ == '__main__': tf.app.run()

把这段代码保存成train_demo.py，然后在终端里跑python train_demo.py --batch_size=64 --learning_rate=0.01 --nouse_gpu，你会看到输出里batch_size变成 64，learning_rate变成 0.01，use_gpu变成False。如果不传任何参数，就会用定义时的默认值。这个流程看起来很简单，但里面有几个关键点：tf.app.run()会自动把sys.argv传给解析器，并且要求你的main函数接受一个参数（通常是_），否则会报类型错误。另外，FLAGS必须在DEFINE_xxx之后获取，顺序反了会拿不到新定义的参数。

4.2 多文件项目里的参数组织

真实项目里，参数定义往往分散在多个模块。比如数据加载模块定义data_dir和num_workers，模型模块定义hidden_size和num_layers，训练模块定义batch_size和learning_rate。这时候你需要保证所有DEFINE_xxx在解析之前都被执行到。常见的做法是在入口脚本里 import 所有相关模块，利用 import 的副作用完成参数注册。下面是一个简化的目录结构示例。

project/ main.py data/ loader.py model/ network.py train/ trainer.py

在loader.py里写tf.app.flags.DEFINE_string('data_dir', './data', '数据目录')，在network.py里写tf.app.flags.DEFINE_integer('hidden_size', 256, '隐藏层维度')，然后在main.py里依次 import 这些模块，最后调用tf.app.run()。这样所有参数都会在解析前注册好。这里有一个坑：如果你在某个模块里用了from tensorflow import flags然后flags.DEFINE_string(...)，效果是一样的，但要注意不要在不同模块里重复定义同名参数，否则后 import 的会覆盖先 import 的，而且没有任何警告。我一般会在项目里加一个检查脚本，把所有DEFINE_xxx的参数名收集起来，发现重复就报错，这样能提前拦住问题。

4.3 在 Notebook 里临时改参数的正确姿势

很多人会在 Jupyter Notebook 里做实验，想临时改一个参数又不想改代码。直接写FLAGS.batch_size = 64有时候生效有时候不生效，原因就是解析时机不确定。比较稳妥的做法是：在 Notebook 开头先显式调用一次解析，把sys.argv传进去（Notebook 里sys.argv通常只有内核路径，不会干扰），然后再赋值。示例代码如下。

import sys import tensorflow as tf tf.app.flags.DEFINE_integer('batch_size', 32, 'batch size') FLAGS = tf.app.flags.FLAGS # 显式解析，固定住命令行参数 FLAGS(sys.argv) # 现在赋值一定生效 FLAGS.batch_size = 64 print(FLAGS.batch_size) # 输出 64

如果你不调用FLAGS(sys.argv)，而是直接赋值，那么当你后面第一次读FLAGS.batch_size时，库可能会触发懒解析，用命令行参数（或者空参数）覆盖掉你的赋值。这个行为在 Notebook 里特别隐蔽，因为单元格的执行顺序和脚本不一样。我踩过好几次这个坑，后来养成了“Notebook 里先解析再赋值”的习惯，就再也没出过问题。

4.4 参数校验与默认值动态计算

tf.flags本身不提供参数校验钩子，你没法在定义时写一个validator函数。但你可以通过required=True强制某个参数必须由命令行提供，否则解析时报错。比如tf.app.flags.DEFINE_string('ckpt_path', None, 'checkpoint 路径', required=True)，这样如果用户不传--ckpt_path，程序启动就会失败。对于更复杂的校验，比如“batch_size必须是 2 的幂”，你只能在main函数开头手动检查，不满足就raise ValueError。默认值的动态计算也是类似，DEFINE_xxx的默认值只能是字面量，不能是表达式。如果你想让num_epochs根据dataset_size自动算，就得先定义dataset_size，然后在main里读出来再算，最后赋值给FLAGS.num_epochs。注意这个赋值必须发生在解析之后，否则会被命令行参数覆盖。

5. 常见问题与排查技巧实录

5.1 命令行参数不生效的四种原因

这是最高频的问题，我整理了一张排查表，按可能性从高到低排列。

其中“参数名拼写不一致”是最容易犯的错。比如你定义的是learning_rate，命令行写成了--learning-rate，tf.flags不会报错，而是直接忽略这个未知参数，然后继续用默认值。更坑的是，有些版本的tf.flags对未知参数是静默忽略的，你根本不知道哪里出了问题。我的习惯是每次改完参数定义，先在终端跑一次python train.py --help，看看帮助信息里列出的参数名和默认值对不对，这样能快速发现拼写问题。

5.2 布尔参数的坑：为什么--use_gpu False不生效

前面提过，布尔参数的命令行写法比较特殊。--use_gpu等价于--use_gpu=True，--nouse_gpu等价于--use_gpu=False。但如果你写--use_gpu False，解析器会把--use_gpu当成一个独立的 flag（值为True），然后把False当成一个位置参数，结果就是use_gpu变成了True，而False被丢进了未解析的参数列表里。这个行为跟argparse的store_true类似，但很多人第一次用会懵。正确的写法是--use_gpu=False或者--nouse_gpu。另外，如果你在代码里想判断布尔值，直接if FLAGS.use_gpu:就行，不需要跟True比较。

5.3 重复定义参数导致的静默覆盖

前面提到过，重复定义同名参数不会报错，后定义的会覆盖先定义的。这个问题在多文件项目里特别隐蔽，因为两个模块可能由不同的人写，各自定义了一个num_workers，默认值还不一样。程序跑起来之后，到底用哪个默认值取决于 import 顺序，而 import 顺序又可能被各种因素影响。我遇到过一次线上事故，就是因为两个模块都定义了batch_size，一个默认 32 一个默认 64，本地测试时 import 顺序恰好让 32 生效，部署到服务器后 import 顺序变了，变成了 64，导致显存溢出。后来我在项目里加了一个check_flags.py，在main开头遍历FLAGS.flag_values_dict()，如果发现某个参数被定义了多次（可以通过检查注册表实现），就直接报错退出。虽然tf.flags没有直接提供“定义次数”的接口，但你可以通过FLAGS.__dict__['__flags']之类的内部结构去查，或者干脆在 CI 里跑一个静态检查脚本，扫描所有DEFINE_xxx调用，发现重名就 fail。

5.4 与 argparse 混用的冲突表现

如果你的项目里同时用了argparse和tf.flags，两者都会去读sys.argv，结果就是参数被抢来抢去。典型表现是：argparse报“unrecognized arguments”，或者tf.flags读不到本该传进来的参数。更麻烦的是，tf.app.run()内部会调用FLAGS(sys.argv)，而argparse的parse_args()也会消费sys.argv，谁先谁后决定了谁能拿到参数。我试过的一种临时方案是：先用argparse解析出tf.flags需要的参数，然后手动构造一个列表传给FLAGS()，但这很绕，不推荐。长期方案还是统一迁移到absl.flags或者argparse二选一。如果只是临时跑个脚本，可以把tf.flags的参数定义和argparse的参数定义分开，用parse_known_args()让argparse忽略未知参数，但这也只是权宜之计。

5.5 在 tf.app.run 里传自定义参数的技巧

tf.app.run()的签名是run(main=None, argv=None)，你可以通过argv参数传入自定义的参数列表，而不是默认的sys.argv。这个技巧在写单元测试或者从其他脚本调用训练入口时很有用。比如你想在测试里模拟命令行参数，可以这样写：

import sys from train_demo import main if __name__ == '__main__': test_argv = ['train_demo.py', '--batch_size=16', '--nouse_gpu'] tf.app.run(main=main, argv=test_argv)

注意argv的第一个元素通常是脚本名，解析器会跳过它。如果你不传第一个元素，解析可能会出错。这个用法在官方文档里提得不多，但实际调试时很好用，尤其是你想在 Notebook 里调用一个用tf.app.run()写的训练脚本时，可以直接构造argv列表传进去，避免修改sys.argv。

6. 从 tf.flags 迁移到现代方案的实操建议

6.1 迁移到 absl.flags 的步骤

absl.flags是tf.flags的“精神续作”，API 几乎一模一样，迁移成本很低。基本步骤是：把import tensorflow as tf换成from absl import flags和from absl import app，把tf.app.flags.DEFINE_xxx换成flags.DEFINE_xxx，把tf.app.run()换成app.run(main)。FLAGS的获取方式也从tf.app.flags.FLAGS变成flags.FLAGS。行为上的差异主要有两点：第一，absl.flags对未知参数默认会报错，而不是静默忽略，这其实是好事，能帮你发现拼写错误；第二，absl.flags支持--flagfile从文件加载参数，适合管理大量配置。迁移过程中要注意，如果你的代码里同时 import 了 TensorFlow 和 absl，确保不要混用两套FLAGS，否则会出现“定义了但读不到”的情况。

6.2 迁移到 argparse 的注意事项

如果你不想引入 absl 依赖，用标准库argparse也能替代。迁移的核心思路是把每个DEFINE_xxx翻译成parser.add_argument，把FLAGS.xxx换成args.xxx。类型映射关系是：DEFINE_string对应type=str，DEFINE_integer对应type=int，DEFINE_float对应type=float，DEFINE_boolean对应action='store_true'或action='store_false'。DEFINE_enum对应choices=[...]。迁移时最大的变化是“全局单例”没了，你需要把args对象显式传给各个函数，或者用一个全局变量存起来。虽然多写了一些参数传递代码，但依赖关系更清晰，测试也更容易。我个人的经验是：新项目直接用argparse或Hydra，老项目如果只是维护，没必要大规模迁移，但可以在新加的模块里用新方案，逐步替换。

6.3 用配置文件替代命令行参数的场景

当参数数量超过二三十个，命令行传参就变得很痛苦，尤其是那些嵌套结构（比如模型每一层的配置）。这时候可以考虑用 YAML 或 JSON 配置文件，配合argparse只传一个--config路径。tf.flags本身不支持嵌套配置，所以如果你现在的项目里用tf.flags管理了大量参数，迁移到配置文件方案会是一个比较大的重构。我的建议是分两步走：先把所有参数定义集中到一个config.py，用tf.flags管理；等稳定之后，再把config.py改造成读取 YAML 的模块，对外仍然暴露FLAGS风格的接口，这样业务代码几乎不用改。这种“渐进式迁移”在实际项目里比“一刀切重写”稳妥得多。

7. 几个我踩过的坑和独家经验

第一个坑是关于FLAGS的线程安全性。tf.flags的解析过程不是线程安全的，如果你在多线程环境里同时读FLAGS和触发解析，可能会读到半成品状态。我遇到过一次在数据加载线程里读FLAGS.batch_size，结果读到了默认值而不是命令行传的值，原因就是主线程还没完成解析。后来我把所有FLAGS的读取都放在主线程初始化阶段，解析完成后把需要的值拷贝到局部变量或者配置对象里，再传给其他线程。这个习惯一直保留到现在，即使后来用argparse也是这么做的。

第二个坑是关于--help的输出格式。tf.flags生成的帮助信息比较简陋，参数按定义顺序排列，没有分组，参数多了之后很难找。我一般会在项目里维护一个README或者config.md，手动列出所有参数的含义和推荐取值，而不是依赖--help。另外，tf.flags的--help会直接调用sys.exit()，如果你在 Notebook 里不小心触发了，整个内核会重启，这个要注意。

第三个经验是关于参数默认值的“可发现性”。tf.flags的默认值写在DEFINE_xxx的第二个参数里，散落在各个模块中，新人接手项目时很难快速了解“这个模型默认用什么配置”。我的做法是在项目根目录放一个default_config.yaml，把所有参数的默认值集中写一遍，然后在main里读取这个 YAML 并覆盖FLAGS的默认值。这样既保留了tf.flags的命令行接口，又让默认配置一目了然。虽然多了一层间接，但对于需要频繁复现实验的项目来说，这点成本很值得。

第四个经验是关于参数命名的“前缀约定”。当项目变大之后，参数名冲突的概率会上升。我习惯给不同模块的参数加前缀，比如数据相关的用data_，模型相关的用model_，训练相关的用train_。这样即使两个模块都定义了size这种通用名，也能通过data_size和model_size区分开。tf.flags本身不强制这个约定，但团队里统一之后，代码可读性会好很多。

最后再分享一个小技巧：如果你需要在运行时动态添加参数（比如根据某个配置决定要不要加一个--debug开关），tf.flags是做不到的，因为所有参数必须在解析前定义好。这种场景下，你可以先用argparse解析出“模式”参数，再根据模式决定加载哪些tf.flags定义。虽然有点绕，但在一些需要“按需加载配置”的项目里挺实用。不过更现代的做法还是直接用支持动态配置的方案，比如Hydra的composeAPI，这里就不展开了。