135 lines
5.0 KiB
Markdown
135 lines
5.0 KiB
Markdown
# 使用与数据流
|
||
|
||
本文是当前代码的运行说明。历史特征实验不在这里维护；它们只用于追溯模型选择过程。
|
||
|
||
## 依赖
|
||
|
||
运行需要：
|
||
|
||
- Python 3 和本项目的虚拟环境；
|
||
- `pandas`、`numpy`、`scikit-learn`、`joblib` 等项目依赖；
|
||
- Go 和 `/home/ctyun/ban/banbot` 源码；
|
||
- banbot 配置中的 QuestDB 数据库，以及对 Binance 数据的访问。
|
||
|
||
默认配置文件是 `/home/ctyun/ban/banbot/biz/config.yml`。如果路径不同，可通过 `--banbot-config` 和 `--banbot-dir` 覆盖。也可以直接传入 `--dsn`。
|
||
|
||
安装：
|
||
|
||
```bash
|
||
python3 -m venv .venv
|
||
.venv/bin/pip install -e .
|
||
```
|
||
|
||
## 一键更新与预测
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh
|
||
```
|
||
|
||
脚本调用 `python -m cbpred.latest_predict`，按以下顺序执行：
|
||
|
||
1. 检查配置中的 QuestDB 是否可连接；QuestDB 默认不可用时，通过 banbot 的导出命令触发其启动流程。
|
||
2. 从数据库筛选 Binance `linear` 市场、结算币为 USDT、上市至少 730 天且未退市的品种。
|
||
3. 调用 banbot 下载最近 36 个月的 1H K 线。
|
||
4. 调用 banbot 导出原始 K 线，并只保留连续完整的 8 根 1H K 线聚合成 8H K 线。
|
||
5. 写入 `data/manifest.json` 和 `data/raw/*.csv`。
|
||
6. 加载 `artifacts/v1/model.joblib`，对清单中的每个品种使用最新完整 8H K 线预测。
|
||
7. 按最新 8H USDT 成交额降序写入 `predictions/latest_v1/predictions.csv`，并写入 `report.json`。
|
||
|
||
脚本的默认参数可以覆盖：
|
||
|
||
```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 \
|
||
--end 2026-08-23T00:00:00Z
|
||
```
|
||
|
||
`--end` 用于固定数据快照，支持 UTC 日期、ISO 时间或毫秒时间戳。默认使用当前 UTC 时间向下取整到 8H 边界。
|
||
|
||
## 手动命令
|
||
|
||
### 准备数据
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred prepare \
|
||
--banbot-config /home/ctyun/ban/banbot/biz/config.yml \
|
||
--out-dir data
|
||
```
|
||
|
||
只使用已经下载的数据：
|
||
|
||
```bash
|
||
.venv/bin/python -m cbpred prepare \
|
||
--banbot-config /home/ctyun/ban/banbot/biz/config.yml \
|
||
--out-dir data \
|
||
--skip-download
|
||
```
|
||
|
||
`prepare` 的默认范围是最近 36 个月，训练快照前的品种至少上市 730 天，最近 10 个月预留给测试。`manifest.json` 记录筛选出的品种、数据范围、数据库类型和被排除的原因。
|
||
|
||
### 训练模型
|
||
|
||
```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 中最新完整 8H K 线。传入 `--at` 时，时间必须精确匹配一个 8H K 线起始时间，且不能早于模型训练快照。
|
||
|
||
模型需要至少 200 根 8H 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/ # 最近一次批量预测
|
||
```
|
||
|
||
模型版本目录使用 `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 历史不足或该品种没有正式模型画像。
|
||
- 数据只有部分 8H K 线：导出会丢弃不连续或不完整的 8 根 1H 桶，这是为了避免特征和未来标签跨越缺口。
|
||
|
||
## 验证
|
||
|
||
```bash
|
||
./scripts/update_and_predict.sh --help
|
||
.venv/bin/python -m unittest discover -q
|
||
git diff --check
|
||
```
|