diff --git a/docs/USAGE.md b/docs/USAGE.md index 62408e1..29c8ee1 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -1,25 +1,28 @@ # qlib-platform 使用说明 -> 适用代码版本：M1–M5 全部完成（`d9be75a` 及之后）；若文档与代码不一致，以代码与 +> 适用代码版本：M1–M5 全部完成，含 QlibEngine v1（Qlib 数据管线）与 Parquet 导出 +> （HEAD ≈ `bbb5c1e`）；若文档与代码不一致，以代码与 > [ARCHITECTURE.md](./ARCHITECTURE.md) / [ROADMAP.md](./ROADMAP.md) 为准。 > -> 本文覆盖：安装配置、数据同步、启动前后端、研究 API 调用、AI Agent、测试门禁、已知限制。 +> 本文覆盖：安装配置、数据同步、启动前后端、研究 API、研究引擎与 Qlib 接入、 +> AI Agent、测试门禁、已知限制。 --- ## 1. 项目概览（当前完成度） -个人 A 股中低频量化研究平台，当前已完成： +个人 A 股中低频量化研究平台： | 模块 | 位置 / 说明 | |---|---| -| 数据层 | `backend/app/domain`、`backend/app/infrastructure/data_sources`：Tushare 首选 + 新浪备用（Failover 审计），SQLite（未来 MySQL 可切换） | -| 研究引擎 | `backend/app/quant`：ResearchSpec → 因子 → IC/RankIC/分层 → TopK 低频回测 → 标准化 `BacktestResult` | +| 数据层 | `backend/app/domain`、`infrastructure/data_sources`：Tushare 首选 + 新浪备用（Failover 审计）；SQLite 存储 + 日线 Parquet 导出（未来 MySQL 可切换） | +| 研究引擎 | `backend/app/quant`：ResearchSpec → 因子 → IC/RankIC/分层 → TopK 低频回测 → 标准化 `BacktestResult`；**双引擎**：LocalEngine（默认，纯 pandas）与 QlibEngine v1（QLibDataset 数据管线） | +| Qlib 接入 | `quant/qlib_adapter/`：SQLite 行情按官方二进制格式落盘 → `D.features` 读取 → 回测（详见 §6.1 与 docs/QLIB_VERIFICATION.md） | | Web | `frontend/web`：Next.js(TS)+ECharts —— 总览 / 股票池 / 因子研究 / 回测 / 实验 | | 异步与归档 | Job 状态机 + Experiment 自动归档 + 一键复跑 + SSE 进度 | | AI Agent | 受控工具白名单 + LLM 编排（需配置模型 Key） | -**技术栈**：Python 3.12(uv) · FastAPI · SQLAlchemy 2 · Alembic · SQLite · pandas · Next.js 15 · ECharts +**技术栈**：Python 3.12(uv) · FastAPI · SQLAlchemy 2 · Alembic · SQLite · pandas · pyarrow(Parquet) · pyqlib 0.9.8.dev32(源码安装) · LightGBM · Next.js 15 · ECharts --- @@ -32,7 +35,7 @@ python3 -m pip install uv # 1) 后端依赖（backend/.python-version 固定 3.12） cd backend -uv sync # 基础依赖 +uv sync # 基础依赖（含 Qlib/qlib 源码安装依赖） uv sync --extra datasource-tushare # 数据同步需要 Tushare SDK（首次） ``` @@ -44,6 +47,9 @@ pnpm install # 依赖使用 npmmirror 镜像时较快 cp .env.local.example .env.local # NEXT_PUBLIC_API_BASE 默认 http://127.0.0.1:8000/api ``` +> Qlib 安装说明：本机（Linux aarch64 + CPython 3.12）经源码 git 安装并固定 commit， +> 见 `backend/pyproject.toml` 与 [docs/QLIB_VERIFICATION.md](./QLIB_VERIFICATION.md)。 + --- ## 3. 配置 @@ -54,27 +60,25 @@ cp .env.local.example .env.local # NEXT_PUBLIC_API_BASE 默认 http://127.0.0. cp .env.example .env ``` -按需填写： - | 变量 | 必填 | 说明 | |---|---|---| | `TUSHARE_TOKEN` | 同步数据时必填 | Tushare Pro token | -| `LLM_API_KEY` | 使用 Agent 时必填 | 大模型 API Key | +| `LLM_API_KEY` | 使用 Agent 时必填 | 大模型 API Key（URL/模型名在 config.yaml） | | `DATABASE_URL` | 否 | 留空使用 SQLite `<项目根>/data/quant.db` | | `APP_SECRET_KEY` | 否 | 应用密钥（未接登录，可暂不改） | -> 约定：**密钥只放 `.env`**；URL、模型名等可配置项放 `config.yaml`（见下）。`.env` 已被 gitignore，严禁提交。 +> 约定：**密钥只放 `.env`**；URL、模型名等可配置项放 `config.yaml`。`.env` 已被 gitignore，严禁提交。 ### 3.2 根目录 `config.yaml`（可配置项，可入库） -常用字段： +常用字段（节选，完整见仓库根 config.yaml）： ```yaml app: {name, version, debug, secret_key_env} -api: {prefix: "/api"} # API 前缀 +api: {prefix: "/api"} database: {url_env: "DATABASE_URL", echo: false, migrations_dir: ...} data_source: {primary: "tushare", fallback: "sina", tushare_token_env: "TUSHARE_TOKEN"} -storage: {parquet_dir, qlib_dir, ...} # 相对项目根 +storage: {parquet_dir: "data/parquet", qlib_dir: "data/qlib", ...} # 相对项目根 agent: llm: # ← AI Agent 模型接入 base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1" # URL 在这里配 @@ -82,9 +86,9 @@ agent: api_key_env: "LLM_API_KEY" # Key 仍从 .env 读 ``` -- **换模型**：改 `config.yaml → agent.llm.model`（例如 `deepseek-chat` / `qwen-max` 等 - OpenAI 兼容接口模型），并同步 `base_url`（如有平台差异）。 -- 也可以用 `.env` 的 `LLM_BASE_URL` / `LLM_MODEL` 覆盖 yaml 值（两种都支持，env 优先）。 +- **换模型**：改 `config.yaml → agent.llm.model`（如 `qwen-max` / `deepseek-chat` 等 + OpenAI 兼容接口模型），并按平台同步 `base_url`。 +- 也可用 `.env` 的 `LLM_BASE_URL` / `LLM_MODEL` 覆盖 yaml（env 优先）。 ### 3.3 数据库迁移 @@ -98,7 +102,7 @@ uv run alembic upgrade head --- -## 4. 数据同步 +## 4. 数据同步与导出 ```bash cd backend @@ -106,17 +110,17 @@ uv run python -m app.cli.sync basic # 股票基础信息（ uv run python -m app.cli.sync calendar --start 20240101 --end 20241231 uv run python -m app.cli.sync daily --symbols 600519.SH,000858.SZ --start 20230101 uv run python -m app.cli.sync daily --all --start 20240101 --resume # 全市场 + 断点续传 -uv run python -m app.cli.sync financial --symbols 600519.SH +uv run python -m app.cli.sync financial --all # 财务指标快照 uv run python -m app.cli.sync verify --symbol 600519.SH # 新浪交叉验证 -uv run python -m app.cli.sync export --years 2024 # 日线按年导出 Parquet（默认全部） +uv run python -m app.cli.sync export [--years 2023,2024] # 日线按年导出 Parquet ``` -说明： - - 每次拉取写入 `sync_log` 审计（来源 / 成功与否 / 行数 / 区间），禁止静默切换数据源。 - `daily` 同时写入日线与复权因子；`--resume` 从本地最新交易日续传。 -- 新浪（`verify`）仅用于交叉验证，返回**前复权**口径，不会并入不复权主库。 +- 新浪（`verify`）仅交叉验证，返回**前复权**口径，不会并入不复权主库。 - 财务指标带 `announce_date`（公告日），研究侧只允许使用已公告数据（防未来函数）。 +- `export`：`data/parquet/stock_daily/.parquet`（列：symbol/trade_date/ohlc/volume/amount）， + 由 pyarrow 写出，可直接用 pandas 读取分析，或作为 Qlib 等引擎的后续数据源。 --- @@ -139,9 +143,35 @@ pnpm dev --- -## 6. 研究 API（curl 示例） +## 6. 研究 API 与研究引擎 -所有研究输入 = ResearchSpec（统一结构，前端 / API / Agent 同构）： +### 6.1 研究引擎：LocalEngine（默认）与 QlibEngine v1 + +服务通过 `QuantEngine` Protocol 注入引擎（`backend/app/quant/engine.py`）： + +- **LocalEngine**（默认，研究服务与 API 使用）：纯 pandas —— 因子注册表计算 → 截面 + z-score 复合 → TopK 月/周调仓回测。无需 Qlib 数据。 +- **QlibEngine v1**（`quant/qlib_adapter/engine.py`）：同一套因子与记账规则，但行情经 + **QlibDataset** 供给 —— 把本地行情按 qlib 官方二进制格式落盘（默认 `data/qlib`， + 可注入 `QlibEngine(qlib_dir=...)`）→ `qlib.init` + `D.features` 读取 close → 回测。 + +切换示例（代码内）： + +```python +from app.quant.engine import LocalEngine # 默认 +from app.quant.qlib_adapter.engine import QlibEngine # Qlib 数据管线引擎 +from app.quant.service import ResearchService + +engine = LocalEngine() # 或 QlibEngine() +service = ResearchService(stock_repo, daily_repo, engine) +``` + +注意：Qlib bin 以 float32 存储，QlibEngine 结果与 LocalEngine 存在极小数值差 +（真实 20 股对照：-12.81% vs -12.97%），属预期精度差异，不影响结论方向。 + +### 6.2 API（curl 示例） + +研究输入统一为 ResearchSpec（前端 / API / Agent 同构）： ```bash curl -X POST http://127.0.0.1:8000/api/backtests \ @@ -158,15 +188,17 @@ curl -X POST http://127.0.0.1:8000/api/backtests \ | 端点 | 说明 | |---|---| +| `GET /api/health` | 健康检查 | | `GET /api/stocks?q=600519&limit=20` | 股票列表/搜索 | -| `GET /api/factors` | 因子目录（含公式/lookback/方向） | +| `GET /api/stocks/{symbol}` | 单只股票详情 | +| `GET /api/factors` | 因子目录（公式/lookback/方向） | | `POST /api/factor-tests` | 同步单因子测试 → `FactorTestReport` | -| `POST /api/backtests` | 同步回测（小样本）→ `BacktestResult` | +| `POST /api/backtests` | 同步回测 → `BacktestResult`（默认 LocalEngine） | | `GET /api/backtests/last` | 最近一次同步回测 | | `POST /api/jobs` | 创建异步 Job（同 spec），返回 `{"job_id","status":"queued"}` | | `GET /api/jobs/{id}` | 查询状态；成功时内嵌 `result` | | `GET /api/jobs/{id}/events` | SSE 进度（`curl -N ...`） | -| `GET /api/experiments` | 实验归档列表（含收益摘要/代码版本） | +| `GET /api/experiments` | 实验归档列表（收益摘要/代码版本） | | `GET /api/experiments/{id}` | 实验详情（spec + 完整结果） | | `POST /api/experiments/{id}/rerun` | 一键复跑 → 新 Job | | `POST /api/agent/chat` | AI 研究助手（见 §7） | @@ -179,8 +211,8 @@ curl -X POST http://127.0.0.1:8000/api/backtests \ ## 7. AI Agent -前置：`config.yaml → agent.llm`（URL/模型名已配好，默认阿里云百炼 qwen-plus）， -`.env` 中设置 `LLM_API_KEY`。 +前置：`config.yaml → agent.llm`（URL/模型名默认百炼兼容端点 + qwen-plus）， +`.env` 中设置 `LLM_API_KEY`（仅需 Key）。 ```bash curl -X POST http://127.0.0.1:8000/api/agent/chat \ @@ -203,7 +235,7 @@ curl -X POST http://127.0.0.1:8000/api/agent/chat \ Agent 能力边界（内置受控工具，只读）： - `search_stocks` / `get_market_data`：查询 -- `test_factor` / `run_backtest`：研究并自动归档 Experiment +- `test_factor` / `run_backtest`：研究并**自动归档 Experiment** - `get_experiment` / `compare_experiments`：读取/对比归档 **不提供** shell / 任意代码执行 / 删改数据 / 修改配置与凭证。未配置 Key 时接口返回 @@ -217,7 +249,7 @@ Agent 能力边界（内置受控工具，只读）： ```bash cd backend uv run ruff check app tests && uv run ruff format --check app tests -uv run pytest # 当前 79 passed +uv run pytest # 当前 86 passed cd frontend/web pnpm run typecheck @@ -226,25 +258,26 @@ pnpm run build 覆盖重点：Provider 归一化与 Failover 审计、Repository 幂等与「未来函数阻断」 （`as_of_date`/`announce_date`）、Alembic 迁移、因子/IC/分层、回测记账与成本/涨跌停、 -Job 状态机与 Experiment 归档、Agent 工具白名单与编排、API 端到端。 +**QlibEngine 数据管线**（bin 落盘格式/roundtrip/端到端回测）、Job 状态机与 Experiment +归档、Agent 工具白名单与编排、LLM 配置加载、API 端到端。 --- ## 9. 已知限制与说明 -1. **Qlib 引擎（v1 数据管线）**：pyqlib 已通过源码安装可用（qlib 0.9.8.dev32，见 - docs/QLIB_VERIFICATION.md）。`app/quant/qlib_adapter/` 提供 QlibEngine：本地行情按官方 - 二进制格式落盘 QlibDataset → `D.features` 读取 → TopK 因子回测（与 LocalEngine 同记账 - 规则）。默认研究引擎仍为 LocalEngine；切换只需向 ResearchService 注入 QlibEngine。 - Alpha158 特征 + LightGBM 预测信号（walk-forward）为下一步 TODO。 -2. **数据规模**：仓库自带示例数据为 20 只权重股 2023–2024 日线；`sync --all` 可扩展 - 全市场，注意耗时与 Tushare 积分限制。 +1. **QlibEngine v1 边界**：数据管线（落盘→D.features→回测）已打通，见 + docs/QLIB_VERIFICATION.md；**Alpha158 全特征 + LightGBM walk-forward 预测信号仍未实现**， + 当前 QlibEngine 使用共享因子分回测（ROADMAP §2 备注为该增强 TODO）。 +2. **数据规模**：仓库自带示例数据为 20 只权重股 2023–2024 日线（`sync --all` 可扩展 + 全市场，注意耗时与 Tushare 积分限制）。 3. **回测为近似建模**：涨跌停按收盘相对上一有效收盘判定、成交假设调仓日收盘，未建模 开盘一字 / 集合竞价 / 盘中路径（详见结果 `unimplemented`）。 4. **Agent 结论质量取决于模型**：编排只保证「经受控工具 + 归档留痕」，研究有效性判断 - 需要人复核；接不同厂商模型请核对 `base_url` 与 `model` 命名。 -5. **SSE 与 Job 为单进程内存/本地执行**：重启进程后未完成 Job 需重新提交（后续如需 - 可换 Redis/Celery，第一阶段刻意不引入）。 + 需要人复核；接不同厂商模型请核对 `config.yaml` 的 `base_url` 与 `model` 命名。 +5. **SSE 与 Job 为单进程本地执行**：重启进程后未完成 Job 需重新提交（第一阶段刻意 + 不引入 Redis/Celery）。 +6. **Qlib 数据为进程内单例初始化**：`qlib.init` 以 provider_uri 为键幂等，切换不同 + qlib_dir 会重新初始化；测试环境建议注入独立临时目录。 --- @@ -252,7 +285,12 @@ Job 状态机与 Experiment 归档、Agent 工具白名单与编排、API 端到 - **同步报「缺少 TUSHARE_TOKEN」**：把 token 填入根目录 `.env` 的 `TUSHARE_TOKEN`。 - **同步报「未安装 tushare 客户端」**：`cd backend && uv sync --extra datasource-tushare`。 -- **Agent 报 400「未配置 LLM」**：`.env` 设置 `LLM_API_KEY`；换模型改 `config.yaml`。 +- **Agent 报 400「未配置 LLM」**：`.env` 设置 `LLM_API_KEY`；换模型改 `config.yaml` 的 + `agent.llm.model` / `base_url`。 +- **回测默认用哪个引擎？怎么切 Qlib 引擎**：默认 LocalEngine（纯 pandas）。需要在代码 + 中向 `ResearchService` 注入 `QlibEngine()` 启用 QlibDataset 数据管线（见 §6.1）。 +- **Parquet 导出文件在哪、怎么读**：`data/parquet/stock_daily/.parquet`； + `pd.read_parquet(...)` 直接读取（pyarrow 已随依赖安装）。 - **前端连不上后端**：确认后端运行在 8000、`frontend/web/.env.local` 的 `NEXT_PUBLIC_API_BASE` 正确、CORS 白名单含 `localhost:3000 / 127.0.0.1:3000`。 - **数据库被改动想重置**：删除 `data/quant.db` 后 `uv run alembic upgrade head` 重建