ai-agent-book ERP Agent 怎么让 LLM 只生成 SQL 制品而由数据库执行查询

原创2026-09-09 09:41:231,832 阅读
文章标签:人工智能AI Agent教程

ai-agent-book ERP Agent 怎么让 LLM 只生成 SQL 制品而由数据库执行查询

如果你想让 LLM 回答业务数据问题,最脆弱的环节往往是让它“亲自取数再算”:几万行结果塞进上下文既费 token,大模型手算还容易出错。ai-agent-book 仓库(《深入理解 AI Agent:设计原理与工程实践》配套代码)第 5 章的实验 5-10(NL ERP Agent,chapter5/erp-agent/README.md)采用的是相反的分工:LLM 只输出一条可直接执行的 SQLite SELECT——一个“SQL 制品(artifact)”,真正的查询由系统交给数据库执行,结果表直接呈现。本文按该项目的真实代码走一遍:在 employees / salaries 两张表的可复现数据上,让 Agent 回答 10 个中文业务问题,并逐题用独立 Python 参考实现校验对错。

先看角色分工:谁生成 SQL,谁执行 SQL

整个项目只有 8 个核心文件,分工如下(均位于 chapter5/erp-agent/ 目录):

文件 作用
demo.py 命令行入口(run / gold / ask / initdb):建库、灌数据、跑题、执行 SQL、比对、打印通过率
agent.py NL→SQL Agent:构造 prompt、调用模型、清洗返回的 SQL
questions.py 10 个自然语言问题 + 给 Agent 的“返回列/业务口径”提示
seed.py 固定种子 42 的可复现数据生成 + 建表灌数
reference.py 10 题的独立 Python 参考实现(校验基准,不走 SQL)
gold.py 10 题人工编写的标准 SQL(SQLite 方言),供离线自检
env.example 环境变量模板(API Key、模型)

“LLM 只生成 SQL 制品”这一约束落在 agent.py 的系统提示词里,它给模型划了明确的边界:

  • 只输出一条可直接执行的 SQLite SELECT(可含 WITH/CTE),不解释、不要 markdown 代码块、不写多条语句或 DDL/DML;
  • 严禁硬编码年份(如 '2024'),一律用 strftime(...,'now',...) 从数据库当前日期推导,否则模型不知道“今天”是哪年,会把“前年/去年”猜错;
  • 业务口径写在提示里:「A部门」= 研发部、「B部门」= 销售部;「在职」= leave_date IS NULL;「今年」= strftime('%Y','now') 等;
  • 严格按用户附带的「返回列」要求组织 SELECT 的列与顺序(questions.py 每题的 hint 只给列名和顺序这类 schema 级提示,不泄露数值答案)。

