企业官网建设流程全解析

freqtrade convert-data 命令详解：在 json / jsongz / feather / parquet 之间安全转换历史 K 线数据

【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtrade

freqtrade 免费开源加密货币交易机器人通过download-data子命令把交易所历史行情下载到本地user_data/data/<交易所>目录，默认以 Apache Arrow 的feather格式落盘。当需要更换存储格式以节省磁盘空间、加速回测读取、或为旧版本升级迁移历史数据时，freqtrade convert-data子命令提供了纯本地、无需连接交易所的批量格式转换能力。本文以 docs/commands/convert-data.md 为骨架，结合 freqtrade/commands/data_commands.py 与 freqtrade/data/converter/converter.py 的源码实现，完整讲解该命令的全部参数、四种数据格式取舍、真实转换示例及底层执行原理。读完本文，你将能熟练地把已下载的 K 线（OHLCV）数据在json、jsongz、feather、parquet四种格式间相互迁移。

一、命令定位：它解决什么问题

convert-data属于 freqtrade 的数据工具链，与download-data、convert-trade-data、trades-to-ohlcv、list-data协同工作：

按官方数据文档 docs/data-download.md 的说明，下载的原始格式可以通过--data-format-ohlcv/--data-format-trades指定，若曾改动过默认格式，再想迁移存量数据，就必须借助convert-data与convert-trade-data两个子命令。

从命令分发入口 freqtrade/commands/arguments.py 可以看到，convert-data使用RunMode.UTIL_NO_EXCHANGE运行模式（见 data_commands.py 的setup_utils_configuration(args, RunMode.UTIL_NO_EXCHANGE)）——这意味着转换过程不需要创建交易所连接、也不校验市场信息，纯本地磁盘读写，因此即使交易所已停服或网络不可用，历史数据仍可随时转换。

二、四种数据格式与选型依据

convert-data的--format-from/--format-to可选值（定义于 freqtrade/constants.py 的AVAILABLE_DATAHANDLERS）为：

• feather——基于 Apache Arrow 的二进制列式格式。freqtrade 的默认存储格式，读写速度最快、占用适中（官方文档对比中 115Mb / 读取约 1.6s）；
• json——纯文本 JSON，人类可读、便于排查，但体积最大、读取最慢（265Mb / 约 17.1s）；
• jsongz——JSON 的 gzip 压缩版，磁盘占用最小（83Mb），但解压开销使其读取最慢（约 23.6s）；
• parquet——列式存储，仅支持 OHLCV 数据，不支持成交明细数据，体积 149Mb、读取约 2.5s，介于 feather 与 json 之间。

上述体积/耗时对比来自官方文档 数据格式对比（基于 BTC/USDT 1m spot 约 467 万根 K 线实测），官方给出的结论是：兼顾性能与体积，推荐继续使用默认的feather；若磁盘紧张且不频繁读取，可考虑jsongz。

对应的数据读写封装位于 freqtrade/data/history/datahandlers/idatahandler.py，其中get_datahandler()（idatahandler.py）根据传入的data_format字符串返回对应的 Handler 类（缺省也是feather），各格式 Handler 实现在jsondatahandler.py、featherdatahandler.py、parquetdatahandler.py、arrowdatahandler.py中。转换过程本质上是"用一个 Handler 读出、再用另一个 Handler 写入"。

三、命令语法与全部参数解析

在终端执行freqtrade convert-data --help（或查看 docs/commands/convert-data.md）可得到完整 usage：

usage: freqtrade convert-data [-h] [-v] [--no-color] [--logfile FILE] [-V] [-c PATH] [-d PATH] [--userdir PATH] [-p PAIRS [PAIRS ...]] --format-from {json,jsongz,feather,parquet} --format-to {json,jsongz,feather,parquet} [--erase] [--exchange EXCHANGE] [-t TIMEFRAMES [TIMEFRAMES ...]] [--trading-mode {spot,margin,futures}] [--candle-types {spot,futures,mark,index,premiumIndex,funding_rate,open_interest} [{spot,futures,mark,index,premiumIndex,funding_rate,open_interest} ...]]

各参数逐一说明如下：

--candle-types与--trading-mode两个选项在 cli_options.py 中定义；convert-data子命令的可选参数集合定义于 arguments.py：

ARGS_CONVERT_DATA = ["pairs", "format_from", "format_to", "erase", "exchange"] ARGS_CONVERT_DATA_OHLCV = [*ARGS_CONVERT_DATA, "timeframes", "trading_mode", "candle_types"]

即相比convert-trade-data（仅pairs, format_from_trades, format_to, erase, exchange），OHLCV 转换额外多出时间周期、交易模式与 K 线类型三个筛选维度。命令解析器在 arguments.py 中注册，并绑定处理函数partial(start_convert_data, ohlcv=True)。

四、实战用法示例

4.1 典型场景：json 转 jsongz 以节省磁盘

官方文档给出的标准示例（见 docs/data-download.md）：

freqtrade convert-data --format-from json --format-to jsongz \ --datadir ~/.freqtrade/data/binance -t 5m 15m --erase

含义：把~/.freqtrade/data/binance下仅5m、15m两个时间周期的全部交易对 K 线从json转为jsongz，并在转换成功后删除原始 json 文件（--erase），从而腾出磁盘空间。

4.2 无参数缩小范围：转换整个目录

