使用与数据流

本文是当前代码的运行说明。历史特征实验不在这里维护；它们只用于追溯模型选择过程。

依赖

运行需要：

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。

安装：

python3 -m venv .venv
.venv/bin/pip install -e .

一键更新与预测

./scripts/update_and_predict.sh

脚本调用 python -m cbpred.latest_predict，按以下顺序执行：

检查配置中的 QuestDB 是否可连接；QuestDB 默认不可用时，通过 banbot 的导出命令触发其启动流程。
从数据库筛选 Binance linear 市场、结算币为 USDT、上市至少 730 天且未退市的品种。
调用 banbot 下载最近 36 个月的 1H K 线。
调用 banbot 导出原始 K 线，并只保留连续完整的 8 根 1H K 线聚合成 8H K 线。
写入 data/manifest.json 和 data/raw/*.csv。
加载 artifacts/v1/model.joblib，对清单中的每个品种使用最新完整 8H K 线预测。
按最新 8H USDT 成交额降序写入 predictions/latest_v1/predictions.csv，并写入 report.json。

脚本的默认参数可以覆盖：

./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 边界。

手动命令

准备数据

.venv/bin/python -m cbpred prepare \
  --banbot-config /home/ctyun/ban/banbot/biz/config.yml \
  --out-dir data

只使用已经下载的数据：

.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 记录筛选出的品种、数据范围、数据库类型和被排除的原因。

训练模型

.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 仍会作为当前状态字段输出。

单品种预测

.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。

文件布局

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 桶，这是为了避免特征和未来标签跨越缺口。

验证

./scripts/update_and_predict.sh --help
.venv/bin/python -m unittest discover -q
git diff --check

5.0 KiB Raw Blame History Unescape Escape