25. v2 实战：接入 Doris + SQL 三阶段（Planner / Optimizer / Execution）

👉 第二个实战项目：AI 运营助手 ；项目 git 地址：ai-ops-assistant-lab

---

🧠 一、v1 跑通之后，一切就万事大吉了吗？

v1 验证了「自然语言 → 报告」闭环，但上线前运营和 DBA 通常会问三句话：

1. 表和字段从哪来？
2. SQL 能不能先计划、再优化、再执行？
3. 同一句「最近 7 天流失」问两遍，为什么要调两次模型？

v2 的目标非常克制：

👉 在保持 Multi-Agent + 确定性 DAG 的前提下，接入 Schema 目录、SQL 三阶段、Doris（可 Mock）、阶段缓存。

💥 二、v2 核心链路（一张图记住）

用户问题
   ↓
query_understanding_agent        ← 意图 JSON
   ↓
SchemaRetriever(catalog.yaml)    ← 候选表 + schema_context
   ↓
sql_planner_agent                ← initial_sql + rationale
   ↓
sql_optimizer_agent              ← optimized_sql
   ↓
sql_execution_agent              ← rows + explain（Doris/Mock）
   ↓
insight_agent                    ← 业务洞察
   ↓
report_agent                     ← Markdown 报告

对应 workflow/owl_workflow.py 中的 PIPELINE_STAGES：

user_question → intent → schema_context → sql_plan → optimized_sql → query_execution → insight → report

🧩 三、为什么要 SQL「三阶段」？

阶段	回答的问题	输出
Planner	查哪些表、过滤什么、聚合意图是什么？	initial_sql, tables_used, rationale
Optimizer	分区裁剪、JOIN 顺序、列裁剪能否改进？	optimized_sql
Execution	能否执行、扫了多少行、错误是什么？	rows, row_count, explain

💥 和 v1 的本质区别

	v1	v2
SQL 生成	sql_generation_agent 一次出终稿	Planner + Optimizer 两跳
表结构	写在 Prompt 里	schema/catalog.yaml 显式目录
执行	sql_tool 薄封装	sql_execution_agent 统一契约 + EXPLAIN
分析	analysis_agent	insight_agent（上下文含 plan/SQL/行集）

👉 治理粒度从「一句 SQL」变成「计划 + 优化 + 执行可追溯」。

🟢 四、Schema 目录：LLM 的「护栏」

schema/catalog.yaml 描述 Doris 表：

• game_daily_metrics：DAU、留存、流失窗口...
• order_daily_summary：订单笔数、GMV...
• 每列 type + description + 分区键 dt

SchemaRetriever.build_prompt_context(tables) 把 有限表空间 注入 Planner/Optimizer Prompt。

infer_tables_from_intent(intent) 根据意图先筛候选表，避免模型在全库字段里幻觉。

🟡 五、结构化状态：OpsWorkflowState

v2 引入 workflow/state.py 中的 OpsWorkflowState，字段与阶段一一对应：

• intent / schema_context / sql_plan / sql_optimizer
• query_execution / insight / report
• cache_hits：各阶段是否命中缓存

编排器只做 搬运与 memo，不在类里写业务 if-else 地狱------这是 OWL「显式 DAG」思想的落地。

🔵 六、StageCache：重复问数为什么变快

workflow/cache.py 对每个阶段用 stable_hash 做 key，例如：

• sql_plan：依赖 question + intent_sig + schema_sig
• query_execution：依赖 sql_sig
• insight：依赖 rows_sig

python main.py --json 返回的 cache_hits 可直接用于：

• 演示「第二次问同一句话几乎不花钱」
• 回归测试对比 trace

配置项：workflow_cache_enabled（见 config.py）。

🧠 七、Doris Mock 双轨

v2 支持：

• doris_use_mock=True：本地无 Doris 集群也能跑
• use_mock_agents=True：无 API Key 时 Planner 等走规则 Mock

两轨独立，适合 CI：只测编排不测 LLM，或只测 LLM 不测集群。

🧠 八、Prompt 文件一览

文件	阶段
prompts/query_prompt.txt	意图理解
prompts/sql_planner_prompt.txt	SQL 计划
prompts/sql_optimizer_prompt.txt	SQL 优化
prompts/report_prompt.txt	报告

Planner 的 Mock 示例会根据 churn_analysis / revenue_analysis 生成 带分区过滤 的 SQL 片段，强调 WHERE dt >= DATE_SUB(...)。

🧠 九、如何运行

cd ai-ops-assistant-v2
pip install -r requirements.txt
cp .env.example .env   # 可选

python main.py "最近7天用户流失情况如何？"
python main.py --json  # 看 cache_hits / state，不打印全文报告

❗ 十、v2 仍没解决的问题（故意留给 v3）

这三点是 v2 的 已知技术债，也是 v3 的存在理由：

1. 终稿 SQL 仍可能来自 LLM（Optimizer）

   → 口径仍可能漂移，难以审计「对应哪个官方指标」。

2. catalog 里有 metrics 片段，但没有 Metric Registry 闭环

   → 无法强制「只能查白名单指标」。

3. CLI 一键跑完，无人回路

   → 运营不能在出数后改指标再审报告。

🧠 十一、总结

💥 一句话

👉 v2 = 把 v1 的「能跑」升级为「敢接 Doris、敢排错、敢缓存」的工程化问数流水线。

🚀 下一篇预告

👉 《v3 核心升级：语义层 + 指标体系------禁止 LLM 直连 SQL》