DDB 后端系统性优化：bug 修复、并发安全、健壮性与查询性能（面向社区版 2核/8GB）

[hugo2046]

概述

在 optimize/ddb-backend 分支上对 DolphinDB 后端做一轮系统性优化，共 19 个原子提交。硬前提：目标服务器为 DolphinDB 社区版（2 核 / 8GB）——优化方向是省往返、省传输、省服务器内存、控会话数，明确不堆并行。D.features()/D.calendar()/D.instruments() 等公共接口的签名与返回结果完全兼容。

变更内容

Bug 修复（5 项，全部带回归测试）

• ddb_dataset_processor 传入 inst_processors 时提前 return pd.DataFrame()，并行处理结果被整体丢弃（data.py:782）
• DDBClient 连接池生命周期双重损坏：_pool_instance 类变量致多客户端共享同一池；close_pool 引用不存在的 _pool_lock 且永远读到 None（从未真正关闭过池）；删除调用不存在 get_session() 的死方法与 __main__ 硬编码凭据
• DolphinDBClientProvider init 急切创建 4 连接池（无消费方）→ 懒创建
• load_mysql_plugin 误装 lgbm 插件（应为 mysql）
• DolphinDBDataLoader.__exit__/__del__ 无条件关闭进程级共享 session → _owns_session 所有权标志

并发/线程安全

• 新增会话级 DBClient.session_lock（RLock）：feature 查询是「run→upload→run」多步会话对话，并发交错会互相覆盖服务器端变量（跨线程数据污染根因）；所有 session 触点统一持锁
• QlibDataLoader 全局 _load_lock 收窄至 DDB 路径，文件后端恢复无锁并行

健壮性/质量

• 12 处 print → loguru；3 处裸 except: 收敛；异常重包装补 from e
• MySQL 同步 SQL 参数白名单校验（唯一真实用户可控注入面）
• 清理死代码（注释块 ×2、零调用者函数 ×2、16KB 备份脚本）与 OPERATOR_MAPPING 重复键（生效映射不变，ast 测试锁定）

性能（计算分支每批 RPC 3-4 次 → 预热后 2 次）

• 日历缓存：Alpha158 一次 D.features 从 ~6 次全量日历下载 → 0；DBCalendarStorage.index()/__getitem__ 改走 H["c"]
• 往返缩减：日期字面量内联、纯字段分支单脚本查询、上传字典按分支裁剪；fetch_features_from_ddb 拆为编排器 + 4 个 helper
• 多级缓存：existsTable 仅正向缓存、股票池走 H["i"]、表 schema 进程内缓存、表达式翻译 lru_cache；统一由 invalidate_ddb_caches() 失效（写路径自动调用）
• 结果直构：计算分支直构 (instrument, datetime) MultiIndex 面板，替代 concat→unstack→stack→swaplevel 的 ~4 次全景拷贝（保留 legacy 兜底 + 逐值等价测试）
• 惰性加载：三个 alpha 因子库（~119KB）按字段前缀按需加载，"Cannot recognize the token" 兜底重试，ddb_preload_alpha_libs 逃生开关
• 写路径：按 URI 复用共享 DDBClient（批量导入 N 会话 → 1）
• 配置化：ddb_field_chunk_size=30、ddb_days_step=252（默认值不变，附 8GB 内存模型说明与 live 基准脚本）

明确不做（2 核/8GB 约束）

读路径不引入 DBConnectionPool 并发、不调高 mr 并行度、不做服务器端全景 pivot、不引入 module/functionView 持久化。

追加（2026-07-22，ab525e91）：滚动算子自动取前序期 + 真实分段计算

• 取前序期：DDB 分支此前把 start_time 原样下发，Mean($close,20) 在区间头部前 19 个交易日必然 NaN。现在 Python 侧复用 qlib 算子树 get_extended_window_size 解析每批表达式的（向前, 向后）外扩交易日数（嵌套递归、双臂取 max、Ref($close,-2) 标签向后外扩），经 FeatureEngineeringByDate 尾参下发；DDB 端外扩查询窗口计算后截断回请求区间。qlib 解析不了的表达式退回正则扫窗口 + ddb_lookback_default（默认 252）兜底
• 真实分段：移除从未生效的 repartitionDS(RANGE,[start,end])+mr（2 个边界只产生 1 个数据源的"虚假分区"）。改为内存估算放得下整段单次计算；放不下按 ddb_days_step 切段顺序循环，每段带 lookback 重叠（halo）、段内截断、统一列标签对齐后 concatMatrix 纵向合并——分段边界处滚动结果与整段一致
• 兼容：FeatureEngineeringByDate 新尾参默认 0，旧调用不变；D.features() 签名不变。离线套件 +4 项至 119 项全部通过（新增 tests/test_ddb_lookback.py）；DDB 端脚本行为列入 live 验证清单（见 docs/DDB取前序期与分段计算_20260722.md）

