freqtrade convert-data 命令详解在 json / jsongz / feather / parquet 之间安全转换历史 K 线数据【免费下载链接】freqtradeFree, open source crypto trading bot项目地址: https://gitcode.com/GitHub_Trending/fr/freqtradefreqtrade 免费开源加密货币交易机器人通过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协同工作命令作用download-data从交易所下载 OHLCV或搭配--dl-trades下载成交明细convert-data将已下载的 **K 线OHLCV**数据在格式之间转换本文主题convert-trade-data将已下载的**成交明细trades**数据在格式之间转换trades-to-ohlcv把成交明细聚合为 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.6sjson——纯文本 JSON人类可读、便于排查但体积最大、读取最慢265Mb / 约 17.1sjsongz——JSON 的 gzip 压缩版磁盘占用最小83Mb但解压开销使其读取最慢约 23.6sparquet——列式存储仅支持 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可得到完整 usageusage: 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} ...]]各参数逐一说明如下参数必填含义与取值范围--format-from是源格式{json, jsongz, feather, parquet}。在 cli_options.py 中定义choices 即AVAILABLE_DATAHANDLERS--format-to是目标格式同上取值cli_options.py-p / --pairs否仅转换指定交易对多个交易对以空格分隔-t / --timeframes否仅转换指定时间周期空格分隔列表--candle-types否指定转换的 K 线类型如spot futures funding_rate mark index premiumIndex open_interest默认转换该数据目录下全部可用类型--trading-mode/--tradingmode否选择交易模式spot / margin / futuresconstants.py 的TRADING_MODES。注意帮助文本注明查看/操作期货数据时需配合使用--erase否转换完成后删除源格式的原始数据文件。若源格式与目标格式相同则不会触发删除--exchange否交易所名称仅在不提供配置文件时有效-c / --config否配置文件路径默认取userdir/config.json或config.json支持多个--config可用-表示从 stdin 读取-d / --datadir否交易所历史数据的基础目录默认形如~/.freqtrade/data/binance若要处理期货数据需配合--trading-mode--userdir否userdata 目录路径-v / --no-color / --logfile / -V否通用日志与版本参数--candle-types与--trading-mode两个选项在 cli_options.py 中定义convert-data子命令的可选参数集合定义于 arguments.pyARGS_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, exchangeOHLCV 转换额外多出时间周期、交易模式与 K 线类型三个筛选维度。命令解析器在 arguments.py 中注册并绑定处理函数partial(start_convert_data, ohlcvTrue)。四、实战用法示例4.1 典型场景json 转 jsongz 以节省磁盘官方文档给出的标准示例见 docs/data-download.mdfreqtrade 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-timerange4.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 mark4.4 姊妹命令转换成交明细数据若需要转换的是下载的成交明细trades而非 K 线应使用convert-trade-data子命令其完整参数见 docs/commands/convert-trade-data.md官方示例docs/data-download.mdfreqtrade 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_fromargs[format_from], convert_toargs[format_to], eraseargs[erase], )两个关键点先做数据迁移再转换migrate_data()定义于 freqtrade/util/migrations/init.py会调用migrate_funding_fee_timeframe()把旧版资金费率数据的时间周期对齐到新格式避免旧数据在格式转换后被新版本误读。这一点与 docs/deprecated.md 中升级前请用convert-data子命令把旧数据转为受支持格式的建议相呼应。不需交易所UTIL_NO_EXCHANGE模式意味着不初始化交易所对象命令既可以在无网络环境运行也解释了为何--exchange仅在无配置文件时才需要。5.2 转换核心convert_ohlcv_format真正执行转换的函数位于 freqtrade/data/converter/converter.py逻辑如下获取读写 Handlersrc get_datahandler(datadir, convert_from)、trg get_datahandler(datadir, convert_to)同一数据目录下源/目标 Handler 并存枚举待转换集合分别调用src.ohlcv_get_available_data(datadir, TradingMode.SPOT)与...TradingMode.FUTURES)扫描现货与期货两套目录得到所有(交易对, 时间周期, K线类型)组合三级过滤若配置含pairs则按交易对过滤含timeframes则按时间周期过滤最后按candle_typesK线类型过滤未显式指定时默认取CandleType全部枚举与帮助文本默认所有可用类型一致。组合按 交易对/时间周期/K线类型 排序后在日志中完整打印转换过程透明可审计逐组合转换src.ohlcv_load(...)读取fill_missingFalse、drop_incompleteFalse即保持原样搬运、不做补全与去尾避免转换前后数据不一致→ 有数据时trg.ohlcv_store(...)写入按需清理源文件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_formatconvert_fromjson、convert_tojsongz、eraseFalse而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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
