freqtrade list-freqaimodels 命令详解：FreqAI 模型清单、参数说明与源码级查找机制

在 Freqtrade 的 FreqAI 机器学习体系中，模型（Model）是策略的核心组件，但 FreqAI 模型不像策略那样在文档中被频繁展示。freqtrade list-freqaimodels 正是用来盘点当前环境中所有可用 FreqAI 模型的命令行工具：它会扫描内置模型目录、用户模型目录以及 --freqaimodel-path 指定的附加路径，按名称输出每个模型的类名、来源文件与加载状态。读完本文，你将掌握该命令的完整参数用法、两种输出模式的区别、模型搜索路径的优先级机制，以及它与 --freqaimodel 配置项和 REST API /freqaimodels 端点之间的调用关系。

命令概述与完整帮助输出

list-freqaimodels 是 Freqtrade CLI 的内置子命令之一，在 命令注册代码 中注册，帮助文本为 "Print available freqAI models."。它的命令行选项来自参数组 ARGS_LIST_FREQAIMODELS（即 freqaimodel_path 与 print_one_column 两项，定义于 arguments.py），再加上所有 list-* 命令共用的 Common arguments 父解析器。

官方文档 docs/commands/list-freqaimodels.md 由构建脚本 build_helpers/create_command_partials.py 自动从 argparse 解析器抓取生成（该脚本要求 Python 3.13+ 运行以保证输出格式一致），其完整内容如下：

usage: freqtrade list-freqaimodels [-h] [-v] [--no-color] [--logfile FILE]
                                   [-V] [-c PATH] [-d PATH] [--userdir PATH]
                                   [--freqaimodel-path PATH] [-1]

options:
  -h, --help            show this help message and exit
  --freqaimodel-path PATH
                        Specify additional lookup path for freqaimodels.
  -1, --one-column      Print output in one column.

Common arguments:
  -v, --verbose         Verbose mode (-vv for more, -vvv to get all messages).
  --no-color            Disable colorization of hyperopt results. May be
                        useful if you are redirecting output to a file.
  --logfile, --log-file FILE
                        Log to the file specified. Special values are:
                        'syslog', 'journald'. See the documentation for more
                        details.
  -V, --version         show program's version number and exit
  -c, --config PATH     Specify configuration file (default:
                        `userdir/config.json` or `config.json` whichever
                        exists). Multiple --config options may be used. Can be
                        set to `-` to read config from stdin.
  -d, --datadir, --data-dir PATH
                        Path to the base directory of the exchange with
                        historical backtesting data. To see futures data, use
                        trading-mode additionally.
  --userdir, --user-data-dir PATH
                        Path to userdata directory.

命令专属选项

选项	源码定义位置	作用说明
--freqaimodel-path PATH	cli_options.py	指定一个附加的 FreqAI 模型查找路径。从源码结构看，该值会进入 config["freqaimodel_path"]，并在解析器构建搜索路径时被插入到搜索列表的最前面，因此其优先级高于内置模型目录与 user_data/freqaimodels
-1, --one-column	arguments.py	单列输出模式：每行仅打印一个模型类名，便于脚本/管道处理（如配合 grep、xargs）

公共选项（Common arguments）

以下选项继承自所有子命令共用的父解析器，在 arguments.py 中统一定义：

选项	说明
-h, --help	显示帮助信息并退出
-v, --verbose	详细日志模式，-vv 更多，-vvv 输出全部消息
--no-color	禁用输出着色，适合将输出重定向到文件
--logfile, --log-file FILE	日志写入指定文件；特殊值 syslog、journald 可写到系统日志
-V, --version	显示程序版本号并退出
-c, --config PATH	指定配置文件；默认为 userdir/config.json 或 config.json（取存在者），可多次使用以叠加配置，设为 - 时从 stdin 读取
-d, --datadir, --data-dir PATH	历史回测数据根目录（配合 trading-mode 可查看合约数据）。注意该命令本身并不读取历史数据，此项仅为公共参数统一注入
--userdir, --user-data-dir PATH	指定 userdata 目录，直接决定模型搜索路径中的用户模型目录位置

命令入口实现：从 CLI 参数到模型清单

list-freqaimodels 的执行入口是 start_list_freqAI_models，其执行链路非常清晰：

1. 调用 setup_utils_configuration(args, RunMode.UTIL_NO_EXCHANGE) 完成配置加载与校验。这里使用 RunMode.UTIL_NO_EXCHANGE，说明该命令不需要连接交易所、可以完全离线运行，适合在纯开发环境中盘点模型；
2. 调用 FreqaiModelResolver.search_all_objects(config, not args["print_one_column"]) 扫描所有搜索路径。第二个参数 enum_failed 的取值与输出模式绑定：表格模式下为 True（导入失败的模块会被标记出来），单列模式下为 False（导入失败的模块直接跳过）；
3. 按模型名 sorted(..., key=lambda x: x["name"]) 字母序排序；
4. 根据 print_one_column 决定输出方式：单列模式逐行 print 类名；表格模式交给共用的 _print_objs_tabular 函数渲染 Rich 表格。

单元测试 test_start_list_freqAI_models 验证了两种模式的行为：-1 模式下输出仅包含 LightGBMClassifier、LightGBMRegressor、XGBoostRegressor 等类名而不含 <builtin>/... 位置信息；默认表格模式则同时输出名称与位置列。

模型从哪里被找到：FreqaiModelResolver 的搜索路径机制

这是理解 list-freqaimodels 输出的关键。FreqaiModelResolver 继承自通用的 IResolver，通过四个类属性声明自己的解析规则：

属性	值	含义
object_type	IFreqaiModel	只识别 IFreqaiModel 接口的子类
object_type_str	"FreqaiModel"	报错信息中使用的对象类型名
user_subdir	USERPATH_FREQAIMODELS	用户模型目录名，即 user_data/freqaimodels（常量定义见 constants.py）
initial_search_path	freqtrade/freqai/prediction_models	内置模型目录，对应仓库中的 freqtrade/freqai/prediction_models
extra_path	"freqaimodel_path"	从 config["freqaimodel_path"]（即 --freqaimodel-path）读取的附加路径

结合 IResolver.build_search_paths 的插入逻辑（extra_path 与用户目录均以 insert(0, ...) 插到列表头部），最终搜索顺序为：

1. --freqaimodel-path / freqaimodel_path（若设置）——最高优先级；
2. user_data/freqaimodels/——用户自定义模型目录；
3. freqtrade/freqai/prediction_models/——内置模型目录，输出中位置列带 <builtin>/ 前缀（由 _build_rel_location 生成）。

内置模型目录当前包含 LightGBM 系列（LightGBMClassifier、LightGBMClassifierMultiTarget、LightGBMRegressor、LightGBMRegressorMultiTarget）、XGBoost 系列（XGBoostClassifier、XGBoostRFClassifier、XGBoostRFRegressor、XGBoostRegressor、XGBoostRegressorMultiTarget）、PyTorch 系列（PyTorchMLPClassifier、PyTorchMLPRegressor、PyTorchTransformerRegressor）、sklearn 分类器（SKLearnRandomForestClassifier）以及强化学习模型（ReinforcementLearner、ReinforcementLearner_multiproc）。注意这些模型依赖 requirements-freqai.txt / requirements-freqai-rl.txt 中的第三方库，若依赖未安装，对应模块在表格模式中会呈现为加载失败状态。

模型识别规则由 _get_valid_object 决定：只有在目标 .py 文件内部定义（obj.__module__ == module_name）且不是 IFreqaiModel 本身的类才算有效模型；导入时捕获 ModuleNotFoundError、ImportError 等异常并记录 warning。两个对实际使用有影响的行为：

