第 5 章 · 02 数据格式转换

第 5 章 · 02 数据格式转换

本节摘要:本节讲清 freqtrade 支持的几种历史数据存储格式,以及如何在它们之间互相转换。freqtrade 同时支持 feather(基于 Apache Arrow,默认推荐)、json(纯文本)、jsongz(gzip 压缩的 json)、parquet(列式存储)。同一个数据集,不同格式的体积和读取速度差异巨大——以一份 6 个交易对/周期组合(约 1600 万根 K 线)的实测为例:feather 115MB / 1.6 秒,而 json 要 265MB / 17.1 秒。本节先对比四种格式的优劣,讲清为什么默认推荐 feather;再讲 convert-data 和 convert-trade-data 两个转换命令的用法;最后说怎么把格式偏好固化进配置文件,避免每次都敲一长串参数。

内容来源:原项目文档 docs/data-download.md 的 Data format 与 convert-data 章节,汉化并套用体系化模板。

学习目标

阅读完本节,你应当能够:

1. 列举 freqtrade 支持的 四种数据格式 及各自特点。
2. 解释 为什么默认推荐 feather(体积、速度、与 Arrow 生态)。
3. 用 convert-data 在 OHLCV 格式间互转。
4. 用 convert-trade-data 转换逐笔成交数据。
5. 把格式偏好 固化进配置,不再每次手敲参数。

一、四种数据格式

freqtrade 的 K 线数据可以落成四种格式:

下载时通过 --data-format-ohlcv 和 --data-format-trades 分别指定 OHLCV 与 trades 数据的格式:

freqtrade download-data --exchange binance --pairs BTC/USDT --timeframes 5m \
    --data-format-ohlcv feather --data-format-trades feather
​

OHLCV 与 trades 是两种独立的数据,trades 是逐笔成交(详见第 01 节末),通常只在 Kraken 等无历史 OHLCV 的交易所才用。

二、为什么默认推荐 feather

官方用一份约 1600 万根 K 线(BTC/ETH/XRP 的 1m + 5m,跨度数年)做的实测对比:

结论很清楚:

• feather 在「体积 + 速度」上综合最优,所以是默认值。
• jsongz 虽然最小,但解压太慢,只在「磁盘极度紧张、又不常读」时才考虑。
• json 体积最大、又慢,基本只有「需要人眼直接读文件调试」时才用。
• parquet 与 feather 接近,但只支持 OHLCV,不支持 trades,且生态集成度略逊 feather。

💡 没有特殊理由就用 feather。下文讲的转换命令,主要用途就是把历史上为了「可读性」存的 json 转成 feather。

三、convert-data:OHLCV 格式互转

convert-data 把磁盘上已有的 OHLCV 数据从一种格式转成另一种。典型场景:早期下载的 json 太大太慢,转成 feather。

# 把 binance 上所有 5m、15m 的 OHLCV 从 json 转成 jsongz,并删除原 json
freqtrade convert-data \
    --format-from json --format-to jsongz \
    --datadir user_data/data/binance \
    -t 5m 15m --erase
​

关键参数:

⚠️ --erase 谨慎用:--erase 会删源文件,建议先不加 --erase 跑一遍,确认目标格式生成无误,再删源文件释放磁盘。

四、convert-trade-data:逐笔成交格式互转

逐笔成交(trades)数据与 OHLCV 是两套独立文件,转换用 convert-trade-data:

# 把 kraken 上的 trades 数据从 jsongz 转回 json
freqtrade convert-trade-data \
    --format-from jsongz --format-to json \
    --datadir user_data/data/kraken --erase
​

参数与 convert-data 一致,只是作用于 -trades.feather / -trades.json 这类文件。trades 数据本身很大(逐笔),强烈建议用 feather 或 jsongz,不要用纯 json。

五、trades-to-ohlcv:从 trades 重采样出 OHLCV

如果你之前用 --dl-trades 拉了逐笔成交,又想生成多个周期的 OHLCV(不必重新下载),用 trades-to-ohlcv:

freqtrade trades-to-ohlcv --exchange kraken -t 5m 1h 1d --pairs BTC/EUR ETH/EUR
​

这会把已有的 trades 数据重采样成指定的多个周期。这通常是 Kraken 用户下载流程的「最后一步」:先 download-data --dl-trades,再 trades-to-ohlcv 生成各周期。

六、把格式偏好固化进配置

每次敲 --data-format-ohlcv feather 太啰嗦。把它写进 config.json 即可一劳永逸:

{
    // ... 其他配置
    "dataformat_ohlcv": "feather",
    "dataformat_trades": "feather"
    // ...
}
​

写入后,download-data、backtesting、list-data 等所有命令默认就按 feather 读写,不必再传命令行参数。

💡 格式与命令要一致:如果你在配置里改了 dataformat_ohlcv,记得后续所有命令(backtesting、list-data 等)都会按新格式找文件。如果磁盘上还是旧格式的数据,会找不到。这时用 convert-data 先把存量数据转成新格式。

七、常见踩坑

1. 混格式存:同目录下既有 BTC_USDT-5m-feather 又有 BTC_USDT-5m-json,freqtrade 只读配置指定那一种,另一个会被忽略或造成困惑。统一格式,用 list-data 确认。
2. 改了格式没转存量:配置改成 feather 后,旧 json 数据「还在但用不上」,回测报「找不到数据」。先 convert-data。
3. 跨目录混用:--datadir 指错目录,或现货/合约数据混在一个目录,导致回测读到错的数据类型。建议按 <exchange>-<mode> 分目录。
4. parquet 不能存 trades:parquet 只支持 OHLCV;如果你下 trades,别选 parquet。

本节要点回顾

1. 四种格式:feather(默认推荐)、parquet(仅 OHLCV)、jsongz(最小但慢)、json(最大最慢,人读用)。
2. 为什么 feather:实测 115MB / 1.6s,体积与速度综合最优;Arrow 生态,支持 OHLCV 与 trades。
3. convert-data:--format-from --format-to --datadir -t --erase,转 OHLCV;--erase 谨慎用。
4. convert-trade-data:转逐笔成交;trades 体积大,务必用 feather/jsongz。
5. trades-to-ohlcv:从已有 trades 重采样出多周期 OHLCV,Kraken 用户的最后一步。
6. 配置固化:dataformat_ohlcv / dataformat_trades 写进 config.json,避免每次手敲。
7. 避坑:别混格式、别跨目录、parquet 不支持 trades;改格式后用 convert-data 转存量。

下一节,我们用 list-data 看本地有哪些数据,用 plot-dataframe 把 K 线+指标+买卖点画出来,用 plot-profit 看资金曲线。