feat(question_gen): add v2 material sampler with family constraints
Implement sample_material_v2 module that samples tree nodes with QuestionFamilySpec-aware constraint validation, providing richer MaterialContext output (subtitles, cross-L2 context, frame paths). Key components: - AnchorContext/MaterialContext frozen dataclasses - _validate_sampling_constraints: multi-level constraint checking - _collect_subtitle_sentences: subtree subtitle extraction - _collect_cross_l2_context: peer L2 event descriptions - sample_material_v2: main entry with retry-on-constraint-violation Tests: 11 unit tests covering normal sampling, used-node exclusion, constraint violation retries, cross-L2 population, and subtitle collection. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,549 @@
|
||||
"""v2 素材采样器 — 基于家族约束的树节点采样与上下文收集。
|
||||
|
||||
在 v1 synthesizer 的基础上引入 QuestionFamilySpec 约束验证，
|
||||
为每次出题提供更丰富的素材上下文（字幕、跨 L2 上下文、帧路径）。
|
||||
|
||||
典型调用路径::
|
||||
|
||||
material = sample_material_v2(
|
||||
tree=tree_index,
|
||||
family_spec=REASONING_FAMILY,
|
||||
task_type="Causal Reasoning",
|
||||
used_node_ids=already_used,
|
||||
rng=rng,
|
||||
)
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from loguru import logger
|
||||
|
||||
if TYPE_CHECKING:
|
||||
import random
|
||||
|
||||
from app.question_gen.families import QuestionFamilySpec, SamplingConstraint
|
||||
from app.tree.index import L1Node, L2Node, TreeIndex
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 题型 → 采样层级映射
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_TASK_TYPE_TO_LEVEL: dict[str, int] = {
|
||||
# Level 3（细粒度帧级）
|
||||
"Action Recognition": 3,
|
||||
"Object Recognition": 3,
|
||||
# Level 2（片段/事件级）
|
||||
"Action Reasoning": 2,
|
||||
"Action Prediction": 2,
|
||||
"Action Sequence": 2,
|
||||
"Object Reasoning": 2,
|
||||
"Object Interaction": 2,
|
||||
"Scene Understanding": 2,
|
||||
"Event Reasoning": 2,
|
||||
"Causal Reasoning": 2,
|
||||
# Level 1（段落/场景级）
|
||||
"Temporal Reasoning": 1,
|
||||
"Spatial Reasoning": 1,
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 数据类型
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class AnchorContext:
|
||||
"""采样锚点上下文。
|
||||
|
||||
属性:
|
||||
node_id: 锚节点 ID。
|
||||
level: 锚节点所在层级（1/2/3）。
|
||||
l2_id: 锚节点所属的 L2 节点 ID（若自身为 L2 则等于 node_id；
|
||||
若为 L1 则取其第一个 L2 子节点 ID）。
|
||||
"""
|
||||
|
||||
node_id: str
|
||||
level: int
|
||||
l2_id: str
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class MaterialContext:
|
||||
"""采样素材上下文 — 出题所需的全部素材打包。
|
||||
|
||||
属性:
|
||||
anchor: 采样锚点信息。
|
||||
source_nodes: 参与采样的节点 ID 元组。
|
||||
subtitle_sentences: 锚节点子树中收集的字幕句列表。
|
||||
frame_paths: 锚节点子树中可用的帧路径列表。
|
||||
cross_l2_texts: 跨 L2 段的上下文文本列表（仅 cross_l2_span 时填充）。
|
||||
"""
|
||||
|
||||
anchor: AnchorContext
|
||||
source_nodes: tuple[str, ...]
|
||||
subtitle_sentences: list[str]
|
||||
frame_paths: list[str]
|
||||
cross_l2_texts: list[str]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 内部索引辅助
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _find_l2_node(tree: TreeIndex, l2_id: str) -> tuple[L2Node, L1Node] | None:
|
||||
"""按 ID 定位 L2 节点及其父 L1。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
l2_id: L2 节点 ID。
|
||||
|
||||
返回:
|
||||
(L2Node, 父L1Node) 元组；未找到返回 None。
|
||||
"""
|
||||
for l1 in tree.roots:
|
||||
for l2 in l1.children:
|
||||
if l2.id == l2_id:
|
||||
return (l2, l1)
|
||||
return None
|
||||
|
||||
|
||||
def _find_l1_node(tree: TreeIndex, l1_id: str) -> L1Node | None:
|
||||
"""按 ID 定位 L1 节点。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
l1_id: L1 节点 ID。
|
||||
|
||||
返回:
|
||||
L1Node；未找到返回 None。
|
||||
"""
|
||||
for l1 in tree.roots:
|
||||
if l1.id == l1_id:
|
||||
return l1
|
||||
return None
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 公开辅助函数
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _validate_sampling_constraints(
|
||||
tree: TreeIndex, node_id: str, constraint: SamplingConstraint
|
||||
) -> bool:
|
||||
"""校验指定节点是否满足采样约束。
|
||||
|
||||
根据节点层级自动判断检查范围：
|
||||
- L2 节点：检查其子 L3 的帧/字幕数量。
|
||||
- L1 节点：检查其下全部 L2/L3 的帧/字幕总数。
|
||||
- L3 节点：检查其所属 L2 的子树。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
node_id: 待检查节点 ID。
|
||||
constraint: 采样约束条件。
|
||||
|
||||
返回:
|
||||
True 表示满足所有约束，False 表示至少一项不满足。
|
||||
"""
|
||||
# Phase 1: 确定目标 L2 节点列表
|
||||
target_l2_nodes: list[L2Node] = []
|
||||
parent_l1: L1Node | None = None
|
||||
|
||||
# 先尝试作为 L2
|
||||
result = _find_l2_node(tree, node_id)
|
||||
if result is not None:
|
||||
l2_node, parent_l1 = result
|
||||
target_l2_nodes = [l2_node]
|
||||
else:
|
||||
# 尝试作为 L1
|
||||
l1_node = _find_l1_node(tree, node_id)
|
||||
if l1_node is not None:
|
||||
target_l2_nodes = list(l1_node.children)
|
||||
parent_l1 = l1_node
|
||||
else:
|
||||
# 尝试作为 L3 — 找到其所属 L2
|
||||
for l1 in tree.roots:
|
||||
for l2 in l1.children:
|
||||
for l3 in l2.children:
|
||||
if l3.id == node_id:
|
||||
target_l2_nodes = [l2]
|
||||
parent_l1 = l1
|
||||
break
|
||||
if target_l2_nodes:
|
||||
break
|
||||
if target_l2_nodes:
|
||||
break
|
||||
|
||||
if not target_l2_nodes:
|
||||
return False
|
||||
|
||||
# Phase 2: 统计 L3 节点数
|
||||
total_l3 = sum(len(l2.children) for l2 in target_l2_nodes)
|
||||
if total_l3 < constraint.min_l3_nodes:
|
||||
return False
|
||||
|
||||
# Phase 3: 检查帧路径可用性
|
||||
if constraint.require_frames:
|
||||
has_frame = any(l3.frame_path for l2 in target_l2_nodes for l3 in l2.children)
|
||||
if not has_frame:
|
||||
return False
|
||||
|
||||
# Phase 4: 统计字幕数
|
||||
subtitle_count = 0
|
||||
for l2 in target_l2_nodes:
|
||||
if l2.card.subtitle:
|
||||
subtitle_count += 1
|
||||
for l3 in l2.children:
|
||||
if l3.card.subtitle:
|
||||
subtitle_count += 1
|
||||
if subtitle_count < constraint.min_subtitles:
|
||||
return False
|
||||
|
||||
# Phase 5: 检查跨 L2 可用性
|
||||
return not (constraint.cross_l2_span and (parent_l1 is None or len(parent_l1.children) < 2))
|
||||
|
||||
|
||||
def _collect_subtitle_sentences(tree: TreeIndex, node_ids: tuple[str, ...]) -> list[str]:
|
||||
"""从指定节点集合中收集字幕句。
|
||||
|
||||
遍历每个 node_id 对应的子树，提取非空字幕。
|
||||
对 L2 节点提取自身 + 子 L3 字幕；对 L1 提取下属全部。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
node_ids: 待收集字幕的节点 ID 元组。
|
||||
|
||||
返回:
|
||||
非空字幕句列表（去除空白后非空的字幕）。
|
||||
"""
|
||||
sentences: list[str] = []
|
||||
|
||||
for nid in node_ids:
|
||||
# 尝试作为 L2
|
||||
result = _find_l2_node(tree, nid)
|
||||
if result is not None:
|
||||
l2_node, _ = result
|
||||
if l2_node.card.subtitle:
|
||||
sentences.append(l2_node.card.subtitle)
|
||||
for l3 in l2_node.children:
|
||||
if l3.card.subtitle:
|
||||
sentences.append(l3.card.subtitle)
|
||||
continue
|
||||
|
||||
# 尝试作为 L1
|
||||
l1_node = _find_l1_node(tree, nid)
|
||||
if l1_node is not None:
|
||||
for l2 in l1_node.children:
|
||||
if l2.card.subtitle:
|
||||
sentences.append(l2.card.subtitle)
|
||||
for l3 in l2.children:
|
||||
if l3.card.subtitle:
|
||||
sentences.append(l3.card.subtitle)
|
||||
continue
|
||||
|
||||
# 尝试作为 L3
|
||||
for l1 in tree.roots:
|
||||
for l2 in l1.children:
|
||||
for l3 in l2.children:
|
||||
if l3.id == nid and l3.card.subtitle:
|
||||
sentences.append(l3.card.subtitle)
|
||||
|
||||
return sentences
|
||||
|
||||
|
||||
def _collect_cross_l2_context(tree: TreeIndex, anchor_l2_id: str, max_peers: int = 3) -> list[str]:
|
||||
"""收集锚 L2 的同级 L2 节点描述文本（跨 L2 上下文）。
|
||||
|
||||
找到锚 L2 所属的 L1 父节点，取该父节点下除锚 L2 之外的其他 L2 描述。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
anchor_l2_id: 锚 L2 节点 ID。
|
||||
max_peers: 最多返回的同级 L2 描述数量。
|
||||
|
||||
返回:
|
||||
同级 L2 的 event_description 列表（最多 max_peers 条）。
|
||||
"""
|
||||
result = _find_l2_node(tree, anchor_l2_id)
|
||||
if result is None:
|
||||
return []
|
||||
|
||||
_, parent_l1 = result
|
||||
peers: list[str] = []
|
||||
for l2 in parent_l1.children:
|
||||
if l2.id != anchor_l2_id:
|
||||
peers.append(l2.card.event_description)
|
||||
if len(peers) >= max_peers:
|
||||
break
|
||||
|
||||
return peers
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 层级采样策略
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _sample_l3_node(
|
||||
tree: TreeIndex,
|
||||
used_node_ids: set[str],
|
||||
rng: random.Random,
|
||||
) -> tuple[str, str] | None:
|
||||
"""随机采样一个未使用的 L3 节点，返回 (l3_id, 所属l2_id)。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
used_node_ids: 已用节点 ID 集合。
|
||||
rng: 随机数生成器。
|
||||
|
||||
返回:
|
||||
(l3_id, l2_id) 元组；无候选返回 None。
|
||||
"""
|
||||
candidates: list[tuple[str, str]] = []
|
||||
for l1 in tree.roots:
|
||||
for l2 in l1.children:
|
||||
for l3 in l2.children:
|
||||
if l3.id not in used_node_ids:
|
||||
candidates.append((l3.id, l2.id))
|
||||
|
||||
if not candidates:
|
||||
return None
|
||||
return rng.choice(candidates)
|
||||
|
||||
|
||||
def _sample_l2_node(
|
||||
tree: TreeIndex,
|
||||
used_node_ids: set[str],
|
||||
rng: random.Random,
|
||||
) -> tuple[str, str] | None:
|
||||
"""随机采样一个未使用的 L2 节点，返回 (l2_id, l2_id)。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
used_node_ids: 已用节点 ID 集合。
|
||||
rng: 随机数生成器。
|
||||
|
||||
返回:
|
||||
(l2_id, l2_id) 元组；无候选返回 None。
|
||||
"""
|
||||
candidates: list[str] = []
|
||||
for l1 in tree.roots:
|
||||
for l2 in l1.children:
|
||||
if l2.id not in used_node_ids:
|
||||
candidates.append(l2.id)
|
||||
|
||||
if not candidates:
|
||||
return None
|
||||
chosen = rng.choice(candidates)
|
||||
return (chosen, chosen)
|
||||
|
||||
|
||||
def _sample_l1_node(
|
||||
tree: TreeIndex,
|
||||
used_node_ids: set[str],
|
||||
rng: random.Random,
|
||||
) -> tuple[str, str] | None:
|
||||
"""随机采样一个未使用的 L1 节点，返回 (l1_id, 首个子l2_id)。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
used_node_ids: 已用节点 ID 集合。
|
||||
rng: 随机数生成器。
|
||||
|
||||
返回:
|
||||
(l1_id, first_l2_id) 元组；无候选返回 None。
|
||||
"""
|
||||
candidates: list[tuple[str, str]] = []
|
||||
for l1 in tree.roots:
|
||||
if l1.id not in used_node_ids and l1.children:
|
||||
candidates.append((l1.id, l1.children[0].id))
|
||||
|
||||
if not candidates:
|
||||
return None
|
||||
return rng.choice(candidates)
|
||||
|
||||
|
||||
def _collect_frame_paths(tree: TreeIndex, node_id: str) -> list[str]:
|
||||
"""收集节点子树下的所有可用帧路径。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
node_id: 目标节点 ID。
|
||||
|
||||
返回:
|
||||
帧路径列表。
|
||||
"""
|
||||
paths: list[str] = []
|
||||
|
||||
# L2 节点
|
||||
result = _find_l2_node(tree, node_id)
|
||||
if result is not None:
|
||||
l2_node, _ = result
|
||||
for l3 in l2_node.children:
|
||||
if l3.frame_path:
|
||||
paths.append(l3.frame_path)
|
||||
return paths
|
||||
|
||||
# L1 节点
|
||||
l1_node = _find_l1_node(tree, node_id)
|
||||
if l1_node is not None:
|
||||
for l2 in l1_node.children:
|
||||
for l3 in l2.children:
|
||||
if l3.frame_path:
|
||||
paths.append(l3.frame_path)
|
||||
return paths
|
||||
|
||||
# L3 节点
|
||||
for l1 in tree.roots:
|
||||
for l2 in l1.children:
|
||||
for l3 in l2.children:
|
||||
if l3.id == node_id and l3.frame_path:
|
||||
paths.append(l3.frame_path)
|
||||
return paths
|
||||
|
||||
return paths
|
||||
|
||||
|
||||
def _collect_source_nodes(tree: TreeIndex, node_id: str) -> tuple[str, ...]:
|
||||
"""收集节点子树涉及的全部节点 ID（包含自身）。
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
node_id: 目标节点 ID。
|
||||
|
||||
返回:
|
||||
相关节点 ID 元组。
|
||||
"""
|
||||
ids: list[str] = [node_id]
|
||||
|
||||
# L2 节点：加入子 L3
|
||||
result = _find_l2_node(tree, node_id)
|
||||
if result is not None:
|
||||
l2_node, _ = result
|
||||
for l3 in l2_node.children:
|
||||
ids.append(l3.id)
|
||||
return tuple(ids)
|
||||
|
||||
# L1 节点：加入子 L2 + L3
|
||||
l1_node = _find_l1_node(tree, node_id)
|
||||
if l1_node is not None:
|
||||
for l2 in l1_node.children:
|
||||
ids.append(l2.id)
|
||||
for l3 in l2.children:
|
||||
ids.append(l3.id)
|
||||
return tuple(ids)
|
||||
|
||||
# L3 节点：仅自身
|
||||
return tuple(ids)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 主入口
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def sample_material_v2(
|
||||
tree: TreeIndex,
|
||||
family_spec: QuestionFamilySpec,
|
||||
task_type: str,
|
||||
used_node_ids: set[str],
|
||||
rng: random.Random,
|
||||
*,
|
||||
max_attempts: int = 10,
|
||||
) -> MaterialContext:
|
||||
"""基于家族约束从视频树中采样素材上下文。
|
||||
|
||||
采样流程：
|
||||
1. 根据 task_type 确定采样层级
|
||||
2. 随机选取候选节点（排除 used_node_ids）
|
||||
3. 验证 SamplingConstraint 约束
|
||||
4. 约束不满足则重试（最多 max_attempts 次）
|
||||
5. 收集字幕、帧路径、跨 L2 上下文
|
||||
|
||||
参数:
|
||||
tree: 三层树索引。
|
||||
family_spec: 问题家族规格（含采样约束）。
|
||||
task_type: 任务类型字符串。
|
||||
used_node_ids: 本轮已用节点 ID 集合。
|
||||
rng: 可控随机数生成器。
|
||||
max_attempts: 最大尝试次数。
|
||||
|
||||
返回:
|
||||
MaterialContext 实例。
|
||||
|
||||
异常:
|
||||
RuntimeError: 耗尽 max_attempts 次尝试仍无法满足约束。
|
||||
KeyError: task_type 不在 _TASK_TYPE_TO_LEVEL 映射中。
|
||||
"""
|
||||
level = _TASK_TYPE_TO_LEVEL[task_type]
|
||||
constraint = family_spec.sampling
|
||||
|
||||
for attempt in range(max_attempts):
|
||||
# Phase 1: 按层级采样候选节点
|
||||
if level == 3:
|
||||
sampled = _sample_l3_node(tree, used_node_ids, rng)
|
||||
elif level == 2:
|
||||
sampled = _sample_l2_node(tree, used_node_ids, rng)
|
||||
else:
|
||||
sampled = _sample_l1_node(tree, used_node_ids, rng)
|
||||
|
||||
if sampled is None:
|
||||
logger.debug(
|
||||
"sample_material_v2 尝试 {}/{}: 无可用候选节点 (level={})",
|
||||
attempt + 1,
|
||||
max_attempts,
|
||||
level,
|
||||
)
|
||||
continue
|
||||
|
||||
node_id, l2_id = sampled
|
||||
|
||||
# Phase 2: 验证约束
|
||||
if not _validate_sampling_constraints(tree, node_id, constraint):
|
||||
logger.debug(
|
||||
"sample_material_v2 尝试 {}/{}: 约束违反 (node={})",
|
||||
attempt + 1,
|
||||
max_attempts,
|
||||
node_id,
|
||||
)
|
||||
continue
|
||||
|
||||
# Phase 3: 构造 AnchorContext
|
||||
anchor = AnchorContext(node_id=node_id, level=level, l2_id=l2_id)
|
||||
|
||||
# Phase 4: 收集素材
|
||||
source_nodes = _collect_source_nodes(tree, node_id)
|
||||
subtitle_sentences = _collect_subtitle_sentences(tree, (node_id,))
|
||||
frame_paths = _collect_frame_paths(tree, node_id)
|
||||
|
||||
# Phase 5: 跨 L2 上下文（仅 cross_l2_span 时收集）
|
||||
cross_l2_texts: list[str] = []
|
||||
if constraint.cross_l2_span:
|
||||
cross_l2_texts = _collect_cross_l2_context(tree, l2_id)
|
||||
|
||||
logger.debug(
|
||||
"sample_material_v2 成功: node={}, level={}, attempt={}/{}",
|
||||
node_id,
|
||||
level,
|
||||
attempt + 1,
|
||||
max_attempts,
|
||||
)
|
||||
|
||||
return MaterialContext(
|
||||
anchor=anchor,
|
||||
source_nodes=source_nodes,
|
||||
subtitle_sentences=subtitle_sentences,
|
||||
frame_paths=frame_paths,
|
||||
cross_l2_texts=cross_l2_texts,
|
||||
)
|
||||
|
||||
raise RuntimeError(
|
||||
f"sample_material_v2: 耗尽 max_attempts={max_attempts} 次尝试，"
|
||||
f"无法为 task_type='{task_type}' 满足家族 '{family_spec.name}' 的采样约束"
|
||||
)
|
||||
@@ -0,0 +1,360 @@
|
||||
"""v2 素材采样器单元测试。
|
||||
|
||||
测试 sample_material_v2 及其辅助函数的核心行为：
|
||||
- 正常采样返回 MaterialContext
|
||||
- 已用节点排除
|
||||
- 约束违反时重试直至 RuntimeError
|
||||
- 跨 L2 上下文收集
|
||||
- 字幕收集
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import random
|
||||
|
||||
import pytest
|
||||
|
||||
from app.question_gen.families import (
|
||||
REASONING_FAMILY,
|
||||
RETRIEVAL_FAMILY,
|
||||
VISUAL_FAMILY,
|
||||
SamplingConstraint,
|
||||
)
|
||||
from app.tree.index import (
|
||||
IndexMeta,
|
||||
L1Card,
|
||||
L1Node,
|
||||
L2Card,
|
||||
L2Node,
|
||||
L3Card,
|
||||
L3Node,
|
||||
TreeIndex,
|
||||
)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Fixture: 构建含丰富数据的真实树结构
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _make_l3(
|
||||
l1_idx: int,
|
||||
l2_idx: int,
|
||||
l3_idx: int,
|
||||
*,
|
||||
subtitle: str = "",
|
||||
frame_path: str | None = None,
|
||||
) -> L3Node:
|
||||
"""构建 L3 节点，带可控 subtitle/frame_path。"""
|
||||
node_id = f"l1_{l1_idx}_l2_{l2_idx}_l3_{l3_idx}"
|
||||
return L3Node(
|
||||
id=node_id,
|
||||
card=L3Card(
|
||||
frame_summary=f"帧{l3_idx}描述:L1={l1_idx},L2={l2_idx}",
|
||||
visible_entities=[f"实体_{l3_idx}"],
|
||||
ongoing_actions=[f"动作_{l3_idx}"],
|
||||
visible_text=[],
|
||||
spatial_layout="居中",
|
||||
visual_attributes={"lighting": "明亮"},
|
||||
subtitle=subtitle,
|
||||
),
|
||||
timestamp=float(l3_idx * 2),
|
||||
frame_path=frame_path,
|
||||
)
|
||||
|
||||
|
||||
def _make_l2(
|
||||
l1_idx: int,
|
||||
l2_idx: int,
|
||||
n_l3: int = 3,
|
||||
*,
|
||||
subtitle: str = "",
|
||||
with_frames: bool = True,
|
||||
with_subtitles: bool = True,
|
||||
) -> L2Node:
|
||||
"""构建 L2 节点，可控子节点数量和属性。"""
|
||||
children: list[L3Node] = []
|
||||
for i in range(n_l3):
|
||||
sub = f"字幕L1={l1_idx}_L2={l2_idx}_L3={i}" if with_subtitles else ""
|
||||
fp = f"frames/l1_{l1_idx}_l2_{l2_idx}_l3_{i}.jpg" if with_frames else None
|
||||
children.append(_make_l3(l1_idx, l2_idx, i, subtitle=sub, frame_path=fp))
|
||||
|
||||
l2_subtitle = subtitle or (f"L2事件字幕:L1={l1_idx}_L2={l2_idx}" if with_subtitles else "")
|
||||
return L2Node(
|
||||
id=f"l1_{l1_idx}_l2_{l2_idx}",
|
||||
card=L2Card(
|
||||
event_description=f"事件:L1={l1_idx},L2={l2_idx}",
|
||||
entities=[f"角色_{l2_idx}"],
|
||||
actions=[f"行为_{l2_idx}"],
|
||||
action_subjects=[f"主体_{l2_idx}"],
|
||||
visible_text=[],
|
||||
spatial_relations="左右排列",
|
||||
state_changes=None,
|
||||
subtitle=l2_subtitle,
|
||||
),
|
||||
time_range=(l2_idx * 30.0, (l2_idx + 1) * 30.0),
|
||||
children=children,
|
||||
)
|
||||
|
||||
|
||||
def _make_l1(l1_idx: int, n_l2: int = 3, n_l3: int = 3) -> L1Node:
|
||||
"""构建 L1 节点，含多个 L2 子节点。"""
|
||||
return L1Node(
|
||||
id=f"l1_{l1_idx}",
|
||||
card=L1Card(
|
||||
scene_summary=f"场景{l1_idx}摘要",
|
||||
main_setting="室内" if l1_idx % 2 == 0 else "户外",
|
||||
key_entities=[f"主角_{l1_idx}"],
|
||||
main_actions=[f"主行为_{l1_idx}"],
|
||||
topic_keywords=[f"关键词_{l1_idx}"],
|
||||
visible_text=[],
|
||||
temporal_flow="从左到右",
|
||||
),
|
||||
time_range=(l1_idx * 600.0, (l1_idx + 1) * 600.0),
|
||||
children=[_make_l2(l1_idx, j, n_l3) for j in range(n_l2)],
|
||||
)
|
||||
|
||||
|
||||
@pytest.fixture()
|
||||
def real_tree() -> TreeIndex:
|
||||
"""构建包含 2 个 L1、每个 L1 含 3 个 L2、每个 L2 含 5 个 L3 的真实树。
|
||||
|
||||
共 2*3*5 = 30 个 L3 节点，6 个 L2 节点，2 个 L1 节点。
|
||||
所有节点有帧路径和字幕。满足 REASONING_FAMILY 的 min_l3_nodes=4 要求。
|
||||
"""
|
||||
meta = IndexMeta(source_path="/test/video.mp4", modality="video")
|
||||
roots = [_make_l1(i, n_l2=3, n_l3=5) for i in range(2)]
|
||||
return TreeIndex(metadata=meta, roots=roots)
|
||||
|
||||
|
||||
@pytest.fixture()
|
||||
def sparse_tree() -> TreeIndex:
|
||||
"""构建一棵稀疏树——无帧、少字幕，用于测试约束违反。
|
||||
|
||||
只有 1 个 L1, 1 个 L2, 1 个 L3。L3 无帧无字幕。
|
||||
"""
|
||||
meta = IndexMeta(source_path="/test/sparse.mp4", modality="video")
|
||||
l3 = _make_l3(0, 0, 0, subtitle="", frame_path=None)
|
||||
l2 = L2Node(
|
||||
id="sparse_l2_0",
|
||||
card=L2Card(
|
||||
event_description="稀疏事件",
|
||||
entities=[],
|
||||
actions=[],
|
||||
action_subjects=[],
|
||||
visible_text=[],
|
||||
spatial_relations="",
|
||||
state_changes=None,
|
||||
subtitle="",
|
||||
),
|
||||
time_range=(0.0, 30.0),
|
||||
children=[l3],
|
||||
)
|
||||
l1 = L1Node(
|
||||
id="sparse_l1_0",
|
||||
card=L1Card(
|
||||
scene_summary="稀疏场景",
|
||||
main_setting="未知",
|
||||
key_entities=[],
|
||||
main_actions=[],
|
||||
topic_keywords=[],
|
||||
visible_text=[],
|
||||
temporal_flow="",
|
||||
),
|
||||
time_range=(0.0, 600.0),
|
||||
children=[l2],
|
||||
)
|
||||
return TreeIndex(metadata=meta, roots=[l1])
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 测试类
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class TestSampleMaterialV2:
|
||||
"""sample_material_v2 核心行为测试。"""
|
||||
|
||||
def test_returns_material_context(self, real_tree: TreeIndex) -> None:
|
||||
"""正常采样返回 MaterialContext，字段类型正确。"""
|
||||
from app.question_gen.sampler_v2 import MaterialContext, sample_material_v2
|
||||
|
||||
rng = random.Random(42)
|
||||
result = sample_material_v2(
|
||||
tree=real_tree,
|
||||
family_spec=RETRIEVAL_FAMILY,
|
||||
task_type="Action Reasoning",
|
||||
used_node_ids=set(),
|
||||
rng=rng,
|
||||
)
|
||||
|
||||
assert isinstance(result, MaterialContext)
|
||||
assert result.anchor.node_id # 非空
|
||||
assert result.anchor.level in (1, 2, 3)
|
||||
assert len(result.source_nodes) > 0
|
||||
assert isinstance(result.subtitle_sentences, list)
|
||||
assert isinstance(result.frame_paths, list)
|
||||
assert isinstance(result.cross_l2_texts, list)
|
||||
|
||||
def test_respects_used_nodes(self, real_tree: TreeIndex) -> None:
|
||||
"""已用节点被正确排除，不会重复采样。"""
|
||||
from app.question_gen.sampler_v2 import sample_material_v2
|
||||
|
||||
rng = random.Random(42)
|
||||
|
||||
# 把所有 L2 节点标记为已用（除了最后一个）
|
||||
all_l2_ids: set[str] = set()
|
||||
for l1 in real_tree.roots:
|
||||
for l2 in l1.children:
|
||||
all_l2_ids.add(l2.id)
|
||||
|
||||
# 留下恰好一个 L2 未用
|
||||
last_l2_id = real_tree.roots[-1].children[-1].id
|
||||
used = all_l2_ids - {last_l2_id}
|
||||
|
||||
result = sample_material_v2(
|
||||
tree=real_tree,
|
||||
family_spec=RETRIEVAL_FAMILY,
|
||||
task_type="Action Reasoning",
|
||||
used_node_ids=used,
|
||||
rng=rng,
|
||||
)
|
||||
|
||||
# 锚节点应该是那个未被排除的 L2
|
||||
assert result.anchor.node_id == last_l2_id
|
||||
|
||||
def test_constraint_violation_retries(self, sparse_tree: TreeIndex) -> None:
|
||||
"""稀疏树上，严格约束满足不了，耗尽重试后抛 RuntimeError。"""
|
||||
from app.question_gen.sampler_v2 import sample_material_v2
|
||||
|
||||
rng = random.Random(42)
|
||||
|
||||
# VISUAL_FAMILY 要求 require_frames=True, min_l3_nodes=3
|
||||
# sparse_tree 只有 1 个 L3 且无帧 → 约束必然违反
|
||||
with pytest.raises(RuntimeError, match="max_attempts"):
|
||||
sample_material_v2(
|
||||
tree=sparse_tree,
|
||||
family_spec=VISUAL_FAMILY,
|
||||
task_type="Object Recognition",
|
||||
used_node_ids=set(),
|
||||
rng=rng,
|
||||
max_attempts=3,
|
||||
)
|
||||
|
||||
def test_cross_l2_populated_for_reasoning(self, real_tree: TreeIndex) -> None:
|
||||
"""REASONING 家族要求 cross_l2_span=True，cross_l2_texts 应被填充。"""
|
||||
from app.question_gen.sampler_v2 import sample_material_v2
|
||||
|
||||
rng = random.Random(42)
|
||||
|
||||
result = sample_material_v2(
|
||||
tree=real_tree,
|
||||
family_spec=REASONING_FAMILY,
|
||||
task_type="Causal Reasoning",
|
||||
used_node_ids=set(),
|
||||
rng=rng,
|
||||
)
|
||||
|
||||
# cross_l2_span=True 时必须有跨 L2 文本
|
||||
assert len(result.cross_l2_texts) > 0
|
||||
|
||||
def test_subtitle_sentences_from_anchor(self, real_tree: TreeIndex) -> None:
|
||||
"""采样结果的 subtitle_sentences 来自锚节点所属子树。"""
|
||||
from app.question_gen.sampler_v2 import sample_material_v2
|
||||
|
||||
rng = random.Random(42)
|
||||
|
||||
result = sample_material_v2(
|
||||
tree=real_tree,
|
||||
family_spec=RETRIEVAL_FAMILY,
|
||||
task_type="Action Reasoning",
|
||||
used_node_ids=set(),
|
||||
rng=rng,
|
||||
)
|
||||
|
||||
# real_tree 所有节点都有字幕，所以 subtitle_sentences 非空
|
||||
assert len(result.subtitle_sentences) > 0
|
||||
# 字幕应来自锚节点所属的子树（L2 自身字幕 + 子 L3 字幕）
|
||||
# fixture 中 L2 字幕格式: "L2事件字幕:L1={l1_idx}_L2={l2_idx}"
|
||||
# fixture 中 L3 字幕格式: "字幕L1={l1_idx}_L2={l2_idx}_L3={l3_idx}"
|
||||
# 解析锚 L2 的索引信息来验证
|
||||
anchor_l2_id = result.anchor.l2_id # 如 "l1_1_l2_2"
|
||||
# 从 ID 提取 L1/L2 索引
|
||||
parts = anchor_l2_id.split("_") # ["l1", "1", "l2", "2"]
|
||||
l1_idx, l2_idx = parts[1], parts[3]
|
||||
# 字幕中应包含 "L1={l1_idx}_L2={l2_idx}" 格式
|
||||
pattern = f"L1={l1_idx}_L2={l2_idx}"
|
||||
has_related = any(pattern in s for s in result.subtitle_sentences)
|
||||
assert has_related
|
||||
|
||||
|
||||
class TestValidateSamplingConstraints:
|
||||
"""_validate_sampling_constraints 辅助函数测试。"""
|
||||
|
||||
def test_passes_relaxed_constraint(self, real_tree: TreeIndex) -> None:
|
||||
"""宽松约束在丰富树上应通过。"""
|
||||
from app.question_gen.sampler_v2 import _validate_sampling_constraints
|
||||
|
||||
relaxed = SamplingConstraint(
|
||||
min_subtitles=1,
|
||||
min_l3_nodes=1,
|
||||
require_frames=False,
|
||||
cross_l2_span=False,
|
||||
)
|
||||
# 取第一个 L2 节点
|
||||
node_id = real_tree.roots[0].children[0].id
|
||||
assert _validate_sampling_constraints(real_tree, node_id, relaxed) is True
|
||||
|
||||
def test_fails_strict_frame_constraint(self, sparse_tree: TreeIndex) -> None:
|
||||
"""require_frames=True 但无帧时应返回 False。"""
|
||||
from app.question_gen.sampler_v2 import _validate_sampling_constraints
|
||||
|
||||
strict = SamplingConstraint(
|
||||
min_subtitles=0,
|
||||
min_l3_nodes=1,
|
||||
require_frames=True,
|
||||
cross_l2_span=False,
|
||||
)
|
||||
node_id = sparse_tree.roots[0].children[0].id
|
||||
assert _validate_sampling_constraints(sparse_tree, node_id, strict) is False
|
||||
|
||||
|
||||
class TestCollectSubtitleSentences:
|
||||
"""_collect_subtitle_sentences 辅助函数测试。"""
|
||||
|
||||
def test_collects_from_l2_and_l3(self, real_tree: TreeIndex) -> None:
|
||||
"""收集指定节点的 L2 字幕和子 L3 字幕。"""
|
||||
from app.question_gen.sampler_v2 import _collect_subtitle_sentences
|
||||
|
||||
l2_id = real_tree.roots[0].children[0].id
|
||||
sentences = _collect_subtitle_sentences(real_tree, (l2_id,))
|
||||
# 应包含 L2 自身字幕 + 3 个 L3 子节点字幕
|
||||
assert len(sentences) >= 1
|
||||
|
||||
def test_empty_for_no_subtitles(self, sparse_tree: TreeIndex) -> None:
|
||||
"""无字幕节点返回空列表。"""
|
||||
from app.question_gen.sampler_v2 import _collect_subtitle_sentences
|
||||
|
||||
l2_id = sparse_tree.roots[0].children[0].id
|
||||
sentences = _collect_subtitle_sentences(sparse_tree, (l2_id,))
|
||||
assert sentences == []
|
||||
|
||||
|
||||
class TestCollectCrossL2Context:
|
||||
"""_collect_cross_l2_context 辅助函数测试。"""
|
||||
|
||||
def test_returns_peer_l2_descriptions(self, real_tree: TreeIndex) -> None:
|
||||
"""跨 L2 上下文应返回同 L1 下其他 L2 的描述。"""
|
||||
from app.question_gen.sampler_v2 import _collect_cross_l2_context
|
||||
|
||||
anchor_l2_id = real_tree.roots[0].children[0].id
|
||||
texts = _collect_cross_l2_context(real_tree, anchor_l2_id, max_peers=3)
|
||||
# L1_0 有 3 个 L2，排除 anchor 后剩 2 个
|
||||
assert len(texts) == 2
|
||||
|
||||
def test_max_peers_limits_output(self, real_tree: TreeIndex) -> None:
|
||||
"""max_peers 参数限制返回数量。"""
|
||||
from app.question_gen.sampler_v2 import _collect_cross_l2_context
|
||||
|
||||
anchor_l2_id = real_tree.roots[0].children[0].id
|
||||
texts = _collect_cross_l2_context(real_tree, anchor_l2_id, max_peers=1)
|
||||
assert len(texts) <= 1
|
||||
Reference in New Issue
Block a user