基于 DeepSeek V3.2 构建企业级 Text-to-SQL 专家系统

这段代码通过设置 stream=True 开启了流式输出。流式输出对于生成 SQL 这种可能需要一定推理时间的任务非常重要，它可以让用户实时看到生成的字符，减少等待焦虑。值得注意的是，DeepSeek 模型支持 reasoning_content（推理内容），代码中专门增加了对这一字段的处理逻辑，将模型的'思考过程'与'最终结果'分别输出，有助于开发者调试和理解模型的决策路径。

2.2 项目结构初始化

将上述逻辑封装到完整的项目结构中。

上图展示了将核心逻辑保存为 README.md 或相关说明文件的过程，同时也暗示了项目的基础文件结构。一个完整的 Python 项目通常包含代码文件、依赖说明文件以及环境配置。

上图呈现了项目目录结构，包含自动生成的代码文件。合理的目录结构有助于后续的维护与部署。

为了运行项目，必须安装 Python 依赖。通常需要安装 openai 用于 API 调用，以及 streamlit 用于构建 Web 界面。

pip install -r requirements.txt

上图展示了在终端执行 pip install -r requirements.txt 的过程。系统正在下载并安装所需的库文件，这是程序运行前的必要环境准备步骤，确保所有调用的模块都已正确安装在当前 Python 环境中。

第三章：Streamlit 可视化界面开发

为了让业务人员能够方便地使用 Text-to-SQL 功能，单纯的命令行脚本是不够的。我们需要构建一个 Web 界面。Streamlit 是一个无需编写 HTML/CSS 即可快速构建数据应用的 Python 框架。

启动应用的命令如下：

streamlit run app.py

在初次启动 Streamlit 时，终端会提示输入邮箱（用于接收更新通知），开发者可以直接回车跳过。随后，终端会显示本地访问地址（通常是 http://localhost:8501）和网络访问地址。

启动成功后，浏览器会自动打开应用界面。上图展示了初始化的 Streamlit 界面，界面简洁明了，通常包含侧边栏用于参数设置（如输入 Schema），以及主区域用于对话交互。这种布局设计非常适合问答式的工具应用。

第四章：Schema 定义与 SQL 生成实测

Text-to-SQL 的核心在于 Prompt Engineering（提示词工程）。为了让模型生成准确的 SQL，必须向其提供精确的数据库 Schema。

4.1 全能型电商 Schema 设计

为了测试模型的泛化能力，我们设计了一套涵盖用户、产品、订单及订单详情的复杂电商 Schema。

-- 1. 用户表：包含等级、注册时间和地域信息
CREATE TABLE users (
    user_id INT PRIMARY KEY COMMENT '用户唯一 ID',
    username VARCHAR(50),
    email VARCHAR(100),
    vip_level INT DEFAULT 0 COMMENT 'VIP 等级：0=普通，1=白银，2=黄金，3=钻石',
    balance DECIMAL(10,2) COMMENT '账户余额',
    created_at DATETIME COMMENT '注册时间',
    region VARCHAR(50) COMMENT '用户所在地区，如：Beijing, Shanghai'
);

-- 2. 产品表：包含价格、成本、库存和分类
CREATE TABLE products (
    product_id INT PRIMARY KEY,
    product_name VARCHAR(100),
    category_name VARCHAR(50) COMMENT '产品分类，如：电子产品，家居，服装',
    price DECIMAL(10,2) COMMENT '当前售价',
    cost DECIMAL(10,2) COMMENT '进货成本',
    stock_quantity INT COMMENT '剩余库存数量',
    status VARCHAR(20) COMMENT '状态：on_shelf(上架), off_shelf(下架)'
);

-- 3. 订单主表：记录谁买的、什么时候买的、总金额
CREATE TABLE orders (
    order_id INT PRIMARY KEY,
    user_id INT COMMENT '关联 users 表',
    total_amount DECIMAL(10,2) COMMENT '订单实付总金额',
    order_date DATETIME COMMENT '下单时间',
    status VARCHAR(20) COMMENT '订单状态：pending(待支付), paid(已支付), cancelled(已取消), refunded(已退款)',
    payment_method VARCHAR(20) COMMENT '支付方式：alipay, wechat, credit_card'
);

-- 4. 订单详情表：记录具体买了哪些商品（用于分析销量和爆款）
CREATE TABLE order_items (
    item_id INT PRIMARY KEY,
    order_id INT COMMENT '关联 orders 表',
    product_id INT COMMENT '关联 products 表',
    quantity INT COMMENT '购买数量',
    unit_price DECIMAL(10,2) COMMENT '购买时的单价（可能与当前产品价格不同）'
);

将这段 Schema 代码输入到应用的侧边栏或配置区域中。

上图展示了将定义好的 SQL Schema 粘贴至应用左侧配置栏的效果。这一步至关重要，DeepSeek 模型将把这部分内容作为上下文（Context），理解表名、字段名以及字段的含义（通过注释），从而在后续生成 SQL 时引用正确的标识符。

4.2 场景化测试

测试场景一：用户筛选
提问：'帮我找出所有 VIP 等级大于 2 的用户，并按注册时间倒序排列。'

从上图的生成结果可以看出，DeepSeek 准确识别了 users 表，正确理解了'VIP 等级大于 2'对应 vip_level > 2，以及'注册时间倒序'对应 ORDER BY created_at DESC。模型生成的 SQL 语法完全符合标准。

测试场景二：销售统计
提问：'统计'电子产品'类目下，上个月的总销售额是多少？'

这是一个涉及多表关联的复杂查询。上图显示，模型识别到需要关联 products 表（获取类目）和 order_items 表（获取销售金额），甚至可能关联 orders 表（获取时间）。模型生成的 SQL 使用了 JOIN 操作，并利用 SUM 函数计算总额，同时对时间进行了条件过滤。这体现了模型对业务逻辑的深度理解。

测试场景三：库存预警
提问：'查找库存少于 10 件且状态为'上架'的所有商品名称。'

上图展示了针对库存管理的查询生成。模型精准定位到 products 表，使用了 stock_quantity < 10 和 status = 'on_shelf' 两个条件进行 AND 逻辑组合，仅筛选出 product_name 字段。这种精准的字段筛选避免了 SELECT * 带来的性能浪费。

在进行了一系列测试后，我们可以在管理后台查看 API 调用详情。

上图是管理后台的调用日志界面，记录了 API 的调用次数、Token 消耗量以及请求状态。监控这些数据有助于开发者掌握应用的使用成本和运行稳定性。

第五章：生产环境服务器部署

为了让团队成员随时随地访问该工具，需要将其部署到云服务器上。

5.1 远程连接与代码传输

使用 SSH 工具（如 Kiro 或 Putty）连接到 Linux 服务器。

上图展示了通过终端远程连接服务器并将本地代码文件传输到服务器目录的过程。这是部署的第一步，确保生产环境拥有最新的代码版本。

5.2 自动化部署脚本

为了简化部署流程，编写了一个名为 deploy.sh 的 Shell 脚本。该脚本集成了环境安装、虚拟环境创建、Systemd 服务配置以及 Nginx 反向代理配置。

#!/bin/bash
# MySQL_Agent Streamlit 应用部署脚本
set -e
echo "=== 1. 安装系统依赖 ==="
sudo apt update
sudo apt install -y nginx python3-pip python3-venv

echo "=== 2. 创建虚拟环境并安装依赖 ==="
cd ~/MySQL_Agent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

echo "=== 3. 创建 systemd 服务 ==="
sudo tee /etc/systemd/system/mysql-agent.service > /dev/null <<'EOF'
[Unit]
Description=MySQL Agent Streamlit App
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/root/MySQL_Agent
Environment="PATH=/root/MySQL_Agent/venv/bin"
ExecStart=/root/MySQL_Agent/venv/bin/streamlit run app.py --server.port 8501 --server.address 127.0.0.1 --server.headless true
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target
EOF
# 路径已硬编码为 root 用户
echo "=== 4. 配置 Nginx 反向代理 ==="
sudo tee /etc/nginx/sites-available/mysql-agent > /dev/null <<'EOF'
server {
    listen 80;
    server_name _;
    location / {
        proxy_pass http://127.0.0.1:8501;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 86400;
    }
    location /_stcore/stream {
        proxy_pass http://127.0.0.1:8501/_stcore/stream;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_read_timeout 86400;
    }
}
EOF
echo "=== 5. 启用站点配置 ==="
sudo ln -sf /etc/nginx/sites-available/mysql-agent /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default

echo "=== 6. 启动服务 ==="
sudo systemctl daemon-reload
sudo systemctl enable mysql-agent
sudo systemctl start mysql-agent
sudo systemctl restart nginx

echo "=== 部署完成! ==="
echo "访问地址：http://$(hostname -I | awk '{print $1}')"

脚本核心内容解析：

1. 依赖安装：自动执行 apt install nginx python3-pip python3-venv，安装必要的系统组件。
2. 虚拟环境：创建 venv 并安装 requirements.txt，确保 Python 环境隔离，不污染系统全局环境。
3. Systemd 服务化：创建一个 .service 文件，定义服务的启动命令、工作目录和重启策略（Restart=always）。这确保了应用在崩溃或服务器重启后能自动运行，实现了守护进程化。
4. Nginx 反向代理：配置 Nginx 监听 80 端口，将流量转发到 Streamlit 的 8501 端口。脚本中特别配置了 Upgrade 和 Connection 头，这是为了支持 Streamlit 基于 WebSocket 的通信机制，防止连接中断。

执行部署脚本：

cd ~/MySQL_Agent && ./deploy.sh

上图展示了 deploy.sh 脚本的具体内容，代码逻辑清晰，涵盖了从环境准备到服务启动的全过程。

上图显示脚本执行完成，提示服务已启动。此时，应用已在后台运行，并由 Nginx 接管外部请求。