• 表格模式（enum_failed=True）下，导入失败的文件仍会列出，状态列显示 LOAD FAILED（红色加粗）；类名重复时显示 DUPLICATE NAME（黄色），加载成功且唯一时显示 OK（绿色）。这些状态逻辑在共用的 _print_objs_tabular 中实现，因此表头与 list-strategies 相同（Strategy name / Location / Status）；
• 单列模式（enum_failed=False）下，导入失败的模块被直接跳过，输出中不会出现。

从源码结构看，search_all_objects 的 recursive 参数对 FreqAI 模型固定为 False（该命令没有类似 list-strategies 的 --recursive-strategy-search 选项），即模型文件必须位于上述三个目录的顶层，子目录中的模型文件不会被枚举。

与 FreqAI 主流程的关系

list-freqaimodels 是"只读盘点"命令，而真正加载模型供 FreqAI 策略使用走的是 FreqaiModelResolver.load_freqaimodel。两者共用同一套搜索路径，但加载逻辑有两点差异值得注意：

• 加载时读取的是 config["freqaimodel"]（即 FreqAI 策略配置中的 freqaimodel 字段），未设置时抛出 OperationalException 提示使用 --freqaimodel；
• 存在一个禁止名单 disallowed_models = ["BaseRegressionModel"]：基类不允许被直接指定为运行模型，必须选择其具体子类或自行继承。

除了 CLI，Webserver 的 REST API 也复用同一个解析器：api_webserver.py 中的 GET /freqaimodels 端点同样调用 FreqaiModelResolver.search_all_objects，但固定 enum_failed=False 且只返回排序后的模型名列表（{"freqaimodels": [...]}）。因此 FreqUI 或 API 客户端中看到的模型清单与 freqtrade list-freqaimodels -1 的结果来源完全一致。

实战使用示例与常见问题

基本用法——列出所有模型（表格输出，含位置与状态）：

freqtrade list-freqaimodels

脚本化用法——单列输出，配合 grep 检查某个模型是否可用：

freqtrade list-freqaimodels -1 | grep PyTorchTransformerRegressor

扫描私有模型仓库——将团队共享的模型目录加入查找路径：

freqtrade list-freqaimodels --freqaimodel-path /path/to/shared/models

由于 extra_path 被插入搜索路径最前，该目录中的同名模型会在搜索中先于 user_data/freqaimodels 与内置目录命中。同样的值也可以写入配置文件的 freqaimodel_path 字段（解析器通过 config.get(cls.extra_path) 读取），效果等价。

常见问题排查：

1. 模型文件存在但列表中没有：确认文件位于 user_data/freqaimodels/、--freqaimodel-path 指定目录或内置目录的顶层（不支持递归子目录），且文件中定义的是 IFreqaiModel 的子类并在文件内直接定义（不是从别处导入后再暴露）；
2. 表格中出现 LOAD FAILED：通常是第三方依赖缺失（如未安装 FreqAI 的 requirements），可结合 -vv 查看详细 warning，日志中会输出 "Could not import <文件> due to '<原因>'"；
3. 切换 userdata 目录：用 --userdir 指向不同的 userdata 根目录，模型搜索的用户目录部分会随之变化；
4. 与 list-strategies 的区别：两者共享表格渲染与解析框架，但 FreqAI 模型命令没有 --recursive-strategy-search 选项，且只识别 IFreqaiModel 子类而非策略类。

小结

list-freqaimodels 是 FreqAI 工作流中低门槛的"模型库存查询"入口：它不需要交易所连接，默认扫描内置 freqtrade/freqai/prediction_models、用户 user_data/freqaimodels 与 --freqaimodel-path 三类路径，并以带状态的 Rich 表格或纯类名两种形式输出。理解它背后的 IResolver 搜索路径优先级与 FreqaiModelResolver 的加载规则，能让你在自定义 FreqAI 模型、排查模型未加载问题以及对接 REST API /freqaimodels 端点时都有据可依。