136 lines
5.2 KiB
Markdown
136 lines
5.2 KiB
Markdown
# cbpred
|
||
|
||
`cbpred` 是一个面向 Binance U 本位 USDT 永续合约的统一 K 线回撤预测管线，默认正式模型使用 8H 周期。数据由 [banbot](../banbot) 下载，模型只使用 OHLCV，不使用资金费率、盘口、持仓量或外部行情。
|
||
|
||
当前默认正式模型是 [`artifacts/v1/model.joblib`](artifacts/v1/model.joblib)。它由最近 18 根 8H K 线预测未来 6 根 8H K 线的稳健低点收益，并输出点预测以及用于区间参考的 q20/q80 结果。1d 模型作为独立实验产物保存在 [`artifacts_1d/best/model.joblib`](artifacts_1d/best/model.joblib)，不会覆盖默认 8h 模型；实验报告见 [`docs/1d_2026-08-24.md`](docs/1d_2026-08-24.md)。
|
||
|
||
|
||
|
||
## 快速开始
|
||
|
||
运行环境需要 Python 3、Go、可访问的 banbot 源码和 banbot 配置中的 QuestDB。默认路径是：
|
||
|
||
```text
|
||
/data/ban/banbot
|
||
/data/ban/banbot/biz/config.yml
|
||
```
|
||
|
||
安装项目及依赖：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -e .
|
||
```
|
||
|
||
一键更新最新 K 线、导出完整 8H 数据并生成全部品种预测：
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh
|
||
```
|
||
|
||
结果默认写入：
|
||
|
||
```text
|
||
predictions/latest_v1_8h/predictions.csv
|
||
predictions/latest_v1_8h/report.json
|
||
```
|
||
|
||
查看脚本参数：
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh --help
|
||
```
|
||
|
||
完整的数据流、参数和目录说明见 [`docs/usage.md`](docs/usage.md)。
|
||
|
||
## 定时部署
|
||
|
||
推荐使用常驻 Python 服务：它会在每个完整 8H K 线结束后的宽限期运行一次，使用状态文件防止重启后重复执行，并可将结果推送到 HTTP 服务和 SMTP 邮箱。配置与 systemd 部署方式见 [`docs/deployment.md`](docs/deployment.md)。
|
||
|
||
## 手动流程
|
||
|
||
如果需要单独准备数据和训练模型：
|
||
|
||
```bash
|
||
# 下载 1H K 线，导出并整理为 8H CSV
|
||
.venv/bin/python -m cbpred prepare \
|
||
--banbot-config /data/ban/banbot/biz/config.yml \
|
||
--out-dir data
|
||
|
||
# 使用 data/ 训练并覆盖 artifacts/v1 下的正式模型和报告
|
||
.venv/bin/python -m cbpred train \
|
||
--data-dir data \
|
||
--artifact-dir artifacts/v1
|
||
|
||
# 对单个已导出的 8H CSV 使用最新锚点预测
|
||
.venv/bin/python -m cbpred predict \
|
||
--artifact artifacts/v1/model.joblib \
|
||
--csv data/raw/123_BTC_USDT_USDT.csv \
|
||
--symbol BTC/USDT:USDT
|
||
```
|
||
|
||
也可以用 `run` 完成 `prepare + train`：
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred run --out-dir data --artifact-dir artifacts/v1
|
||
```
|
||
|
||
如果数据已经由 banbot 更新完成，可在 `prepare` 中加入 `--skip-download`，只执行筛选、导出和整理。
|
||
|
||
### 1d 实验
|
||
|
||
1d 使用相同的 `compact6` 特征、ExtraTrees 点模型、q20/q80 分位数模型、过滤和训练切分协议，只有 K 线周期改为 1d：
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred prepare \
|
||
--timeframe 1d \
|
||
--out-dir data_1d \
|
||
--banbot-config /data/ban/banbot/biz/config.yml
|
||
.venv/bin/python -m cbpred.experiments \
|
||
--data-dir data_1d \
|
||
--output-dir artifacts_1d \
|
||
--variants compact6 \
|
||
--n-estimators 20
|
||
```
|
||
|
||
结果目录为 `data_1d/`、`artifacts_1d/` 和 `predictions/latest_1d/`。1d 批量预测的成交额列名为 `quote_volume_usdt_1d`。
|
||
|
||
## 预测 CSV
|
||
|
||
一键脚本生成的 CSV 固定只包含以下 10 列：
|
||
|
||
|
||
| 列 | 含义 |
|
||
| --------------------------- | ------------------------------------- |
|
||
| `rank` | 按请求周期 USDT 成交额从高到低的排名 |
|
||
| `symbol` | 合约符号 |
|
||
| `latest_bar_start_utc` | 最新完整请求周期 K 线的 UTC 起始时间 |
|
||
| `close` | 最新完整请求周期 K 线收盘价 |
|
||
| `quote_volume_usdt_8h` / `quote_volume_usdt_1d` | 最新请求周期的 USDT 成交额 |
|
||
| `atr_rank_200_pct` | 当前 ATR 在过去 200 根 8H ATR 中的百分位，单位为 `%` |
|
||
| `drawdown_point_pct` | 点预测对应的回撤百分比 |
|
||
| `drawdown_cap_80pct_pct` | q80 对应的回撤百分比上界参考 |
|
||
| `price_level_reached_80pct` | q20 对应的价格水平参考 |
|
||
| `price_level_cap_80pct` | q80 对应的价格水平参考 |
|
||
|
||
|
||
回撤列是收益的相反数：预测收益为负时表示价格可能低于当前收盘；预测收益为正时，回撤列可能为负，表示未来稳健低点仍高于当前收盘。模型不满足资格条件时，预测字段为空，不应把空值当作零回撤。
|
||
|
||
## 当前模型
|
||
|
||
当前模型为 `compact6` 特征版本，使用 146 个特征和 ExtraTrees 点模型，同时使用两个 HistGradientBoosting 分位数模型生成 q20/q80。测试集结果和特征定义见 [`docs/model.md`](docs/model.md)，训练产物报告见 [`artifacts/v1/report.md`](artifacts/v1/report.md)。
|
||
|
||
## 测试
|
||
|
||
运行标准库回归测试：
|
||
|
||
```bash
|
||
.venv/bin/python -m unittest discover -q
|
||
```
|
||
|
||
项目文档按用途分为：
|
||
|
||
- [`docs/usage.md`](docs/usage.md)：安装、数据流、命令、目录和故障排查。
|
||
- [`docs/model.md`](docs/model.md)：目标定义、特征、训练协议、指标和限制。
|
||
- [`docs/v0_0823.md`](docs/v0_0823.md)、[`docs/v1_0823.md`](docs/v1_0823.md)：历史实验记录，不是当前运行入口。
|