测试

• 离线套件（mock 会话，不依赖 DDB 服务器）：119 项全部通过（2026-07-22 起，含回看窗口解析与脚本接线测试）；新增 tests/ddb_mocks.py 可复用记录型假会话与 RPC 计数基线
• 行为等价保障：D0 先固化 fetch_features_from_ddb 四大分支行为，再做重构；直构重塑与 legacy 路径逐值等价测试（乱序轴/NaN/单 alias 等边界）
• ⏳ Live 验证待做（需 DDB 服务器）：DDB_BENCH_URI=... python scripts/benchmark_ddb_backend.py 前后对比 + spans 成分股回测样例比对

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[hugo2046]

Code review

Found 1 issue:

1. QlibDataLoader._load_lock 收窄到 is_using_dolphindb() 条件后，破坏了引入该锁的原始回归测试 tests/data_mid_layer_tests/test_dataloader_concurrency.py（复现：python -m pytest tests/data_mid_layer_tests/test_dataloader_concurrency.py -q → 80 failed，失败信息即当初 9be4b72 修复的跨线程 instruments 污染）。该测试通过注入不安全共享层的子类模拟竞态、不依赖 database_uri 配置，收窄后锁不再生效。此外 _load_lock 类注释（L162-169）仍宣称“串行化整个 load 体……对本仓库所有消费方安全”，与收窄后的行为矛盾。建议：要么恢复无条件锁，要么同步改写该回归测试与类注释，明确锁的作用域是“仅 DDB 后端”并说明自定义共享态子类需自行加锁。

qlib-ddb/qlib/data/dataset/loader.py

Lines 216 to 228 in 3a9cac0

	def load(self, instruments=None, start_time=None, end_time=None) -> pd.DataFrame:
	# 跨线程数据污染仅在 DolphinDB 后端出现（单一共享 session + 全局 H 缓存）；
	# 文件后端本就线程安全，加锁反而是吞吐回归，故锁收窄到 DDB 路径。
	# DDB 路径在会话级 session_lock（B1）之外保留本 load 级锁，作为全局 H
	# MemCache 写模式的双保险。详见 _load_lock 注释。
	from ..data import is_using_dolphindb
	if is_using_dolphindb():
	with QlibDataLoader._load_lock:
	return super().load(instruments, start_time, end_time)
	return super().load(instruments, start_time, end_time)

相关：原始修复引入的回归测试 https://github.com/hugo2046/qlib-ddb/blob/3a9cac099f06414ac2691b3ab566c76ab02621c6/tests/data_mid_layer_tests/test_dataloader_concurrency.py 与类注释

qlib-ddb/qlib/data/dataset/loader.py

Lines 161 to 170 in 3a9cac0

	# 类级锁：跨所有 QlibDataLoader 实例共享（类变量形式的全局互斥锁）。
	# 并发 load() 会共享 qlib 全局数据层（DolphinDB session / 内部缓存），该层非线程
	# 安全，并发求值时共享缓冲被互相覆盖——线程 A 请求 instruments X、线程 B 请求
	# instruments Y（X∩Y=∅），并发执行后 A 的返回会混入 Y 的 instruments（反之亦然）。
	# 串行化整个 load 体是已知最小正确修法（吞吐换正确性，对本仓库所有消费方安全）。
	# Reentrancy：load_group_df → D.features 不会回调本类 load / 不再获取本锁，无嵌套
	# 加锁风险，故用 Lock 而非 RLock。
	_load_lock = threading.Lock()

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[hugo2046]

Code review

针对新增提交 ab525e91（取前序期 + 真实分段计算）复查，发现 2 个问题，均位于本 PR 自述「待 live 验证」的分段/兜底路径：

1. mergeSegmentResults 在任一分段计算失败时会丢弃该表达式其余分段的正确结果。分段路径下，某个分段对某表达式失败/空结果时 computeRangeFeatures 存入 createEmptyTable(...)（TABLE 而非 MATRIX）占位；合并时一旦命中非 MATRIX 的 part，即 merged[alias] = part; break，把已累积在 mats 里的其它分段矩阵全部丢弃，整个区间的该 alias 塌缩为单个短占位表——与提交自述「分段边界处滚动结果与整段计算一致」相矛盾。仅在内存不足的分段分支触发。建议：跳过失败分段（不 break），或对该 alias 全区间统一回退占位。

