perf: 全市场报价改单连接流水线(3.5s → 0.33s)+ 修复基金笔数口径 (#9)

## 性能:get_quotes 全市场 5,227 只 A股 3.5s → 0.33s

协议硬上限 80 只/请求 → 必须切 66 片;老实现是纯串行 for 循环,
每片一次往返(≈60ms),3.5s 全花在等网络上。

发现通达信响应是自描述长度帧且服务器按序应答,因此同一连接可连发
多条请求只付一次往返:实测单连接流水 66 请求 526ms(串行 7,372ms)。

- TdxConnection.execute_pipeline(cmds):一次下发全部 → 按序读回;中途失败强制断连
- _quotes_std 改工作窃取调度(快台多干,避免被最慢节点拖累)
- DynamicPool.warm(n):并发预建连接(acquire 在全局锁内一次一条,22 并发首拉会多花 5~6s)
- CacheManager.get_or_fetch_obj:回源直接返回对象,省掉冷路径 pickle→unpickle 白烧
- pool_max 默认 12 → 24

调优实测 p50/max:每台 1 连接×深度 6 = 455ms;每台 2 连接×深度 3 = 325ms。
端到端(全默认):首次 783ms、稳态 300~343ms、热缓存 67ms。
正确性:用昨收价交叉比对 30 只零错配,流水线与逐片结果集合完全一致。

## 修复:指数 / ETF / LOF 的 trade_count 不再伪装成笔数

通达信对指数和多数场内基金不提供笔数,那 4 字节里塞的是「价格 × 1000」
(指数是「均价 × 1000」)。旧版直接当笔数用,tdx transactions sh510310
会打印出「3994 笔」这种假数据。

- 新增 TransactionRecord.trade_count_available
- 新增 symbols.has_order_count(market, code) 按品种判定
  (沪市 501x/502x/506x 实测有真实笔数,不能按「5 开头=基金」一刀切)
- 历史通道 0x013001 无笔数字段,同样标记不可用

## 文档:可转债量纲口径

核查可转债分时/逐笔后确认数据本身无缺陷(16 只当日 + 8 只历史日,
分时末价/现价、Σvol/日线vol、逐笔 VWAP 比值均 1.000000),
但 vol 单位是「手」(=10 张)导致 amount/vol 是均价的 10 倍,对外文档缺失。

- SecurityBar / TransactionRecord / MinuteBar 量纲注释补全
- has_order_count 实测表补沪可转债 110/111/113/118、沪 EB 132、深可转债 123/127/128
- API_REFERENCE 新增跨品种量纲对照表;llms.txt / SKILL.md 同步

## 版本

0.6.7

## 测试

306 → 346 全通过(新增 tests/test_pipeline.py 11 项 + 基金笔数相关回归)

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
This commit is contained in:
openbotandopenbot-coder authored and GitHub committed 2026-10-22 19:41:55 +08:00
1 parent 2c07400a3a
commit 8a78156145
17 files changed
+860 -61

No files matched your search

+100
View File
@@ -2,6 +2,106 @@
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
## [0.6.7] - 2026-10-22
### 性能
- **全市场 A股报价 3.5s → 0.33s:单连接流水线 + 工作窃取**(5,227 只 / 66 片实测)。
老实现 `get_quotes` 是**纯串行 for 循环**逐片发请求:协议硬上限 80 只/请求,
全市场必须切 66 片,每片一次往返(≈60ms)→ 3.5s 全花在等网络上。
关键发现:通达信响应是**自描述长度帧**(16B 帧头 + body)且服务器**按序应答**,
因此同一 TCP 连接上可以连续下发多条请求、只付一次往返。实测单连接流水 66 个请求
只要 526ms(串行 7,372ms),响应顺序与代码完全对得上(用昨收价交叉比对 30 只,零错配)。
| 位置 | 变化 |
|---|---|
| `TdxConnection.execute_pipeline(cmds)`(新) | 一次 write 全部请求 → 按序读回全部响应。中途失败**强制断连**(响应流已错配,不可复用) |
| `PooledConnection.execute_pipeline`(新) | 池化包装转发 |
| `api._execute_std_pipeline`(新) | 借一条连接流水一整组分片;节点不支持流水线时自动降级为逐片 |
| `get_quotes(..., pipeline=True, concurrency=None)` | 新参数;小批量(≤80 只)仍走原路径,零额外开销 |
| `_quotes_std` | 改为**工作窃取**:分片放队列,连接做完一批回来再取,快的多干、慢的少干 |
| `DynamicPool.warm(n)`(新) | **并发**预建连接。`acquire()` 建连在全局锁内一次一条,22 并发首次会串行握手 22 次 —— 全市场首拉因此多花 5~6s;预热后降到 0.78s |
| `CacheManager.get_or_fetch_obj`(新) | 回源直接返回对象,省掉冷路径「pickle→立刻 unpickle」的一次白烧(5,227 条实测 ~40ms) |
| `TdxData(pool_max=)` | 默认 12 → 24,让报价并发能到「每台 2 连接」(池仍是懒扩容,不影响其他接口) |
调优实测(5,227 只 A股,11 台服务器,p50/max):
| 并发 | 每台连接 | 流水深度 | p50 | max |
|---|---|---|---|---|
| 11 | 1 | 6 | 455ms | 464ms |
| 12 | 1~2 | 3 | 457ms | 523ms |
| **22** | **2** | **3** | **325ms** | **334ms** |
| 33 | 3 | 2 | 328ms | 345ms |
⚠️ 剩余下限由公网决定:本机 → 服务器 TCP 握手 RTT 59~80ms,66 片最多只能压到
「1 次往返」;网络抖动时段实测会到 460~600ms。
端到端实测(全默认参数 `TdxData()`,11 台服务器,5,227 只):
| 场景 | 耗时 |
|---|---|
| 首次调用(含并发建 22 条连接) | 783ms |
| 稳态(第 2 次起) | **300~343ms** |
| 命中 TTL 缓存 | 67ms |
| 老版本对照(串行) | 5,996ms(首次)/ 3,460ms(稳态) |
### 修复
- **指数 / ETF / LOF 的 `trade_count` 不再伪装成成交笔数**。
通达信对**指数**和**多数场内基金**不提供笔数,但逐笔报文里那 4 字节仍塞了值:
指数是「当时均价 × 1000」,ETF/LOF 是「价格 × 1000」,货币 ETF(`sh511990`)恒为 `0`。
旧版直接把它当笔数,于是 `tdx transactions sh510310` 会打印出「3994笔」这种假数据
(实测 2026-10-22,价 3.989,原字段 3994)。
| 位置 | 变化 |
|---|---|
| `TransactionRecord.trade_count_available`(新字段) | 该品种协议上是否带笔数;默认 `True` |
| `symbols.has_order_count(market, code)`(新函数) | 按品种判定;**沪市 501x/502x/506x 实测有真实笔数**,不能按「5 开头=基金」一刀切 |
| `transaction.py` 三个解析器 | 不可用时 `trade_count=0` + `trade_count_available=False`;历史通道(0x013001,无笔数字段)同样标记 |
| `tdx transactions` CLI | 不可用时打印 `(-)`,不再打印假笔数 |
实测样本(2026-10-22,按前缀各取样):沪股票/科创/深股票/深可转债/沪逆回购 → 真实笔数;
沪 `51/52/56/58`、深 `159/15x/16x/17x/18x`、所有指数 → 不可用。
### 文档
- **可转债的量纲口径补全**(数据本身无缺陷,但对外文档一片空白,很容易被误判成 bug)。
起因:核查可转债的分时(`0x122D`)与逐笔(`0x122F`)是否有类似 ETF/LOF 的笔数问题。
结论是**价格 / 成交量 / 笔数三样全部正确**,顺带确认了 K 线标度也对;唯一的问题是
`vol` 的单位没人写清楚 —— 直接拿 `amount / vol` 算均价会**错 10 倍**。
实测(2026-10-22,16 只 A股可转债当日 + 8 只历史日 `2026-10-21`):
| 校验项 | 结果 |
|---|---|
| 分时末价 / 快照现价 | **1.000000** |
| Σ分时 vol / 日线 vol | **1.000000** |
| Σ逐笔 vol / 日线 vol | **1.000000** |
| 逐笔 VWAP vs `amount/(vol×10)` | 吻合(差 ≤0.002,是 amount 精度) |
| 快照 `pre_close` vs 上一交易日日线 `close` | **16/16 精确相等** |
| `trade_count` | 真实笔数(`sh111000` 3631 条切片 / 20443 笔) |
关键口径对照(这是文档缺失的部分):
| 品种 | 分时 / 逐笔 `vol` | 日线 `vol` | `Σ分时vol / 日线vol` | `amount / vol` |
|---|---|---|---|---|
| 股票 / ETF / LOF | 手(= 100 股) | 股 | **0.01** | 均价 ✓ |
| 可转债 | 手(= 10 张) | **手** | **1.0** | 均价 **×10** ⚠️ |
| 位置 | 变化 |
|---|---|
| `SecurityBar` / `TransactionRecord` / `MinuteBar` | 量纲注释补可转债(`vol`=手;日线 `amount/vol` 需再 `/10`) |
| `symbols.has_order_count` | 实测表补沪可转债 `110/111/113/118`、沪 EB `132`、深可转债 `123/127/128`,并说明它们走「排除法」兜底分支 |
| `docs/API_REFERENCE.md` | 新增**跨品种量纲对照表** |
| `docs/llms.txt` / `SKILL.md` | 同步同一口径 |
**代码逻辑未改**:可转债在 `has_order_count` 里本来就判为「有笔数」(不在基金/指数的
排除前缀里),本次只是把实测依据补进注释与文档。
## [0.6.6] - 2026-10-22
### 改进