前言
大家好，我是倔强青铜三。欢迎关注我，微信公众号：倔强青铜三。欢迎点赞、收藏、关注，一键三连！！！
本文将展示如何构建一个自我提升的 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。
我们的目标很明确：
-
给我们的智能体提供在运行时检索正确上下文的工具（架构、连接、过去的查询、指标定义、陷阱）。 -
生成基于已建立使用模式的 SQL（不猜测，不重新发明轮子）。 -
验证 SQL（查询可解析、架构检查等）。 -
运行 SQL 并“分析”结果。不要只给我数据，给我洞察。 -
捕获学习内容，以便下次运行更好（新的连接路径、修正的列映射、查询模板、指标定义）。 -
重复。
2. 什么是“动态上下文”
动态上下文就是：智能体在查询时检索相关的知识，这使它能够基于已建立的使用模式生成 SQL。上下文是动态的，因为它会根据查询、数据和用户的意图而变化。
智能体可以检索的例子包括：
-
表架构和关系。 -
常见的连接键和关系。 -
常见用例的已知查询。 -
指标定义和业务规则。 -
已知的陷阱（“状态在 orders.state 中，而不是 orders.status 中”）。
如果你的知识库中有“每周活跃用户”的查询，你的智能体应该检索它，而不是重新发明它。
3. 什么是“穷人的持续学习”（以及为什么它有效）
“穷人的持续学习”意味着：
-
我们不更新模型权重。 -
我们更新检索知识，当我们找到一个成功的结果时。 -
系统通过将经验作为可重用的工件捕获来改进。
每个好的查询都成为未来的上下文。 每个错误都成为一条规则。 每次澄清都成为共享知识。
穷人的持续学习之所以有效，是因为它提供了一个务实的学习循环：稳定的在线行为，受控的改进。最好的部分是，你总是可以手动探索知识库并修复问题或错误，想象一下手动更新模型权重。
4. 统一智能体架构
系统分为两部分：
-
Text-to-SQL 智能体：通过从知识库中检索架构和查询模式（动态上下文）来回答问题。 -
持续学习：从成功的运行中学习，并将新条目添加到知识库中。
查询流程
-
用户提问 -
智能体从 KB（混合搜索）中检索上下文，使用：
-
问题文本。 -
检测到的实体（表、列、指标）。 -
可选的数据库内省结果。 -
这些知识通过动态上下文增强输入： -
检索到的知识片段。 -
规则和约束（只读、限制等）。 -
这些知识指导 SQL 的生成。 -
智能体在安全环境中执行查询。 -
智能体分析结果并返回答案。 -
如果结果成功，智能体询问用户是否希望将查询保存到知识库中。 -
如果用户同意，智能体将查询存储在知识库中。 -
如果用户不同意，智能体重新审视查询，更新它并再次尝试。
你可以对学习路径进行两项改进：
-
在每次运行 Text-to-SQL 智能体后单独运行持续学习。这样，持续学习始终与最新的查询和结果保持同步。 -
为持续学习添加回归工具。这样，你可以在更新前后测试知识库，以确保它仍然有效。
5. 知识库设计（保持结构化）
我们希望知识库存储三种信息：
-
表信息：包括表架构、列元数据、查询规则、常见陷阱（例如：日期列包含一条规则：“在按日期过滤时使用 TO_DATE函数”）。 -
示例查询：包括常见的查询模式和最佳实践。以及如何检索常见的指标和 KPI。无需重新发明轮子。 -
业务语义和关系：将你的组织谈论数据的方式映射到数据库的结构。
我提供的示例代码库包含以下文件（表信息和常见查询）：
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，请运行以下命令：
-
安装 Railway CLI：
brew install railway
-
登录到 Railway：
railway login
-
部署应用程序：
./scripts/railway_up.sh
此命令将：
-
创建一个 Railway 项目。 -
将 PgVector 数据库服务部署到你的 Railway 项目中。 -
构建并部署 Docker 镜像到你的 Railway 项目。 -
设置 AgentOS 服务中的环境变量。 -
为你的 AgentOS 服务创建一个新的域名。
