1. 项目概述RAG‑SQL 智析工作台是一个基于自然语言处理与数据分析技术的智能数据服务系统面向数据仓库Data Warehouse应用场景旨在帮助用户通过对话方式高效获取数据仓库中的数据洞察。用户无需掌握复杂的查询语法即可用自然语言提出问题系统自动完成对数据仓库数据的理解、计算分析与结果可视化大幅提升数据使用效率降低数据分析门槛助力业务决策智能化。RAG‑SQL 智析工作台核心实现NL2SQLNatural Language to SQL,它是自然语言处理NLP的一个细分方向目标是将用户用自然语言描述的查询需求自动转换成语法正确、可直接执行的 SQL 语句.简单理解RAG‑SQL 智析工作台本质上就是实现一个RAG的过程,通过用户的问题进行处理后将处理后的数据交给大模型进行处理最终生成sql,执行后返回结果。生成的sql语句SELECTd.year,d.month,dp.product_name,SUM(fo.order_quantity)AStotal_salesFROMfact_order foJOINdim_date dONfo.date_idd.date_idJOINdim_product dpONfo.product_iddp.product_idGROUPBYd.year,d.month,dp.product_id,dp.product_nameHAVINGSUM(fo.order_quantity)(SELECTMAX(monthly_sales)FROM(SELECTd2.year,d2.month,fo2.product_id,SUM(fo2.order_quantity)ASmonthly_salesFROMfact_order fo2JOINdim_date d2ONfo2.date_idd2.date_idGROUPBYd2.year,d2.month,fo2.product_id)subWHEREsub.yeard.yearANDsub.monthd.month)ORDERBYd.year,d.month;生成的sql:SELECTdr.region_nameAS地区,SUM(fo.order_amount)AS销售总额FROMfact_order foJOINdim_region drONfo.region_iddr.region_idJOINdim_date ddONfo.date_iddd.date_idWHEREdd.date_idBETWEEN20250101AND20251231GROUPBYdr.region_nameORDERBY销售总额DESC;生成的sql:SELECTSUM(fo.order_amount)AS销售总额FROMfact_order foJOINdim_region drONfo.region_iddr.region_idWHEREdr.region_name华北;2. 项目架构2.1 概述本项目以数据仓库的元数据为核心使用 MySQL 存储结构化元数据信息结合 Qdrant 构建语义向量索引、Elasticsearch 构建全文索引形成统一的元数据知识库。查询过程中系统首先根据用户自然语言问题进行多路召回筛选相关表、字段及指标定义再将元数据信息与用户问题共同输入大模型生成 SQL最终完成自动查询与结果返回确保生成结果的准确性与可控性。读音/ˈkwɒdrənt/谐音夸准特名字源自单词 quadrant象限。Qdrant 是一款由 Rust 语言开发的开源向量数据库具备高性能、低延迟、支持 Payload 元数据过滤的特点。项目中用来存储数据表 Schema 元数据向量实现语义检索把相关表结构给到 LLM辅助完成 NL2SQL 生成。存储数据表元数据、表结构、字段注释、业务描述的向量。用户输入自然语言问题 → 问题向量化 → 在 Qdrant 做向量检索召回业务相关的表、字段信息 → 把检索出来的 schema 上下文喂给大模型 → 大模型生成 SQL。2.2 元数据知识库元数据知识库作为数据仓库的语义基础设施用于集中管理和高效检索表结构、字段定义、字段取值示例及复杂指标说明等元数据信息支撑后续的智能检索与 SQL 生成。元数据信息主要来源于两部分一部分数据仓库自动采集另一部分由人工进行补充与配置。完整的元数据统一存储于 MySQL 数据库中并对其中部分关键信息构建向量索引和全文索引以提升语义召回与关键词召回的效果。2.2.1 元数据库meta元数据库共包含四张表具体结构如下图所示metric_info:指标描述信息表column_metric:字段指标关联表column_info:字段描述信息表table_info:表描述信息表列角色说明primary_key:主键 foreign_key外键 measure: 度量可计算的数值主要用于做统计例如卖了多少钱、买了几件、耗时多少 dimension维度 分析的“角度”,主要用于来做筛选和分组例如按时间看、按区域看、按商品分类看metric_info(指标信息表)字段名类型注释idvarchar(64)指标编码主键唯一标识一个指标namevarchar(128)指标名称如 “销售总额”descriptiontext指标描述详细说明指标的业务含义、计算口径relevant_columnsjson关联列信息JSON 格式记录该指标计算时依赖的物理列aliasjson指标别名JSON 格式记录指标的别名、简称等column_metric列 - 指标关联表字段名类型注释column_idvarchar(64)列编号外键关联column_info.idmetric_idvarchar(64)指标编号外键关联metric_info.idcolumn_info列信息表字段名类型注释idvarchar(64)列编号主键唯一标识一个物理列namevarchar(128)列名称如order_amounttypevarchar(64)数据类型如INT,VARCHAR,DATETIMErolevarchar(32)列角色如primary key,dimension,measureexamplesjson数据示例JSON 格式记录该列的示例值descriptiontext列描述详细说明该列的业务含义aliasjson列别名JSON 格式记录该列的别名table_idvarchar(64)所属表编号外键关联table_info.idtable_info表信息表字段名类型注释idvarchar(64)表编号主键唯一标识一个物理表namevarchar(128)表名称如fact_sales_orderrolevarchar(32)表类型如fact事实表dim维度表descriptiontext表描述详细说明该表的业务含义构建指令知识库python-mapp.scripts.build_meta_knowledge-c.\conf\meta_config.yaml2.2.2 数据仓库dwdim_customer: 客户维度表dim_date: 日期维度表dim_product: 商品维度表dim_region: 区域维度表fact_order: 订单事实表类型说明1以dim_开头的是维度表用于描述业务的 “维度属性”比如客户信息、商品信息、时间维度、区域信息是分析的 “上下文”在实际使用中维度表主要用于分组和过滤操作2以fact_开头的是事实表存储核心业务的 “度量值”如订单数量、订单金额并通过外键关联各个维度表是分析的 “核心数据” 在实际使用中事实表主要用于聚合操作特点订单分析的星型模型fact_order事实表是中心关联 4 张 dim_维度表是数据仓库中最经典的建模方式。dim_date日期维度表字段名类型注释date_idint日期 ID主键唯一标识一条日期记录yearint年份如 2025quartervarchar(2)季度如 Q1、Q2monthint月份1-12dayint日期1-31dim_region地区维度表字段名类型注释region_idvarchar(20)地区 ID主键唯一标识一条地区记录provincevarchar(50)省份region_namevarchar(50)地区名称countryvarchar(50)国家dim_customer客户维度表字段名类型注释customer_idvarchar(20)客户 ID主键唯一标识一个客户customer_namevarchar(50)客户名称gendervarchar(10)性别member_levelvarchar(20)会员等级dim_product商品维度表字段名类型注释product_idvarchar(20)商品 ID主键唯一标识一个商品product_namevarchar(200)商品名称categoryvarchar(50)商品类别brandvarchar(50)品牌fact_order订单事实表字段名类型注释order_idvarchar(30)订单 ID主键唯一标识一条订单记录customer_idvarchar(20)客户 ID外键关联dim_customer.customer_idproduct_idvarchar(20)商品 ID外键关联dim_product.product_iddate_idint日期 ID外键关联dim_date.date_idregion_idvarchar(20)地区 ID外键关联dim_region.region_idorder_quantityint订单数量度量本次订单购买的商品件数order_amountfloat订单金额度量本次订单的总金额2.2.3 向量索引本项目选用 Qdrant 作为向量数据库向量索引主要用于对指标信息和字段信息进行语义召回。向量索引的构建内容具体如下Qdrant_python_clientmetric_info 需要建立向量索引的字段如下图所示具体示例如下图所示column_info 需要建立向量索引的字段如下图所示具体示例如下图所示2.2.4 全文索引本项目使用 Elasticsearch 作为全文检索引擎全文索引主要用于对字段取值进行检索与匹配索引内容以各类维度值为主具体如下针对字段取值的索引建立主要选择维度表的维度角色字段只有维度字段在召回时用于过滤匹配具体示例如下图所示2.3 智析智能体本项目的智能体主体基于Langgraph构建具体结构如下图所示开始接收用户自然语言提问例如查询本月各个地区销售额提取关键字对用户问题做 NLP 解析提取问题里的实体、业务关键词比如地区、销售额、本月等用于后续向量检索。三路并行召回向量数据库 Qdrant 做检索字段信息召回检索和问题相关数据表的字段、字段注释指标信息召回检索业务指标销售额、订单量这类业务统计指标字段值召回检索字段枚举值例如地区字段有 “北京、上海”防止大模型编造不存在的字段值合并召回信息将上面三路向量检索拿到的表、字段、指标、枚举值全部整合作为原始上下文。过滤表信息 过滤指标信息对召回出来的大量信息做过滤清洗剔除无关、冗余的表和指标减少 prompt 长度防止大模型被无关信息干扰。添加额外上下文信息补充数据库约束、业务规则、示例 SQL、数据库方言等额外提示词组装完整大模型 Prompt。生成 SQL把组装好的 prompt 交给大模型大模型输出 SQL 语句。校验 SQL校验语法合法性、表 / 字段是否真实存在、是否存在高危 SQLdrop、delete❌ False校验失败 →校正 SQL修正语法错误、字段错误校正完成后交给执行 SQL✅ True校验通过直接进入执行执行 SQL将 SQL 提交到数仓执行拿到查询结果返回前端。结束 大模型项目之RAG‑SQL智析工作台-01-项目概要
1. 项目概述RAG‑SQL 智析工作台是一个基于自然语言处理与数据分析技术的智能数据服务系统面向数据仓库Data Warehouse应用场景旨在帮助用户通过对话方式高效获取数据仓库中的数据洞察。用户无需掌握复杂的查询语法即可用自然语言提出问题系统自动完成对数据仓库数据的理解、计算分析与结果可视化大幅提升数据使用效率降低数据分析门槛助力业务决策智能化。RAG‑SQL 智析工作台核心实现NL2SQLNatural Language to SQL,它是自然语言处理NLP的一个细分方向目标是将用户用自然语言描述的查询需求自动转换成语法正确、可直接执行的 SQL 语句.简单理解RAG‑SQL 智析工作台本质上就是实现一个RAG的过程,通过用户的问题进行处理后将处理后的数据交给大模型进行处理最终生成sql,执行后返回结果。生成的sql语句SELECTd.year,d.month,dp.product_name,SUM(fo.order_quantity)AStotal_salesFROMfact_order foJOINdim_date dONfo.date_idd.date_idJOINdim_product dpONfo.product_iddp.product_idGROUPBYd.year,d.month,dp.product_id,dp.product_nameHAVINGSUM(fo.order_quantity)(SELECTMAX(monthly_sales)FROM(SELECTd2.year,d2.month,fo2.product_id,SUM(fo2.order_quantity)ASmonthly_salesFROMfact_order fo2JOINdim_date d2ONfo2.date_idd2.date_idGROUPBYd2.year,d2.month,fo2.product_id)subWHEREsub.yeard.yearANDsub.monthd.month)ORDERBYd.year,d.month;生成的sql:SELECTdr.region_nameAS地区,SUM(fo.order_amount)AS销售总额FROMfact_order foJOINdim_region drONfo.region_iddr.region_idJOINdim_date ddONfo.date_iddd.date_idWHEREdd.date_idBETWEEN20250101AND20251231GROUPBYdr.region_nameORDERBY销售总额DESC;生成的sql:SELECTSUM(fo.order_amount)AS销售总额FROMfact_order foJOINdim_region drONfo.region_iddr.region_idWHEREdr.region_name华北;2. 项目架构2.1 概述本项目以数据仓库的元数据为核心使用 MySQL 存储结构化元数据信息结合 Qdrant 构建语义向量索引、Elasticsearch 构建全文索引形成统一的元数据知识库。查询过程中系统首先根据用户自然语言问题进行多路召回筛选相关表、字段及指标定义再将元数据信息与用户问题共同输入大模型生成 SQL最终完成自动查询与结果返回确保生成结果的准确性与可控性。读音/ˈkwɒdrənt/谐音夸准特名字源自单词 quadrant象限。Qdrant 是一款由 Rust 语言开发的开源向量数据库具备高性能、低延迟、支持 Payload 元数据过滤的特点。项目中用来存储数据表 Schema 元数据向量实现语义检索把相关表结构给到 LLM辅助完成 NL2SQL 生成。存储数据表元数据、表结构、字段注释、业务描述的向量。用户输入自然语言问题 → 问题向量化 → 在 Qdrant 做向量检索召回业务相关的表、字段信息 → 把检索出来的 schema 上下文喂给大模型 → 大模型生成 SQL。2.2 元数据知识库元数据知识库作为数据仓库的语义基础设施用于集中管理和高效检索表结构、字段定义、字段取值示例及复杂指标说明等元数据信息支撑后续的智能检索与 SQL 生成。元数据信息主要来源于两部分一部分数据仓库自动采集另一部分由人工进行补充与配置。完整的元数据统一存储于 MySQL 数据库中并对其中部分关键信息构建向量索引和全文索引以提升语义召回与关键词召回的效果。2.2.1 元数据库meta元数据库共包含四张表具体结构如下图所示metric_info:指标描述信息表column_metric:字段指标关联表column_info:字段描述信息表table_info:表描述信息表列角色说明primary_key:主键 foreign_key外键 measure: 度量可计算的数值主要用于做统计例如卖了多少钱、买了几件、耗时多少 dimension维度 分析的“角度”,主要用于来做筛选和分组例如按时间看、按区域看、按商品分类看metric_info(指标信息表)字段名类型注释idvarchar(64)指标编码主键唯一标识一个指标namevarchar(128)指标名称如 “销售总额”descriptiontext指标描述详细说明指标的业务含义、计算口径relevant_columnsjson关联列信息JSON 格式记录该指标计算时依赖的物理列aliasjson指标别名JSON 格式记录指标的别名、简称等column_metric列 - 指标关联表字段名类型注释column_idvarchar(64)列编号外键关联column_info.idmetric_idvarchar(64)指标编号外键关联metric_info.idcolumn_info列信息表字段名类型注释idvarchar(64)列编号主键唯一标识一个物理列namevarchar(128)列名称如order_amounttypevarchar(64)数据类型如INT,VARCHAR,DATETIMErolevarchar(32)列角色如primary key,dimension,measureexamplesjson数据示例JSON 格式记录该列的示例值descriptiontext列描述详细说明该列的业务含义aliasjson列别名JSON 格式记录该列的别名table_idvarchar(64)所属表编号外键关联table_info.idtable_info表信息表字段名类型注释idvarchar(64)表编号主键唯一标识一个物理表namevarchar(128)表名称如fact_sales_orderrolevarchar(32)表类型如fact事实表dim维度表descriptiontext表描述详细说明该表的业务含义构建指令知识库python-mapp.scripts.build_meta_knowledge-c.\conf\meta_config.yaml2.2.2 数据仓库dwdim_customer: 客户维度表dim_date: 日期维度表dim_product: 商品维度表dim_region: 区域维度表fact_order: 订单事实表类型说明1以dim_开头的是维度表用于描述业务的 “维度属性”比如客户信息、商品信息、时间维度、区域信息是分析的 “上下文”在实际使用中维度表主要用于分组和过滤操作2以fact_开头的是事实表存储核心业务的 “度量值”如订单数量、订单金额并通过外键关联各个维度表是分析的 “核心数据” 在实际使用中事实表主要用于聚合操作特点订单分析的星型模型fact_order事实表是中心关联 4 张 dim_维度表是数据仓库中最经典的建模方式。dim_date日期维度表字段名类型注释date_idint日期 ID主键唯一标识一条日期记录yearint年份如 2025quartervarchar(2)季度如 Q1、Q2monthint月份1-12dayint日期1-31dim_region地区维度表字段名类型注释region_idvarchar(20)地区 ID主键唯一标识一条地区记录provincevarchar(50)省份region_namevarchar(50)地区名称countryvarchar(50)国家dim_customer客户维度表字段名类型注释customer_idvarchar(20)客户 ID主键唯一标识一个客户customer_namevarchar(50)客户名称gendervarchar(10)性别member_levelvarchar(20)会员等级dim_product商品维度表字段名类型注释product_idvarchar(20)商品 ID主键唯一标识一个商品product_namevarchar(200)商品名称categoryvarchar(50)商品类别brandvarchar(50)品牌fact_order订单事实表字段名类型注释order_idvarchar(30)订单 ID主键唯一标识一条订单记录customer_idvarchar(20)客户 ID外键关联dim_customer.customer_idproduct_idvarchar(20)商品 ID外键关联dim_product.product_iddate_idint日期 ID外键关联dim_date.date_idregion_idvarchar(20)地区 ID外键关联dim_region.region_idorder_quantityint订单数量度量本次订单购买的商品件数order_amountfloat订单金额度量本次订单的总金额2.2.3 向量索引本项目选用 Qdrant 作为向量数据库向量索引主要用于对指标信息和字段信息进行语义召回。向量索引的构建内容具体如下Qdrant_python_clientmetric_info 需要建立向量索引的字段如下图所示具体示例如下图所示column_info 需要建立向量索引的字段如下图所示具体示例如下图所示2.2.4 全文索引本项目使用 Elasticsearch 作为全文检索引擎全文索引主要用于对字段取值进行检索与匹配索引内容以各类维度值为主具体如下针对字段取值的索引建立主要选择维度表的维度角色字段只有维度字段在召回时用于过滤匹配具体示例如下图所示2.3 智析智能体本项目的智能体主体基于Langgraph构建具体结构如下图所示开始接收用户自然语言提问例如查询本月各个地区销售额提取关键字对用户问题做 NLP 解析提取问题里的实体、业务关键词比如地区、销售额、本月等用于后续向量检索。三路并行召回向量数据库 Qdrant 做检索字段信息召回检索和问题相关数据表的字段、字段注释指标信息召回检索业务指标销售额、订单量这类业务统计指标字段值召回检索字段枚举值例如地区字段有 “北京、上海”防止大模型编造不存在的字段值合并召回信息将上面三路向量检索拿到的表、字段、指标、枚举值全部整合作为原始上下文。过滤表信息 过滤指标信息对召回出来的大量信息做过滤清洗剔除无关、冗余的表和指标减少 prompt 长度防止大模型被无关信息干扰。添加额外上下文信息补充数据库约束、业务规则、示例 SQL、数据库方言等额外提示词组装完整大模型 Prompt。生成 SQL把组装好的 prompt 交给大模型大模型输出 SQL 语句。校验 SQL校验语法合法性、表 / 字段是否真实存在、是否存在高危 SQLdrop、delete❌ False校验失败 →校正 SQL修正语法错误、字段错误校正完成后交给执行 SQL✅ True校验通过直接进入执行执行 SQL将 SQL 提交到数仓执行拿到查询结果返回前端。结束