qka 1.2.4.dev3__tar.gz → 1.3.1.dev5__tar.gz

{qka-1.2.4.dev3 → qka-1.3.1.dev5}/.gitignore

@@ -179,4 +179,7 @@ _momentum_output.txt
 
 # 示例和测试（不入库）
 examples/
-tests/
+tests/
+
+# 回测报告
+reports/

{qka-1.2.4.dev3 → qka-1.3.1.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qka
-Version: 1.2.4.dev3
+Version: 1.3.1.dev5
 Summary: 快捷量化助手（Quick Quantitative Assistant）- 简洁易用的A股量化交易框架
 Project-URL: Home, https://github.com/zsrl/qka
 Project-URL: Documentation, https://zsrl.github.io/qka

qka-1.3.1.dev5/docs/advanced/performance.md

@@ -0,0 +1,203 @@
+# 性能优化
+
+QKA 回测引擎的 **dask 分区迭代** 架构，使其能够在一台笔记本上高效处理数百只股票数年的数据。
+
+---
+
+## 问题：大规模回测的内存瓶颈
+
+传统回测引擎的典型做法：
+
+```python
+# 常规做法：一次性加载所有数据
+all_data = pd.read_parquet('data/*.parquet')
+# all_data 可能在内存中占 2-3 GB
+for date in all_data.index.unique():
+    run_strategy(date, all_data.loc[date])
+```
+
+当股票数量增多时，内存占用线性增长：
+
+| 股票数 | 日线数据（5年） | 内存占用 |
+|--------|----------------|----------|
+| 10 只  | ~1250k 行     | ~100 MB  |
+| 100 只 | ~12500k 行    | ~1 GB    |
+| 300 只 | ~37500k 行    | ~3+ GB   |
+
+3 GB 对现代电脑不算大，但加上回测过程中的副本、numpy 数组、中间结果，很容易吃掉 8-12 GB。
+
+---
+
+## 方案：dask 分区迭代
+
+QKA 的解决方案绕开了"全量加载"这个前提：
+
+### 1. 数据存储：每只股票独立 parquet
+
+```
+datadir/baostock/1d/qfq/
+├── 000001.SZ.parquet    # 平安银行，~1MB
+├── 600000.SH.parquet    # 浦发银行，~1MB
+└── ...                  # 每只股票独立文件
+```
+
+优势：
+- **增量更新**：新股票只需下载自己的文件，不影响已有数据
+- **独立压缩**：每只股票独立列式存储，读取某个因子时只加载需要的列
+
+### 2. 加载：dask 构建 lazy 计算图
+
+```python
+import dask.dataframe as dd
+
+# 读取每个 parquet，添加 symbol 列
+parts = []
+for symbol in symbols:
+    df = dd.read_parquet(f'{symbol}.parquet')
+    df['symbol'] = symbol
+    parts.append(df)
+
+# 合并 → 此时仍是 lazy（0 内存占用）
+merged = dd.concat(parts)
+```
+
+到目前为止，**没有读取任何实际数据**。dask 只记录了"去哪里读什么文件"的计算图。
+
+### 3. 变换：字符串列名
+
+```python
+# 将 symbol+factor 拼合为扁平列名
+for factor in factors:
+    merged[f'{symbol}_{factor}'] = ...
+```
+
+使用 `{symbol}_{factor}` 字符串列名而非 MultiIndex，是因为 dask 的 MultiIndex 在 `.compute()` 后存在信息丢失的 bug。
+
+### 4. 分区：按时间排序，分批计算
+
+```python
+# 按日期排序分区，每区约 500 行
+npartitions = max(1, total_rows // 500)
+merged = merged.set_index('date', npartitions=npartitions)
+```
+
+```
+                        全部数据（~36000 行）
+  ┌────────┬────────┬────────┬────────┬────────┬────────┬────────┐
+  │分区 0  │分区 1  │分区 2  │分区 3  │分区 4  │分区 5  │分区 6  │
+  │~500 行 │~500 行 │~500 行 │~500 行 │~500 行 │~500 行 │~500 行 │
+  │第1-2天 │第2-3天 │...     │...     │...     │...     │最后几天│
+  └────────┴────────┴────────┴────────┴────────┴────────┴────────┘
+       │         │         │
+       ▼         ▼         ▼
+   分批 compute() → 每批~500行 → 内存释放
+```
+
+### 5. 迭代：逐分区 compute + DataAccessor 接续
+
+```python
+for i in range(npartitions):
+    partition = merged.get_partition(i).compute()
+    
+    for date, row in partition.iterrows():
+        factors = parse_row(row)  # 还原 {factor: {symbol: value}}
+        
+        for factor, data in factors.items():
+            strategy._data.push(date, factor, data)
+        
+        strategy.on_bar(date)
+        broker.on_bar()
+    
+    # 分区处理完后，partition 变量被回收
+    # DataAccessor 内部缓存（deque）保留历史窗口
+```
+
+关键点：
+- **内存峰值 = 单分区（~500 行）+ DataAccessor 缓存（~250 bar）**
+- 与总股票数解耦，只与分区大小有关
+- DataAccessor 的 `deque(maxlen=N)` 自动丢弃过期数据
+
+### 6. DataAccessor：跨分区缓存
+
+```python
+class DataAccessor:
+    def __init__(self, max_window=250):
+        self._buffer = defaultdict(
+            lambda: defaultdict(
+                lambda: deque(maxlen=max_window)
+            )
+        )
+        self._dates = deque(maxlen=max_window)
+    
+    def push(self, date, factor, data):
+        # 记录日期（去重）
+        if date != self._last_date:
+            self._dates.append(date)
+            self._last_date = date
+        # 推入每个股票的值
+        for symbol, value in data.items():
+            self._buffer[factor][symbol].append(value)
+    
+    def get(self, factor):
+        # 返回最新横截面
+        return pd.Series({
+            sym: vals[-1] 
+            for sym, vals in self._buffer[factor].items()
+        })
+    
+    def history(self, factor, window):
+        # 返回历史 DataFrame
+        data = {
+            sym: list(vals)[-window:]
+            for sym, vals in self._buffer[factor].items()
+        }
+        return pd.DataFrame(data, index=list(self._dates)[-window:])
+```
+
+DataAccessor 的生命周期跨越所有分区——它在 `Backtest.run()` 开始时创建，在回测结束时销毁。
+
+---
+
+## 性能对比
+
+在真实数据上的测试（3 只股票，8604 bar）：
+
+| 方式 | 内存峰值 | 耗时 |
+|------|----------|------|
+| 传统 pandas 全量加载 | ~300 MB | 8-10s |
+| dask 分区迭代（500行/区） | ~5 MB | 11s |
+
+性能差异在 300 只股票时会更加显著：
+
+| 股票数 | 传统方式 | dask 分区 | 优势 |
+|--------|----------|-----------|------|
+| 10 只  | ~100 MB  | ~5 MB     | 20x 内存 |
+| 100 只 | ~1 GB    | ~5 MB     | 200x 内存 |
+| 300 只 | ~3+ GB   | ~5 MB     | 600x+ 内存 |
+
+!!! tip "不在本地运行？"
+    QKA Cloud 使用轻量级沙箱执行回测，dask 分区迭代保证即使在小内存服务器上也能稳定运行 300+ 只股票。
+
+---
+
+## 实际建议
+
+- **< 50 只股票**：用默认模式即可，dask 不会有明显优势
+- **50-200 只股票**：dask 分区迭代自动启用（`Data.get(lazy=True)`），无需额外配置
+- **200+ 只股票**：强烈建议使用，内存占用几乎不变，仅增加少许计算时间
+
+---
+
+## 为什么不直接用 pandas？
+
+pandas 在 300 只股票 × 5 年数据时已经需要 3+ GB 内存。回测过程中还有：
+
+- 策略内部的数据副本（如计算均线时的 rolling 窗口）
+- Broker 的交易记录 DataFrame
+- 多只股票的中间计算结果
+
+这些都叠加在初始数据之上，很容易超过 8 GB。
+
+**dask 的分区迭代将"所有数据都在内存"的前提改为"只有当前窗口的数据在内存"**，从根本上解决了内存问题。
+
+而 DataAccessor 的滚动窗口缓存（deque）确保了策略可以正常查询历史数据，不受分区边界的限制。

qka-1.3.1.dev5/docs/getting-started/concepts.md

@@ -0,0 +1,175 @@
+# 核心概念
+
+了解 QKA 的架构设计和核心抽象。
+
+---
+
+## 整体架构
+
+```
+qka/
+├── core/               ← 核心模块
+│   ├── data.py         # 数据获取与缓存
+│   ├── backtest.py     # 回测引擎（含 dask 分区迭代）
+│   ├── strategy.py     # 策略基类
+│   ├── accessor.py     # 滚动窗口数据访问器（DataAccessor）
+│   ├── broker.py       # 虚拟经纪商（交易执行 + 费用计算）
+│   └── report.py       # HTML 报告生成
+├── brokers/            # QMT 实盘对接
+├── mcp/                # MCP 服务
+├── server/             # Web 服务
+├── utils/              # 工具模块
+└── cli.py              # 命令行
+```
+
+---
+
+## 核心流程
+
+```
+Data ──> Backtest.run() ──> dask 分区迭代 ──> Strategy.on_bar(date) ──> Broker.buy/sell()
+                    │                                                         │
+                    v                                                         v
+               summary() / report()                              DataAccessor (self.get / self.history)
+```
+
+**流程说明：**
+
+1. **`Data`** 从 baostock 下载并缓存数据（每只股票独立 parquet）
+2. **`Backtest`** 用 dask 合并为 lazy DataFrame，按时间分区分批计算
+3. 每个分区 compute() 后，逐 bar 调用 `strategy.on_bar(date)`
+4. **`Strategy.on_bar(date)`** 用 `self.get('close')` / `self.history('close', 20)` 获取数据
+5. **`Broker.buy/sell()`** 执行交易，自动扣费（佣金 + 印花税 + 滑点）
+6. 回测结束后，**`summary()`** 和 **`report()`** 输出结果
+
+---
+
+## 关键抽象
+
+### `DataAccessor` — 滚动窗口数据访问器
+
+DataAccessor 是策略访问数据的中枢。它在回测过程中维护一个滚动窗口缓存：
+
+```
+                        push(date, 'close', {symbol: value})
+                                   │
+                                   ▼
+           ┌─────────────────────────────────────┐
+           │      DataAccessor 内部缓存            │
+           │                                      │
+           │   close: {                            │
+           │     '000001.SZ': deque(maxlen=250),   │
+           │     '600000.SH': deque(maxlen=250),   │
+           │     ...                               │
+           │   }                                   │
+           │   volume: { ... }                     │
+           └─────────────────────────────────────┘
+                    │               │
+                    ▼               ▼
+            self.get()        self.history()
+            (横截面)          (时间序列)
+```
+
+#### `self.get(factor)` — 横截面数据
+
+返回**当前 bar** 所有股票的某个因子值：
+
+```python
+close = self.get('close')
+# pd.Series:
+# 000001.SZ    10.50
+# 600000.SH     8.32
+# 000002.SZ    15.68
+```
+
+#### `self.history(factor, window)` — 历史序列
+
+返回过去 N 个交易日的历史数据：
+
+```python
+hist = self.history('close', 20)
+# pd.DataFrame，行=日期，列=股票代码：
+#              000001.SZ  600000.SH  000002.SZ
+# 2024-01-02      10.2       8.12      15.21
+# 2024-01-03      10.5       8.32      15.68
+# ...              ...        ...        ...
+```
+
+---
+
+### `Broker` — 虚拟经纪商
+
+管理资金、持仓和交易，自动处理：
+
+| 费用 | 方向 | 默认费率 | 最低收费 |
+|------|------|----------|----------|
+| 佣金 | 双向 | 万2.5 | 5 元 |
+| 印花税 | 卖出 | 万5 | 无 |
+| 滑点 | 双向 | 0.1% | 无 |
+
+可在 `Broker` 初始化时自定义：
+
+```python
+self.broker = Broker(
+    initial_cash=1_000_000,
+    commission_rate=0.0001,      # 万1
+    stamp_duty_rate=0.0005,      # 万5（A股固定）
+    slippage=0.0005,             # 0.05%
+)
+```
+
+---
+
+### `Backtest` 三件套
+
+| 方法 | 功能 |
+|------|------|
+| `run(benchmark=None)` | 执行回测，可选基准对比 |
+| `summary()` | 打印绩效指标，返回 dict |
+| `report(title='', output_path=None)` | 生成自包含 HTML 报告 |
+
+---
+
+## 数据存储模型
+
+每只股票的数据独立存储为 parquet 文件：
+
+```
+datadir/
+└── baostock/
+    └── 1d/
+        └── qfq/
+            ├── 000001.SZ.parquet
+            ├── 600000.SH.parquet
+            └── ...
+```
+
+回测时，dask 将所有 parquet 合并为 lazy DataFrame。列名格式为 `{symbol}_{factor}`：
+
+| 列名 | 含义 |
+|------|------|
+| `000001.SZ_close` | 平安银行收盘价 |
+| `000001.SZ_volume` | 平安银行成交量 |
+| `600000.SH_close` | 浦发银行收盘价 |
+
+---
+
+## 性能原理
+
+QKA 的回测引擎使用 **dask 分区迭代** 处理大规模数据：
+
+- **每只股票独立存储** → 增量下载天然支持
+- **dask 合并** → 仅保存计算图，不加载到内存
+- **按时间分区** → 每个分区约 500 bar，逐批 compute()
+- **DataAccessor 跨分区** → deque 缓存延续历史数据
+
+这种设计让 QKA 可以高效处理数百只股票数年数据，同时保持单机运行。详见 [性能优化](../advanced/performance.md)。
+
+---
+
+## 设计原则
+
+1. **开箱即用** — 三行代码跑回测，不折腾环境
+2. **真实成本** — 佣金、印花税、滑点默认开启，回测结果贴近实盘
+3. **结果可见** — `bt.report()` 生成自包含 HTML，手机 PC 都能看
+4. **专注 A 股** — 费率、交易规则、基准对比都针对 A 股市场

qka-1.3.1.dev5/docs/getting-started/first-strategy.md

@@ -0,0 +1,201 @@
+# 第一个策略
+
+本指南带你从零跑通第一个策略。整个过程只需要几步。
+
+---
+
+## 步骤 1：获取数据
+
+```python
+from qka import Data
+
+data = Data(symbols=['000001.SZ'])   # 平安银行
+```
+
+`Data` 会自动从 **baostock** 下载数据并缓存到本地（`datadir/` 目录），下次直接读缓存，不用重复下载。
+
+---
+
+## 步骤 2：定义策略
+
+所有策略都继承 `Strategy` 基类，实现 `on_bar(self, date)` 方法：
+
+```python
+from qka import Strategy, Broker
+
+class BuyAndHold(Strategy):
+    """买入 100 股平安银行并持有"""
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)  # 10万元本金
+        self.bought = False
+
+    def on_bar(self, date):
+        """
+        每个交易日调用一次。
+
+        用 self.get() 获取当前行情，self.history() 获取历史序列。
+
+        Args:
+            date: 当前交易日（pd.Timestamp）
+        """
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+        if not self.bought and '000001.SZ' in close.index:
+            price = float(close['000001.SZ'])
+            if price > 0:
+                self.broker.buy('000001.SZ', price, 100)
+                self.bought = True
+```
+
+### 关键 API
+
+| 方法 | 功能 | 返回 |
+|------|------|------|
+| `self.get('close')` | 当前 bar 所有股票收盘价 | `pd.Series`（index=股票代码） |
+| `self.history('close', 20)` | 过去 N 日收盘价历史 | `pd.DataFrame`（行=日期，列=股票代码） |
+
+!!! tip "不再是闭包"
+    与旧版本不同，`on_bar` 不再接收 `get` 参数。所有数据通过 `self.get()` 和 `self.history()` 访问，代码更简洁一致。
+
+---
+
+## 步骤 3：运行回测
+
+```python
+from qka import Backtest
+
+bt = Backtest(data, BuyAndHold())
+bt.run(benchmark='000300.SH')   # 对比沪深300
+```
+
+`bt.run()` 会：
+1. 按日期遍历所有数据
+2. 每天调用策略的 `on_bar(date)` 方法
+3. 自动记录资金、持仓和交易历史
+4. 如果指定了 `benchmark`，自动下载基准数据
+
+---
+
+## 步骤 4：查看结果
+
+### 绩效指标
+
+```python
+bt.summary()
+```
+
+输出示例：
+
+```
+=======================================================
+           回测绩效报告
+=======================================================
+  初始资金:         RMB 100,000.00
+  最终资产:         RMB 156,283.45
+  总收益率:          +56.28%
+  年化收益率:        +8.34%
+  夏普比率:           0.52
+  最大回撤:          -42.37%
+  胜率:              100.00%
+  总手续费:          RMB 67.50
+=======================================================
+```
+
+### HTML 报告
+
+```python
+bt.report(title='买入持有策略')
+# 自动保存到 reports/ 下
+```
+
+报告包含：
+- 8 个核心指标卡片
+- 净值曲线（含基准对比）+ 回撤曲线
+- 月度收益率热力图
+- 交易明细表
+- 回撤分析表
+
+在手机上也能正常查看——窄屏下表格自动变为堆叠卡片布局。
+
+---
+
+## 完整代码
+
+```python
+from qka import Data, Strategy, Broker, Backtest
+
+class BuyAndHold(Strategy):
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+        self.bought = False
+
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
+        if not self.bought and '000001.SZ' in close.index:
+            price = float(close['000001.SZ'])
+            if price > 0:
+                self.broker.buy('000001.SZ', price, 100)
+                self.bought = True
+
+data = Data(symbols=['000001.SZ'])
+bt = Backtest(data, BuyAndHold())
+bt.run(benchmark='000300.SH')
+bt.summary()
+bt.report(title='买入持有策略')
+```
+
+---
+
+## 进阶：用 `self.history()` 计算均线
+
+用 `self.history()` 获取过去 N 天的收盘价序列：
+
+```python
+from qka import Strategy, Broker
+import numpy as np
+
+class MaCross(Strategy):
+    """5日均线上穿20日均线买入"""
+    def __init__(self):
+        super().__init__()
+        self.broker = Broker(initial_cash=100_000)
+        self.bought = False
+
+    def on_bar(self, date):
+        hist = self.history('close', 20)
+        if len(hist) < 20:
+            return   # 数据不足，跳过
+
+        # hist 是 DataFrame，行=日期，列=股票代码
+        ma5 = hist.iloc[-5:].mean()
+        ma20 = hist.mean()
+
+        for sym in hist.columns:
+            close = self.get('close')
+            if close is None or sym not in close.index:
+                continue
+            price = float(close[sym])
+            if price <= 0:
+                continue
+
+            if ma5[sym] > ma20[sym] and not self.bought:
+                self.broker.buy(sym, price, 100)
+                self.bought = True
+            elif ma5[sym] < ma20[sym] and self.bought:
+                if sym in self.broker.positions:
+                    self.broker.sell(sym, price, self.broker.positions[sym]['size'])
+                self.bought = False
+```
+
+---
+
+## 下一步
+
+- 学习 [核心概念](concepts.md) — 架构设计、DataAccessor 数据流
+- 学习 [回测分析](../user-guide/backtest.md) — 费用设置、绩效指标详解
+- 探索 [性能优化](../advanced/performance.md) — dask 分区迭代原理

{qka-1.2.4.dev3 → qka-1.3.1.dev5}/docs/index.md

@@ -22,13 +22,13 @@ bt.report()                     # 生成 HTML 报告（手机也能看）
 
 | 特性 | 说明 |
 |------|------|
-| **数据** | 基于 akshare，自动缓存，多只股票并发下载 |
-| **策略** | 继承 `Strategy` 基类，实现 `on_bar` 即可 |
-| **回测** | 日线级别，多标的横截面，支持自定义因子 |
+| **数据** | 基于 baostock/akshare，自动缓存，支持大规模数据懒加载 |
+| **策略** | 继承 `Strategy` 基类，实现 `on_bar(self, date)`，使用 `self.get()` / `self.history()` |
+| **回测** | 日线级别，多标的横截面，支持 dask 分区迭代（300+ 股票无压力） |
 | **费用** | 佣金（万2.5，最低5元）+ 印花税（万5）+ 滑点（0.1%） |
 | **基准** | 一键对比沪深300 |
 | **报告** | 自包含 HTML，指标卡片 + 净值曲线 + 月度热力图 + 交易明细，适配手机 |
-| **绩效** | 夏普比率、最大回撤、胜率、盈亏比… 一行输出 |
+| **性能** | 滚动窗口数据访问器（DataAccessor），dask 分区迭代，内存峰值与总数据量解耦 |
 
 ---
 
@@ -44,21 +44,20 @@ uv sync
 ```
 
 ```python
-from qka.core.data import Data
-from qka.core.strategy import Strategy
-from qka.core.backtest import Backtest
-from qka.core.broker import Broker
+from qka import Data, Strategy, Broker, Backtest
 
 # 1. 写策略
 class MyStrategy(Strategy):
     def __init__(self):
-        super().__init__(cash=100_000)
+        super().__init__()
         self.broker = Broker(initial_cash=100_000)
 
-    def on_bar(self, date, get):
-        close = get('close')
+    def on_bar(self, date):
+        close = self.get('close')
+        if close is None or close.empty:
+            return
         if '000001.SZ' in close.index:
-            self.broker.buy('000001.SZ', close['000001.SZ'], 1000)
+            self.broker.buy('000001.SZ', float(close['000001.SZ']), 1000)
 
 # 2. 跑回测
 data = Data(symbols=['000001.SZ', '600000.SH'])