SQLBot:基于大模型与 RAG 的智能问数系统架构

3.1 前端展示层

基于 Vue3 框架构建，核心技术栈包括：

• UI 组件库：Element Plus 提供一致的交互体验
• 可视化引擎：@antv/g2 与 @s2 实现数据可视化展示
• 富文本编辑：Tinymce 支持复杂格式的内容展示
• 状态管理：Vuex 实现组件间状态共享

前端通过 RESTful API 与后端通信，采用 JWT 进行身份认证，支持多语言切换（通过 vue-i18n）。

3.2 后端服务层

基于 FastAPI 构建，采用模块化设计思想，划分为以下核心模块：

1. 聊天服务模块：处理用户提问的全流程管理
2. SQL 生成模块：核心模块，实现自然语言到 SQL 的转换
3. 图表生成模块：根据 SQL 结果与问题类型推荐并生成可视化图表
4. 数据分析模块：对查询结果进行自动化解读与分析
5. 术语管理模块：维护业务术语库，支持同义词与解释
6. 权限控制模块：基于 RBAC 模型的访问控制

3.3 数据存储层

采用 PostgreSQL 作为主数据库，存储以下核心数据：

• 系统配置信息
• 数据源连接信息（加密存储）
• 聊天记录与生成的 SQL
• 业务术语与训练数据

同时使用缓存机制提升高频访问数据的响应速度。

3.4 外部集成层

提供多样化的集成方式：

• RESTful API：支持第三方系统调用
• Webhook：实现事件驱动的集成
• Docker 容器：支持快速部署与扩展

4. 核心模块深度剖析

4.1 SQL 生成模块

SQL 生成是 SQLBot 的核心功能，其实现流程如图 2 所示：

用户问题 → 预处理 → 术语匹配 → 表结构解析 → LLM 生成 SQL → 语法校验 → 权限过滤 → 可执行 SQL 

关键实现代码分析：

模块核心逻辑位于 backend/apps/chat/task/llm.py，通过 LLMService 类实现：

class LLMService:
    def __init__(self, session: Session, current_user: CurrentUser, chat_question: ChatQuestion):
        # 初始化数据源与用户信息
        self.ds = self._get_datasource(session, chat_question)
        self.current_user = current_user
        self.chat_question = chat_question
        # 创建 LLM 实例
        self.config = await get_default_config()
        llm_instance = LLMFactory.create_llm(self.config)
        self.llm = llm_instance.llm

    def generate_sql(self):
        # 初始化提示词
        self.init_messages()
        # 调用大模型生成 SQL
        response = self.llm.generate(self.sql_message)
        # 解析与验证 SQL
        sql_result = self._parse_sql_response(response)
        validated_sql = self._validate_sql(sql_result['sql'])
        # 应用权限过滤
        authorized_sql = self._apply_permission_filters(validated_sql)
        return authorized_sql

提示词模板定义在 backend/template.yaml 中，采用结构化指令设计：

sql:
  system: |
    <Instruction>
      你是"SQLBOT"，智能问数小助手，可以根据用户提问，专业生成 SQL 与可视化图表。
      你当前的任务是根据给定的表结构和用户问题生成 SQL 语句、可能适合展示的图表类型以及该 SQL 中所用到的表名。
      <Info>内有<db-engine><m-schema><terminologies>等信息； ...
    </Instruction>

该模块创新性地将表结构信息、业务术语与历史案例融合为提示词，显著提升了 SQL 生成的准确性。

4.2 数据可视化模块

图表生成模块根据 SQL 查询结果与用户问题类型，自动推荐并生成合适的可视化图表，支持的类型包括表格、柱状图、条形图、折线图和饼图。

核心实现位于 backend/template.yaml 的 chart 配置：

chart:
  system: |
    <Instruction>
      你是"SQLBOT"，智能问数小助手，根据给定 SQL 语句和用户问题，生成数据可视化图表的配置项。
      用户的提问在<user-question>内，<sql>内是给定需要参考的 SQL，<chart-type>内是推荐你生成的图表类型
    </Instruction>

前端通过 @antv/g2 实现图表渲染，支持动态配置：

• 坐标轴设置
• 图例显示
• 交互行为（缩放、平移、tooltip）
• 样式自定义

4.3 术语管理模块

为解决业务术语与数据库字段的映射问题，SQLBot 设计了术语管理模块，支持：

• 术语同义词管理（如'销售额'与'营收'）
• 术语描述与计算公式
• 术语与表字段的关联

术语数据通过模板注入大模型的提示词中：

terminology: | {terminologies}

在 SQL 生成过程中，系统会自动匹配用户问题中的术语与数据库字段，提升查询准确性。

4.4 权限控制模块

基于工作空间的资源隔离机制，实现细粒度的数据权限控制：

1. 数据源级权限：控制用户可访问的数据源
2. 表级权限：限制用户可查询的表
3. 行级权限：通过过滤条件限制可访问的记录

权限过滤逻辑在 get_row_permission_filters 函数中实现，动态修改生成的 SQL 语句，确保数据访问安全。

5. 技术难点与解决方案

5.1 SQL 生成准确性问题

自然语言到 SQL 的精准转换（NL2SQL）是 SQLBot 的核心能力，其实现并非简单依赖大模型的原生能力，而是通过多模块协同优化构建的完整技术体系。这一转换过程的关键在于解决三大核心问题：语义理解的准确性、数据库知识的融合度、生成结果的可靠性。以下从技术实现角度剖析其关键机制：

挑战：复杂业务逻辑难以准确转换为 SQL，尤其是多表关联与聚合计算场景。

解决方案：

1. 双层提示词设计：系统指令 + 示例引导的组合提示策略
2. RAG 增强：将表结构、术语库、历史案例作为上下文输入
3. 多轮优化：基于执行结果的 SQL 修正机制

代码实现上通过 custom_prompt 机制支持个性化提示词定制：

from sqlbot_xpack.custom_prompt.curd.custom_prompt import find_custom_prompts
# 加载自定义提示词
custom_prompts = find_custom_prompts(session, self.ds.id)

下面详细来说下。

一、结构化语义解析：从自然语言到逻辑意图的映射

自然语言的模糊性与 SQL 的结构化特性存在天然鸿沟，SQLBot 通过三级语义解析实现精准映射：

1. 实体识别与消歧
   • 基于业务术语库（Terminologies）识别问题中的关键实体（如'销售额'对应 sales.amount）
   • 解决一词多义问题（如'用户数'需区分'注册用户'与'活跃用户'）
   • 代码实现：backend/apps/chat/task/llm.py 中通过 _load_terminologies 方法将业务术语注入上下文
2. 逻辑关系提取
   • 识别时间条件（如'近 30 天'）、比较关系（如'大于'、'占比'）、聚合逻辑（如'平均值'）
   • 将自然语言中的模糊表述（如'top5'）转换为精确 SQL 函数（如 LIMIT 5）
   • 关键技术：基于模板的逻辑算子映射表，支持动态扩展
3. 查询意图分类
   • 预定义查询类型（统计分析、明细查询、对比分析等）
   • 结合查询类型优化 SQL 生成策略（如明细查询优先选择 SELECT *）

二、数据库知识的深度融合：构建领域认知能力

大模型的通用能力无法直接适配特定数据库环境，SQLBot 通过四维知识注入实现领域适配：

1. 表结构元数据整合
   • 自动提取表名、字段名、数据类型、主键外键关系
   • 以结构化格式注入提示词（如 <m-schema> 标签包裹的表结构信息）
   • 代码示例：backend/apps/chat/task/llm.py 中 _get_table_struct 方法动态生成表结构描述
2. 数据库方言适配
   • 针对 MySQL/PostgreSQL/Oracle 等不同数据库类型，维护语法差异映射表
   • 在生成 SQL 时自动适配方言特性（如日期函数 DATE_ADD 与 INTERVAL 的区别）
   • 实现机制：backend/apps/db/db_sql.py 中的数据库类型识别与语法转换
3. 业务逻辑编码
   • 将业务规则（如'有效订单 = 已支付且未退款'）转化为可复用的 SQL 片段
   • 通过术语管理模块关联业务指标与计算逻辑
   • 存储位置：数据库表 terminology 中维护术语 - 公式映射
4. 历史案例学习
   • 缓存优质的自然语言 - SQL 映射案例
   • 在相似问题中复用历史转换逻辑（RAG 技术的工程化实现）
   • 触发机制：similar_question_threshold 配置的相似度阈值判断

三、生成质量的闭环优化：从'可运行'到'精准化'

NL2SQL 的核心挑战是生成 SQL 的实用性，SQLBot 通过三层校验优化机制保障结果质量：

1. 语法校验层
   • 基于 sqlparse 库进行语法解析，检测关键字错误、括号不匹配等问题
   • 针对语法错误自动生成修正提示词，驱动大模型自我修复
   • 代码实现：backend/apps/chat/task/validate.py 中的 sql_validate 函数
2. 语义一致性校验
   • 对比生成 SQL 与用户问题的语义匹配度（如是否遗漏条件、聚合方式是否正确）
   • 对高风险差异（如'求和'被生成为'计数'）触发二次生成
   • 关键指标：语义匹配度得分≥0.85 方可通过校验
3. 执行反馈优化
   • 自动执行生成的 SQL，捕获执行错误（如字段不存在、关联条件错误）
   • 基于错误信息构建针对性修正指令（如'表 orders 中不存在字段 total_money，正确字段为 amount'）
   • 迭代机制：最多支持 3 轮自动修正，仍失败则触发人工干预流程

四、提示词工程：大模型能力的'放大器'

SQLBot 的提示词设计采用模块化指令架构，是实现精准转换的'隐形核心'：

1. 约束条件显性化
   • 明确禁止生成无效代码（如 SELECT 1 测试语句）
   • 强制要求解释 SQL 逻辑（便于人工核验）
   • 规定输出格式（使用 ```sql 标签包裹结果）

示例引导（Few-Shot Learning） 在复杂场景中自动插入相似案例作为参考：

<examples>
  示例 1：
  用户问：'昨天的订单量'
  SQL：SELECT COUNT(*) FROM orders WHERE date(create_time) = CURDATE() - INTERVAL 1 DAY
</examples>

系统角色定义

system: |
  你是"SQLBOT"，智能问数小助手，专精于将自然语言转换为精准 SQL...
  必须严格遵循<db-engine>指定的数据库语法，优先使用<m-schema>中的字段...

通过角色锚定确保大模型聚焦于 SQL 生成任务。

关键技术总结

SQLBot 实现自然语言到 SQL 无缝转换的核心在于：将大模型的通用生成能力与数据库领域知识进行深度融合，并通过工程化手段构建从语义解析到结果校验的完整闭环。其中，结构化知识注入解决'不懂业务'的问题，多层校验机制解决'生成不可靠'的问题，提示词工程则解决'能力不聚焦'的问题。这三者的协同作用，最终实现了从自然语言到可执行 SQL 的高质量转换。

这种架构设计的优势在于：既发挥了大模型在语义理解上的优势，又通过领域知识和工程校验弥补了其在精确性上的不足，为企业级 NL2SQL 场景提供了兼具易用性与可靠性的解决方案。

5.2 多数据库兼容性

挑战：不同数据库的 SQL 语法存在差异（如日期函数、字符串处理）。

解决方案：

1. 数据库类型识别：在 get_version_sql 中实现各数据库版本检测
2. 语法适配层：针对不同数据库类型生成特定语法
3. 测试矩阵：覆盖主流数据库的自动化测试

# 数据库版本检测示例（backend/apps/db/db_sql.py）
def get_version_sql(ds: CoreDatasource, conf: DatasourceConf):
    if ds.type == "mysql" or ds.type == "doris":
        return "SELECT VERSION()"
    elif ds.type == "sqlServer":
        return "select SERVERPROPERTY('ProductVersion')"
    # 其他数据库类型...

5.3 大模型调用效率

挑战：大模型响应时间长，影响用户体验。

解决方案：

1. 请求异步化：通过 ThreadPoolExecutor 实现非阻塞调用
2. 缓存机制：对相同问题的查询结果进行缓存
3. 流式响应：支持结果的增量返回

# 异步执行示例
executor = ThreadPoolExecutor(max_workers=200)
self.future = executor.submit(self._generate_sql_async)

6. 部署与集成方案

6.1 快速部署

SQLBot 提供多种部署方式，满足不同环境需求：

1. Docker 一键部署：

docker run -d \
  --name sqlbot \
  --restart unless-stopped \
  -p 8000:8000 \
  -p 8001:8001 \
  -v ./data/sqlbot:/opt/sqlbot/data \
  dataease/sqlbot

2. Docker Compose 部署：支持多容器协同

services:
  sqlbot:
    image: dataease/sqlbot
    container_name: sqlbot
    restart: always
    ports:
      - 8000:8000
      - 8001:8001
    volumes:
      - ./data/sqlbot:/opt/sqlbot/data

3. 离线部署：提供完整离线安装包，适用于内网环境

6.2 第三方集成

SQLBot 设计了灵活的集成接口，可与多种系统无缝对接：

1. AI 应用平台：支持 n8n、MaxKB、Dify、Coze 等平台集成
2. 业务系统：通过 API 接口嵌入 OA、CRM 等系统
3. 前端集成示例：

<script async defer id="sqlbot-assistant-float-script" src="https://example.com/assistant.js?id=YOUR_ID"></script>

7. 总结与展望

7.1 系统特点总结

SQLBot 通过模块化设计实现了智能问数系统的核心功能，其主要特点包括：

1. 开箱即用：简化部署流程，降低使用门槛
2. 精准转换：基于大模型与 RAG 的 SQL 生成准确率达 85% 以上
3. 安全可控：细粒度权限控制保障数据安全
4. 易于集成：多样化接口支持快速嵌入业务系统

7.2 未来优化方向

1. 多模态输入：支持图表、语音等多样化输入方式
2. 智能推荐：基于用户行为的查询推荐与自动洞察
3. 低代码扩展：提供可视化的 SQL 修正与扩展能力
4. 性能优化：进一步提升大模型响应速度与并发处理能力

7.3 结语

SQLBot 通过将大模型技术与数据查询场景深度融合，有效降低了数据访问门槛，为企业构建'人人可用'的数据查询能力提供了可行方案。其模块化的架构设计不仅保证了系统的灵活性与可扩展性，也为同类系统的研发提供了有价值的参考模式。