模型输出还要经过 _clean_sql 清洗:剥掉可能残留的 ```sql 围栏和反引号,只留 SQL 本身,再交给数据库执行。

执行与校验都在系统侧完成。demo.py 的主循环对每道题做三步:取 SQL 制品(在线由 Agent 生成,离线取 gold.py 内置 SQL)→ 用 sqlite3 执行并打印结果表 → 把执行结果与 reference.py 的期望答案比对。比对按多重集合(忽略行顺序)+ 数值容差(保留 2 位小数、容差 0.1)进行,逐题打印 通过/不通过,最后给出总通过率。

准备环境

在仓库根目录用统一第 5 章环境安装依赖:

# 仓库根目录
uv sync --locked --python 3.12 --extra ch5

# 切换目录前先激活环境:
# macOS/Linux:
source .venv/bin/activate
# Windows PowerShell:.\.venv\Scripts\Activate.ps1
# Windows cmd:.venv\Scripts\activate.bat

# 未安装 uv 时可用 pip 兜底:
# python -m pip install -e ".[ch5]"

cd chapter5/erp-agent

迁移期间也仍支持单项目兼容路径:python -m pip install -r requirements.txt(见 chapter5/erp-agent/requirements.txt)。

需要在线跑 run / ask 时配置 API Key:

cp env.example .env      # 填入 OPENAI_API_KEY

两点说明:

  • 未配置 OPENAI_API_KEY 时,可改设 OPENROUTER_API_KEY 兜底,代码会自动把 gpt-* → openai/*、kimi-* → moonshotai/*、gemini-* → google/* 等映射后走 OpenRouter;映射不到的模型 id 按原名发出并由 OpenRouter 报错。
  • 默认模型 gpt-5.6-luna 属 gpt-5.x,直连 OpenAI 需组织实名认证,所以设置了 OPENROUTER_API_KEY 时优先走 OpenRouter。换模型用 --model 参数或 OPENAI_MODEL 环境变量。

只做离线部分(gold、initdb)不需要任何 API Key。

第一步:离线自检,先证明数据模型自洽

在线调用模型前,先跑不需要 API 的 gold 子命令。它执行 gold.py 里 10 条人工编写的标准 SQL,再与 Python 参考实现比对:

python demo.py gold                 # 离线跑通 10 题,无需 API

流程是:建 SQLite 内存库(默认 --db :memory:,每次重新灌入种子数据,保证可复现)→ 逐题执行 gold SQL → 打印问题、SQL、结果、是否通过 → 输出总通过率。

判定方式:每道题打印 校验:通过 ✓ 或 校验:不通过 ✗(原因),结尾打印 总通过率:passed/total。文档记录的最近一次真实运行,离线 gold 为 10/10。这一步的意义是:不经过 LLM 就能证明「schema + 种子数据 + 参考实现」这套数据模型本身自洽、可查询——如果 gold 都通不过,说明问题出在数据或参考实现,而不是模型。

第二步:在线运行,让 Agent 生成 SQL 并校验

python demo.py(不带子命令)等价于 run:Agent 对 10 个中文问题逐题生成 SQL → 数据库执行 → 与参考实现比对,最后给出总通过率。

python demo.py                       # 在线跑全部 10 题
python demo.py run --only 2,3,6      # 只跑第 2、3、6 题
python demo.py run --model gpt-5.6-luna --output result.json

常用参数:--only 1,5,10 只跑指定题号;--db erp.db 用文件库而非内存库;--model 覆盖模型(默认读 OPENAI_MODEL,否则 gpt-5.6-luna);--output result.json 把逐题明细(问题、生成的 SQL、结果行、是否通过)导出为 JSON;--max-rows 控制每题结果表最多打印多少行(默认 12)。

每道题的终端输出形如:【问题 N】+ 生成的 SQL + 查询结果表 + 校验:通过/不通过,全部跑完后打印 总通过率:X/10 (XX%)。文档记录最近一次真实在线运行(gpt-5.6-luna)稳定 10/10,可作为参考基准,但 LLM 并非严格确定性,个别题偶发偏差时重跑即可,或设 OPENAI_MODEL 换更强的模型。

第三步:用 ask 子命令做单条自然语言查询

如果你只想验证“一个中文问题 → 一条 SQL → 结果表”这条最短路径,用 ask:

python demo.py ask "研发部现在有多少在职员工?"

它会建库灌数 → 让 Agent 生成 SQL → 执行并打印结果表(结果表默认最多打印 20 行,--max-rows 可调)。可选 --hint 参数补充业务口径或期望返回列,不提供时默认提示为“自行判断需要返回的列;只输出一条 SELECT”。生成失败会打印 [Agent 生成 SQL 失败],执行失败会打印 [SQL 执行出错],两者都会以非零码退出。

可选:把数据库落成文件手工查看

initdb 会把表结构和种子数据写进一个 SQLite 文件,便于用 sqlite3 手工核对数据,再用 --db 让离线复跑走同一个文件:

python demo.py initdb --db erp.db
sqlite3 erp.db "SELECT * FROM employees LIMIT 5;"
python demo.py gold --db erp.db

注意副作用:initdb 遇到已存在的同名文件会先删除再重建(demo.py 中 os.remove),所以不要把 --db 指向有保留数据的文件;它也不接受默认的 :memory:,必须给文件路径。

种子数据由 seed.py 以固定随机种子 42、相对「今天」生成:约 40 名员工跨 5 个部门、多级别,含若干已离职者;工资按「入职基准 + 每年固定涨薪额」逐月生成,每人涨薪额互不相同(保证问题 9 的排名唯一);并刻意为一名在职员工删掉某月工资(制造问题 10 的「拖欠」)。因为数据可完全复现,run 的校验结果才有稳定的比对基准。

结果怎么判定,不通过时看什么

  • 判定逻辑:每题的 SQL 执行结果与 reference.py 的答案做多重集合比对(忽略行顺序),数值带 0.1 容差;行数不一致或缺少匹配行都会判不通过,并打印 参考期望:... 前 12 行,方便对照。
  • 离线 10/10、在线不通过:说明数据模型自洽,问题出在模型生成的 SQL 上。先重跑一次(LLM 非确定性);仍偏差就用 --only 锁定题号复现,并用 --output 导出逐题 SQL 对照 gold.py 里对应题的标准写法找差异。
  • 复杂题:问题 8(工龄分档 + 最近一月工资)和问题 10(递归 CTE 生成在职月份找空缺)最难,questions.py 的 hint 里已给出推荐的 SQL 结构模板,帮助较小模型稳定产出。

迁移到 PostgreSQL 时的差异

本实验用 SQLite(零依赖、可直接复现),书中示例用 PostgreSQL。SQL 大体通用,差异主要在日期函数:本项目用 strftime('%Y','now')、julianday()、date('now','-1 year') 等;迁到 Postgres 时对应换成 EXTRACT(YEAR FROM now())、AGE() / 日期相减、now() - interval '1 year' 等。真实 Postgres 的建表 DDL 见 chapter5/erp-agent/schema_postgres.sql。

参考文件

登录后查看全文
ai-agent-book