若不指定-t与-p，则对数据目录中检测到的所有 交易对 × 时间周期 × K线类型组合执行转换（过滤仅在配置含对应键时生效，见下文源码原理）。建议先用list-data确认将要转换的内容：

freqtrade list-data --userdir ~/.freqtrade/user_data/ --show-timerange

4.3 处理期货与资金费率等非现货数据

convert-data同时扫描现货（TradingMode.SPOT）与期货（TradingMode.FUTURES）目录下的数据。若要显式指定只转某种 K 线类型：

freqtrade convert-data --format-from feather --format-to parquet \ --datadir ~/.freqtrade/data/binance \ --trading-mode futures \ --candle-types futures funding_rate mark

4.4 姊妹命令：转换成交明细数据

若需要转换的是下载的成交明细（trades）而非 K 线，应使用convert-trade-data子命令（其完整参数见 docs/commands/convert-trade-data.md），官方示例（docs/data-download.md）：

freqtrade convert-trade-data --format-from jsongz --format-to json \ --datadir ~/.freqtrade/data/kraken --erase

值得注意：trades 转换的--format-from额外允许kraken_csv（见 cli_options.py），便于直接消化 Kraken 导出的 CSV 原始数据。

五、源码级原理：一条转换命令内部发生了什么

5.1 入口与迁移步骤

convert-data的处理入口是 data_commands.py 的start_convert_data()：

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"], )

两个关键点：

1. 先做数据迁移再转换：migrate_data()定义于 freqtrade/util/migrations/init.py，会调用migrate_funding_fee_timeframe()把旧版资金费率数据的时间周期对齐到新格式，避免旧数据在格式转换后被新版本误读。这一点与 docs/deprecated.md 中"升级前请用convert-data子命令把旧数据转为受支持格式"的建议相呼应。
2. 不需交易所：UTIL_NO_EXCHANGE模式意味着不初始化交易所对象，命令既可以在无网络环境运行，也解释了为何--exchange仅在无配置文件时才需要。

5.2 转换核心convert_ohlcv_format

真正执行转换的函数位于 freqtrade/data/converter/converter.py，逻辑如下：

1. 获取读写 Handler：src = get_datahandler(datadir, convert_from)、trg = get_datahandler(datadir, convert_to)，同一数据目录下源/目标 Handler 并存；
2. 枚举待转换集合：分别调用src.ohlcv_get_available_data(datadir, TradingMode.SPOT)与...TradingMode.FUTURES)扫描现货与期货两套目录，得到所有(交易对, 时间周期, K线类型)组合；
3. 三级过滤：若配置含pairs则按交易对过滤；含timeframes则按时间周期过滤；最后按candle_types（K线类型）过滤，未显式指定时默认取CandleType全部枚举（与帮助文本"默认所有可用类型"一致）。组合按 交易对/时间周期/K线类型 排序后在日志中完整打印，转换过程透明可审计；
4. 逐组合转换：src.ohlcv_load(...)读取（fill_missing=False、drop_incomplete=False，即保持原样搬运、不做补全与去尾，避免转换前后数据不一致）→ 有数据时trg.ohlcv_store(...)写入；
5. 按需清理源文件：if erase and convert_from != convert_to:才执行src.ohlcv_purge(...)删除源文件——两个硬性保证：只有--erase时删除、源格式与目标格式相同绝不会误删。

单元测试 tests/commands/test_commands.py 的test_convert_data与test_convert_data_trades通过 mock 验证了命令分发正确性：convert-data只触发convert_ohlcv_format（convert_from="json"、convert_to="jsongz"、erase=False），而convert-trade-data只触发convert_trades_format，证明两个子命令严格区分 OHLCV 与 trades 数据流。

六、注意事项与最佳实践

• 转换前先备份：虽然转换默认不删除源数据，但配合--erase会永久移除源格式文件，务必确认目标格式数据写入完整后再使用；
• --erase的误删防护：如源码所示，同格式转换时即使加了--erase也不会删除任何文件，可放心使用；
• 配置文件持久化：若你通过命令行--data-format-ohlcv/--data-format-trades改变了默认存储格式，官方建议同时把dataformat_ohlcv、dataformat_trades键写入配置（jsonc示例见 docs/data-download.md），否则回测等后续流程仍会按默认feather查找数据；
• parquet的局限：该格式只支持 OHLCV，不支持成交明细，因此不要用convert-trade-data的目标格式写成parquet；
• 时间周期筛选：-t用于把转换限定到少数周期以缩短耗时；不带该参数则会转换目录内检测到的所有周期（源码仅在有timeframes配置时才做过滤）；
• 数据格式相关配置变动后的统一迁移：例如从json全面切到feather，可先执行一次全量convert-data（不带-t、不加--erase）验证无误，再补跑一次带--erase的命令清理旧文件。

七、延伸阅读

• 命令帮助文档：docs/commands/convert-data.md
• 数据下载与格式对比的完整章节：docs/data-download.md
• 成交明细转换（姊妹命令）：docs/commands/convert-trade-data.md
• 本地数据清单查询：docs/commands/list-data.md
• 实现源码：freqtrade/commands/data_commands.py、freqtrade/data/converter/converter.py、freqtrade/commands/arguments.py、freqtrade/commands/cli_options.py
• 旧数据格式迁移说明：docs/deprecated.md

【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtrade