项目概览¶

项目使命¶

TTD 是一个企业级 NL2SQL + Agentic BI 平台。
核心使命：将用户自然语言问题转化为 可治理、可解释、安全执行 的 SQL 查询与分析洞察。

不只是问答机器人

TTD 关注的不仅是"能否出结果"，更关注：

语义治理 — 术语消歧、业务规则约束、上下文假设显式化
执行安全 — SQL Guardrails（语法 + 安全 + EXPLAIN 成本） + 权限过滤
分析体验 — 流式过程展示、智能图表、洞察摘要、会话回放

核心技术架构¶

系统基于以下六大技术支柱构建：

graph TD
    A[三层语义治理<br/>Semantic Governance] --> E[AI Agent 编排]
    B[R/V/G 三引擎<br/>Triple-Engine] --> E
    C[LangGraph Supervisor<br/>+ Sub-agents] --> E
    D[多模型注册表<br/>Multi-Model Registry] --> E
    OBS[双通道观测体系<br/>Langfuse + AutoMQ] --> E
    MEM[Trace-Native 记忆系统<br/>Memory Facade] --> E
    E --> F[可信 SQL 生成 + 安全执行]

1. 三层语义治理（Three-Layer Semantic Governance）¶

层级	名称	内容	目录
Layer 1	Metadata Contracts	表/列/指标定义、关联规则、Few-shot 示例	`domains/`, `few_shots/`, `join_rules/`
Layer 2	Terminology Governance	术语生命周期、消歧矩阵、同义词网络、术语关系	`terms/`, `term_relationships/`
Layer 3	Business Rules & Context	业务规则表达式、上下文假设、约束条件	`business_rules/`, `business_contexts/`

2. R/V/G Triple-Engine 架构¶

graph LR
    subgraph "R — Relational"
        R1[PostgreSQL]
        R2[结构化元数据查询]
    end
    subgraph "V — Vector"
        V1[pgvector]
        V2[语义相似度搜索]
    end
    subgraph "G — Graph"
        G1[Apache AGE]
        G2[关系推理 & 路径发现]
    end
    R1 --> R2
    V1 --> V2
    G1 --> G2

Relational（R）：结构化精确查询——表定义、列属性、指标公式
Vector（V）：语义模糊匹配——自然语言问题与元数据的相似度检索
Graph（G）：关系推理——表间关联路径、术语网络、业务规则依赖链

3. LangGraph Supervisor + Sub-agent 编排¶

flowchart TD
    User[用户问题] --> SUP[Supervisor]
    SUP --> QUA[Query Understanding Agent]
    QUA --> Router{Intent Router}
    Router -->|KPI 查询| KPI[kpi_lookup]
    Router -->|NL2SQL| SQL[nl2sql_query]
    Router -->|深度分析| DEEP[deep_analysis_workflow]
    Router -->|分析工作流| ANA[analytical_workflow]
    Router -->|图推理| GRAPH[graph_reasoning]
    Router -->|知识问答| BK[business_knowledge_qa]
    Router -->|需澄清| CLAR[clarification_required]

4. 多模型注册表（Multi-Model Registry）¶

支持多 LLM Provider 注册与 Fallback 链式降级，按任务类型（理解 / 生成 / 评估）路由到最适合的模型。

版本基线¶

当前版本

Backend 应用版本：4.0.0（见 backend/app/main.py）
Monorepo 管理：uv workspace（Python 3.12+）
前端框架：Next.js 16 + React 19
编排引擎：LangGraph（Supervisor 模式）

子项目全景¶

子项目	路径	技术栈	职责
Semantic Plane	`semantic-plane/`	YAML + JSON Schema + 校验脚本	三层治理元数据资产的编写、验证与版本管理
Data Plane	`data-plane/`	PostgreSQL + AGE + pgvector + pg_mooncake + MinIO	本地数据执行环境（列存表 + 知识图谱 + 向量索引）
Backend	`backend/`	FastAPI + LangGraph + psycopg + multi-model	AI Agent 编排、API 服务、记忆系统、安全模块、元数据发布管道
Web	`web/`	Next.js 16 + React 19 + Zustand + shadcn/ui	对话式 Chat 界面 + 管理后台

graph TB
    subgraph "开发时"
        SP[Semantic Plane<br/>YAML 编写] --> VAL[CI 校验]
        VAL --> PUB[S3 发布]
    end
    subgraph "运行时"
        PUB --> BE[Backend<br/>semantic_plane agent<br/>R+V+G]
        BE --> DP[Data Plane<br/>R+V+G]
        DP --> AGENTS[Backend<br/>Agent 编排]
        AGENTS --> WEB[Web<br/>用户交互]
    end

测试数据集¶

H&M Personalized Fashion Recommendations

项目使用 Kaggle H&M 数据集作为端到端验证基线，包含 3 张核心表：

表名	类型	说明
`dim_article`	维度表	商品属性（颜色、类别、部门等）
`dim_customer`	维度表	客户人口统计信息
`fact_transaction`	事实表	交易记录（客户 × 商品 × 时间 × 金额）

数据通过 data-plane/scripts/load_hm_data.py 加载至 pg_mooncake 列存表，由 pg_mooncake 提供查询引擎。

七大设计原则¶

1. Two-Plane 分离¶

graph LR
    SEM[Semantic Plane<br/>治理 & 定义] -->|发布| DATA[Data Plane<br/>存储 & 执行]

Semantic Plane = 治理态（DPO/Steward 维护 YAML，CI 校验，版本控制）
Data Plane = 执行态（R+V+G 引擎加载后供 Agent 查询）

2. R/V/G Triple-Engine 互补¶

不同访问模式使用不同引擎：精确匹配走 R、模糊语义走 V、关系推理走 G。三者协同而非替代。

3. Supervisor 轻量委托¶

Supervisor 职责是 编排与路由，不执行具体分析逻辑。
每个 Sub-agent 专注单一能力域，Supervisor 仅负责意图判断 → 委托 → 聚合。

4. 显式意图路由（Explicit Intent Routing）¶

非学习式路由

系统采用 7 条显式路由（非 ML 学习），确保可预测、可审计：

kpi_lookup — 指标直查
nl2sql_query — 自然语言转 SQL
deep_analysis_workflow — 多步深度分析
analytical_workflow — 结构化分析流程
graph_reasoning — 图谱推理
business_knowledge_qa — 业务知识问答
clarification_required — 需要用户澄清

5. SQL Guardrails¶

三道安全防线：

语法校验 — SQL 解析验证合法性
安全检查 — 禁止 DDL/DML、子查询深度限制、敏感表访问控制
术语绑定校验 — 当术语绑定到特定列时，校验 SQL 是否将该列引用到正确的表
成本预估 — EXPLAIN 执行计划成本阈值拦截

6. 双语元数据（Bilingual Metadata）¶

所有元数据资产同时维护 _zh（中文）和 _en（英文）字段，支持多语言 Agent 检索与用户展示。

7. 治理优先（Governance-First）¶

机制	说明
PII Masking	`llm_exposure_policy: hidden/masked/visible`
Domain Boundaries	每张表归属明确业务域，跨域查询需显式授权
Tenant Overlays	支持多租户元数据覆盖

文档治理策略¶

统一主干 + 历史归档

本 handbook 是 单一可信来源（Single Source of Truth）
旧文档（docs/talk-to-data-*.md）保留在仓库中仅供历史回溯
mkdocs.yml 的 exclude_docs 已将旧文件排除出构建
所有新增/修改内容请直接更新 handbook 对应页面