Text-to-SQL总失败？我搞了个能自动学习的AI，效果惊了！

前言

大家好，我是倔强青铜三。欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！

本文将展示如何构建一个自我提升的 Text-to-SQL 智能体，它利用动态上下文和“穷人的持续学习”来回答问题。我们将问题分为两部分：

• Text-to-SQL 智能体（在线路径）：通过从知识库中检索架构和查询模式（动态上下文）来回答问题。
• 持续学习（离线路径）：从成功的运行中学习，并将新条目添加到知识库中。

当智能体找到一个成功的结果时，它会将其存储在知识库中，供以后使用。这为 Text-to-SQL 智能体提供了一个自我提升的反馈循环，同时保持在线路径的稳定性。

1. Text-to-SQL 在实践中失败的原因

大多数 Text-to-SQL 智能体在实践中失败，是因为它们每次从头开始，描述表、列、查找连接键。每次都会重复同样的错误。

相比之下，高级分析师或数据工程师不会每次都从头开始。他们会利用部落知识和经验，挖掘过去的查询以找到正确的查询。一旦找到有用的查询，他们就会将其保存在知识库中，供以后参考。我们的 Text-to-SQL 智能体也是如此。

我发现，大多数 Text-to-SQL 的失败并非“模型很蠢”，而是“模型缺少上下文和部落知识”的问题。让我们看看常见的错误：

• 模型每次从头开始，描述表、列、查找连接键。每次都会重复同样的错误。
• 模型猜测列名、使用模式，或者不知道正确的连接键。
• 模型缺少领域定义（活跃用户、流失率、ARR 等），或者不知道正确的业务规则（例如：“状态在 orders.state 中，而不是 orders.status 中”）。
• 模型缺少常见的陷阱（日期格式错误、空值位置错误等）。
• 模型重新发明了已经存在于组织知识库中的查询。

你可以为 Text-to-SQL 智能体提供的最大改进是赋予它与人类工程师相同的部落知识。这使他们能够重用我们知道有效的查询，并在运行时让模型搜索已建立的使用模式。 称之为 RAG、智能体 RAG 或动态上下文，都是一样的：模型在运行时可以访问正确的上下文以生成正确的 SQL。

我们的目标很明确：

1. 给我们的智能体提供在运行时检索正确上下文的工具（架构、连接、过去的查询、指标定义、陷阱）。
2. 生成基于已建立使用模式的 SQL（不猜测，不重新发明轮子）。
3. 验证 SQL（查询可解析、架构检查等）。
4. 运行 SQL 并“分析”结果。不要只给我数据，给我洞察。
5. 捕获学习内容，以便下次运行更好（新的连接路径、修正的列映射、查询模板、指标定义）。
6. 重复。

2. 什么是“动态上下文”

动态上下文就是：智能体在查询时检索相关的知识，这使它能够基于已建立的使用模式生成 SQL。上下文是动态的，因为它会根据查询、数据和用户的意图而变化。

智能体可以检索的例子包括：

• 表架构和关系。
• 常见的连接键和关系。
• 常见用例的已知查询。
• 指标定义和业务规则。
• 已知的陷阱（“状态在 orders.state 中，而不是 orders.status 中”）。

如果你的知识库中有“每周活跃用户”的查询，你的智能体应该检索它，而不是重新发明它。

3. 什么是“穷人的持续学习”（以及为什么它有效）

“穷人的持续学习”意味着：

• 我们不更新模型权重。
• 我们更新检索知识，当我们找到一个成功的结果时。
• 系统通过将经验作为可重用的工件捕获来改进。

每个好的查询都成为未来的上下文。 每个错误都成为一条规则。 每次澄清都成为共享知识。

穷人的持续学习之所以有效，是因为它提供了一个务实的学习循环：稳定的在线行为，受控的改进。最好的部分是，你总是可以手动探索知识库并修复问题或错误，想象一下手动更新模型权重。

4. 统一智能体架构

系统分为两部分：

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

查询流程

1. 用户提问
2. 智能体从 KB（混合搜索）中检索上下文，使用：

• 问题文本。
• 检测到的实体（表、列、指标）。
• 可选的数据库内省结果。
• 这些知识通过动态上下文增强输入：
• 检索到的知识片段。
• 规则和约束（只读、限制等）。
• 这些知识指导 SQL 的生成。
• 智能体在安全环境中执行查询。
• 智能体分析结果并返回答案。
• 如果结果成功，智能体询问用户是否希望将查询保存到知识库中。
• 如果用户同意，智能体将查询存储在知识库中。
• 如果用户不同意，智能体重新审视查询，更新它并再次尝试。

你可以对学习路径进行两项改进：

1. 在每次运行 Text-to-SQL 智能体后单独运行持续学习。这样，持续学习始终与最新的查询和结果保持同步。
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 应用程序运行我们的智能体。
• 使用 Postgres 数据库存储会话、记忆和知识。

这里是 仓库(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. 运行自己的 Text-to-SQL 智能体的步骤

克隆仓库

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

配置 API 密钥

我们将使用 OpenAI 作为 Text-to-SQL 智能体（我们还在服务中为其他智能体使用 Anthropic 和 Parallel Search）。请导出以下环境变量：

# 必需
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 以开始。

安装 Docker

我们将使用 Docker 在本地运行应用程序并将其部署到 Railway。如果需要，请安装 Docker Desktop (https://www.docker.com/products/docker-desktop)。

在本地运行应用程序

使用 docker compose 运行应用程序：

docker compose up --build -d

此命令构建 Docker 镜像并启动应用程序：

• FastAPI 应用程序，运行在 localhost:8000 上。
• PostgreSQL 数据库，用于存储智能体会话、知识和记忆，可通过 localhost:5432 访问。

启动后，你可以：

• 在 localhost:8000/docs 查看 FastAPI 应用程序。

加载 SQL 智能体的数据

要加载 SQL 智能体的数据，请运行：

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

要填充知识库，请运行：

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

将 AgentOS UI 连接到 FastAPI 应用程序

• 打开 AgentOS UI (https://os.agno.com/)
• 登录并添加 http://localhost:8000 作为一个新的 AgentOS。你可以将其命名为 Local AgentOS（或你喜欢的任何名称）。

演示

演示视频地址：https://www.ashpreetbedi.com/videos/sql-agent-demo.mp4

这是一个 Text-to-SQL 智能体的演示。注意我如何将一个查询添加到知识库中，当再次提出相同的问题时，智能体使用它来生成 SQL。

停止应用程序

完成后，使用以下命令停止应用程序：

docker compose down

将应用程序部署到 Railway

要将应用程序部署到 Railway，请运行以下命令：

1. 安装 Railway CLI：

brew install railway

1. 登录到 Railway：

railway login

1. 部署应用程序：

./scripts/railway_up.sh

此命令将：

• 创建一个 Railway 项目。
• 将 PgVector 数据库服务部署到你的 Railway 项目中。
• 构建并部署 Docker 镜像到你的 Railway 项目。
• 设置 AgentOS 服务中的环境变量。
• 为你的 AgentOS 服务创建一个新的域名。