ReAct 让 Agent 自主决定调什么工具、传什么参数、什么时候收敛。
Agent 有"刹车系统"（Harness），防止失控：
此外，所有 Agent 生成的 SQL 都经过 SQL Validator Gate 后置校验，确保语法正确、表名存在、字段合法。
这是整个系统最关键的技术选型。
直接 Text-to-SQL │ ├── ❌ 幻觉字段：LLM 编造不存在的列名 ├── ❌ 口径错误：不知道某表的 WHERE 条件该加什么 └── ❌ 不可复用：每次从零生成，没有沉淀
LLM 不知道 ads_bybt_flow_sum_di 表必须有 activity_type = '百亿补贴' 这个 WHERE 条件。它会编造字段，会漏掉过滤条件，每次生成结果还不一样。
WrenAI 引入了 MDL（Model Definition Language）——类似 dbt 的语义建模层：
用户问题 │ ▼WrenAI MDL 语义层 │ ├── mdl.json（模型定义文件） ← 表名、字段、关系、描述 ├── dry_plan（NL → SQL 预演） ← 自然语言转 SQL ├── recall（查询历史召回） ← 记住之前问过什么 └── fetch_context（上下文召回） ← 给 LLM 补充表结构信息 │ ▼生成的 SQL 经过语义层校验 │ ▼✅ 字段存在 ✅ 口径正确 ✅ 可复用
mdl.json 定义了每个表的结构化语义：
{ "models": [ { "name": "ads_flow_sum_di","tableReference": { "table": "ads_flow_sum_di" }, "columns": [ { "name": "gmv_amt", "type": "decimal", "expression": "pay_amt" }, { "name": "bizdate", "type": "date" } ], "description": "汇总日表" } ]}
Agent 在生成 SQL 前会先从 MDL 获取表结构，确保只用真实存在的字段。
Agent 根据表类型自动选择 SQL 构建策略：
4.3 节展示了 ReAct 的 Thought→Action→Result 机制。在取数场景中，这些工具调用可以按知识层级归为四个阶段：
Agent 在 ReAct 循环中自主决定调用顺序和是否需要每个阶段——简单取数可能跳过知识应用，复杂分析可能多轮调用。
数据分析场景涉及多次递归下钻查询，每次走 ODPS 执行 SQL 耗时 30-120 秒。当 Agent 需要执行 5-10 次 SQL 才能完成一次诊断时，总耗时可能超过 10 分钟。引入 Hologres 外部表直读 ODPS，将单次查询加速到 3-10 秒。
为什么选 Holo 外部表而不是全量同步：
选择外部表直读：不需要 DBA 介入，onboard 新表自动挂载，第一次查询时自动创建外部表，后续 LRU 缓存命中。
场景闸门——只在数据分析场景启用：
Holo 加速仅对 stream_analysis（多步分析编排器）生效，普通 NL2SQL、CLI 脚本、运维查询一律走 ODPS。通过 contextvars.ContextVar 实现线程/协程安全的场景标记：
LLM 生成 ODPSSQL │ ▼odps_query 工具（接口签名不变） │ ├─ Step0: 场景闸门——HOLO_ROUTE_MODE=always 且 holo_scope=True？ │ 否 → 直走 Step7ODPS │ 是 ↓ ├─ Step1: 变量替换（${bizdate} → 具体日期值） ├─ Step2: 黑名单检测（GET_JSON_OBJECT/EXPLODE 等不兼容函数 → 直走 ODPS） ├─ Step3: 抽取 SQL 中所有表名（sqlglot AST 解析） ├─ Step4: ensure_foreign_tables——按需创建外部表 │ 检查 information_schema.foreign_tables 是否已存在 │ 不存在 → IMPORTFOREIGNSCHEMA LIMITTO () │ LRU 缓存 + 持久化 JSON，避免重复 DDL ├─ Step5: sqlglot 方言转换（ODPS → PostgreSQL） │ + 表名重写（bm_dw.xxx → public.xxx） ├─ Step6: 通过 aistudio HTTP 网关执行 │ ├─ 成功 → 返回结果（标记 "via Hologres"） │ └─ 失败 → Step7 └─ Step7: FallbackODPS（PyODPS execute_sql，原路径）
外部表自动管理：
不需要 DBA 预先 IMPORT 整个 project（上千表一次性 IMPORT 很贵）。而是拿到 SQL 后用 sqlglot 抽出表名，按需创建。首次查某表多 1-3 秒建表开销，后续查 LRU 命中零开销。
# 进程内存缓存（set）+ 持久化文件（.holo_foreign_imported.json）# 幂等去重，重启不丢失# 外部表与 ODPS 表同名，默认 prefix/suffix 为空
当 Hologres 实例切库（如重建实例）后，所有外部表丢失。此时查询会报 relation "xxx" does not exist。系统自动检测该错误，清空 IMPORT 缓存，重新 ensure 外部表后重试一次。整个过程对 Agent 透明，最多增加 3 秒。
知识库是 Agent 的"记忆"。一个能正确取数、能深度归因的 Agent，背后必须有一套结构化的知识体系支撑。本章从存储、采集、应用三个维度展开。
┌─────────────────────────────────────────────────────────────┐│ 应用层 ││ Agent ReAct 循环主动调用知识检索工具 ││ search_metrics / cap_search / snippet_search / rule_search ││ lightrag_column_logic / parse_sql_lineage │├─────────────────────────────────────────────────────────────┤│ 采集层 ││ ││ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ ││ │ AST 血缘 │ │ 指标注册 │ │ Onboard 流水线 │ ││ │ 解析引擎 │ │ 体系 │ │ (表接入) │ ││ │ (6-Phase) │ │ (3 种公式) │ │ (5 步自动接入) │ ││ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ ││ │ │ │ ││ ▼ ▼ ▼ │├─────────────────────────────────────────────────────────────┤│ 存储层 ││ ││ Layer 1: 表能力清单 + MDL 语义模型 ││ Layer 2: SQL 片段库 (Snippet Store) ││ Layer 3: SQL 规则库 (Rule Store) ││ Layer 4: 血缘知识图谱 (LightRAG KG) + AST 实时解析 ││ Layer 5: 指标注册表 (Metric Registry) ││ Layer 6: 会话记忆 (Session Memory) │└─────────────────────────────────────────────────────────────┘
知识分为六层，每层有不同的粒度、变更频率和权威等级：
血缘知识（Layer 4）的数据从哪来？答案是 AST 血缘解析引擎——一套基于 sqlglot 的 SQL 静态分析管线，从 ETL 源代码中自动提取字段级血缘。血缘关系是数据治理的核心：某张表的 GMV 字段来自哪几张上游表？经过了什么计算？WHERE 条件是什么？这些信息分散在数百行的 ETL SQL 中，人工维护不可持续。
原始 ETL SQL │ ▼Phase 0: Schema Registry ← 加载所有相关表的字段定义 │ (本地 JSON 文件 + DataWorks API 降级) ▼Phase 1: 预处理 (Preprocess) ← 全角标准化 / DDL 剥离 / 变量替换 │ 多 INSERT 拆分 / 方言兼容 ▼Phase 2: AST 标准化 (Normalize) ← sqlglot 解析 SQL → AST │ 展开 SELECT * 为显式列列表 ▼Phase 3: 节点提取 (Extract) ← DFS 遍历 AST，按 scope 提取 │ CTE / 子查询 / UNION 分支 / 主查询 │ 每个.scope: 源表、输出列、JOIN、WHERE ▼Phase 4: 作用域解析 (Resolve) ← 符号表 + alias 消歧 │ CTE scope 隔离，拓扑序逐层解析 │ 裸列名 → schema 消歧定位 ▼Phase 5: 血缘映射 (Map) ← resolved scopes → 血缘边 (Edge) │ direct: 上游列直传 │ computed: 表达式中的所有列引用 │ aggregated: SUM/COUNT 等聚合 ▼Phase 6: 输出构建 (Output) ← 生成标准化 JSON target_table / source_tables / columns(含 depends_on) / joins / where_conditions
Agent 需要查字段血缘 │ ├── 1. lightrag_column_logic(table, column) ← 先查 LightRAG KG │ ↓ KG 未命中（表未 onboard） ├── 2. dw_get_table_source(table) ← 取 ETL 源代码 │ ↓ 拿到 SQL └── 3. parse_sql_lineage(sql, column) ← AST 实时解析 ↓ 返回字段映射、来源表、WHERE 条件
内置 回归测试框架，覆盖 45 张真实表、296 个节点：
指标注册表（Layer 5）是波动归因诊断的核心知识源——它定义了每个业务指标如何拆解。
归因诊断的核心是"拆解"：GMV 跌了 20%，要拆成访客数 × 转化率 × 客单价，找出哪个因子是主因。但"GMV 等于什么"这个知识从哪来？
如果靠 LLM 自己猜，它可能拆成"流量 × 客单价"——漏掉了转化率。如果写死在代码里，每加一个指标都要改代码。
指标注册体系让指标定义成为声明式配置，运营同学通过 Web 向导就能接入新指标。
metric_id: gmvname: GMVformula_type: multiplicativedescription: 支付GMV，流量漏斗拆解为 曝光UV × 转化率 × 客单价total_col: pay_amtfactors: - name: IPVUV label: 曝光UV type: column # 直接取列值 column: ipv_uv - name: CVR label: 转化率 type: ratio # 分子/分母 numerator: ord_cnt denominator: ipv_uv - name: AOV label: 客单价 type: ratio numerator: pay_amt denominator: ord_cntsource: table: ads_sup_index_didimensions: - dim_col: ind1_name label: 行业 perspective: goods # 供给/商品类 axis: business - dim_col: act_type label: 活动类型 perspective: place # 渠道/流量类 axis: trafficaliases: [gmv_amt, 交易额, 成交额]
乘法型恒等式铁律：因子相乘后约分必须恰好等于 total_col。
GMV = IPVUV × CVR × AOV = ipv_uv × (ord_cnt / ipv_uv) × (pay_amt / ord_cnt) = pay_amt ✅
每个指标关联一组可拆解维度，维度按两个正交轴分类：
指标接入通过 Web 平台的"指标接入向导"完成，AI 辅助生成 MetricDef：
1. 选择 MDL 表 → 系统列出表结构和字段2. AI 生成 MetricDef → LLM 根据 schema 自动推导公式类型和因子3. 预览生成的公式 → 校验恒等式、维度分类4. 确认入库 → 写入 metrics.yaml + formula_registry5. 自动同步 → 刷新 metric_registry 缓存
AI 生成时的容错机制：
perspective/axis 混淆自动修正（LLM 常把 axis 值填到 perspective）
Pydantic schema 逐条校验，不合法的标红但不阻断合法项
注入 table_profile 信息辅助 AI 理解 ROLLUP/CUBE 结构
metrics.yaml (指标定义) │ ▼formula_registry (公式展开) │ GMV → [漏斗公式: IPVUV × CVR × AOV] │ [加法公式: Σ(各行业 GMV)] │ [比率公式: GMV / 总流量] ▼归因诊断引擎 │ 多路筛选 → 选最显著拆解 │ 递归下钻 → 沿主因子逐层拆 ▼诊断树报告
Agent 在 ReAct 循环中会主动调用知识检索工具，每层知识对应不同的工具：
Agent 思考："用户问 GMV，我需要先找表" → search_metrics("GMV") ← Layer 5: 指标定义 (找到 gmv_amt) → cap_search("GMV ") ← Layer 1: 能力清单 (找到表) → snippet_search(table="ads...") ← Layer 2: SQL 模板 → rule_search(table="ads...") ← Layer 3: 编写规则 → lightrag_table_lineage("ads...")← Layer 4: 血缘关系 (KG) → parse_sql_lineage(sql="...") ← Layer 4: 血缘关系 (AST 实时)
知识不是静态的，而是采集 → 沉淀 → 审核 → 复用的闭环：
┌─────────────┐ │ 采集入口 │ └──────┬──────┘ │ ┌────────────────┼────────────────┐ │ │ │ ▼ ▼ ▼ AST 血缘解析 对话产出 SQL 指标接入向导 (ETL 源代码) (自动暂存) (AI 生成) │ │ │ ▼ ▼ ▼ LightRAG KG Staging 队列 metrics.yaml (血缘图谱) (待审核片段) (指标定义) │ │ │ └────────────────┼────────────────┘ │ ┌──────▼──────┐ │ 人工审核 │ │ (Web 平台) │ └──────┬──────┘ │ ┌──────▼──────┐ │ 入库复用 │ │ 下次 Agent │ │ 优先命中 │ └─────────────┘ │ 表结构变更 → 自动 regenerate → 更新规则/片段/AST 血缘
▐ 7.1 波动归因诊断（Analysis Agent）
“昨天 GMV 为什么跌了 20%？”
GMV 环比 -20% │ ├── 漏斗拆解：GMV = 访客数 × 转化率 × 客单价 │ ├── 访客数 +5% ← 不是原因 │ ├── 转化率 -22% ← ⭐ 主因！ │ └── 客单价 +3% ← 不是原因 │ ├── 转化率 -22% 按行业拆 │ ├── 家电 -45% ← ⭐ Top1 贡献 │ ├── 服装 -8% │ └── 食品 +2% │ ├── 家电转化率 -45% 指标拆解 │ ├── 下单量 -40% ← ⭐ 主因 │ └── 访问量 -8% │ └── 结论：家电行业下单量骤降导致 GMV 下跌
“GMV 这个字段是怎么计算出来的？上游依赖哪些表？”
Agent 的血缘溯源有两条路径，形成 KG 优先、AST 降级的降级链：
# 路径 1: 查 LightRAG 知识图谱（local 模式）lightrag_column_logic(table="ads_flow_sum_di", column="gmv_amt")→ gmv_amt = pay_amt (直接映射) 上游: dwd_ord_ent.pay_amt 过滤: WHERE activity_type =''# 路径 2: KG 未命中时，AST 实时解析 ETL 源代码dw_get_table_source(table="ads_flow_sum_di") → 拿到 SQLparse_sql_lineage(sql_text="INSERT OVERWRITE TABLE ...", target_column="gmv_amt")→ gmv_amt = pay_amt source_columns: [dwd_ord_ent.pay_amt] where_conditions: [activity_type ='']# 查表的完整上游依赖（hybrid 模式）lightrag_table_lineage(table="ads_flow_sum_di")→ 上游依赖 3 张表:1. dwd_ord_ent (交易明细)2. dim_activity_info (活动维表)3. dws_flow_sum_h (小时汇总)
KG 中的血缘数据由 AST 引擎在 onboard 时离线解析并灌入，实时解析作为降级补充。详见 6.3 节。
当查询结果需要二次加工时（帕累托、排名、透视、环比计算），Agent 会调用 python_analyze：
# Agent 生成的分析代码（沙箱内执行）df['环比'] = (df['today'] - df['yesterday']) / df['yesterday']df = df.sort_values('today', ascending=False)df['累计占比'] = df['today'].cumsum() / df['today'].sum()result = df[['industry', 'today', 'yesterday', '环比', '累计占比']].head(10)print(result.to_markdown())
1. 表结构同步 → ODPS schema → mdl.json + TisPlus32. 表类型探查 → A类(预聚合)/B类(普通) + 主键 + 维度3. 规则抽取 → 下游血缘代码 → LLM 提取 WHERE 条件4. SQL 模板生成 → B类表自动生成标准模板5. 入库 → 规则/片段/能力清单写入 TisPlus3
bybt-data-analysis-assistant/├── agent.py # CLI 入口 + Agent 构建├── agent_analysis.py # 模板分析入口├── config.py # 全局配置（ODPS/LLM/TisPlus3/...）├── boot.sh # 生产部署脚本│├── agents/ # 多 Agent 架构│ ├── supervisor.py # 路由调度器│ ├── intent_agent.py # 意图识别 Agent│ ├── base_expert.py # 专家 Agent 基类│ ├── query_agent.py # 取数+血缘+元数据+源代码+SQL开发│ ├── analysis_agent.py # 波动归因+数据分析│ ├── ops_agent.py # 调度运维│ ├── other_agent.py # 兜底寒暄│ ├── harness.py # 运行时安全守卫│ └── sql_validator_gate.py # SQL 后置校验│├── tools/ # 工具集（Agent 的"手"）│ ├── odps/ # ODPS 查询 + SQL 构建│ ├── capabilities/ # 表能力清单检索│ ├── snippets/ # SQL 片段检索│ ├── rules/ # SQL 规则检索│ ├── lineage/ # 血缘知识图谱│ ├── analysis/ # Python 分析沙箱│ ├── attribution/ # 归因诊断引擎│ ├── dataworks/ # DataWorks API│ ├── memory/ # 会话记忆│ └── intent/ # 意图识别│├── web/ # Web 平台│ ├── api/ # FastAPI 后端│ └── frontend/ # React 前端│└── wren_project/ # WrenAI MDL 语义模型 ├── target/mdl.json # 模型定义文件 └── .wren/memory/ # 向量索引
Agent 的「聪明」不能靠感觉判断，必须有可量化、可复现的评测体系。本章回答三个核心问题：评什么（6D 维度）、怎么构造样例（Golden Dataset）、怎么打分（意图感知权重 + 节点归因）。
评测从 6 个维度对 Agent 的每次回答打分，每个维度 0-100 分：
不同意图关注点不同——归因分析不关心 SQL 正确性（D5=0），取数不关心因子命中（D1=0）。系统为每个意图配置了差异化权重：
权重为 0 的维度显示为 --，不参与打分。权重可通过 Web 界面自定义调整（scripts/eval/metrics_config.json）。
▐ 9.3 Golden Dataset — 样例构造
评测样例存放在 scripts/eval/datasets/default.json，当前覆盖 6 类意图、15 个用例：
{"id":"gmv_daily_attribution","question":"20260610 GMV波动分析","intent":"analysis","tags":["attribution","gmv","daily"],"expected":{"main_factor":["3C数码","坑产","平台出资","GMV_PER_ITEM"],"main_factor_fuzzy":["3C","坑产","平台"],"formula_used":["gmv.industry","gmv.supply","gmv_per_item.is_bt"],"direction":"up","min_tree_depth":2,"must_call_tools":["attribution_diagnose","attribution_explain"],"must_not_call_tools":[],"conclusion_must_contain":["贡献","主因","3C"]}}
样例设计原则：
expected 多层校验：不只看最终回答，还看中间过程（工具调用序列、SQL 内容、诊断树结构）
模糊匹配兜底：main_factor_fuzzy 允许部分命中得 60 分，避免因措辞差异误判
意图覆盖：每类意图至少 2 个用例，边界用例覆盖错误输入场景
可扩展：通过 Web 界面「评测中心」可在线增删用例，无需改代码
用户提问 │ ▼harness.run_case(question) │ 调用 stream_supervised() 获取 SSE 事件流 │ 收集: tool_call / tool_result / token / routing / validation 事件 │ 解析: attribution_diagnose 返回的诊断树 JSON │ 检测: HOLO fallback 标记 ▼EvalTrace (结构化 trace) │ events: 全部 SSE 事件 │ tool_calls: 工具调用序列 │ tool_results: 工具返回结果 │ diagnosis_tree: 诊断树 JSON │ final_answer: 最终回答 │ nodes: 7 个关键节点的状态 ▼6D 打分 (scorers) │ D1 factor_scorer → 严格匹配(100) / 模糊匹配(60) / 方向匹配(30) / 不匹配(0) │ D2 tree_scorer → 深度 + 分支数 + 方向 │ D3 tool_scorer → must_call(40) + must_not_call(25) + ordering(20) + step(15) │ D4 conclusion_scorer → LLM-as-Judge 按意图 Rubric 打分 │ D5 sql_scorer → 语法 + 表名 + 字段名 + WHERE + 白名单 │ D6 faithfulness_scorer → 规则检查 + LLM 幻觉检测 ▼加权总分 = Σ(Di × Wi) → 意图感知权重 ▼报告输出 ├── 终端彩色报告 (6D 分数 + 归因诊断) ├── JSON 报告 → reports/eval__.json ├── Bad Case 归档 → badcases/ (总分60 或任一维度=0) └── 版本对比 → --compare old.json new.json
评测不只给分数，还自动定位失败根因。Harness 从事件流中提取 7 个关键节点的状态：
当总分低于预期时，归因诊断会指出是哪个节点出了问题，例如：
根因: gate - validation_exhausted (重试 3 次未通过)根因: tool_call - 工具返回错误: odps_query根因: quality - 各节点均成功，但回答质量未达预期
粤ICP备14082021号
免费POC，
零成本试错