qlib-ddb/qlib/data/backend/ddb_qlib/ddb_scripts/featureEngineering.dos

Lines 752 to 761 in ab525e9

	continue;
	};
	part = seg[alias];
	if(regexFind(typestr(part), "MATRIX") == -1){
	merged[alias] = part;
	broken = true;
	break;
	};
	if(part.rows() > 0){
	mats.append!(part);

2. 回看窗口正则兜底会把表达式中的普通数值常量误判为超大回看窗口。get_expression_extended_window 的兜底路径（qlib 解析不了时，即 DDB 专属 alpha 函数）取最大独立整数为窗口：gtjaAlpha191_005($volume/1000000, $close) 会被 _STANDALONE_INT_PATTERN 解析出 1000000，进而 shiftTradeDays(qStart, -1000000) 向前外扩百万交易日，在 2 核/8GB 上触发超量查询（OOM 风险）。结果因末端截断仍正确，属资源/性能问题；现有 12 个测试未覆盖含大常量的兜底表达式。建议：对兜底窗口设上限（如 clamp 到日历范围或一个合理上界）。

qlib-ddb/qlib/data/backend/ddb_qlib/ddb_features.py

Lines 238 to 242 in ab525e9

	except Exception:
	ints = [int(s) for s in _STANDALONE_INT_PATTERN.findall(expr)]
	lft_etd = max(ints) if ints else int(default_lookback)
	futures = [int(s) for s in _FUTURE_INT_PATTERN.findall(expr)]
	return lft_etd, max(futures) if futures else 0

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[hugo2046]

审查问题修复（6ee10965）

两个问题均已修复：

1. mergeSegmentResults 丢弃正确分段 — 失败/空分段的占位改由 buildPlaceholderMatrix 统一产出「行-该段交易日、列-presentCodes」的 NULL 矩阵，与正常结果同为带标签矩阵。合并时对所有分段一视同仁按行拼接，任一分段异常不再 break 丢弃其它分段；顺带消除空 baseData 分段的日期空洞与 Python 侧 TABLE/MATRIX 类型隐患。占位填 NULL（非 0）避免污染因子值，并移除因此零调用的 createEmptyTable。

qlib-ddb/qlib/data/backend/ddb_qlib/ddb_scripts/featureEngineering.dos

Lines 740 to 780 in 6ee1096

	def mergeSegmentResults(segResults, colLabels){
	merged = dict(STRING, ANY, true);
	aliases = [];
	for(seg in segResults){
	for(k in keys(seg)){
	if(!(k in aliases)){
	aliases.append!(k);
	};
	};
	};
	for(alias in aliases){
	mats = [];
	rowLabs = array(DATE, 0);
	for(seg in segResults){
	if(!(alias in keys(seg))){
	continue;
	};
	part = seg[alias];
	// 防御：占位统一为矩阵后此处正常不触发；非矩阵则跳过该段，
	// 保留其它分段已算出的正确矩阵，不整体丢弃
	if(regexFind(typestr(part), "MATRIX") == -1){
	continue;
	};
	if(part.rows() > 0){
	mats.append!(part);
	rowLabs.append!(part.rowNames());
	};
	};
	if(size(mats) == 0){
	continue;
	};
	if(size(mats) == 1){
	merged[alias] = mats[0];
	continue;
	};
	m = concatMatrix(mats, false);
	m.rename!(rowLabs, colLabels);
	merged[alias] = m;
	};
	return merged;
	};

2. 正则兜底误判数值常量 — 新增 _MAX_FALLBACK_WINDOW=2000（约 8 年交易日）上界，扫到的整数超过它即视为常量剔除，剔除后无候选则退回 ddb_lookback_default。$volume/1000000 中的 1000000 不再被当成回看窗口。

qlib-ddb/qlib/data/backend/ddb_qlib/ddb_features.py

Lines 204 to 210 in 6ee1096

	# 而非滚动窗口，避免误判成百万日回看导致 shiftTradeDays 外扩到不合理区间。
	# 约 8 年交易日，远超常见滚动窗口（年化 252、双年 504 等）
	_MAX_FALLBACK_WINDOW: int = 2000
	@functools.lru_cache(maxsize=4096)
	def get_expression_extended_window(expr: str, default_lookback: int) -> Tuple[int, int]:

离线套件 122 项通过（新增 3 项兜底单测）。DDB 端占位矩阵/拼接行为已列入 live 验证清单（含「单分段失败不丢弃其它分段」用例）。

🤖 Generated with Claude Code