[Python] Text-to-SQL智能体实践：基于动态上下文与持续学习的SQL自动生成与优化

本文将介绍如何构建一个具备自我提升能力的Text-to-SQL智能体。该智能体通过结合动态上下文检索与一种务实的“持续学习”机制来生成和优化SQL查询。整个系统工作流程分为两部分：

• 在线路径 (Text-to-SQL智能体)：通过从知识库中检索相关架构和查询模式（动态上下文）来响应用户问题并生成SQL。
• 离线路径 (持续学习)：从成功的查询执行中学习，并将新的有效模式或规则存入知识库，供未来使用。

当智能体成功执行一次查询后，该经验会被捕获并存储，从而形成一个自我提升的反馈循环，同时确保在线服务路径的稳定与高效。

1. Text-to-SQL在实践中面临的挑战与根源

许多Text-to-SQL系统在实际应用中效果不佳，其根本原因往往在于它们每次处理查询时都“从零开始”：重新描述表结构、列信息，尝试寻找连接关系，并可能重复犯下相同的错误。

这与经验丰富的数据分析师或工程师的工作方式截然不同。后者会充分利用已有的“部落知识”和过往经验，查阅历史查询记录以找到正确模式。一旦发现有效的查询，他们会将其保存下来以备后用。我们的智能体旨在模拟这一过程。

实践表明，多数Text-to-SQL的失败并非源于模型能力不足，而是“模型缺乏必要的上下文与领域知识”所导致。常见问题包括：

• 模型每次都需要重新理解数据库结构，导致效率低下并重复错误。
• 模型会猜测列名、使用不准确的模式，或无法识别正确的表连接键。
• 模型缺乏业务领域的明确定义（如“活跃用户”、“流失率”的计算方式），或不了解特定的业务规则（例如：“订单状态字段是orders.state，而非orders.status”）。
• 模型不清楚常见的“陷阱”（如日期格式处理不当、对空值的错误假设等）。
• 模型耗费精力重新构建那些在组织知识库中已存在的查询模板。

因此，对Text-to-SQL智能体最大的改进，就是赋予它人类工程师所拥有的“部落知识”。 这使得智能体能够复用已知有效的查询，并在运行时让模型检索已确立的使用模式。无论称之为检索增强生成(RAG)、智能体RAG还是动态上下文，其核心一致：让模型在运行时能够访问正确的上下文，从而生成准确的SQL。

我们的目标明确：

1. 为智能体提供在运行时检索正确上下文的工具（包括表结构、连接关系、历史查询、指标定义、常见陷阱）。
2. 基于已确立的使用模式生成SQL，避免猜测和重复造轮子。
3. 验证生成的SQL（语法可解析性、模式兼容性检查等）。
4. 执行SQL并“分析”结果，提供洞察而不仅仅是原始数据。
5. 捕获成功经验，以便在下一次运行时表现更好（例如，记录新的连接路径、修正的列映射、查询模板、指标定义）。
6. 不断重复并优化这一过程。

2. 理解“动态上下文”的价值

动态上下文是指：智能体在响应用户查询时，实时检索相关的知识片段，并基于这些已确立的使用模式来生成SQL。其“动态”特性体现在上下文会根据当前查询的具体内容、数据状态及用户意图而变化。

智能体可以检索的上下文示例包括：

• 表结构定义与表间关系。
• 常用的连接键和关联路径。
• 针对常见业务场景的已知查询模板。
• 关键指标的定义与业务规则。
• 已知的易错点提示（例如：“注意，状态字段在orders.state中”）。

如果知识库中已存在关于“计算每周活跃用户”的成熟查询，你的智能体应当直接检索并复用它，而非重新构建。

3. “持续学习”的务实实现方案

这里提出的“持续学习”是一种务实方案，其特点是：

• 我们不更新底层大语言模型的权重参数。
• 我们更新的是检索知识库中的内容，每当系统产生一个成功的结果，便将其转化为可重用的知识资产。
• 系统通过将经验固化为可检索的工件来实现自我改进。

每一次成功的查询都会成为未来的参考上下文，每一个被纠正的错误都会形成一条避免再次发生的规则，每一次用户澄清都会转化为共享知识。这种方式之所以有效，是因为它构建了一个稳健的学习循环：在线服务行为保持稳定，而改进在受控的知识库层面进行。最大的优势在于，你可以随时手动审查和修正知识库中的条目，这远比直接调整模型权重要简单和安全。

4. 系统架构设计概览

整个系统分为两个核心部分，协同工作：

1. Text-to-SQL智能体：负责在线响应用户问题，通过检索知识库中的架构和查询模式（动态上下文）来生成并执行SQL。
2. 持续学习模块：负责从成功的查询运行中学习，并将新的知识条目添加到知识库中。

核心查询流程

1. 用户提问。
2. 智能体检索上下文：从知识库中进行混合搜索，搜索依据包括：
   • 用户问题文本。
   • 检测到的实体（如表名、列名、指标名）。
   • 可选的数据库自省结果。
3. 增强输入：将检索到的知识片段（如查询模式、规则和约束）作为动态上下文注入给大语言模型。
4. 生成SQL：模型在上下文的指导下生成SQL语句。
5. 安全执行：智能体在预设的安全环境中执行生成的SQL。
6. 分析与返回：智能体分析查询结果，并向用户返回答案和洞察。
7. 学习与存储：如果查询成功，智能体可询问用户是否将此次查询保存至知识库。若用户同意，则存储；若不同意或有误，则智能体重新审视并优化查询后再次尝试。

对于学习路径，可以考虑两项优化：

1. 将持续学习作为独立于在线智能体的异步任务运行，确保知识库能持续与最新的查询和结果同步。
2. 为持续学习模块添加回归测试工具，在知识库更新前后进行测试，以确保变更不会破坏现有功能。

5. 知识库的结构化设计

一个高效的知识库应系统化地存储三类信息：

1. 表信息：包括表结构、列元数据、查询规则、常见陷阱（例如，为日期列设置规则：“按日期过滤时请使用TO_DATE函数”）。
2. 示例查询：存储常见的查询模式与最佳实践，以及如何计算常用指标和KPI，避免重复工作。
3. 业务语义与关系：将组织内通用的业务术语映射到具体的数据库结构上。

在提供的示例代码库中，知识库包含以下结构化文件（表信息与常见查询）：

agents/sql/knowledge/
├── constructors_championship.json
├── drivers_championship.json
├── fastest_laps.json
├── race_results.json
├── race_wins.json
└── common_queries.sql

6. 生产就绪的实现方案

我们提供了一个可用于生产环境的实现，采用以下技术栈构建：

• 使用 FastAPI 构建应用程序来运行智能体服务，这是一个现代、高性能的Python Web框架。
• 使用 PostgreSQL 数据库存储会话、记忆和知识库条目。

项目仓库地址：https://github.com/agno-agi/agentos-railway，其中包含了完整的生产代码。

项目结构如下：

.
├── agents
│   ├── __init__.py
│   ├── sql
│   │   ├── __init__.py
│   │   ├── knowledge
│   │   ├── load_f1_data.py
│   │   ├── load_sql_knowledge.py
│   │   ├── sql_agent.py
│   │   └── test_questions.txt
│   └── ... more agents
├── app
│   ├── __init__.py
│   └── main.py
├── compose.yaml
├── db
│   └── ... database configuration
├── Dockerfile
├── pyproject.toml
├── railway.json
├── README.md
├── requirements.txt
├── scripts
│   ├── dev_setup.sh
│   ├── entrypoint.sh
│   ├── railway_up.sh
│   ├── format.sh
│   └── validate.sh
├── teams
│   └── finance_team.py
└── workflows
    └── research_workflow.py

7. 部署与运行步骤

1. 克隆代码仓库

git clone https://github.com/agno-agi/agentos-railway.git
cd agentos-railway

2. 配置API密钥

本智能体使用OpenAI模型。请设置必要的环境变量：

# 必需
export OPENAI_API_KEY="YOUR_API_KEY_HERE"
# 可选（用于其他智能体功能）
export ANTHROPIC_API_KEY="YOUR_API_KEY_HERE"
export PARALLEL_API_KEY="YOUR_API_KEY_HERE"

你可以复制项目中的 example.env 文件并重命名为 .env 来管理这些变量。

3. 安装Docker

我们将使用Docker在本地运行并部署应用。请确保已安装Docker Desktop或等效的Docker环境。

4. 在本地启动应用

使用Docker Compose构建并启动所有服务：

docker compose up --build -d

此命令将构建Docker镜像并启动以下服务：

• FastAPI应用：运行在 http://localhost:8000。
• PostgreSQL数据库：用于存储智能体会话和知识，可通过 localhost:5432 访问。

启动后，你可以通过 http://localhost:8000/docs 访问交互式API文档。

5. 加载示例数据与知识库

为SQL智能体加载示例的F1赛事数据：

docker exec -it agentos-railway-agent-os-1 python -m agents.sql.load_f1_data

接着，将预定义的SQL知识填充到知识库：

docker exec -it agentos-railway-agent-os-1 python -m agents.sql.load_sql_knowledge

6. 连接前端管理界面（可选）

• 打开AgentOS UI (https://os.agno.com/)。
• 登录后，添加 http://localhost:8000 作为一个新的AgentOS后端，可命名为“Local AgentOS”。

7. 停止应用

完成测试后，使用以下命令停止并清理所有容器：

docker compose down

8. 部署至Railway平台（生产部署）

若需部署到生产环境，可遵循以下步骤使用Railway CLI：

1. 安装Railway CLI：

   brew install railway

2. 登录Railway：

   railway login

3. 执行部署脚本：

   ./scripts/railway_up.sh

该脚本将自动完成以下工作：

• 在Railway上创建新项目。
• 部署PgVector数据库服务。
• 构建并部署Docker镜像。
• 配置必要的环境变量。
• 为你的服务生成一个可公开访问的域名。