freqtrade convert-trade-data 深度解析：成交数据（Trades）存储格式转换与 Kraken CSV 导入模式

freqtrade convert-trade-data 是 freqtrade 数据工具链中专门用于在不同存储格式之间转换逐笔成交数据（trades）的命令。本文基于仓库文档 convert-trade-data.md 的完整参数说明，结合 start_convert_data 与 convert_trades_format 的源码实现，系统讲解该命令的参数含义、底层数据流转路径、kraken_csv 特殊导入模式，以及 --erase 的删除语义与边界行为，帮助你在数据格式迁移、Kraken 历史成交导入等场景中正确且安全地使用它。

命令定位：它处理的是 Trades 数据，而非 OHLCV

freqtrade 提供了三个相邻但职责不同的数据命令，在使用前需要先厘清边界（参见 arguments.py 中的子命令注册）：

命令	作用对象	入口函数
convert-data	OHLCV 蜡烛数据	start_convert_data(ohlcv=True)
convert-trade-data	逐笔成交（trades）数据	start_convert_data(ohlcv=False)
trades-to-ohlcv	将 trades 聚合为 OHLCV	start_convert_trades

三者的注册逻辑如下：convert-data 与 convert-trade-data 共用同一个入口函数 start_convert_data，仅通过 ohlcv 参数区分分支，而 trades-to-ohlcv 走独立的 start_convert_trades 流程（其文档见 trades-to-ohlcv.md，OHLCV 转换见 convert-data.md）。

之所以需要转换 trades 格式，是因为逐笔成交数据通常由 download-data --dl-trades 下载而来（见 data-download.md），默认存储为 feather 格式；当你需要压缩体积（jsongz）、提升可读性/兼容性（json）、或与具备列式压缩的 parquet 对齐时，就需要该命令。此外，Kraken 等平台不提供标准历史 OHLCV 接口，官方推荐的流程是导入 CSV 成交文件再自行聚合，这正是 kraken_csv 源格式存在的原因。

完整参数说明（继承官方帮助输出）

以下是仓库文档 convert-trade-data.md 中的完整命令行帮助输出：

usage: freqtrade convert-trade-data [-h] [-v] [--no-color] [--logfile FILE]
                                    [-V] [-c PATH] [-d PATH] [--userdir PATH]
                                    [-p PAIRS [PAIRS ...]]
                                    --format-from {json,jsongz,feather,parquet,kraken_csv}
                                    --format-to {json,jsongz,feather,parquet}
                                    [--erase] [--exchange EXCHANGE]

options:
  -h, --help            show this help message and exit
  -p, --pairs PAIRS [PAIRS ...]
                        Limit command to these pairs. Pairs are space-
                        separated.
  --format-from {json,jsongz,feather,parquet,kraken_csv}
                        Source format for data conversion.
  --format-to {json,jsongz,feather,parquet}
                        Destination format for data conversion.
  --erase               Clean all existing data for the selected
                        exchange/pairs/timeframes.
  --exchange EXCHANGE   Exchange name. Only valid if no config is provided.

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.

核心参数逐一说明如下（取值范围以 cli_options.py 中的实际定义为准）：

参数	必填	取值/说明
--format-from	是	源格式，可选 json、jsongz、feather、parquet、kraken_csv。注意 kraken_csv 仅能作为源格式出现
--format-to	是	目标格式，可选 json、jsongz、feather、parquet（不含 kraken_csv）
-p/--pairs	否	空格分隔的交易对列表，将转换范围限定为指定交易对
--erase	否	转换后删除源格式数据。源码层面仅在源格式与目标格式不同时才真正执行删除
--exchange	否	交易所名称，仅在未提供配置文件时有效；该命令以 RunMode.UTIL_NO_EXCHANGE 启动，不连接交易所
-c/--config	否	指定配置文件，默认取 userdir/config.json 或 config.json，可多次指定叠加
-d/--datadir	否	数据根目录，trades 数据文件位于其中的 \<exchange>\ 子目录下
--userdir	否	用户数据目录（userdata）路径
-v/--verbose	否	日志详细度，-vv/-vvv 逐级提高
--no-color / --logfile / -V	否	禁用彩色输出 / 输出日志到文件或 syslog、journald / 打印版本号

其中四种二进制/文本格式的合法性由 constants.py 中的常量统一约束：

AVAILABLE_DATAHANDLERS = ["json", "jsongz", "feather", "parquet"]

--format-from 在其基础上额外加入了 "kraken_csv"，而 --format-to 严格限定为这四种标准格式——这与下文源码中 kraken_csv 分支单独提前返回、不复用 datahandler 通道的实现方式完全一致。

