一、案例背景
Text2SQL技术代表了人工智能在数据库交互领域的重要突破，它将自然语言查询自动转换为结构化查询语言（SQL），极大地降低了数据库操作的技术门槛。该技术基于先进的深度学习模型（如大型语言模型LLM），通过智能解析用户的自然语言表述，并动态结合数据库的元数据信息（包括表结构、字段类型、索引关系等），能够自动生成语法正确且逻辑合理的SQL执行语句。
这一技术的核心价值在于实现了数据访问的民主化，使得非技术背景的业务人员也能够通过自然语言直接与数据库进行交互，无需掌握复杂的SQL语法规则。在实际应用场景中，Text2SQL技术已被广泛应用于企业级数据分析平台、商业智能系统、医疗信息查询系统、金融数据分析等多个领域，为各行各业的数据驱动决策提供了强有力的技术支撑。
本案例将通过构建一个完整的Text2SQL智能代理系统，演示如何利用FastGPT平台实现从自然语言到SQL语句，再到数据可视化图表的全流程自动化处理，为读者提供一个具有实际业务价值的端到端解决方案。
二、实现效果预览
如图1-1所示，本案例实现的智能代理系统展现了卓越的自然语言理解和数据处理能力。当用户输入"查询所有用户的姓名和他们购买的商品名称"这一自然语言查询请求时，系统能够进行以下智能化处理：
首先，Agent通过语义解析模块准确理解用户意图，识别出查询涉及用户信息和商品信息两个数据实体，以及它们之间的关联关系。接着，系统自动生成对应的SQL语句，该语句不仅语法正确，而且能够精确表达用户的查询需求，包括必要的表连接操作和字段选择。
随后，Agent将生成的SQL语句提交至数据库执行，并获取查询结果。更为重要的是，系统不仅返回原始的数据结果，还通过自然语言处理技术将查询结果转换为用户友好的自然语言描述，使得查询结果更加易于理解和分析。
最终，系统调用可视化图表生成工具，根据查询结果的数据特征和用户需求，自动创建精美的可视化图表，为用户提供直观的数据展示效果。整个过程实现了从自然语言输入到可视化输出的完整闭环，充分体现了人工智能技术在数据分析领域的强大应用潜力。
图1-1 效果预览
三、前置工作
3.1 初始化数据库
为确保本案例的实用性和可操作性，我们需要构建一个公网可访问的数据库环境。本案例选择使用Sealos企业级云操作系统提供的数据库资源，该平台具有部署简便、性能稳定、安全可靠的特点，能够为我们的Text2SQL系统提供理想的数据存储和查询环境。
首先，访问Sealos官方网站（https://hzh.sealos.run） ，进入云操作系统的主界面。如图1-2所示，在Sealos主界面中，可以清晰地看到各种云服务组件的图标排列，点击数据库图标即可进入数据库管理模块。
图1-2 Sealos首页
在数据库服务选择界面中，我们选择MySQL数据库作为本案例的数据存储解决方案。MySQL作为世界上最流行的开源关系型数据库管理系统之一，具有成熟稳定、性能优越、兼容性强的特点，非常适合作为Text2SQL系统的后端数据库。如图1-3所示，选择MySQL选项后，点击"部署"按钮即可启动一键部署流程。
该一键部署功能的最大优势在于用户无需关心底层的环境配置细节，包括操作系统选择、数据库版本配置、网络设置、安全策略等复杂问题，系统会自动完成所有必要的配置工作，大大降低了部署的技术门槛和时间成本。
图1-3 部署数据库
由于FastGPT平台中的数据库连接节点需要访问具有公网地址的数据库服务，因此我们必须开启数据库的外网访问功能。如图1-4所示，在数据库管理界面中，启用外网地址功能。这一步骤将为数据库分配一个公网可访问的IP地址和端口，使得我们的FastGPT工作流能够顺利连接到数据库服务。
需要注意的是，开启外网访问功能时应当配置适当的安全策略，包括访问权限控制、IP白名单设置、SSL加密连接等，以确保数据库服务的安全性不受损害。
图1-4 开启外网地址
为了构建一个功能完整且数据丰富的测试环境，本案例提供了精心设计的数据库初始化脚本和模拟数据脚本。这些脚本包含了完整的电商业务场景数据模型，涵盖用户管理、商品管理、订单管理等核心业务功能，能够有效支撑各种复杂度的SQL查询测试。
您可以通过数据库管理工具（如Navicat、DBeaver、MySQL Workbench等）或者直接在数据库终端中执行这些初始化脚本。如图1-5、图1-6所示，使用Navicat执行数据库脚本，脚本的执行顺序应当首先运行数据库初始化脚本以创建表结构，然后执行模拟数据脚本以填充测试数据，确保数据的完整性和一致性。
图1-5 执行数据库初始化脚本
图1-6 执行模拟数据脚本
以下是完整的数据库初始化脚本和模拟数据脚本，包括适当的索引设计、外键约束、数据类型优化等。
数据库初始化脚本
该脚本创建了一个完整的电商系统数据模型，包含用户、商品、订单三个核心实体，通过外键关系建立了完整的业务数据关联。
-- 创建数据库DROP DATABASE IF EXISTS test_db;CREATE DATABASE test_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;USE test_db;-- 1. 用户表 (users)DROP TABLE IF EXISTS users;CREATE TABLE users (user_id INT PRIMARY KEY AUTO_INCREMENT,username VARCHAR(50) NOT NULL UNIQUE,email VARCHAR(100) NOT NULL UNIQUE,full_name VARCHAR(100) NOT NULL,phone VARCHAR(20),status ENUM('active', 'inactive', 'suspended') DEFAULT 'active',created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,INDEX idx_username (username),INDEX idx_email (email),INDEX idx_status (status));-- 2. 商品表 (products)DROP TABLE IF EXISTS products;CREATE TABLE products (product_id INT PRIMARY KEY AUTO_INCREMENT,product_name VARCHAR(200) NOT NULL,category VARCHAR(50) NOT NULL,price DECIMAL(10,2) NOT NULL,stock_quantity INT NOT NULL DEFAULT 0,description TEXT,status ENUM('available', 'out_of_stock', 'discontinued') DEFAULT 'available',created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,INDEX idx_category (category),INDEX idx_price (price),INDEX idx_status (status));-- 3. 订单表 (orders)DROP TABLE IF EXISTS orders;CREATE TABLE orders (order_id INT PRIMARY KEY AUTO_INCREMENT,user_id INT NOT NULL,product_id INT NOT NULL,quantity INT NOT NULL DEFAULT 1,unit_price DECIMAL(10,2) NOT NULL,total_amount DECIMAL(10,2) NOT NULL,order_status ENUM('pending', 'confirmed', 'shipped', 'delivered', 'cancelled') DEFAULT 'pending',order_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,delivery_date TIMESTAMP NULL,created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,FOREIGN KEY (user_id) REFERENCES users(user_id) ON DELETE CASCADE,FOREIGN KEY (product_id) REFERENCES products(product_id) ON DELETE CASCADE,INDEX idx_user_id (user_id),INDEX idx_product_id (product_id),INDEX idx_order_status (order_status),INDEX idx_order_date (order_date));
模拟数据脚本
该脚本插入了丰富的测试数据，涵盖多种业务场景，包括不同状态的用户、多品类的商品、各种状态的订单，为后续的SQL查询测试提供了全面的数据基础。
-- 插入用户数据INSERT INTO users (username, email, full_name, phone, status) VALUES('john_doe', 'john.doe@email.com', 'John Doe', '13800001111', 'active'),('jane_smith', 'jane.smith@email.com', 'Jane Smith', '13800002222', 'active'),('bob_wilson', 'bob.wilson@email.com', 'Bob Wilson', '13800003333', 'active'),('alice_brown', 'alice.brown@email.com', 'Alice Brown', '13800004444', 'inactive'),('charlie_davis', 'charlie.davis@email.com', 'Charlie Davis', '13800005555', 'active'),('diana_miller', 'diana.miller@email.com', 'Diana Miller', '13800006666', 'active'),('eva_garcia', 'eva.garcia@email.com', 'Eva Garcia', '13800007777', 'suspended'),('frank_taylor', 'frank.taylor@email.com', 'Frank Taylor', '13800008888', 'active'),('grace_lee', 'grace.lee@email.com', 'Grace Lee', '13800009999', 'active'),('henry_white', 'henry.white@email.com', 'Henry White', '13800010000', 'active');-- 插入商品数据INSERT INTO products (product_name, category, price, stock_quantity, description, status) VALUES('MacBook Pro 14寸', 'Electronics', 15999.00, 50, '苹果MacBook Pro 14英寸笔记本电脑', 'available'),('iPhone 15 Pro', 'Electronics', 7999.00, 100, '苹果iPhone 15 Pro智能手机', 'available'),('iPad Air', 'Electronics', 4599.00, 75, '苹果iPad Air平板电脑', 'available'),('Nike Air Max 270', 'Sports', 1299.00, 200, 'Nike气垫运动鞋', 'available'),('Adidas Ultraboost', 'Sports', 1599.00, 150, 'Adidas跑步鞋', 'available'),('普洱茶叶礼盒', 'Food', 299.00, 500, '云南普洱茶叶精装礼盒', 'available'),('有机大米 5kg', 'Food', 89.00, 1000, '东北有机大米', 'available'),('Sony WH-1000XM4', 'Electronics', 2299.00, 80, '索尼无线降噪耳机', 'available'),('Canon EOS R5', 'Electronics', 25999.00, 20, '佳能全画幅无反相机', 'available'),('Levi\'s 501牛仔裤', 'Clothing', 699.00, 300, 'Levi\'s经典501牛仔裤', 'available'),('The North Face冲锋衣', 'Clothing', 1299.00, 120, '北面户外冲锋衣', 'available'),('星巴克咖啡豆', 'Food', 128.00, 800, '星巴克精品咖啡豆', 'out_of_stock'),('小米13 Pro', 'Electronics', 4999.00, 0, '小米13 Pro智能手机', 'out_of_stock'),('古龙香水', 'Beauty', 399.00, 150, '男士古龙香水', 'available'),('SK-II神仙水', 'Beauty', 1599.00, 60, 'SK-II护肤精华液', 'available');-- 插入订单数据INSERT INTO orders (user_id, product_id, quantity, unit_price, total_amount, order_status, order_date, delivery_date) VALUES(1, 1, 1, 15999.00, 15999.00, 'delivered', '2024-01-15 10:30:00', '2024-01-20 14:30:00'),(1, 4, 2, 1299.00, 2598.00, 'delivered', '2024-01-20 09:15:00', '2024-01-25 16:20:00'),(2, 2, 1, 7999.00, 7999.00, 'shipped', '2024-02-01 14:20:00', NULL),(2, 6, 3, 299.00, 897.00, 'delivered', '2024-01-25 16:45:00', '2024-01-28 10:15:00'),(3, 3, 1, 4599.00, 4599.00, 'confirmed', '2024-02-10 11:30:00', NULL),(3, 8, 1, 2299.00, 2299.00, 'pending', '2024-02-12 15:20:00', NULL),(4, 7, 5, 89.00, 445.00, 'cancelled', '2024-01-30 13:10:00', NULL),(5, 9, 1, 25999.00, 25999.00, 'shipped', '2024-02-05 10:00:00', NULL),(5, 10, 2, 699.00, 1398.00, 'delivered', '2024-01-28 12:30:00', '2024-02-02 09:45:00'),(6, 11, 1, 1299.00, 1299.00, 'delivered', '2024-01-22 14:15:00', '2024-01-26 11:30:00'),(6, 14, 2, 399.00, 798.00, 'confirmed', '2024-02-08 16:20:00', NULL),(8, 5, 1, 1599.00, 1599.00, 'delivered', '2024-01-18 09:45:00', '2024-01-23 15:10:00'),(8, 15, 1, 1599.00, 1599.00, 'pending', '2024-02-11 13:25:00', NULL),(9, 1, 1, 15999.00, 15999.00, 'confirmed', '2024-02-09 11:40:00', NULL),(9, 6, 2, 299.00, 598.00, 'shipped', '2024-02-07 10:20:00', NULL),(10, 2, 1, 7999.00, 7999.00, 'delivered', '2024-01-16 15:30:00', '2024-01-21 12:15:00'),(10, 4, 1, 1299.00, 1299.00, 'delivered', '2024-01-29 14:50:00', '2024-02-03 16:40:00'),(1, 12, 2, 128.00, 256.00, 'cancelled', '2024-02-06 12:10:00', NULL),(3, 7, 10, 89.00, 890.00, 'delivered', '2024-01-24 11:20:00', '2024-01-27 13:45:00'),(2, 13, 1, 4999.00, 4999.00, 'cancelled', '2024-02-04 09:30:00', NULL);
这套完整的测试数据脚本构建了一个高度真实的电商业务环境，具有以下突出特点：
表结构设计特点：
users表: 用户基础信息管理表，包含完整的用户身份信息、联系方式、账户状态等关键字段，支持用户生命周期管理和多维度用户分析
products表: 商品信息管理表，涵盖商品基本属性、分类体系、价格策略、库存管理等核心业务要素，支持商品维度的各类统计分析
orders表: 订单业务流程表，通过外键关联实现用户与商品的多对多关系，支持复杂的订单状态跟踪和深度业务分析
测试数据特点：
用户维度: 10个测试用户，涵盖活跃、非活跃、暂停等多种账户状态，模拟真实的用户生态环境
商品维度: 15个商品记录，横跨电子产品、运动用品、食品、服装、美妆等5大品类，价格分布从几十元到数万元，覆盖不同消费层次
订单维度: 20个订单记录，包含待处理、已确认、已发货、已送达、已取消等完整的订单状态流转，时间跨度覆盖近期多个月份
如图1-7、图1-8、图1-9所示，通过执行这些数据库脚本，我们成功创建了三个核心数据表，形成了完整的业务数据模型。
图1-7 用户基础信息表
图1-8 商品信息表
图1-9 订单表（关联用户和商品）
3.2 测试数据库连接工具
在正式构建Text2SQL工作流之前，我们需要验证数据库连接工具的可用性和稳定性。FastGPT平台提供了专业的数据库连接工具，该工具经过严格的安全测试和性能优化，支持多种主流数据库系统，包括MySQL、PostgreSQL、SQL Server，能够满足不同企业的数据库技术栈需求。
如图1-10所示，在FastGPT工作台的工具箱模块中，选择"数据库连接"工具。工具箱提供了丰富的预配置工具，用户可以根据项目需求灵活选择和组合不同的功能组件。
图1-10 添加数据库连接工具
数据库连接工具的配置过程需要填入准确的外网访问参数，这些参数的正确性直接决定了后续工作流的运行效果。如图1-11所示，在配置界面中需要输入以下关键连接参数：
数据库类型：支持MySQL、PostgreSQL、SQL Server三种数据库类型
主机地址: 数据库服务器的公网IP地址或域名
数据库连接端口号: 数据库服务监听的端口，MySQL默认为3306
数据库名称: 目标数据库的名称，本案例为test_db
数据库账号: 具有相应权限的数据库用户账号
数据库密码: 对应用户的访问密码
输入所有必要参数后，点击"确认"按钮即可激活数据库连接工具。系统会自动验证连接参数的有效性，并建立与目标数据库的连接会话。
图1-11 激活数据库连接工具
为了验证数据库连接工具是否正常工作，我们需要执行一个简单的测试查询来确认连接状态。如图1-12所示，输入"SHOW TABLES;"命令来测试数据库连接的有效性。这个SQL命令是数据库管理中的标准命令，用于列出当前数据库中的所有表格，是验证连接状态最可靠的方法。
当工具执行成功并返回数据库中的表格列表（users、products、orders）时，说明连接配置完全正确，数据库连接工具已成功激活并可以正常使用。如果执行过程中出现错误，需要仔细检查连接参数的配置，排查网络连通性问题，必要时联系数据库服务提供商获取技术支持。
成功的测试结果表明工具已经准备就绪，可以在后续的工作流中执行各种复杂的SQL查询操作。
图1-12 调试数据库连接工具
3.3 Chart-MCP工具集创建
为了实现数据查询结果的专业可视化展示，本案例采用了Chart-MCP工具集来进行图表绘制。MCP（Model Context Protocol）是由Anthropic公司主导开发的一种标准化工具集成协议，它定义了AI模型与外部工具之间的通信规范和数据交换格式，使得各种专业工具能够无缝集成到AI工作流中，形成强大的复合智能系统。
Chart-MCP工具集是基于MCP协议开发的专业数据可视化工具集，它集成了业界领先的AntV图表引擎，支持多种图表类型和可视化方案。该工具集不仅包含传统的柱状图、折线图、饼图、散点图等基础图表，还支持热力图、桑基图、词云图、地理信息图等高级可视化形式。同时，工具集还提供了丰富的图表样式定制、数据动态绑定、交互功能配置等高级特性，能够满足不同业务场景的可视化需求。
如图1-13所示，首先需要访问魔搭社区的MCP广场(链接：https://modelscope.cn/mcp/servers/@antvis/mcp-server-chart) 。魔搭社区是阿里巴巴达摩院推出的AI开发者社区平台，MCP广场作为其重要组成部分，汇集了经过严格认证和测试的高质量MCP工具集，为开发者提供了丰富的AI工具生态。
在平台中找到"可视化图表-MCP-Server"工具集，该工具集由AntV团队开发维护，具有稳定可靠的性能表现和持续的技术支持。获取其MCP解析地址，该地址是工具集的唯一标识符，包含了工具集的元数据信息、API接口定义、参数规范等关键信息，是实现工具集集成的核心要素。
图1-13 MCP解析地址
获取解析地址后，如图1-14所示，回到FastGPT工作台，点击"新建MCP工具集"按钮。FastGPT平台提供了便捷的MCP工具集集成功能，支持一键导入和配置，大大简化了工具集的部署流程。平台的MCP集成模块经过了深度优化，能够自动处理协议转换、参数映射、错误处理等技术细节，为用户提供了开箱即用的工具集成体验。
图1-14 新建MCP工具集
如图1-15所示，在MCP工具集创建界面中，输入前面获取的MCP解析地址，然后点击"解析"按钮。如图1-15所示，系统将自动解析该地址，通过标准的MCP协议与工具集服务器进行通信，获取工具集中包含的所有工具定义和功能描述。解析成功后，用户可以看到工具集中包含的具体工具列表，每个工具都有详细的功能说明、参数定义、使用示例等信息，便于用户了解和选择合适的工具进行集成。
图1-15 解析MCP工具
如图1-16所示，MCP工具集还提供了专业的可视化调试界面，这是FastGPT平台的独特优势之一。调试界面允许用户在正式集成前对工具功能进行全面的测试和验证，大大提高了开发效率和集成质量。
图1-16 MCP工具集调试界面
四、工作流搭建
4.1 系统配置
为了让用户更好地理解数据库结构并提出准确的查询需求，我们需要在系统中配置详细的数据库表结构作为对话开场白。这个开场白将在用户初次访问时展示，帮助用户了解可查询的数据范围和表结构关系，从而提出更精准的查询请求。
如图1-17所示，在系统配置中输入完整的数据库表结构描述作为对话开场白。这个开场白包含了三个核心数据表的详细信息：用户表(users)、商品表(products)和订单表(orders)，每个表都详细列出了字段名称、数据类型、约束条件和业务含义说明。同时还明确说明了表间的关联关系，包括用户与订单的一对多关系、商品与订单的一对多关系，以及订单表作为关联表连接用户和商品的作用。
这种结构化的表结构展示不仅让用户清楚了解数据库的组织形式，还为用户提供了查询思路的指导。用户可以根据这些信息，准确描述自己的查询需求，比如"查询某个用户的所有订单"、"统计各类商品的销售情况"、"分析订单状态分布"等，从而获得更准确的查询结果。
# 数据库表结构## 1. 用户表 (users)| 字段名 | 数据类型 | 约束 | 说明 ||--------|----------|------|------|| user_id | INT | PRIMARY KEY, AUTO_INCREMENT | 用户ID || username | VARCHAR(50) | NOT NULL, UNIQUE | 用户名 || email | VARCHAR(100) | NOT NULL, UNIQUE | 邮箱 || full_name | VARCHAR(100) | NOT NULL | 真实姓名 || phone | VARCHAR(20) | | 手机号 || status | ENUM | DEFAULT 'active' | 状态(active/inactive/suspended) || created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 || updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |## 2. 商品表 (products)| 字段名 | 数据类型 | 约束 | 说明 ||--------|----------|------|------|| product_id | INT | PRIMARY KEY, AUTO_INCREMENT | 商品ID || product_name | VARCHAR(200) | NOT NULL | 商品名称 || category | VARCHAR(50) | NOT NULL | 商品分类 || price | DECIMAL(10,2) | NOT NULL | 价格 || stock_quantity | INT | NOT NULL, DEFAULT 0 | 库存数量 || description | TEXT | | 商品描述 || status | ENUM | DEFAULT 'available' | 状态(available/out_of_stock/discontinued) || created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 || updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |## 3. 订单表 (orders)| 字段名 | 数据类型 | 约束 | 说明 ||--------|----------|------|------|| order_id | INT | PRIMARY KEY, AUTO_INCREMENT | 订单ID || user_id | INT | NOT NULL, FOREIGN KEY | 用户ID || product_id | INT | NOT NULL, FOREIGN KEY | 商品ID || quantity | INT | NOT NULL, DEFAULT 1 | 购买数量 || unit_price | DECIMAL(10,2) | NOT NULL | 单价 || total_amount | DECIMAL(10,2) | NOT NULL | 总金额 || order_status | ENUM | DEFAULT 'pending' | 订单状态(pending/confirmed/shipped/delivered/cancelled) || order_date | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 下单时间 || delivery_date | TIMESTAMP | NULL | 收货时间 || created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP | 创建时间 || updated_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP ON UPDATE | 更新时间 |## 表关系- **users** 1:N **orders** (一个用户可以有多个订单)- **products** 1:N **orders** (一个商品可以被多次购买)- **orders** 通过 `user_id` 和 `product_id` 关联用户表和商品表
图1-17 对话开场白
4.2 问题分类-确保数据库安全
数据库安全是Text2SQL系统设计中的核心考虑因素。为了防止恶意用户通过自然语言输入执行危险的数据库操作，如数据删除、表结构修改、权限提升等，我们必须建立严格的安全防护机制。
如图1-18所示，我们采用问题分类节点作为系统的第一道安全防线。该节点基于先进的自然语言理解技术，能够智能识别用户输入的真实意图，严格区分安全的查询请求和潜在的危险操作。
安全防护系统的设计理念包括：
白名单机制: 只允许SELECT类型的查询操作通过，严格禁止所有修改、删除、创建类操作关键词检测: 建立了全面的危险关键词库，包括中英文的各种危险操作词汇语义分析: 不仅检测明显的危险词汇，还能识别隐含的恶意意图和变形表达
这种安全机制的设计确保了系统在提供便捷查询服务的同时，最大限度地保护数据库的安全性和数据完整性。
# 自然语言查询请求判断系统## 任务描述你是一个专门用于判断用户输入是否为数据库查询请求的安全检测系统。你的核心职责是确保只有安全的查询操作能够通过，严格阻止任何可能修改、删除或破坏数据库数据的请求。## 判断标准### ✅ 允许通过的查询类型（仅限SELECT操作）：- 数据检索和查看请求- 统计分析请求（计数、求和、平均值等）- 条件筛选查询- 排序和分组查询- 多表联合查询- 聚合函数查询- 数据库元数据查询（查询所有表格名称及表格字段结构）### ❌ 严格拒绝的操作类型：- 数据修改操作（UPDATE、INSERT、DELETE）- 表结构变更（CREATE、ALTER、DROP）- 权限管理操作（GRANT、REVOKE）- 数据库管理操作（BACKUP、RESTORE）- 存储过程和函数调用- 事务控制语句- 任何包含潜在恶意意图的输入### ⚠️ 高风险关键词识别：拒绝包含以下意图的输入：- 修改、更新、删除、插入、添加、变更- 创建、建立、新建、删除表/数据库- 授权、权限、用户管理- 执行、运行脚本- 备份、恢复、导入、导出
图1-18 确保数据库安全
如图1-19所示，根据问题分类的结果，系统采用不同的处理路径：
查询类请求: 通过安全验证的查询请求将继续进入后续的SQL生成和执行流程
非查询类请求: 被识别为潜在危险的请求将被定向到专门的回复节点，向用户说明系统仅支持数据查询功能，并提供正确的使用指导
这种分流机制不仅保证了系统安全，还提供了良好的用户体验，通过友好的提示信息引导用户正确使用系统功能。
图1-19 分类设置
4.3 返回本轮SQL书写所需数据表名
为了优化SQL生成的精度和效率，系统需要智能识别用户查询涉及的具体数据表。这一步骤的核心目标是从用户的自然语言输入中提取相关的数据实体，并映射到对应的数据库表名，为后续的表结构查询和SQL生成提供精确的目标范围。
如图1-20所示，这个模块包含三个关键组件：
数据库表名获取: 通过执行"SHOW TABLES;"命令获取数据库中所有可用的表名列表，为后续的表名匹配提供完整的候选集合。
AI语义分析: 利用大型语言模型的强大语义理解能力，分析用户输入的查询内容，识别其中涉及的业务实体和数据概念，并将这些概念与数据库表名进行智能匹配。匹配过程考虑了同义词、关联关系、业务逻辑等多种因素，确保匹配结果的准确性。
数据格式转换: 通过代码运行节点将分析得到的表名列表转换为标准的数组字符串格式，为后续的批量表结构查询提供规范化的输入参数。
这种智能表名识别机制显著提高了系统的查询效率，避免了不必要的表结构查询，同时为SQL生成提供了更精确的上下文信息。
任务：根据用户输入内容分析并返回相关的数据库表名输入：- 用户查询内容：[用户输入]- 可用表名列表：[数据库表名列表]要求：1. 分析用户输入的语义和意图2. 匹配最相关的数据库表名3. 按相关性从高到低排序4. 仅返回JSON数组格式：["table1", "table2", "table3"]5. 如无匹配结果则返回：[]6. 禁止输出任何解释、说明或其他内容输出格式：严格按照JSON数组格式，例如：["users", "orders", "products"]
图1-20 查询所需表名
4.4 查询数据表字段
获取准确的数据表字段信息是SQL生成的关键步骤。系统需要根据前一步骤识别出的相关表名，批量查询这些表的详细结构信息，包括字段名称、数据类型、约束条件、注释信息等。这些元数据将为大型语言模型提供完整的数据模型参考，确保生成的SQL语句在语法和语义上都完全正确。
如图1-21所示，该模块采用了高效的批量处理架构：
批量执行机制: 使用批量执行节点接收表名数组，并为每个表名自动生成对应的"SHOW FULL COLUMNS FROM 表名;"查询命令。这种批量处理方式显著提高了系统的执行效率，避免了多次单独查询带来的性能开销。
详细结构查询: "SHOW FULL COLUMNS FROM"命令能够返回表的完整字段信息，包括字段名、数据类型、是否允许NULL、默认值、额外属性、权限、注释等详细信息。这些丰富的元数据为SQL生成提供了全面的参考依据。
信息整合处理: 通过文本拼接节点将表名与其对应的字段结构信息进行关联整合，形成结构化的表结构描述文档。这种整合处理确保了信息的完整性和关联性，便于后续的AI模型理解和使用。
标准化输出: 使用结束节点对整合后的表结构信息进行标准化输出，确保数据格式的一致性和规范性，为下一阶段的SQL生成提供高质量的输入。
图1-21 查询数据表字段
4.5 自然语言生成SQL语句
这一阶段是整个Text2SQL系统的核心环节，需要将用户的自然语言查询需求转换为语法正确、逻辑合理的SQL语句。该过程不仅需要准确理解用户的查询意图，还要结合数据库的具体结构信息，生成高效且安全的SQL代码。
如图1-22所示，SQL生成模块采用了专业的AI对话节点，该节点配置了经过精心设计的专家提示词，确保生成的SQL语句具有以下特性：
语法准确性: 严格遵循MySQL的SQL语法规范，确保生成的语句能够正确执行语义正确性: 准确理解用户的查询意图，生成符合业务逻辑的查询语句性能优化: 考虑查询效率，合理使用索引、连接方式和查询条件安全可靠: 避免生成可能导致性能问题或安全风险的SQL语句
AI专家提示词的设计包含了以下关键要素：
角色定义：明确AI的专业身份和核心职责
技能描述：详细说明SQL生成所需的各项专业技能
限制条件：明确输出格式要求和安全约束
优化要求：强调生成SQL的效率和可维护性
这种专业化的提示词设计确保了AI模型能够始终保持高质量的SQL生成性能。
# 角色你是SQL语句生成专家，你擅长将用户输入的自然语言转换为高效的MySQL数据库SQL语句，你能够确保生成的SQL语句既符合语法规范，又能满足用户的查询需求。仅输出SQL，不要使用markdown格式输出，不要输出任何提示内容，例如SQL语句：## 背景在日常工作中，用户经常需要将自然语言描述的查询需求转换为SQL语句，以便在MySQL数据库中执行。你作为SQL语句生成专家，能够准确理解用户的意图，并将其转化为精确的SQL语句。## 技能### 技能 1: 需求解析与语义理解你能够深入解析用户输入的自然语言，准确识别出查询的目标表、字段、条件、排序方式等关键要素。通过语义分析，确保生成的SQL语句与用户的查询意图完全一致。### 技能 2: SQL语句生成你能够根据解析出的需求，生成符合MySQL语法的SQL语句。无论是简单的SELECT查询，还是复杂的JOIN、GROUP BY、HAVING等操作，你都能熟练处理，并确保语句的效率和正确性。### 技能 3: 优化与验证你能够对生成的SQL语句进行优化，确保其执行效率最大化。同时，你具备验证SQL语句正确性的能力，能够在生成后通过模拟执行或语法检查，确保语句无误。## 限制- 生成的SQL语句必须严格符合MySQL语法规范。- 不能改变用户的原始查询意图。- 在涉及复杂查询时，需确保生成的SQL语句具有可读性和可维护性。- 对于模糊或不明确的用户输入，需通过进一步询问来澄清需求。- 生成的SQL语句应避免潜在的安全风险，如SQL注入等。- 仅输出SQL，不要使用markdown形式输出- 避免生成可能导致性能问题或安全风险的SQL语句
图1-22 自然语言生成SQL
4.6 SQL执行并转成自然语言
生成SQL语句后，系统需要执行该语句并将查询结果转换为用户友好的自然语言描述。这一步骤不仅验证了SQL语句的正确性，还为用户提供了直观易懂的查询结果解释，大大提升了系统的用户体验。
如图1-23所示，这个模块包含两个核心组件：
SQL执行: 使用前面配置的数据库连接工具执行生成的SQL语句。执行过程中系统会进行多项检查，包括语法验证、权限确认、执行超时控制等，确保查询过程的安全性和稳定性。
结果解释生成: 通过专门的AI对话节点将SQL查询结果转换为自然语言描述。该节点配置了专业的结果解释提示词，能够：
准确解读查询结果的数据内容
提供清晰的数据统计和分析
根据查询类型调整解释的详细程度
结合业务上下文提供有意义的数据洞察
使用用户友好的语言表达技术性内容
结果解释系统的设计遵循了专业数据分析师的工作方式，不仅报告数据的表面信息，还能够挖掘数据背后的业务含义和趋势特征。这种智能化的结果解释功能使得非技术用户也能够轻松理解复杂的查询结果。
角色你是SQL查询结果解释专家，你擅长将复杂的SQL查询结果转化为清晰、易懂的自然语言描述，你能够根据用户的具体问题和查询结果，提供准确且易于理解的分析报告。# 背景在数据分析和业务决策过程中，SQL查询结果是获取信息的关键步骤。然而，这些结果往往以表格或数据集的形式呈现，对于非技术人员来说可能难以理解。你作为SQL查询结果解释专家，能够将这些数据转化为自然语言，帮助用户更好地理解数据背后的含义。# 技能## 技能 1: 数据结果的自然语言转化你能够将SQL查询结果中的关键数据点转化为自然语言描述，确保用户能够轻松理解数据的含义。例如，将“SELECT COUNT(*) FROM users WHERE age > 30;”的结果解释为“在用户表中，年龄大于30岁的用户共有500人。”## 技能 2: 提供上下文和洞察你不仅能够解释数据结果，还能根据用户的问题提供进一步的上下文和洞察。例如，如果用户询问“哪些产品的销量最高？”，你不仅能列出销量最高的产品，还能分析这些产品的销售趋势或与其他产品的对比情况。## 技能 3: 定制化解释你能够根据用户的需求定制解释的详细程度和重点。例如，对于需要详细分析的业务人员，你可以提供深入的数据解读；对于只需要概括信息的管理层，你可以提供简洁的总结。# 限制- 解释必须基于SQL查询结果的准确数据，不能添加未经证实的信息。- 解释语言必须清晰、简洁，避免使用过于专业的术语，除非用户明确要求。- 根据用户的时间要求，确保解释的及时性，避免过度延迟。- 解释中应避免主观判断，除非用户明确要求提供个人见解。- 确保解释的格式易于阅读，如有必要，可以使用分段、列表等方式增强可读性。
图1-23 SQL执行结果转自然语言
4.7 根据SQL查询结果生成可视化图表
数据可视化是现代数据分析不可缺少的重要环节，能够将抽象的数据转换为直观的图形表现，帮助用户快速理解数据模式、发现数据趋势、获得业务洞察。本系统通过集成Chart-MCP工具集，实现了查询结果的智能可视化功能。
如图1-24所示，可视化模块采用工具调用节点连接前面配置的Chart-MCP工具集。
## 角色定义你是一位**专业的数据可视化专家和图表绘制助手**，拥有丰富的数据分析和可视化经验，每次绘制图表都必须调用Chart-MCP工具。你能够：- 深度理解用户的数据分析需求- 基于数据特征智能推荐最优图表类型- 生成高质量、专业的可视化图表- 提供数据洞察和可视化建议- 绘制词云图布局要求紧凑，突出重点- 绘制路径规划时，既要返回预览图也要返回二维码扫码图## 标准输出模板### 成功生成格式：📊 **生成结果**:点击预览：[图表描述 - 核心洞察](图表URL)💡 **数据洞察**:- 关键发现1- 关键发现2- 趋势解读📈 **优化建议**:- 可视化改进点- 数据补充建议### 错误处理格式：⚠️ **数据问题**: [具体问题描述]🔧 **解决方案**: [详细建议]📞 **需要信息**: [补充要求]
图1-24 绘制可视化图表
4.8 完整工作流截图
经过以上各个模块的精心设计和配置，我们构建了一个功能完整、结构清晰的Text2SQL智能代理系统。该系统从用户输入的自然语言开始，经过安全验证、语义分析、SQL生成、数据查询、结果解释、图表可视化等多个环节，最终为用户提供了全方位的数据查询和分析服务。
如图1-25所示，完整的工作流呈现了以下特点：
模块化设计: 每个功能模块都具有明确的职责和清晰的输入输出接口，便于维护和扩展流程化处理: 整个处理流程遵循了数据分析的标准步骤，确保了结果的准确性和可靠性安全性保障: 在关键环节设置了多重安全检查机制，有效防范了潜在的安全风险用户体验优化: 从系统配置到结果展示，每个环节都考虑了用户的使用体验和理解能力
这种系统性的设计方法不仅确保了技术实现的可靠性，还为用户提供了专业级的数据分析服务体验。
图1-25 完整工作流截图
五、运行预览测试
为了全面验证Text2SQL系统的功能完整性和性能表现，我们设计了一套全面的测试用例，涵盖了从基础查询到复杂业务分析的各种应用场景。这些测试用例不仅验证了系统的技术能力，还展示了其在实际业务环境中的应用价值。
基础查询（简单多表联查）
基础查询测试主要验证系统处理简单多表联接查询的能力，这是Text2SQL系统最基础也是最重要的功能。如图1-26所示，当用户输入"查询所有用户的姓名和他们购买的商品名称"时，系统表现出了出色的语义理解能力：
SQL生成准确性: 系统准确识别了查询涉及users和products两个表，并通过orders表建立了正确的关联关系，生成了语法正确的JOIN查询语句。
自然语言解释: 系统将查询结果转换为清晰的自然语言描述，准确统计了查询到的记录数量，并简要说明了数据的含义。
可视化展示: 根据查询结果的特征，系统智能选择了合适的图表类型，生成了直观的可视化图表，帮助用户更好地理解数据分布情况。
这个测试用例验证了系统在处理最常见的关联查询时的稳定性和准确性，为更复杂的查询场景奠定了坚实基础。
图1-26 基础查询（简单多表联查）
中级查询（含聚合和分组）
中级查询测试重点验证系统处理聚合函数和分组查询的能力，这类查询在数据分析中极为重要。如图1-27所示，测试用例可能包括统计各类商品的销售情况、分析用户购买行为等场景：
聚合函数应用: 系统能够正确理解并生成包含COUNT、SUM、AVG、MAX、MIN等聚合函数的SQL语句，准确计算统计指标。
分组逻辑处理: 对于需要按照特定维度进行分组统计的查询，系统能够准确识别分组字段，生成正确的GROUP BY子句。
条件筛选优化: 系统能够合理使用WHERE和HAVING子句，确保查询条件的准确应用和查询性能的优化。
结果解释深度: 对于聚合查询结果，系统不仅提供数值统计，还能够分析数据的业务含义和趋势特征。
图1-27 中级查询（含聚合和分组）
高级查询（复杂条件和子查询）
高级查询测试旨在验证系统处理复杂查询逻辑的能力，包括子查询、复合条件、多表关联等高级SQL特性。如图1-28所示，这类查询通常涉及更复杂的业务逻辑：
子查询处理: 系统能够理解嵌套查询的逻辑结构，正确生成相关子查询和非相关子查询，并优化查询执行计划。
复合条件构建: 对于包含多个AND、OR逻辑条件的查询，系统能够准确理解条件间的逻辑关系，生成正确的WHERE子句。
性能优化意识: 在生成复杂查询时，系统会考虑查询性能，合理使用索引提示和查询优化技巧。
错误处理机制: 对于可能产生歧义或错误的复杂查询，系统具备一定的错误检测和纠正能力。
图1-28 高级查询（复杂条件和子查询）
复杂分析查询
复杂分析查询测试验证系统进行深度数据分析的能力，这类查询通常涉及多维度的业务分析需求。如图1-29所示，测试场景可能包括趋势分析、对比分析、关联分析等：
多维度分析: 系统能够理解跨多个业务维度的分析需求，生成包含多个关联表和复杂计算逻辑的SQL语句。
时间序列处理: 对于涉及时间维度的分析查询，系统能够正确处理日期函数和时间范围条件。
比较分析逻辑: 系统能够理解同比、环比等比较分析的业务含义，生成相应的计算逻辑。
数据洞察能力: 对于复杂分析结果，系统能够提供深入的业务洞察和趋势解读。
图1-29 复杂分析查询
业务洞察查询
业务洞察查询测试重点验证系统将技术查询转化为业务价值的能力，这是Text2SQL系统的高级应用场景。如图1-30所示，这类查询不仅要求技术上的准确性，更要求业务理解的深度：
业务场景理解: 系统能够理解具体的业务术语和概念，将其准确转换为相应的数据库查询逻辑。
指标计算准确性: 对于关键业务指标（如转化率、留存率、增长率等），系统能够生成准确的计算公式。
趋势识别能力: 系统能够从查询结果中识别重要的业务趋势和异常情况。
决策支持价值: 查询结果和分析洞察能够为业务决策提供有价值的数据支持。
图1-30 业务洞察查询
这套全面的测试用例全面验证了Text2SQL系统的各项核心功能，证明了系统在不同复杂度和应用场景下的稳定性和准确性。测试结果表明，系统不仅具备了强大的技术实现能力，还具有良好的用户体验和实际应用价值。
六、发布Agent
完成Text2SQL系统的开发和测试后，我们需要将其发布为可供用户访问的智能代理服务。FastGPT平台提供了多种灵活的发布渠道，能够满足不同应用场景和集成需求，为开发者提供了完整的产品化解决方案。
6.1 共享链接直连模式
共享链接直连模式是最简单快捷的发布方式，特别适合快速原型验证、演示展示、公开服务等场景。该模式通过生成唯一的访问链接，允许用户无需注册登录即可直接使用智能代理服务。
如图1-31所示，在FastGPT导航栏中点击"发布渠道"选项，选择"免登录窗口"功能，然后点击"创建新链接"按钮。这个过程非常简单，只需几步操作即可完成配置。
免登录窗口的核心优势在于：
零门槛访问: 用户无需任何注册或登录过程，点击链接即可使用
快速部署: 创建过程简单快速，适合敏捷开发和快速迭代
广泛兼容: 支持各种设备和浏览器，确保用户访问的便利性
灵活配置: 支持多种个性化配置选项，满足不同场景需求
图1-31 创建免登录窗口连接
如图1-32所示，在配置界面中可以设置多项参数来定制用户体验，完成配置后点击确认，系统将自动生成唯一的访问链接，该链接可以直接分享给目标用户或嵌入到网站页面中。
图1-32 填写免登录窗口配置参数
如图1-33、图1-34所示，通过唯一URL（如shareId参数）直接访问特定会话，无需身份验证即可进入预设的聊天界面。适用于公开分享场景，用户仅需点击链接即可交互。
图1-33 共享链接直连模式
图1-34 共享链接直连模式演示界面
6.2 嵌入式iframe集成模式
嵌入式iframe集成模式为开发者提供了将Text2SQL功能无缝集成到现有网站或应用中的解决方案。通过标准的HTML iframe标签，可以将智能代理服务作为独立组件嵌入到任何网页环境中，保持界面风格的一致性和功能的完整性。
如图1-35所示，系统自动生成标准的iframe嵌入代码，该代码包含了完整的配置参数和安全属性。
图1-35 嵌入式iframe集成模式
如图1-36所示，嵌入式iframe的实际应用效果展示了其在第三方网站中的完美集成表现。聊天窗口与网站的整体设计风格保持一致，用户体验流畅自然。
图1-36 嵌入式iframe集成模式演示
6.3 脚本化动态加载模式
脚本化动态加载模式代表了最灵活和功能丰富的集成方案，通过JavaScript脚本实现聊天窗口的动态加载和高度定制化配置。这种模式特别适合需要复杂交互逻辑和个性化用户体验的高级应用场景。
如图1-37所示，系统提供了完整的JavaScript集成脚本，该脚本包含了丰富的配置选项和交互功能。
图1-37 脚本化动态加载模式
如图1-38所示，脚本化动态加载模式的演示界面展示了其强大的定制能力和用户体验。浮动式的聊天窗口可以根据用户偏好进行位置调整，支持拖拽操作，并且具有智能的显示/隐藏逻辑。
应用场景优势:
SaaS平台集成: 为云服务平台提供增值的AI查询功能
移动应用嵌入: 通过WebView在移动应用中集成查询功能
桌面软件集成: 在桌面应用中嵌入Web形式的AI助手
定制化项目: 需要深度品牌定制和功能扩展的项目
图1-38 脚本化动态加载模式演示界面
6.4 静态密钥认证接口集成模式
静态密钥认证接口集成模式为开发者提供了最灵活的后端集成方案，通过RESTful API接口实现Text2SQL功能的深度集成。这种模式特别适合需要将AI查询能力集成到现有系统架构中的企业级应用场景。
如图1-39所示，首先需要在FastGPT平台的发布渠道中选择"API访问"选项，然后点击"新建"按钮来创建API访问密钥。API密钥是确保接口安全性的重要凭证，每个密钥都有独特的权限控制和使用范围。
API密钥管理特性:
权限控制: 可以为不同的API密钥设置不同的访问权限
使用统计: 实时监控API调用频次和资源使用情况
安全审计: 完整的API调用日志和安全审计功能
配额管理: 灵活的调用频次和并发限制设置
图1-39 新建API密钥
如图1-40所示，在API配置界面中填写相关参数后，系统将生成唯一的API密钥。这个密钥需要妥善保管，并在后续的API调用中作为身份认证凭证。
图1-40 复制API密钥
如图1-41所示，系统提供了标准的RESTful API调用示例，展示了如何使用Bearer Token认证方式进行接口调用。这种API设计遵循了业界标准规范，确保了良好的兼容性和易用性。
curl POST 'https://api.fastgpt.in/api/v1/chat/completions' \--header 'Authorization: Bearer fastgpt-xxxxxx' \--header 'Content-Type: application/json' \--data-raw '{"chatId": "my_chatId","stream": false,"detail": false,"responseChatItemId": "my_responseChatItemId","variables": {"uid": "asdfadsfasfd2323","name": "张三"},"messages": [{"role": "user","content": "查询所有用户的姓名和他们购买的商品名称"}]}'
核心参数说明:
chatId: 会话标识符，用于维护多轮对话的上下文状态
stream: 流式响应控制，支持实时消息推送和长文本生成
detail: 响应详细程度控制，可获取更多调试和分析信息
variables: 动态上下文变量，支持个性化和上下文感知的交互
messages: 标准的对话消息格式，支持多轮对话历史
企业级集成优势:
高度灵活性: 可以完全控制用户界面和交互逻辑
深度集成: 与现有系统的用户认证、权限管理等无缝集成
性能优化: 支持批量处理、并发调用、缓存策略等优化方案
监控分析: 完整的调用链路跟踪和性能监控能力
图1-41 API测试
如图1-42所示，在FastGPT的对话日志中可以清晰地看到API调用的详细记录，包括请求参数、响应内容、执行时间等关键信息。这种透明的日志机制为系统调试和性能优化提供了重要支持。
图1-42 对话日志
如图1-43所示，开发者可以非常便捷地将API集成到自己开发的网站或应用中。通过标准的HTTP请求调用，可以在任何支持网络请求的开发环境中使用Text2SQL功能。
图1-43 静态密钥认证接口集成模式演示界面
七、总结
通过本实战案例的完整实现，我们成功构建了一个功能强大的Text2SQL智能代理系统，实现了从自然语言输入到数据库查询，再到可视化图表展示的完整数据分析流程。该系统不仅具备了准确的语言理解能力，能够将用户的自然语言查询转换为语法正确的SQL语句，还建立了完善的安全防护机制，通过多层验证确保只允许安全的查询操作。系统采用模块化架构设计，包含问题分类、智能表结构识别、SQL生成、结果解释和可视化展示等核心模块，各环节相互配合形成了完整的处理链路。通过全面测试验证，系统在从基础查询到复杂业务分析的各种场景下都表现出色，能够准确理解用户意图并生成高质量的查询结果。
在实际应用价值方面，该系统真正实现了数据访问的民主化，使得没有技术背景的业务用户也能轻松进行数据库查询和分析，大大降低了技术门槛并提高了工作效率。系统不仅提供原始查询结果，还通过AI智能解读转换为易于理解的自然语言描述，并集成Chart-MCP工具集自动生成专业的可视化图表，为用户提供全方位的数据分析体验。本案例还展示了四种灵活的部署发布方案，包括共享链接直连、嵌入式iframe集成、脚本化动态加载和API接口集成，满足了从快速演示到企业级系统集成的各种应用需求，具有广泛的适用性和推广价值。
本案例在技术创新方面的突破体现在将自然语言理解技术成功应用于数据库安全防护、实现动态元数据获取、提供多模态结果展示，以及展示了MCP协议在AI工具集成中的应用价值。展望未来，该系统在企业数据分析、商业智能平台、教育培训、客户服务和决策支持等领域都具有广阔的应用前景。通过本案例的学习和实践，读者不仅掌握了Text2SQL系统的完整构建方法，还深入了解了FastGPT平台的强大功能，为在实际工作中构建类似的智能数据分析系统提供了宝贵的参考和指导，具有重要的实用价值和推广意义。