26.v3 核心升级：语义层 + 指标体系——禁止 LLM 直连 SQL

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

🧠 一、v2 之后，为什么还要 v3？

v2 已经能接 Doris、能 Planner/Optimizer，但 DBA 仍会问：

❗ 「这条 SQL 是谁写的？对应公司哪个指标口径？」

如果答案是「GPT 昨晚写的」，在生产环境几乎不可接受。

v3 的设计宣言写在 main.py 里：

👉 指标驱动，不经 LLM 直连 SQL。

💥 二、v3 一句话

模块	谁来做	做什么
LLM	Metric Agent	选指标 ID（白名单内）
Python	Semantic Planner	意图 + 指标 → QueryPlan
Python	SQL Compiler	QueryPlan → 唯一合法 SQL
Tool	sql_execution_agent	Doris 执行
LLM	Insight / Report Agent	读行集 → 洞察与报告

模型不再产出可执行 SQL 终稿。

🧩 三、v3 全链路

复制代码

用户问题
   ↓
query_understanding_agent
   ↓
metric_agent                    ← metric_ids（registry 白名单）
   ↓
semantic_planner.plan_query     ← QueryPlan（纯 Python）
   ↓
sql_compiler.compile_query_plan ← SQL（纯 Python）
   ↓
sql_execution_agent → Doris
   ↓
insight_agent → report_agent

编排类：OWLSemanticWorkflow（workflow/owl_workflow.py）。

🟢 四、指标注册表：Metric Registry

metrics/registry.yaml 是每个指标的 唯一事实来源：

yaml 复制代码

metrics:
  active_user:
    description: 日活跃用户数（DAU）
    sql_template: "dau"          # Doris 表达式片段，不是自由文本
    source_table: game_daily_metrics
    dimensions: [dt]
    grain: day

  retention_rate:
    sql_template: "retention_d1_pct"
    source_table: game_daily_metrics
    ...

MetricRegistry.validate_ids() 在规划前拦截未知指标。

💥 业务价值

没有 registry	有 registry
「活跃」五种 SQL	「active_user」一种编译路径
审计靠猜	日志可写 `metric_ids + compilation_method`
新同学改 Prompt	新同学改 YAML

🟡 五、Semantic Planner：中间语言 QueryPlan

semantic_layer/semantic_planner.py 把 metric_bundle + understanding 转成结构化计划，例如：

source_table / dimensions / resolved_metrics
time_range_days / partition_field / order_by / limit
失败时返回 valid_metric_ids，不进入编译

这是 v2「sql_plan 文本」的升级版：计划面向指标 IR，面向编译器，而不是面向自然语言 SQL。

🔵 六、SQL Compiler：安全闸

semantic_layer/sql_compiler.py 核心规则：

表名、列名、指标 ID 走 标识符白名单 正则
sql_template 表达式 字符集白名单 ，拒绝 ;、--、/*
LIMIT 上限、days 来自计划而非模型

编译成功时带：

json 复制代码

"compilation_method": "semantic_sql_compiler_v3"

❗ 纠正架构篇里一个容易误导的说法

早期草稿里写过「SQL Compiler 也用 Prompt」------v3 实现里 Compiler 是纯代码 ，Prompt 只用于 Metric Agent 选指标，不用于拼 SQL 终稿。

🟣 七、术语映射：运营「人话」→ 指标候选

semantic_layer/term_map.yaml + term_mapping.py：

「活跃度」→ 候选 active_user
「付费」「GMV」→ order_amount / paying_user

减轻 Metric Agent 负担，也降低选错指标概率。

🧠 八、与 v2 对照表

维度	v2	v3
SQL 来源	Planner + Optimizer（LLM）	Compiler（模板 + 计划）
治理单元	表 / 列（Schema）	指标（Metric）
中间表示	sql_plan	QueryPlan
Workflow	`OWLWorkflow`	`OWLSemanticWorkflow`
状态类	`OpsWorkflowState`	`SemanticWorkflowState`

v3 保留 v2 的 StageCache、Camel Task、Insight/Report 链路------换的是 数据面治理。

🧠 九、运行与 trace

bash 复制代码

cd ai-ops-assistant-v3
pip install -r requirements.txt
python main.py "最近7天用户流失与留存怎么样？"
python main.py --json

JSON 里关注：

compiled_sql_preview
sql_compilation_method
row_count / insight_summary

👉 证明系统是可审计的，而不只是「一篇好看的 Markdown」。

🧠 十、v3 的边界

v3 仍是 CLI 单次跑完：

不能在出数后 改指标再审报告
编排仍绑在 owl_workflow.py Python 类里
无 Web UI、无 Hook 时间线、无多模型适配层

这些由 v4 Agent Native 解决------但 v4 不会推翻 v3 的 registry + compiler，而是把它们装进 Skill。

🧠 十一、总结

💥 核心一句话

👉 v3 的本质：把 AI 运营助手从「会写 SQL 的 LLM」变成「会选指标的平台 + 确定性编译器」。

🚀 下一篇预告

👉 《v4 Agent Native：Runtime + Skill + Hook + HITL三栏 UI》

将回答：语义层稳定之后，产品化、可观测、可插拔 靠什么承载。

关键文件：metrics/registry.yaml、semantic_layer/sql_compiler.py、workflow/owl_workflow.py。