底层实现路径：从 CLI 参数到 DataHandler

命令分发

在 arguments.py 中，convert-trade-data 子命令被注册为 start_convert_data 的部分应用（partial），ohlcv=False 标志决定了后续走 trades 分支：

convert_trade_data_cmd = subparsers.add_parser(
    "convert-trade-data",
    help="Convert trade data from one format to another.",
    parents=[_common_parser],
)
convert_trade_data_cmd.set_defaults(func=partial(start_convert_data, ohlcv=False))
self._build_args(optionlist=ARGS_CONVERT_DATA_TRADES, parser=convert_trade_data_cmd)

入口函数：配置装配与分支

data_commands.py 的 start_convert_data 负责装配配置并分派：

def start_convert_data(args: dict[str, Any], ohlcv: bool = True) -> None:
    config = setup_utils_configuration(args, RunMode.UTIL_NO_EXCHANGE)
    if ohlcv:
        migrate_data(config)
        convert_ohlcv_format(config, convert_from=args["format_from"],
                            convert_to=args["format_to"], erase=args["erase"])
    else:
        convert_trades_format(config, convert_from=args["format_from_trades"],
                              convert_to=args["format_to"], erase=args["erase"])

两个值得注意的细节：

1. trades 分支不做 migrate_data。OHLCV 分支在转换前会调用 migrate_data 修复历史数据文件命名，而 trades 分支不执行这一步——从源码结构看，trades 文件的命名约定（见下文文件模式）相对简单，无需额外迁移逻辑。
2. 参数名差异：trades 分支读取的源格式参数键是 format_from_trades（对应 CLI 上同一个 --format-from 选项），与 OHLCV 分支的 format_from 区分开，避免两个子命令共享命名空间时冲突。
3. RunMode.UTIL_NO_EXCHANGE 表明该命令不初始化交易所连接，纯本地文件操作，因此 --exchange 只在无配置文件时用于确定数据子目录名。

核心转换函数：convert_trades_format

真正的转换逻辑位于 trade_converter.py：

def convert_trades_format(config: Config, convert_from: str, convert_to: str, erase: bool):
    if convert_from == "kraken_csv":
        if config["exchange"]["name"] != "kraken":
            raise OperationalException(
                "Converting from csv is only supported for kraken."
                "Please refer to the documentation for details about this special mode."
            )
        from freqtrade.data.converter.trade_converter_kraken import import_kraken_trades_from_csv
        import_kraken_trades_from_csv(config, convert_to)
        return

    from freqtrade.data.history import get_datahandler

    src = get_datahandler(config["datadir"], convert_from)
    trg = get_datahandler(config["datadir"], convert_to)

    if "pairs" not in config:
        config["pairs"] = src.trades_get_pairs(config["datadir"])
    logger.info(f"Converting trades for {config['pairs']}")
    trading_mode: TradingMode = config.get("trading_mode", TradingMode.SPOT)
    for pair in config["pairs"]:
        data = src.trades_load(pair, trading_mode)
        logger.info(f"Converting {len(data)} trades for {pair}")
        trg.trades_store(pair, data, trading_mode)

        if erase and convert_from != convert_to:
            logger.info(f"Deleting source Trade data for {pair}.")
            src.trades_purge(pair, trading_mode)

这段源码揭示了四个关键行为：

1. 交易对自动发现：未指定 -p/--pairs 时，通过 src.trades_get_pairs(datadir) 扫描源格式下所有可识别的交易对。其实现（idatahandler.py）是按扩展名 glob 匹配 *trades.<ext> 文件并用正则 ^(\S+)(?=\-trades\.<ext>) 反解文件名——也就是说 trades 数据文件的命名模式固定为 \<PAIR\>-trades.\<ext>（如 XRP_ETH-trades.json.gz，仓库测试数据 XRP_ETH-trades.json.gz 即为例证）。这也解释了为什么源目录中混放的非 trades 文件不会被误转换。
2. 加载即清洗：trades_load（idatahandler.py）在读取文件后会自动调用 trades_df_remove_duplicates 按 timestamp 与 id 两列去重，并通过 trades_convert_types 按 TRADES_DTYPES 规整数据类型、追加 date 列。因此转换产出的目标文件天然去重且类型规范。
3. 存储只保留标准列：trades_store（idatahandler.py）在落盘前过滤为 DEFAULT_TRADES_COLUMNS，即去掉加载时追加的 date 列，保证各格式间列结构一致（timestamp、id、type、side、price、amount、cost，见 test_converter.py 中的列序断言）。
4. --erase 的双重条件：只有当 erase=True 且 源格式不等于目标格式时才删除源文件。这一条件在代码中显式保护了"同格式转换"这种（虽然少见但合法的）调用，防止把刚读出来的数据立即删掉。

