一个自然语言数据查询系统，解决了传统 NL2SQL 方案中 LLM 直接生成 SQL 导致的准确率低、结果不稳定等问题。注意，本开源项目只包括伪代码，提供思路参考。
- 业务知识缺失：LLM 不了解企业内部指标口径（如"销售额是否含退款"）
- 结果不确定性：同一问题可能输出不同 SQL，与业务需要的"唯一数据真相"相悖
- 信任危机：自然语言问数门槛低，但需反复确认数据口径
┌─────────────────────────────────────────────────────────────────────────────┐
│ 用户自然语言提问 │
│ "桂林门店9月销售额及月环比、年同比" │
└─────────────────────────────────┬───────────────────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Dynamic Few-shot 检索 │
│ (ChromaDB 向量相似度) │
│ │
│ 检索相似示例 → 注入 Prompt │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ LLM 意图解析 Agent │
│ │
│ 提取要素: │
│ • 指标: 销售额 │
│ • 维度: 门店 │
│ • 时间: 9月 │
│ • 分析: 月环比, 年同比 │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ 构建器 │
│ │
│ • 时间表达式归一化 │
│ • 隐含维度补全 │
│ • 默认排序推断 │
└──────────────┬──────────────┘
│
▼
┌──────────────────────────────────────────────────────────────────────────────┐
│ 指标语义层 (核心) │
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────┐ │
│ │ 指标注册中心 │ │ 维度注册中心 │ │ 逻辑数据模型 │ │
│ │ │ │ │ │ │ │
│ │ 销售额=SUM() │ │ 门店→store_name│ │ 表关联关系 │ │
│ │ 订单量=COUNT() │ │ 城市→city_name │ │ JOIN 路径 │ │
│ └────────────────┘ └────────────────┘ └────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────┐ │
│ │ 确定性 SQL 组装引擎 │ │
│ │ │ │
│ │ 要素 → SQL 的工程化映射 │ │
│ │ metrics → SELECT AGG() │ │
│ │ dimensions → GROUP BY │ │
│ │ filters → WHERE │ │
│ │ analysis → 语义函数 │ │
│ └─────────────────────────────┘ │
│ │ │
│ ┌────────────────┐ │ ┌────────────────┐ │
│ │ 权限管控 │◄─────────┴─────────►│ 语义函数库 │ │
│ │ │ │ │ │
│ │ • 列级权限 │ │ • 月环比 │ │
│ │ • 行级权限 │ │ • 年同比 │ │
│ └────────────────┘ │ • 占比/排名 │ │
│ └────────────────┘ │
└──────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ SQL 执行引擎 │
│ │
│ MySQL / PG │
│ + 查询优化 + 物化加速 │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────┐
│ LLM 结果解读 Agent │
│ │
│ 查询结果 → 自然语言回答 │
│ + 指标口径说明 │
└──────────────┬──────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ "桂林门店2024年9月销售额为120万元，月环比增长5.3%，年同比增长12.1%。 │
│ 【数据口径】销售额为含税销售额，不含退款和消费券抵扣金额。" │
└─────────────────────────────────────────────────────────────────────────────┘
| 层次 | 技术选型 | 说明 |
|---|---|---|
| Web 框架 | FastAPI | |
| LLM | DeepSeek / Qwen / OpenAI | |
| Embedding | BAAI/bge-large-zh-v1.5 | 中文语义向量模型 |
| 向量数据库 | ChromaDB | 动态 Few-shot 示例检索 |
| 数仓引擎 | MySQL / PostgreSQL | SQL 执行 |
project/
├── config/
│ ├── settings.yaml # 全局配置
│ └── semantic_config.yaml # 指标语义层配置
├── app/
│ ├── main.py # FastAPI 入口
│ ├── retrieval/
│ │ └── example_store.py # 动态 Few-shot 检索
│ ├── agent/
│ │ ├── intent_parser.py # LLM 意图解析
│ │ ├── mql_builder.py # MQL 构建器
│ │ └── answer_agent.py # LLM 结果解读
│ ├── semantic_layer/
│ │ ├── metric_registry.py # 指标注册中心
│ │ ├── dimension_registry.py # 维度注册中心
│ │ ├── logical_model.py # 逻辑数据模型
│ │ ├── sql_assembler.py # SQL 组装引擎
│ │ ├── semantic_functions.py # 语义函数库
│ │ └── permission.py # 权限管控
│ ├── executor/
│ │ ├── executor.py # SQL 执行器
│ │ └── optimizer.py # 查询优化
│ └── analysis/
│ └── attribution.py # 归因分析引擎
├── data/
│ ├── examples/
│ │ └── seed_examples.json # Few-shot 种子示例
│ └── chroma_db/ # 向量数据库存储
├── tests/
│ ├── test_intent_parser.py
│ ├── test_sql_assembler.py
│ └── test_e2e.py
├── requirements.txt
└── README.md
MIT