原始资料
下文逐字同步仓库 docs/PROJECT.md。其中性能数字与产品对标属于原文的目标或说明，不代表本仓库已实现或已实测。
AtlasSQL｜企业级 NL2SQL 数据智能分析平台
1. 项目概述
1.1 项目名称
AtlasSQL
Enterprise NL2SQL & Data Intelligence Agent
中文定位：
企业级自然语言数据分析与智能问数平台
2. 项目背景
大型企业的数据通常分散在 ERP、CRM、OMS、WMS、财务、会员、营销等多个业务系统中。
业务人员需要进行数据分析时，通常需要经历：
业务人员提出需求
↓
数据分析师理解需求
↓
寻找数据表
↓
确认指标口径
↓
编写 SQL
↓
执行查询
↓
生成结果
↓
业务人员再次确认存在几个典型问题：
- 企业数据库表数量多、字段复杂，普通业务人员无法直接使用。
- 同一个业务概念可能跨越多张事实表、维度表。
- “销售额”“有效客户”“毛利率”等业务指标并不等价于某一个数据库字段。
- 不同部门对相同指标可能存在不同业务口径。
- SQL 编写依赖数据分析师和研发人员，人力成本高。
- 直接让大模型面对完整数据库 Schema，准确率和稳定性不足。
- LLM 生成 SQL 存在错误查询、越权查询和高成本查询风险。
- 模型、Prompt、Schema、指标发生变化后，系统可能出现不可感知的准确率回退。
因此 AtlasSQL 的目标不是简单实现：
Natural Language → SQL而是构建：
Natural Language
↓
Business Semantics
↓
Schema Linking
↓
Query Planning
↓
Governed SQL
↓
Validated Result即：
Text → Semantics → SQL → Validated Result
3. 项目业务场景
为了覆盖真实企业 NL2SQL 的主要复杂问题，AtlasSQL 模拟一家中大型零售集团：
NovaRetail Group
集团同时经营线上商城、线下门店和会员体系。
一期建设以下七个业务域：
| 业务域 | 核心数据 |
|---|---|
| Sales 销售 | 订单、订单明细、付款、退款 |
| Product 商品 | 商品、SKU、品牌、品类 |
| Customer 客户 | 客户、会员等级、客户标签 |
| Store 门店 | 门店、城市、区域 |
| Inventory 库存 | 仓库、库存流水、库存快照 |
| Finance 财务 | 收入、成本、毛利 |
| Marketing 营销 | 活动、渠道、优惠券 |
最终目标数据规模：
7 个业务域
50～80 张核心业务表
600～1000 个字段
数百万～千万级模拟业务数据
30～50 个核心业务指标
500+ NL2SQL Benchmark 问题
200+ Verified Queries该业务模型必须包含：
- 事实表
- 维度表
- 一对一关系
- 一对多关系
- 多对多关系
- 多事实表
- 历史快照表
- 状态字段
- 编码字段
- 枚举字段
- 多时间字段
- 多业务口径
- 敏感字段
- 行级权限
- 列级权限
从数据模型层主动制造真实企业 NL2SQL 难题，而不是建立一个为了让 LLM 容易回答而设计的数据库。
4. 项目目标
AtlasSQL 最终需要实现六类核心能力。
4.1 自然语言问数
用户能够直接输入：
2026 年上半年华东区销售额同比增长多少？
找出销售额下降超过 10%，但是毛利率提升的城市。
苹果手机上个月在哪些城市卖得最好？
华南区域本季度新客户数量环比怎么样？
系统自动完成：
问题理解
→ 数据域定位
→ Schema 召回
→ Schema Linking
→ 指标解析
→ Value Linking
→ SQL 生成
→ SQL 校验
→ 权限判断
→ 查询执行
→ 结果校验
→ 自然语言解释5. 产品形态
AtlasSQL 不仅提供 Chat 页面，同时提供完整管理后台。
系统包括两个主要应用：
AtlasSQL
│
├── Data Analyst
│ └── 面向普通业务用户
│
└── Admin Console
└── 面向数据管理员 / 数据分析师 / 平台管理员6. 用户端功能
用户端包括：
AI 问数
支持自然语言数据查询。
多轮分析
例如：
用户：
今年销售额最高的五个城市？
AtlasSQL：
上海、杭州……
用户：
只看华东呢？
用户：
再和去年比较。
用户：
杭州下降主要是什么品类导致的？系统需要正确继承上下文。
SQL 展示
允许用户查看：
- Generated SQL
- 使用的数据表
- 使用字段
- Join Path
- Metric Definition
- 查询条件
数据解释
返回：
销售额：12.8 亿
同比：
+8.4%
主要增长区域：
上海
杭州
苏州可视化
根据查询结果自动选择：
- Table
- Bar
- Line
- Pie
- KPI
- Ranking
7. 管理后台
管理后台必须包括：
DataSource Management
Metadata Management
Business Domain Management
Semantic Model Management
Metric Management
Dimension Management
Business Glossary
Relationship Management
Verified Query Repository
Permission Management
Benchmark Management
Prompt Management
Model Management
Query Trace
Evaluation Dashboard
Failure Analysis这一部分是 AtlasSQL 与普通 NL2SQL Demo 的重要区别。
8. 企业级总体架构
AtlasSQL 从第一版开始采用完整企业级基础设施：
┌───────────────┐
│ Web UI │
│ Next.js │
└───────┬───────┘
│
▼
┌────────────────┐
│ FastAPI │
│ API Gateway │
└───────┬────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
Query Orchestrator Admin Service
│
▼
Query Understanding
│
▼
Domain Router
│
▼
Retrieval Engine
│
┌────────┴─────────┐
│ │
▼ ▼
OpenSearch Milvus
BM25 / Keyword Dense Vector
│ │
└────────┬─────────┘
▼
RRF Fusion
│
▼
Reranker
│
▼
Schema Linking
│
┌────────┼────────┐
▼ ▼ ▼
Schema Semantic Verified
Context Context Queries
│ │ │
└────────┼────────┘
▼
Query Planner
│
▼
IR
│
▼
SQL Generator
│
▼
SQL Validator
SQLGlot
│
▼
Policy Engine
│
▼
SQL Executor
│
┌──────┴──────┐
│ │
Error Result
│ │
▼ ▼
SQL Repair Result Validator
│
▼
Answer Generator9. 三类核心数据基础设施
这是 AtlasSQL 最重要的基础架构设计之一。
9.1 PostgreSQL：Control Plane
PostgreSQL 不承担主要向量搜索。
它负责保存结构化、强一致、需要治理的数据。
包括：
datasource
database
schema
table_metadata
column_metadata
relationships
business_domain
semantic_model
metric_definition
dimension_definition
business_terms
permissions
verified_query
benchmark
evaluation_result
query_history
prompt_version
model_configPostgreSQL 是整个 AtlasSQL 的：
Metadata & Governance Control Plane
10. Milvus：Semantic Retrieval Engine
Milvus 专门负责 Dense Vector Retrieval。
主要 Collection：
schema_embeddings
semantic_embeddings
verified_query_embeddings
business_term_embeddings
value_embeddings例如：
用户：
“最近卖得最好的苹果手机”Embedding 可以召回：
product.brand_name
product.product_name
sales_order_item
metric.sales_quantityMilvus主要解决：
语义相似性召回。
11. OpenSearch：Lexical Retrieval Engine
OpenSearch 负责：
BM25
Keyword Retrieval
Field Name Search
Business Term Search
Alias Search
Value Search
Fuzzy Search例如用户输入：
SKU
GMV
VIP
Apple
WH-001
SKU000392这种明确关键词、编码和数据库真实值，Lexical Search 往往比纯 Embedding 更可靠。
因此 AtlasSQL 不采用：
Vector Search Only而采用：
Dense Retrieval
+
Lexical Retrieval12. SearchRepository
业务层不能直接：
milvus.search()
opensearch.search()而是统一依赖：
SearchRepository例如：
class SearchRepository:
async def search_schema(...):
...
async def search_values(...):
...
async def search_semantics(...):
...
async def search_verified_queries(...):
...内部实现：
SearchRepository
│
├── MilvusRetriever
│
├── OpenSearchRetriever
│
├── RRFFusion
│
└── Reranker这样基础设施实现不会污染业务层。
13. Hybrid Retrieval
AtlasSQL 默认检索链路：
Question
│
├────────────────────┐
▼ ▼
OpenSearch Milvus
BM25 Dense
│ │
▼ ▼
Top K Top K
│ │
└──────────┬─────────┘
▼
RRF
│
▼
Top Candidates
│
▼
Reranker
│
▼
Final Context采用：
Hybrid Search + RRF + Reranker
而不是纯 Vector Search。
14. Redis
Redis 主要负责：
Query Cache
Schema Cache
Semantic Context Cache
Value Cache
Session Context
Rate Limit
Distributed Lock例如一个数据源的 Schema 不需要每次查询 PostgreSQL。
可以：
PostgreSQL
↓
Redis
↓
Query Pipeline15. Metadata Center
Metadata Center 自动从业务数据库采集：
Database
Schema
Table
Column
Primary Key
Foreign Key
Index
Type
Nullable
Comment
Statistics
Sample Value除此之外，还允许人工补充：
Business Name
Business Description
Domain
Grain
Authoritative Source
Sensitivity
Alias例如：
fact_order_item
技术描述：
订单商品明细
Business Grain：
一行代表一个订单中的一个 SKU
Business Domain：
Sales
Authoritative：
销售商品级分析权威事实表Microsoft Fabric 2026 年的数据 Agent 最佳实践同样明确强调 Schema 范围、对象描述、表 Grain、关系、业务术语以及 Example Queries，因为仅凭表名和字段名不足以支撑可靠的企业问数。
16. Query Understanding
自然语言首先转换成结构化 Query Intent。
例如：
找出今年华东地区销售额同比下降超过 10% 的城市。
转换：
{
"intent": "analytical_query",
"domain": "sales",
"metrics": [
"net_sales"
],
"dimensions": [
"city"
],
"filters": [
{
"field": "region",
"value": "华东"
}
],
"time": {
"period": "2026",
"comparison": "year_over_year"
},
"conditions": [
{
"metric": "growth_rate",
"operator": "<",
"value": -0.1
}
]
}主要识别：
Intent
Domain
Metric
Dimension
Entity
Filter
Time
Comparison
Aggregation
Ranking
Limit17. Domain Routing
第一层不直接找表，而是确定问题属于哪个业务域。
例如：
Question
↓
Domain Router
│
├── sales 0.96
├── finance 0.51
├── marketing 0.21
└── inventory 0.08确定：
domain = sales随后 Schema Retrieval 只允许在：
Sales Domain
+
必要关联 Domain范围内工作。
18. Schema Retrieval
Schema Retrieval 分为两级。
Table Retrieval
首先召回相关表。
Question
↓
OpenSearch
+
Milvus
↓
RRF
↓
Top 20
↓
Reranker
↓
Top 5～10Column Retrieval
随后在候选表内部进一步检索字段。
避免把：
10 张表 × 80 个字段全部交给模型。
最终可能只保留：
5 张表
+
20～40 个关键字段19. Schema Linking
Schema Retrieval 解决：
哪些 Schema 可能相关？
Schema Linking 进一步解决：
用户问题里的每一个业务概念到底对应哪个字段？
例如：
“销售额”
↓
metric.net_sales
“华东”
↓
dim_region.region_name
“城市”
↓
dim_city.city_name
“今年”
↓
fact_order.order_date输出：
Question Concept
↕
Physical Schema20. Join Graph
仅检索到正确字段仍然不够。
例如：
fact_order_item.net_amount和：
dim_region.region_name之间可能没有直接关联。
关系图：
fact_order_item
│
│ order_id
▼
fact_order
│
│ store_id
▼
dim_store
│
│ city_id
▼
dim_city
│
│ region_id
▼
dim_region系统维护：
Join Graph如果 Schema Linking 只选中了起点和终点：
fact_order_item
dim_region系统自动通过 Join Graph 找到合法路径并补齐：
fact_order
dim_store
dim_cityJoin Graph 第一阶段不引入 Neo4j。
关系定义仍然存 PostgreSQL。
查询服务加载为内存 Graph，通过图算法完成：
Shortest Path
Path Validation
Cardinality Check避免为了“用了图”额外引入没有必要的基础设施。
21. Value Linking
用户表达的实体并不一定等于数据库真实值。
例如：
苹果手机数据库：
brand_name = Apple
category_name = Smartphone系统需要完成：
苹果
↓
Apple
↓
dim_product.brand_nameValue Linking 使用：
OpenSearch Exact Search
BM25
Fuzzy Search
Milvus Semantic Search
Alias Dictionary
Sample Values最终确认：
Value
+
ColumnDatabricks 2026 年的 Genie Agent 配置同样已经显式支持 example values、value dictionary、join、measures、filters 和 expressions 等知识信息，说明数据库值与业务语义本身已经成为现代 NL2SQL/Data Agent 的核心上下文。
22. Semantic Layer
Semantic Layer 是 AtlasSQL 最核心的业务知识层。
数据库可能不存在：
销售额
活跃客户
客单价
毛利率
复购率这些字段。
例如：
metric:
name: net_sales
label: 销售额
synonyms:
- 营收
- 净销售额
- 销售收入
expression:
SUM(fact_order_item.net_amount)
filters:
- fact_order.status = 'PAID'
- fact_order.is_test = false
dimensions:
- date
- city
- region
- productSemantic Layer 管理：
Metric
Measure
Dimension
Entity
Relationship
Filter
Synonym
Business Term
Fiscal Calendar
Time Definition23. Semantic Model 生命周期
Semantic Model 必须版本化。
状态：
Draft
Testing
Published
Deprecated例如：
net_sales v1
↓
net_sales v2
↓
net_sales v3如果财务部门调整销售额计算规则：
修改 Metric
↓
生成 Semantic Model v4
↓
Benchmark Regression
↓
审核
↓
Publish
↓
Cache Invalidation不能直接修改线上定义。
24. Verified Query Repository
维护经过人工或自动审核的：
Natural Language
+
Verified SQL例如：
Question:
华东地区今年销售额是多少？对应：
SELECT ...保存：
question
sql
domain
semantic_model_version
description
tags
verified_by
verified_at
versionQuestion 和 SQL 的语义向量进入 Milvus。
文本信息进入 OpenSearch。
查询时：
Current Question
↓
Hybrid Retrieval
↓
Similar Verified Queries
↓
Top K
↓
SQL Generator Context这不是把 Few-shot 固定写在 Prompt 中，而是动态选择真正相关的 Example SQL。
Snowflake 当前的 Verified Query Repository 就采用“问题 + 已验证 SQL”的方式，为相似问题提供可信参考；Databricks Genie Agent 也把 Example SQL 和 Trusted Assets 作为提升可靠性的重要配置。
25. Query Planner
复杂问题禁止直接：
Question → SQL采用：
Question
↓
Query Planner
↓
Intermediate Representation
↓
SQL Generator例如：
{
"metrics": [
"net_sales",
"gross_margin_rate"
],
"dimensions": [
"city"
],
"time_ranges": {
"current": "2026",
"comparison": "2025"
},
"filters": {
"region": "East China"
},
"operations": [
"year_over_year",
"filter",
"ranking"
]
}IR 可以独立进行：
Validation
Evaluation
Logging
Debugging同时将：
业务理解与：
SQL Dialect解耦。
26. SQL Generation
SQL Generator 的 Context 不再是：
Question + 全部 Schema而是：
System Policy
Question
Query Plan
Selected Schema
Join Path
Semantic Definitions
Business Rules
Value Mapping
Verified Queries
SQL Dialect最终：
Context Builder
↓
LLM
↓
SQL Candidate27. SQL Validator
生成 SQL 禁止直接进入数据库。
首先使用：
SQLGlot
解析：
SQL
↓
AST检查：
Statement Type
Tables
Columns
Functions
JOIN
Subquery
CTE
Limit
Aggregation拦截：
INSERT
UPDATE
DELETE
DROP
ALTER
TRUNCATE
CREATE同时检查：
Unknown Table
Unknown Column
Forbidden Table
Sensitive Column
Cartesian Join
Unsafe Function28. Policy Engine
SQL 安全不能依赖 Prompt。
权限分三层：
User
↓
Application Policy
↓
Authorized Metadata
↓
SQL Validation
↓
Database Native Permission例如：
CEO
→ 全国
华东区域经理
→ 华东数据
上海门店经理
→ 上海门店
Finance
→ 成本字段
Sales
→ 无薪资字段权限权限必须同时作用于：
Schema Retrieval
Semantic Retrieval
SQL Validation
Database Execution未经授权的 Schema 最好根本不进入模型 Context。
29. SQL Execution
SQL Validator 通过以后：
SQL
↓
EXPLAIN
↓
Cost Estimation
↓
Execution执行账户必须：
Read Only配置：
Statement Timeout
Maximum Rows
Maximum Scan
Maximum Cost
Maximum Concurrent Queries避免模型产生：
全表扫描
巨型 Join
超大结果集30. SQL Repair
SQL 执行失败后允许自动修复。
例如：
column net_sale does not exist链路：
SQL
↓
Database Error
↓
Error Classifier
↓
Repair Context
↓
LLM
↓
SQL v2错误分类：
SyntaxError
SchemaError
TypeError
FunctionError
TimeoutError
PermissionError
CostError其中：
PermissionError
SecurityViolation禁止进入 Repair。
默认：
MAX_REPAIR_ATTEMPTS = 231. Result Validator
SQL 可以执行不意味着业务答案正确。
系统需要继续校验：
Result Empty?
Abnormal Value?
Unexpected NULL?
Duplicate Amplification?
Aggregation Grain Correct?
Metric Rule Applied?
Required Filter Applied?例如：
Metric = net_sales要求：
status = PAID
is_test = falseResult Validator 可以结合 AST 和 Semantic Definition 检查这些规则是否真正进入 SQL。
32. Clarification
对于信息不足的问题：
看一下今年表现怎么样。
系统不能自己猜：
销售额？
订单量？
毛利率？
客户数？而应该返回：
你希望查看销售额、订单量、毛利率还是客户增长？
因此系统需要：
Confidence达到阈值：
High
→ Execute
Medium
→ Additional Retrieval
Low
→ Clarification33. LLM Gateway
系统不绑定某一个模型厂商。
统一接口：
LLMGateway底层实现：
OpenAI Compatible
Claude
Gemini
Qwen
DeepSeek
Local Model支持：
不同任务使用不同模型例如：
Domain Routing
→ Fast Model
Query Understanding
→ Fast Model
SQL Generation
→ Strong Model
SQL Judge
→ Strong Model
Answer Summary
→ Fast Model后续可根据：
Accuracy
Latency
Token Cost动态选择模型。
34. 技术栈
前端
Next.js
React
TypeScript
Tailwind CSS
Apache ECharts主要负责：
AI Chat
Query Result
SQL Explain
Trace
Admin Console
Evaluation Dashboard后端
Python 3.12+
FastAPI
Pydantic
SQLAlchemy
Alembic元数据与控制数据
PostgreSQLDense Retrieval
Milvus主要：
Schema Embedding
Semantic Embedding
Verified Query Embedding
Business Term Embedding
Value EmbeddingLexical Retrieval
OpenSearch主要：
BM25
Keyword
Fuzzy
Alias
Field Name
Business ValueRanking
RRF
+
BGE RerankerEmbedding
默认：
BGE-M3Embedding 层同样抽象 Provider，便于模型对比。
Cache
RedisSQL Parser
SQLGlot后台任务
Celery
+
Redis主要执行：
Metadata Sync
Embedding
Index Building
Benchmark
Batch EvaluationObservability
OpenTelemetry
Prometheus
Grafana
LangfuseDeployment
Docker
Docker Compose
Kubernetes开发环境使用：
Docker Compose生产部署方案：
Kubernetes35. AtlasSQL V0 —— Enterprise Data Foundation
目标
先建立真正能把 NL2SQL 做难的数据环境。
这一阶段不追求聊天功能。
实现内容
建立：
7 Business Domains
50～80 Tables
600～1000 Columns
Millions of Rows设计：
Fact Table
Dimension Table
Snapshot Table
Bridge Table
Multi Fact
Complex Join同时加入：
Bad Column Names
Abbreviations
Multiple Date Columns
Similar Tables
Historical Tables
Status Code
Internal Code
Sensitive FieldsV0 同时搭建全部基础设施
从第一天启动：
PostgreSQL
Milvus
OpenSearch
Redis不设计 pgvector 过渡阶段。
V0 建立 Benchmark
首批：
100～150 Questions覆盖：
Single Table
Join
Aggregation
Group By
Top N
Time Filter
同比
环比
Value Mapping
Business Metric
Complex Join
Ambiguity
Permission保存：
Question
Gold SQL
Expected Result
Required Domain
Required Tables
Required Columns
Required Metrics
DifficultyV0 交付结果
企业数据模型
数据生成器
Metadata Crawler
PostgreSQL Metadata Center
Milvus
OpenSearch
Redis
Benchmark v136. AtlasSQL V1 —— Baseline NL2SQL
目的
建立一个最基础 Baseline。
故意保持简单，以便后续可以量化架构优化带来的提升。
Pipeline
Question
↓
Domain
↓
Schema
↓
Prompt
↓
LLM
↓
SQL
↓
SQLGlot
↓
Execute
↓
Result只开放：
Sales Domain约：
10～15 TablesV1 重点
实现：
LLM Gateway
Prompt Builder
Basic SQL Generator
SQLGlot Parser
Read-only Executor
Result Renderer
Query TraceV1 必须形成 Failure Taxonomy
例如：
Wrong Table
Wrong Column
Wrong Join
Wrong Value
Wrong Metric
Wrong Time
Wrong Aggregation
Syntax Error统计：
Schema Error 31%
Business Metric 24%
Join Error 18%
Value Error 10%
Time Error 9%
Other 8%V2 的设计必须针对 V1 的真实 Failure 演进。
37. AtlasSQL V2 —— Enterprise Schema Linking
这一版解决：
大 Schema 场景下，LLM 无法可靠找到正确数据。
增加
Domain Router
SearchRepository
OpenSearch Retrieval
Milvus Retrieval
RRF
Reranker
Table Retrieval
Column Retrieval
Schema Linking
Value Linking
Join GraphPipeline：
Question
↓
Domain Router
↓
Hybrid Table Retrieval
↓
Reranker
↓
Column Retrieval
↓
Schema Linking
↓
Value Linking
↓
Join Graph Completion
↓
SQL GenerationV2 独立评测
增加：
Domain Accuracy
Table Recall@K
Table Precision@K
Column Recall@K
Column Precision@K
Value Linking Accuracy
Join Path Accuracy例如项目目标：
Domain Accuracy
≥ 98%
Table Recall@10
≥ 97%
Column Recall
≥ 95%这些是 AtlasSQL 项目目标，不作为通用行业标准。
38. AtlasSQL V3 —— Semantic NL2SQL
V3 是整个项目最关键的一次演进。
V2 可以找到：
Table
Column
Value但是仍然不知道：
企业里的“销售额”到底怎么算。
因此 V3 建立：
Semantic Layer
Metric Registry
Dimension Registry
Business Glossary
Synonym
Business Rule
Semantic Relationship同时建设：
Verified Query RepositoryPipeline：
Question
│
├──────────────────┐
▼ ▼
Schema Retrieval Semantic Retrieval
│ │
└────────┬─────────┘
▼
Verified Query Retrieval
↓
Context Builder
↓
SQL GenerationV3 开始真正从：
Text-to-SQL演进为：
Text-to-Semantics-to-SQLDatabricks 当前 Genie Agent 已经把 measures、filters、dimensions、join relationships、example SQL 和 Trusted Assets 都作为独立知识内容管理；这与 AtlasSQL V3 的设计方向是一致的。
39. AtlasSQL V4 —— Production NL2SQL
V4 开始把系统从：
高准确率实验系统提升为：
Production Ready NL2SQL增加：
Query Planner
Intermediate Representation
SQL AST Validation
Policy Engine
RBAC / ABAC
Row Permission
Column Permission
EXPLAIN
Cost Control
Timeout
SQL Repair
Result Validation
Audit Log完整 Pipeline：
Question
↓
Understanding
↓
Retrieval
↓
Semantic Linking
↓
Query Plan
↓
IR
↓
SQL
↓
AST Validator
↓
Policy Engine
↓
EXPLAIN
↓
Execute
↓
Result Validator
↓
AnswerV4 定义为 AtlasSQL Enterprise NL2SQL 1.0。
也就是说：
做到 V4，这个项目已经可以完整地作为企业级 NL2SQL 项目进行面试讲解。
40. AtlasSQL V5 —— Agentic Data Analyst
V5 不再只是：
NL → SQL而开始解决复杂数据分析任务。
此阶段再引入：
LangGraph而不是项目第一天使用 Agent Framework。
增加 Tool：
SchemaSearchTool
SemanticSearchTool
ValueSearchTool
VerifiedQueryTool
SQLGenerateTool
SQLExecuteTool
SQLRepairTool
ChartToolComplex Query Decomposition
例如：
找出今年销售额下降但是毛利率提高的城市，并分析主要原因。
Planner 可以拆：
Task
│
├── 当前销售额
│
├── 去年销售额
│
├── 当前毛利率
│
├── 去年毛利率
│
├── 产品结构
│
└── 客户结构
│
▼
SynthesisMulti-Candidate SQL
仅：
Complexity = HIGH或：
Confidence = LOW时：
SQL A
SQL B
SQL C然后通过：
Syntax
Schema
Semantic
Execution
Result
Cost综合选择最终 SQL。
41. AtlasSQL V6 —— NL2SQL Ops
最后一个版本解决：
系统上线以后，怎么知道它有没有越来越差？
建立：
Evaluation Platform
Prompt Version
Model Version
Semantic Version
Retriever Version
Benchmark Version
Trace
Feedback
Failure Mining
Regression Test
Canary Release
Cost AnalysisCI Evaluation
每次修改：
Prompt
Model
Embedding
Reranker
Semantic Model
Retrieval Strategy自动运行：
Benchmark输出：
Execution Accuracy
Semantic Accuracy
Schema Recall
First Pass Success
Repair Rate
Latency
Token Cost例如：
AtlasSQL 4.3
Execution Accuracy
88.7% → 91.2%
Table Recall@10
96.4% → 98.1%
First Pass Success
82.1% → 86.7%
P95
5.4s → 4.8s
Token Cost
-13%
Regression
3 cases如果关键指标低于阈值：
CI FAILEDMicrosoft Fabric 当前也明确建议从 Benchmark 开始，通过持续测试、修改 Schema Context、Instructions 和 Example Queries 形成迭代闭环。
42. 最终版本路线
AtlasSQL 的整体演进：
V0
Enterprise Data Foundation
│
▼
V1
Baseline NL2SQL
│
▼
V2
Schema Retrieval & Linking
│
▼
V3
Semantic NL2SQL
│
▼
V4
Production NL2SQL
│
▼
V5
Agentic Data Analyst
│
▼
V6
NL2SQL Ops每一次演进都回答一个明确问题：
V1
LLM 面对 Schema
为什么经常选错表？
↓
V2 Schema RetrievalV2
表字段都找对了，
为什么销售额还是算错？
↓
V3 Semantic LayerV3
准确率已经不错，
为什么还不能直接上生产？
↓
V4 Guardrail & GovernanceV4
单条 SQL 可以解决，
复杂分析任务怎么办？
↓
V5 Agentic Data AnalystV5
系统已经很强，
升级模型之后怎么知道有没有退化？
↓
V6 NL2SQL Ops这条演进路线也是 AtlasSQL 最重要的面试叙事主线。
43. 最终工程结构
AtlasSQL
│
├── apps
│ ├── web
│ └── admin
│
├── server
│ │
│ ├── api
│ ├── auth
│ ├── datasource
│ ├── metadata
│ ├── domain
│ ├── semantic
│ ├── search
│ │ ├── milvus
│ │ ├── opensearch
│ │ ├── fusion
│ │ └── reranker
│ ├── linking
│ ├── planner
│ ├── generation
│ ├── validation
│ ├── policy
│ ├── execution
│ ├── repair
│ ├── evaluation
│ ├── observability
│ └── llm
│
├── semantic_models
│
├── datasets
│
├── benchmarks
│
├── migrations
│
├── scripts
│
├── tests
│
├── deploy
│
└── docs44. 核心评测指标
最终 AtlasSQL 不能只说：
SQL 准确率 90%。
必须建立多维指标。
Retrieval
Domain Accuracy
Table Recall@K
Table Precision@K
Column Recall@K
Value Linking Accuracy
Join Path AccuracyGeneration
Syntax Valid Rate
Schema Valid Rate
First Pass Success Rate
Execution Accuracy
Semantic AccuracyRuntime
Execution Success Rate
Repair Rate
Timeout Rate
Clarification RateSecurity
Unauthorized Query Block Rate
Sensitive Column Violation
Unsafe SQL Block RateEngineering
P50 Latency
P95 Latency
Average Token
Average Cost
Cache Hit Rate45. 项目最终定位
AtlasSQL 不是：
ChatGPT
+
Database也不是：
Prompt
+
SQL Generator最终系统应该具备六层核心能力：
① Metadata Intelligence
② Retrieval & Schema Linking
③ Business Semantic Layer
④ Query Planning & SQL Generation
⑤ Security & Execution Governance
⑥ Evaluation & NL2SQL Ops其真正核心问题不是：
LLM 会不会写 SQL？
而是：
系统能否把业务人员的自然语言，可靠地映射到企业真实的数据模型、指标定义和权限体系，并生成可以安全执行且业务语义正确的 SQL。
因此 AtlasSQL 最终要证明的并不是“模型很聪明”，而是：
即使底层 LLM 存在不确定性，AtlasSQL 仍然能够通过 Metadata、Retrieval、Schema Linking、Semantic Layer、Verified Query、Query Planning、Guardrail、Execution Feedback 和 Evaluation，将这种不确定性约束在企业可以接受的范围内。
这就是 AtlasSQL 的企业级设计目标。