kraken_csv 特殊模式

--format-from kraken_csv 是一条独立的导入通道：它不经过 datahandler 的 trades_load/trades_store 管道，而是直接调用 trade_converter_kraken.py 中的 import_kraken_trades_from_csv(config, convert_to)，将 Kraken 官方导出的 CSV 成交记录解析并写入 --format-to 指定的标准 trades 格式。

两个硬性约束需要牢记（源码中直接抛出 OperationalException）：

• 仅 Kraken 可用：config["exchange"]["name"] 必须为 kraken，否则命令直接报错退出。这意味着你必须在配置文件中（或通过 --exchange kraken）将交易所设为 kraken；
• 仅能作为源格式：kraken_csv 不出现在 --format-to 的可选值中，即不存在"导出为 Kraken CSV"的方向。

从源码结构看，该模式的定位是：对于不提供历史 OHLCV 接口的交易所，用 CSV 成交导入 + trades-to-ohlcv 聚合，构成一条完整的历史数据自建链路。

erase 语义的测试验证

对 --erase 行为的完整往返验证可见于 test_converter.py 中的 test_convert_trades_format 用例：

convert_trades_format(default_conf, convert_from="jsongz", convert_to="json", erase=False)
# 断言：新文件存在，且源文件仍然存在

convert_trades_format(default_conf, convert_from="json", convert_to="jsongz", erase=True)
# 断言：源（json）文件被删除，目标（jsongz）文件存在

该测试用 XRP_ETH-trades.json.gz 与 XRP_OLD-trades.json.gz 两份测试数据（tests/testdata/）验证了：erase=False 时双格式共存、erase=True 时源格式文件被清除——与 convert_trades_format 源码中 if erase and convert_from != convert_to 的判定逻辑一一对应。

实操建议与常见组合

结合上述源码行为，给出几个可直接复制的用法（假设数据目录为默认 user_data/data/<exchange>/，交易所为 kraken）：

# 1. 将 feather 格式 trades 转为压缩的 jsongz，转换后删除源文件
freqtrade convert-trade-data --format-from feather --format-to jsongz --erase

# 2. 仅转换指定交易对，保留源数据
freqtrade convert-trade-data --format-from feather --format-to json -p "XRP/ETH ADA/ETH"

# 3. 无配置文件时用 --exchange 指定交易所数据子目录
freqtrade convert-trade-data --exchange kraken --format-from feather --format-to parquet

# 4. Kraken CSV 成交导入（配置文件 exchange 需为 kraken），导入为 feather 后再聚合为 OHLCV
freqtrade convert-trade-data --format-from kraken_csv --format-to feather
freqtrade trades-to-ohlcv

几点注意事项：

1. 数据文件命名是自动识别的前提。如果你的 trades 文件不符合 \<PAIR\>-trades.\<ext> 模式（idatahandler.py 的正则约定），不会被自动发现，需先用 -p 显式指定或修正文件名；
2. 转换是逐交易对、逐文件格式独立进行的，每个交易对转换时都会打印 Converting N trades for <pair> 日志，便于核对成交量级是否异常；
3. feather 与 parquet 均依赖对应 Python 包（pyarrow 等，见 requirements.txt），缺失时应在安装阶段解决，而不是转换中途失败；
4. 同格式转换（--format-from 与 --format-to 相同）虽然允许，但配合 --erase 时源码保证不会删除源文件，这一"防自毁"行为值得在自动化脚本中依赖；
5. 该命令纯本地操作、不连接交易所（RunMode.UTIL_NO_EXCHANGE），可安全地在数据准备流水线中反复执行。

小结

freqtrade convert-trade-data 是 freqtrade 数据管理链路中 trades 数据的格式迁移入口：参数层面通过 --format-from/--format-to（含 kraken_csv 专属源格式）与 --erase 控制转换方向与清理策略；实现层面经由 start_convert_data 分派至 convert_trades_format，依托 datahandler 抽象完成"按文件模式发现交易对 → 去重规整 → 标准列落盘 → 可选删除源文件"的完整流程，并由 tests/data/test_converter.py 的往返测试锁定其行为边界。理解这些内部机制后，无论是跨格式迁移、压缩存储还是 Kraken 历史成交自建链路，都可以有依据地选择参数组合并预判结果。