支持一键预测脚本
This commit is contained in:
105
README.md
105
README.md
@@ -1,78 +1,109 @@
|
||||
# cbpred
|
||||
|
||||
这是一个统一模型的 8H U 本位 USDT 合约回调预测管线。它只使用 banbot 的 K 线 OHLCV 数据，默认调用 banbot 下载 1H 存储数据，再按完整的 8 根 1H K 线聚合为 8H；不使用资金费率、盘口、持仓量或外部行情。
|
||||
`cbpred` 是一个面向 Binance U 本位 USDT 永续合约的统一 8H K 线回撤预测管线。数据由 [banbot](../banbot) 下载，模型只使用 OHLCV，不使用资金费率、盘口、持仓量或外部行情。
|
||||
|
||||
目标定义为有符号的未来最低价收益，并按品种训练期波动尺度归一化：
|
||||
当前正式模型只有一个：[`artifacts/v1/model.joblib`](artifacts/v1/model.joblib)。它由最近 18 根 8H K 线预测未来 6 根 8H K 线的稳健低点收益，并输出点预测以及用于区间参考的 q20/q80 结果。根目录不放置历史实验模型；历史实验说明保留在 [`docs/v0_0823.md`](docs/v0_0823.md) 和 [`docs/v1_0823.md`](docs/v1_0823.md)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
运行环境需要 Python 3、Go、可访问的 banbot 源码和 banbot 配置中的 QuestDB。默认路径是：
|
||||
|
||||
```text
|
||||
raw_return = quantile(low[t+1:t+6], 0.20) / anchor_close - 1
|
||||
target = raw_return / asset_atr_price_top20_median
|
||||
/home/ctyun/ban/banbot
|
||||
/home/ctyun/ban/banbot/biz/config.yml
|
||||
```
|
||||
|
||||
这里的 20% 分位数是未来窗口的稳健低点参考，不会被单根异常影线完全决定；它不是严格的 `lowestLow`。负值表示该低点参考低于当前收盘价，正值表示它仍高于当前收盘价；因此上涨阶段不会被强行压成 0。`asset_atr_price_top20_median` 是该品种训练期 ATR/price 降序前 20% 的中位数，预测输出会乘回该尺度。训练锚点和未来 6 根必须连续，跨越测试边界的训练样本会被丢弃，避免把测试期标签泄漏进训练集。
|
||||
|
||||
## 运行
|
||||
|
||||
先安装依赖：
|
||||
安装项目及依赖：
|
||||
|
||||
```bash
|
||||
python3 -m venv .venv
|
||||
.venv/bin/pip install -e .
|
||||
```
|
||||
|
||||
使用 banbot 的配置连接数据库，筛选 `market=linear`、符号为 `BASE/USDT:USDT`、上市至少 730 天且未退市的品种；默认连接配置来自 `/home/ctyun/ban/banbot/biz/config.yml`：
|
||||
一键更新最新 K 线、导出完整 8H 数据并生成全部品种预测：
|
||||
|
||||
```bash
|
||||
./scripts/update_and_predict.sh
|
||||
```
|
||||
|
||||
结果默认写入：
|
||||
|
||||
```text
|
||||
predictions/latest_v1/predictions.csv
|
||||
predictions/latest_v1/report.json
|
||||
```
|
||||
|
||||
查看脚本参数：
|
||||
|
||||
```bash
|
||||
./scripts/update_and_predict.sh --help
|
||||
```
|
||||
|
||||
完整的数据流、参数和目录说明见 [`docs/usage.md`](docs/usage.md)。
|
||||
|
||||
## 手动流程
|
||||
|
||||
如果需要单独准备数据和训练模型：
|
||||
|
||||
```bash
|
||||
# 下载 1H K 线，导出并整理为 8H CSV
|
||||
.venv/bin/python -m cbpred prepare \
|
||||
--banbot-config /home/ctyun/ban/banbot/biz/config.yml \
|
||||
--out-dir data
|
||||
```
|
||||
|
||||
如果数据已经由 banbot 下载完成，可以跳过下载，只执行筛选和导出：
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m cbpred prepare --skip-download --out-dir data
|
||||
```
|
||||
|
||||
训练会执行三轮特征迭代。点模型候选包括随机森林平方误差和 ExtraTrees，另用 HistGradientBoosting 分位数模型输出 q20/q80；验证集和测试集均为最近 10 个月中的按品种随机拆分，测试集只在最终选模后使用：
|
||||
|
||||
```bash
|
||||
# 使用 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
|
||||
```
|
||||
|
||||
默认保留所有连续样本，把当前 ATR 在过去 200 根 8H K 线中的排名作为特征；可以通过 `--volatility-rank-threshold 0.80` 或 `0.90` 做高波动样本对照实验。训练阶段会把数据集行数、过滤前后数量、阶段和候选模型进度输出到 stderr。
|
||||
|
||||
一条命令完成准备和训练：
|
||||
也可以用 `run` 完成 `prepare + train`：
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m cbpred run --out-dir data --artifact-dir artifacts/v1
|
||||
```
|
||||
|
||||
输出在 `artifacts/v1/report.md`、`artifacts/v1/report.json` 和 `artifacts/v1/model.joblib`。当前 `v1` 是最终特征复核中保留的 `compact6` 模型。
|
||||
如果数据已经由 banbot 更新完成，可在 `prepare` 中加入 `--skip-download`，只执行筛选、导出和整理。
|
||||
|
||||
对某个已导出的 8H CSV 预测任意锚点：
|
||||
## 预测 CSV
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m cbpred predict \
|
||||
--artifact artifacts/v1/model.joblib \
|
||||
--csv data/raw/123_BTC_USDT_USDT.csv \
|
||||
--at 2026010100000000
|
||||
```
|
||||
一键脚本生成的 CSV 固定只包含以下 10 列：
|
||||
|
||||
`future_low_return_q20` 是稳健未来低点收益的较低分位，对应 `future_low_price_q20` 这个保守的价格下界；`future_low_return_q80` 是较浅、较乐观的分位。负收益才表示回撤，正收益表示稳健未来低点仍高于当前收盘价。兼容字段 `drawdown_*` 等于对应收益取负，实际覆盖率应以测试集校准报告为准，不能把 80% 当成保证概率。
|
||||
| 列 | 含义 |
|
||||
| --- | --- |
|
||||
| `rank` | 按 8H USDT 成交额从高到低的排名 |
|
||||
| `symbol` | 合约符号 |
|
||||
| `latest_bar_start_utc` | 最新完整 8H K 线的 UTC 起始时间 |
|
||||
| `close` | 最新完整 8H K 线收盘价 |
|
||||
| `quote_volume_usdt_8h` | 最新 8H 的 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 对应的价格水平参考 |
|
||||
|
||||
如果预测时 `eligible_for_model` 为 `false`，说明过去 200 根不足以计算 ATR 排名，或显式设置的 ATR 排名门槛未达到，返回的模型数值为 `null`，应跳过该时刻。
|
||||
回撤列是收益的相反数：预测收益为负时表示价格可能低于当前收盘；预测收益为正时，回撤列可能为负，表示未来稳健低点仍高于当前收盘。模型不满足资格条件时，预测字段为空，不应把空值当作零回撤。
|
||||
|
||||
## 特征迭代
|
||||
## 当前模型
|
||||
|
||||
第一轮使用 18 根 K 线的方向、实体/影线占比、收盘在 K 线中的位置、相对波幅、对数收益，以及基于法币成交额的 18 根窗口成交量排名和相对中位数；再加入两个固定的品种画像值：训练期 `ATR/price` 降序前 20% 的中位数、训练期法币成交额对数前 20% 的中位数。所有绝对价格都被转换为比例或滚动相对量，品种画像再用训练品种的均值/标准差标准化。
|
||||
当前模型为 `compact6` 特征版本，使用 146 个特征和 ExtraTrees 点模型，同时使用两个 HistGradientBoosting 分位数模型生成 q20/q80。测试集结果和特征定义见 [`docs/model.md`](docs/model.md)，训练产物报告见 [`artifacts/v1/report.md`](artifacts/v1/report.md)。
|
||||
|
||||
第二轮追加归一化 ATR、RSI、布林带位置/宽度、EMA 距离、趋势收益、滚动波动率和滚动回撤；第三轮追加 18 根窗口的趋势、波幅、方向比例、成交量趋势、收盘位置和指标交互摘要。三轮使用同一批训练/验证/测试边界，选择验证 q80 pinball loss 加覆盖率偏差后的最佳组合，最后只在测试集报告一次。
|
||||
## 测试
|
||||
|
||||
运行标准库回归测试：
|
||||
|
||||
```bash
|
||||
.venv/bin/python -m unittest discover -v
|
||||
.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)：历史实验记录，不是当前运行入口。
|
||||
|
||||
Reference in New Issue
Block a user