155 lines
6.3 KiB
Markdown
155 lines
6.3 KiB
Markdown
# 使用与数据流
|
||
|
||
本文是当前代码的运行说明。历史特征实验不在这里维护；它们只用于追溯模型选择过程。
|
||
|
||
## 依赖
|
||
|
||
运行需要：
|
||
|
||
- Python 3 和本项目的虚拟环境；
|
||
- `pandas`、`numpy`、`scikit-learn`、`joblib` 等项目依赖；
|
||
- Go 和 `/data/ban/banbot` 源码；
|
||
- banbot 配置中的 TimescaleDB（优先）或 QuestDB 数据库，以及对 Binance 数据的访问。
|
||
|
||
一键脚本优先使用 `config/banbot.local.yml`，其次使用 banbot 同级 `data/config.timescale.yml` 或 `biz/config.timescale.yml` 中的 TimescaleDB 配置，最后使用 `biz/config.yml`。本机 banbot 目录会自动查找，也可通过 `--banbot-dir`、`--banbot-config`，或 `CBPRED_BANBOT_DIR`、`CBPRED_BANBOT_CONFIG` 环境变量指定。
|
||
|
||
`--dsn`（或 `CBPRED_DSN`）覆盖数据库连接；`--db-type timescale`（或 `CBPRED_DB_TYPE=timescale`）明确使用 TimescaleDB。自动检测优先选择 `exsymbol` 表对应的 TimescaleDB。Python 筛选、Go 下载和导出使用同一连接和数据库类型；连接失败会报错。只有 QuestDB 配置会尝试自动启动 QuestDB。
|
||
|
||
安装：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -e .
|
||
```
|
||
|
||
## 一键更新与预测
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh
|
||
```
|
||
|
||
脚本调用 `python -m cbpred.latest_predict`，按以下顺序执行：
|
||
|
||
1. 检查所选数据库是否可连接；TimescaleDB 不可用时直接报错，QuestDB 配置可通过 banbot 的导出命令触发其启动流程。
|
||
2. 从数据库筛选 Binance `linear` 市场、结算币为 USDT、上市至少 730 天且未退市的品种。
|
||
3. 调用 banbot 下载最近 36 个月的 1H K 线。
|
||
4. 调用 banbot 读取 1H 历史，并按 UTC 边界聚合请求周期的完整 K 线；默认是 8H，也可以通过 `--timeframe 1d` 导出日线。缺少小时数据的周期会被排除。
|
||
5. 写入 `data/manifest.json` 和 `data/raw/*.csv`。
|
||
6. 加载 `artifacts/v1/model.joblib`，对清单中的每个品种使用最新完整 8H K 线预测。
|
||
7. 按最新 8H USDT 成交额降序写入 `predictions/latest_v1_8h/predictions.csv`，并写入 `report.json`。
|
||
|
||
分别生成 8H 和日线预测：
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh --timeframe 8h --db-type timescale
|
||
./scripts/update_and_predict.sh --timeframe 1d --db-type timescale
|
||
```
|
||
|
||
两个 CSV 分别位于 `predictions/latest_v1_8h/predictions.csv` 和 `predictions/latest_v1_1d/predictions.csv`。其中 `price_level_reached_80pct` 是预测的 80% 命中位置，`price_level_cap_80pct` 是回调上限参考位置。
|
||
|
||
脚本的默认参数可以覆盖：
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh \
|
||
--banbot-dir /path/to/banbot \
|
||
--banbot-config /path/to/config.yml \
|
||
--data-dir data \
|
||
--artifact artifacts/v1/model.joblib \
|
||
--output-dir predictions/latest_v1_8h \
|
||
--end 2026-08-23T00:00:00Z
|
||
```
|
||
|
||
`--end` 用于固定数据快照，支持 UTC 日期、ISO 时间或毫秒时间戳。默认按 `--timeframe` 向下取整到对应边界。
|
||
|
||
## 手动命令
|
||
|
||
### 准备数据
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred prepare \
|
||
--banbot-config /data/ban/banbot/biz/config.yml \
|
||
--out-dir data
|
||
```
|
||
|
||
只使用已经下载的数据：
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred prepare \
|
||
--banbot-config /data/ban/banbot/biz/config.yml \
|
||
--out-dir data \
|
||
--skip-download
|
||
```
|
||
|
||
`prepare` 的默认范围是最近 36 个月，训练快照前的品种至少上市 730 天，最近 10 个月预留给测试。`manifest.json` 记录筛选出的品种、数据范围、数据库类型和被排除的原因。
|
||
|
||
导出日线时使用独立目录，避免覆盖 8H 快照：
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred prepare \
|
||
--timeframe 1d \
|
||
--out-dir data_1d \
|
||
--banbot-config /data/ban/banbot/biz/config.yml
|
||
```
|
||
|
||
### 训练模型
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred train \
|
||
--data-dir data \
|
||
--artifact-dir artifacts/v1
|
||
```
|
||
|
||
训练会输出阶段和候选模型进度到 stderr，并在 `artifacts/v1/` 写入：
|
||
|
||
- `model.joblib`：当前可供预测的模型；
|
||
- `report.json`：机器可读的训练协议和评估指标；
|
||
- `report.md`：人类可读的评估摘要。
|
||
|
||
`--volatility-rank-threshold` 可以做 ATR 排名过滤实验。正式 `v1` 模型的阈值是 `0.0`，因此不会过滤低波动样本；`atr_rank_200_pct` 仍会作为当前状态字段输出。
|
||
|
||
### 单品种预测
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred predict \
|
||
--artifact artifacts/v1/model.joblib \
|
||
--csv data/raw/123_BTC_USDT_USDT.csv \
|
||
--symbol BTC/USDT:USDT
|
||
```
|
||
|
||
不传 `--at` 时使用 CSV 中最新完整周期 K 线。传入 `--at` 时，时间必须精确匹配一个模型周期 K 线起始时间，且不能早于模型训练快照。
|
||
|
||
模型需要至少 200 根对应周期 K 线计算 ATR 排名，并需要模型中保存的该品种训练画像。`eligible_for_model` 为 `false` 时，预测数值返回空值，并包含 `skip_reason`。
|
||
|
||
## 文件布局
|
||
|
||
```text
|
||
cbpred/
|
||
├── cbpred/ # Python CLI、特征和训练/预测管线
|
||
├── scripts/update_and_predict.sh # 一键入口
|
||
├── data/
|
||
│ ├── manifest.json # 数据快照和品种清单
|
||
│ └── raw/*.csv # 导出的 8H OHLCV
|
||
├── artifacts/
|
||
│ └── v1/ # 唯一正式模型版本
|
||
└── predictions/
|
||
└── latest_v1_8h/ # 最近一次 8H 批量预测
|
||
```
|
||
|
||
模型版本目录使用 `v1` 形式维护。历史实验可以保留在文档或实验输出目录中，但不应作为默认预测模型或在项目根目录新增多个 `artifacts_*` 入口。
|
||
|
||
## 故障排查
|
||
|
||
- `missing virtualenv Python`：先执行安装命令，确认 `.venv/bin/python` 存在。
|
||
- QuestDB 连接失败：检查 banbot 配置中的数据库地址、QuestDB 服务和端口；一键脚本只对默认 QuestDB 端口尝试触发 banbot 启动。
|
||
- `missing data/manifest.json`：先运行 `prepare`，或确认一键脚本没有在下载/导出阶段失败。
|
||
- 某品种预测为空：检查 `eligible_for_model` 和 `skip_reason`，通常是 200 根 ATR 历史不足或该品种没有正式模型画像。
|
||
- 数据只有部分 K 线：导出和训练会丢弃不连续或不完整的 bar，这是为了避免特征和未来标签跨越缺口。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh --help
|
||
.venv/bin/python -m unittest discover -q
|
||
git diff --check
|
||
```
|