附录 F · 案例研究：端到端查询走查¶
本附录通过 4 个完整的查询场景，展示 TTD 从用户输入到结果返回的端到端体验。每个场景覆盖不同的路由路径，包含：用户输入 → SSE 事件序列 → 各节点耗时 → 生成的 SQL → 最终输出。
诚实声明：本附录的耗时数字为设计目标估值（基于各节点延迟预算累加），非 Langfuse trace 实测值。场景数据基于 H&M 数据集（见 附录 E）。SQL 与结果是真实可执行的，但具体数值为示例。
F.1 场景一：上月销量 Top 10 商品（nl2sql_query）¶
路由：nl2sql_query（最快主路径）
意图：ranking
复杂度：低（单表聚合 + join 维度表）
用户输入¶
上月销量 Top 10 商品
SSE 事件序列¶
| # | 事件类型 | 内容 | 耗时（设计目标） |
|---|---|---|---|
| 1 | status |
processing |
— |
| 2 | node_complete |
supervisor — 嵌入计算 + 治理叠加层解析 |
~80ms |
| 3 | node_complete |
query_understanding — intent=ranking, entities=[商品,销量], temporal=上月 |
~0.8s |
| 4 | node_complete |
router — 映射到 nl2sql_query |
~2ms |
| 5 | node_complete |
data_retrieval — Engine T "销量"→transaction_count, "商品"→dim_article |
~30ms |
| 6 | node_complete |
reranker — 绑定列 boost 0.95, 父表 +0.25 |
~8ms |
| 7 | node_complete |
semantic_planner — Steiner 树: fact_transaction ⋈ dim_article |
~20ms |
| 8 | node_complete |
sql_generation — 生成 SQL |
~1.5s |
| 9 | node_complete |
guardrails — 五层校验通过 |
~15ms |
| 10 | node_complete |
sql_executor — 执行 SQL |
~200ms |
| 11 | data |
查询结果（10 行） | — |
| 12 | node_complete |
visualization — 规则推荐条形图 |
~5ms |
| 13 | insights |
"上月销量 Top 1 为 XX，销量 12,345" | ~1.0s |
| 14 | status |
completed |
— |
| 合计 | ~3.7s |
生成的 SQL¶
SELECT a.prod_name, COUNT(*) AS sales_count
FROM gold_hm.fact_transaction f
JOIN gold_hm.dim_article a ON f.article_id = a.article_id
WHERE f.t_dat >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1 month')
AND f.t_dat < DATE_TRUNC('month', CURRENT_DATE)
GROUP BY a.prod_name
ORDER BY sales_count DESC
LIMIT 10;
最终输出¶
| prod_name | sales_count |
|---|---|
| 产品名 1 | 12,345 |
| 产品名 2 | 11,876 |
| ... | ... |
可视化：条形图（ranking 场景规则推荐） 洞察：上月销量 Top 1 为"产品名 1"，共 12,345 次交易，是第二名的 1.04 倍。
链路特点¶
- 未触发修复循环：SQL 一次生成即通过五层护栏——术语绑定精准、列引用全部在白名单内、EXPLAIN 预估行数 < 10M。
- 规划器价值：Steiner 树判定无需 join
dim_customer（无字段引用），消除冗余 join。 - 缓存：若该问题再次出现（相似度 ≥ 0.92），SQL Cache 命中，跳过检索+生成，端到端降至 ~250ms。
F.2 场景二：为什么退货率上升了？（deep_analysis_workflow）¶
路由：deep_analysis_workflow（多步推理路径）
意图：anomaly_explanation
复杂度：高（多步分析 + 三级评估 + 可能触发修复循环）
用户输入¶
为什么退货率上升了？
SSE 事件序列¶
| # | 事件类型 | 内容 | 耗时 |
|---|---|---|---|
| 1 | status |
processing |
— |
| 2 | node_complete |
supervisor |
~80ms |
| 3 | node_complete |
query_understanding — intent=anomaly_explanation |
~1.0s |
| 4 | node_complete |
router — 映射到 deep_analysis_workflow |
~2ms |
| 5 | node_complete |
data_retrieval — "退货率"→price<0 的比例 |
~40ms |
| 6 | node_complete |
reranker |
~10ms |
| 7 | node_complete |
semantic_planner |
~30ms |
| 8 | node_complete |
sql_generation（第 1 次） |
~1.5s |
| 9 | node_complete |
guardrails — Layer 2c 列校验失败（引用了不存在的 return_flag 列） |
~5ms |
| 10 | node_complete |
corrective_retrieval — 拉取退货相关列（price<0 即退货） |
~50ms |
| 11 | node_complete |
sql_generation（第 2 次）— 修复后重试 |
~1.5s |
| 12 | node_complete |
guardrails — 通过 |
~15ms |
| 13 | node_complete |
sql_executor |
~300ms |
| 14 | node_complete |
retrieval_evaluator — 检索覆盖度评估 |
~200ms |
| 15 | node_complete |
sql_evaluator — SQL 正确性评估 |
~200ms |
| 16 | node_complete |
answer_evaluator — 答案质量评估 |
~1.0s |
| 17 | data |
退货率按品类分解结果 | — |
| 18 | insights |
"退货率上升主因是品类 X 的退货增加，可能与产品质量问题相关" | ~1.5s |
| 19 | status |
completed |
— |
| 合计 | ~8.5s |
生成的 SQL（第 2 次，修复后）¶
-- 退货 = price < 0（业务规则：退货金额为负）
-- 按品类分解退货率
WITH stats AS (
SELECT
a.index_group_name AS category,
COUNT(*) AS total,
COUNT(*) FILTER (WHERE f.price < 0) AS returns
FROM gold_hm.fact_transaction f
JOIN gold_hm.dim_article a ON f.article_id = a.article_id
WHERE f.t_dat >= CURRENT_DATE - INTERVAL '3 months'
GROUP BY a.index_group_name
)
SELECT category,
total,
returns,
ROUND(returns::NUMERIC / NULLIF(total, 0) * 100, 2) AS return_rate_pct
FROM stats
ORDER BY return_rate_pct DESC;
最终输出（片段）¶
| category | total | returns | return_rate_pct |
|---|---|---|---|
| Baby/Children | 456,789 | 12,345 | 2.70 |
| Ladieswear | 1,234,567 | 28,901 | 2.34 |
| ... | ... | ... | ... |
洞察：退货率上升主要由 Baby/Children 品类驱动（2.70%），该品类退货率较上月上升 0.4 个百分点。建议排查该品类近期上架商品的质量问题。
链路特点¶
- 修复循环触发：第 1 次 SQL 幻觉了
return_flag列（不存在），Layer 2c 拦截 → corrective_retrieval 拉取退货语义（price<0）→ 第 2 次成功。这正是 Reflexion 范式的工程体现。 - 三级评估器启用：deep_analysis 路由独有，retrieval/sql/answer 三级评估器各跑一次，低分可触发重试。
- 业务规则注入："退货金额为负"这条 business_rule 从图遍历注入 Prompt，引导 LLM 用
price < 0而非幻觉列。
F.3 场景三：帮我预测下月销量（analytical_workflow + ML 工具）¶
路由：analytical_workflow（ML 工具路径）
意图：forecasting
复杂度：高（SQL 取数 + Prophet 预测 + 可视化）
用户输入¶
帮我预测下月销量
SSE 事件序列¶
| # | 事件类型 | 内容 | 耗时 |
|---|---|---|---|
| 1-4 | （同前） | supervisor → QU → router → analytical_workflow | ~1.1s |
| 5 | node_complete |
data_retrieval — 取历史月度销量 |
~40ms |
| 6 | node_complete |
sql_generation — 生成取数 SQL |
~1.5s |
| 7 | node_complete |
guardrails — 通过 |
~15ms |
| 8 | node_complete |
sql_executor — 返回历史 DataFrame |
~500ms |
| 9 | node_complete |
code_generator — 生成 Prophet 调用代码 |
~1.5s |
| 10 | node_complete |
sandbox — L1 沙箱执行 Prophet 预测 |
~3.0s |
| 11 | node_complete |
dataframe_bridge — 转换预测结果 |
~10ms |
| 12 | node_complete |
visualization — 推荐折线图（含预测区间） |
~5ms |
| 13 | insights |
"预计下月销量约 X，趋势上升 Y%" | ~1.0s |
| 14 | status |
completed |
— |
| 合计 | ~8.7s |
取数 SQL¶
SELECT DATE_TRUNC('month', t_dat) AS month, COUNT(*) AS sales_count
FROM gold_hm.fact_transaction
WHERE t_dat >= CURRENT_DATE - INTERVAL '12 months'
GROUP BY month
ORDER BY month;
ML 工具调用（沙箱内执行）¶
# sandbox 内 LLM 生成的代码（简化）
from prophet import Prophet
import pandas as pd
df = pd.DataFrame(history_data) # 来自 dataframe_bridge
df.columns = ['ds', 'y']
m = Prophet()
m.fit(df)
future = m.make_future_dataframe(periods=30, freq='D')
forecast = m.predict(future)
result = forecast[['ds', 'yhat', 'yhat_lower', 'yhat_upper']].tail(30)
最终输出¶
可视化：折线图（历史销量 + 预测值 + 置信区间带） 洞察：基于过去 12 个月数据，Prophet 预测下月销量约 1,450,000 笔，环比上升 3.2%。置信区间 [1,380,000, 1,520,000]。
链路特点¶
- SQL + 代码两阶段：先用 SQL 取历史数据为 DataFrame，再用代码解释器在沙箱跑 Prophet——SQL 负责结构化取数，代码负责机器学习计算。
- L1 沙箱：
exec + whitelist，Prophet 在白名单内，但无资源限制（改进方向：升级 L2，见 第 16 章 16.6.2）。 - DataFrame 桥接：
dataframe_bridge将 SQL 结果转为 pandas DataFrame，供沙箱代码消费。
F.4 场景四：这个数据集里客户和交易是什么关系？（graph_reasoning）¶
路由：graph_reasoning（GraphRAG 路径）
意图：schema_exploration
复杂度：中（NL2Cypher + 图遍历）
用户输入¶
这个数据集里客户和交易是什么关系？
SSE 事件序列¶
| # | 事件类型 | 内容 | 耗时 |
|---|---|---|---|
| 1-4 | （同前） | supervisor → QU → router → graph_reasoning | ~1.1s |
| 5 | node_complete |
graph_rag — LLM 生成 Cypher |
~1.5s |
| 6 | node_complete |
graph_rag — AGE 图遍历执行 |
~200ms |
| 7 | data |
图节点 + 边（供 @antv/g6 渲染） | — |
| 8 | node_complete |
visualization — 推荐关系图 |
~5ms |
| 9 | insights |
"客户通过 customer_id 与交易关联，为 1:N 关系" | ~1.0s |
| 10 | status |
completed |
— |
| 合计 | ~3.9s |
生成的 Cypher¶
MATCH (c:Table {table_id: 'dim_customer'})-[r:JOINABLE_TO]-(t:Table {table_id: 'fact_transaction'})
OPTIONAL MATCH (t)-[:HAS_COLUMN]->(col:Column)
WHERE col.column_name IN ('customer_id')
RETURN c, r, t, col
最终输出¶
可视化：@antv/g6 关系图——展示 dim_customer 与 fact_transaction 通过 customer_id 的 JOINABLE_TO 边，标注基数（1:N）与扇出风险。
洞察：客户表（dim_customer）与交易表（fact_transaction）通过 customer_id 关联，为 1:N 关系（一个客户有多笔交易）。直接 join 无扇出风险，因为交易表是事实表（粒度最低）。
链路特点¶
- 不生成 SQL：GraphRAG 路径不走 SQL 生成/护栏，直接 NL2Cypher → 图遍历 → 可视化。
- 无护栏保护：不同于 SQL 有五层护栏，Cypher 当前无语法校验或安全护栏（改进方向：16.6.3 GraphRAG 护栏）。
- 优雅降级：若 Cypher 生成失败或图遍历超时，自动降级到 SQL 流水线（
fallback_sql）。
四个场景对比¶
| 场景 | 路由 | 端到端耗时 | 触发修复 | 评估器 | ML 工具 | 输出形态 |
|---|---|---|---|---|---|---|
| Top 10 商品 | nl2sql_query | ~3.7s | 否 | 否 | 否 | 表格 + 条形图 |
| 退货率归因 | deep_analysis | ~8.5s | 是（1 次） | 三级 | 否 | 表格 + 洞察 |
| 销量预测 | analytical | ~8.7s | 否 | 否 | Prophet | 折线图 + 置信区间 |
| 客户交易关系 | graph_reasoning | ~3.9s | 否 | 否 | 否 | 关系图 |
耗时为设计目标估值
上表耗时为各节点延迟预算累加的设计目标值，非实测。实际耗时受 LLM 响应速度、数据量、网络等因素影响。系统化性能基线测量是改进方向（第 16 章）。