5.3 端口配置与访问优化

在默认情况下，Streamlit 监听 127.0.0.1（仅本地访问）。如果 Nginx 配置正确，通过反向代理即可访问。但如果在调试阶段需要直接通过 IP:端口访问，或者 Nginx 转发出现问题，需要调整监听地址。

上图展示了对启动参数的修改思考。为了允许外部直接访问 Streamlit 端口（非 Nginx 代理模式），需要修改启动命令。

使用以下命令重启 Streamlit，使其监听所有网络接口：

streamlit run app.py --server.port 8501 --server.address 0.0.0.0 --server.headless true

参数解析：

• --server.address 0.0.0.0：允许来自任何 IP 的连接，而不仅仅是本机。
• --server.headless true：在无显示器的服务器模式下运行，不尝试打开浏览器。

部署完成后，通过浏览器访问服务器公网 IP 即可看到最终运行的界面。上图展示了部署在服务器上的应用界面，用户可以通过互联网访问该工具，输入 Schema 和自然语言问题，获取优化后的 SQL 语句。

相关代码如下：

app.py

""" 智能 SQL 生成与优化专家 - Web 界面 """
import streamlit as st
from sql_agent import SQLAgent

st.set_page_config(page_title="SQL 智能助手", page_icon="🔍", layout="wide")
st.title("🔍 智能 SQL 生成与优化专家")
st.caption("将自然语言转换为精准的 SQL 查询")

# 初始化 Agent
if "agent" not in st.session_state:
    st.session_state.agent = SQLAgent()

if "messages" not in st.session_state:
    st.session_state.messages = []

# 侧边栏 - Schema 输入
with st.sidebar:
    st.header("📋 数据库 Schema")
    # 示例 Schema
    example_schema = """-- 用户表
CREATE TABLE users (
    user_id INT PRIMARY KEY,
    username VARCHAR(50),
    email VARCHAR(100),
    created_at DATETIME,
    vip_level INT DEFAULT 0
);
-- 产品表
CREATE TABLE products (
    product_id INT PRIMARY KEY,
    product_name VARCHAR(100),
    category VARCHAR(50),
    price DECIMAL(10,2),
    stock INT
);
-- 订单表
CREATE TABLE orders (
    order_id INT PRIMARY KEY,
    user_id INT,
    order_date DATETIME,
    total_amount DECIMAL(10,2),
    status VARCHAR(20)
);
-- 订单明细表
CREATE TABLE order_items (
    item_id INT PRIMARY KEY,
    order_id INT,
    product_id INT,
    quantity INT,
    unit_price DECIMAL(10,2)
);"""
    schema = st.text_area("请输入表结构（DDL）：", value=example_schema, height=400)
    if st.button("✅ 确认 Schema", use_container_width=True):
        st.session_state.agent.set_schema(schema)
        st.session_state.messages = []
        st.success("Schema 已更新！")
    st.divider()
    st.markdown("### 💡 示例问题")
    examples = [
        "查询上季度复购率最高的前十个产品",
        "统计每个月的销售额趋势",
        "找出消费金额最高的 VIP 用户",
        "哪些产品库存不足 10 件？"
    ]
    for ex in examples:
        st.markdown(f"- {ex}")

# 主界面 - 对话
for msg in st.session_state.messages:
    with st.chat_message(msg["role"]):
        st.markdown(msg["content"])

# 用户输入
if prompt := st.chat_input("请输入您的数据查询需求..."):
    # 显示用户消息
    st.session_state.messages.append({"role": "user", "content": prompt})
    with st.chat_message("user"):
        st.markdown(prompt)

    # 生成 SQL
    with st.chat_message("assistant"):
        placeholder = st.empty()
        full_response = ""
        for chunk in st.session_state.agent.generate_sql(prompt):
            full_response += chunk
            placeholder.markdown(full_response + "▌")
        placeholder.markdown(full_response)
        st.session_state.messages.append({"role": "assistant", "content": full_response})

config.py

# DeepSeek API 配置
API_KEY = "sk-xxxxxxxxxxxxxxx"
BASE_URL = "https://api.example.com/v1"
MODEL_ID = "/maas/deepseek-ai/DeepSeek-V3.2"

结语

通过本文的实战演示，我们成功利用 DeepSeek V3.2 模型和大模型服务（MaaS）平台，构建并部署了一个智能 Text-to-SQL 专家系统。从 API 的接入、Python 逻辑的实现、Streamlit 界面的构建，到最终基于 Nginx 和 Systemd 的自动化部署，涵盖了 AI 应用落地的全流程。

该工具极大地降低了数据查询的门槛，使得非技术人员也能轻松获取数据洞察，同时也为开发者提供了一个探索 LLM 在垂直领域应用（如数据库运维、BI 分析）的优秀范例。随着 DeepSeek 模型的持续迭代，此类工具在理解复杂业务逻辑和生成高性能 SQL 方面的能力将进一步提升。