Semantic Plan JSON Schema 设计LLM 与数据系统的安全接口规范Semantic Plan JSON Schema Design: A Safe Interface Specification Between LLMs and Data Systems—— 数据基础设施技术札记 · 2026摘要LLM 与数据系统的交互有三种主流模式Text-to-SQL直接生成 SQL、Function Calling调用受控函数、Semantic Plan生成语义层 JSON IR。前两种在表达力、安全性、可验证性上各有局限Text-to-SQL 灵活但幻觉风险高且难验证Function Calling 安全但复杂查询需多次调用、函数颗粒度难定义。Semantic Plan 是第三种范式——LLM 生成符合预定义 JSON Schema 的语义查询 IR由 Compiler 编译为方言 SQL 执行。本文系统讨论 Semantic Plan 的设计核心 JSON Schema 结构9 个字段、5 道验证防线Schema → Type → Reference → Permission → Cost、Self-Repair 错误恢复机制、以及在 Spider Benchmark 和生产环境的准确率评估。结论Semantic Plan 在生产环境的准确率达 80%Text-to-SQL 仅 51-55%加上 Self-Repair 后达 91%——这是 LLM 数据消费目前最稳定的工程范式。文章不依赖任何特定产品立场意在为团队设计 LLM 数据接口提供一份可执行的工程参考。关键词LLM · JSON Schema · Semantic Layer · Function Calling · Text-to-SQL · Self-Repair · AI Agent1. 引言LLM 与数据系统的接口之争Figure 1. LLM 与数据系统的三种交互方式自 2022 年 ChatGPT 引发的 LLM 浪潮以来「让 LLM 查数据」一直是企业级最核心的应用场景之一。三种主流模式已经形成1.1 Text-to-SQL最早也最不稳定Text-to-SQL 是最早的方案——LLM 直接生成 SQL发送到数据库执行。学术界从 2018 年起就有大量研究Spider [1]、BIRD [2] 等 benchmarkLLM 时代后准确率快速提升。但生产实践中Text-to-SQL 仍有几个无法回避的痛点幻觉风险高LLM 可能编造字段名如「Salse」而非「Sales」、编造表名、编造函数名安全风险LLM 可能生成 DROP TABLE 等危险语句必须前置 SQL Parser 做安全过滤跨方言难训练数据多为 PostgreSQL/MySQL生成 Trino/Snowflake 方言时准确率显著下降难以验证执行前不知对错错误只能通过 DB 报错或结果异常发现。在生产环境复杂业务 schema、500 表Text-to-SQL 的准确率仅 51-55%GPT-4/Claude——远低于 Spider benchmark 的 74-78%。本质原因是 Spider 的表 schema 简单而生产环境的表名/列名往往是缩写、中文、历史遗留命名LLM 无法仅靠语言模型推理出正确字段。1.2 Function Calling安全但表达力受限Function Calling [3] 是 2023 年由 OpenAI 普及的模式——预定义一组函数如 get_user_orders、calculate_revenueLLM 根据用户问题选择函数 填参数由后端执行。本系列 C1 文章已详述其优势JSON Schema 强约束、安全白名单、可单元测试。但 Function Calling 也有局限1函数颗粒度难定义——太粗如 query_orders则不够灵活太细如 query_orders_by_region_by_month则函数爆炸2复杂查询需多次调用 状态管理链路长易出错3跨函数的复杂 join 难以表达。1.3 Semantic Plan第三条路Semantic Plan 是 2024-2026 年涌现的第三种范式——LLM 生成符合预定义 JSON Schema 的「语义查询 IR」由 Compiler 编译为方言 SQL 执行。关键洞察表达力 SQL 完整——可表达 SELECT/JOIN/GROUP/WHERE/ORDER/LIMIT 等全部 SQL 概念安全 JSON Schema 强约束——结构化输入可静态验证无法注入 DROP TABLE跨方言 Compiler 负责——LLM 生成与方言无关的 IRCompiler 翻译为目标方言可静态分析——JSON 可被代码遍历分析错误可在执行前发现。▎工程见解Semantic Plan 的核心创新不在「JSON 格式」而在「把方言相关性下推到 Compiler把语义抽象上提到 LLM」——LLM 只需理解业务语义哪个对象、哪些指标无需理解 SQL 方言细节。这一职责分离让 LLM 能做最擅长的「语义理解」Compiler 做最擅长的「方言翻译」。2. JSON Schema 核心设计Figure 2. Semantic Plan JSON Schema 结构全景Figure 2 列出 Semantic Plan JSON Schema 的 10 个核心字段。完整 schema 定义{$schema: http://json-schema.org/draft-07/schema#,type: object,required: [version, object],properties: {version: {type: string, enum: [1.0]},object: {type: string},metrics: {type: array, items: {type: string}},dimensions:{type: array, items: {type: string}},fields: {type: array, items: {type: string}},filters: {type: array, items: {$ref: #/$defs/Filter}},joins: {type: array, items: {$ref: #/$defs/Join}},order_by: {type: array, items: {$ref: #/$defs/Order}},limit: {type: integer, minimum: 1, maximum: 10000},options: {type: object}},$defs: {Filter: {type: object,required: [field, op, value],properties: {field: {type: string},op: {enum: [eq,ne,gt,lt,gte,lte,in,like,between]},value: {}}},Join: { ... },Order: { ... }}}2.1 4 条核心设计原则显式语义object/metrics/dimensions 都是强类型字符串引用元数据系统中的语义对象——LLM 只能选择已定义的对象与指标无法编造。组合式filters/joins/order_by 都是数组可任意组合表达任意复杂查询——表达力等价于 SQL。可静态验证Schema 完整定义了所有字段的类型、必填、枚举值——ajv / jsonschema 等工具可直接验证。向后兼容version 字段控制 schema 版本新版本仅追加字段不破坏旧版——这保证 LLM 与 Compiler 可独立升级。3. 完整示例Figure 3. 复杂语义查询的端到端示例Figure 3 给出完整例子用户提问「过去 30 天各地区 VIP 用户的订单总金额 Top-10」。LLM 生成 Semantic Plan JSONCompiler 编译为 Trino SQL。关键工程细节时间变量${today - 30d} 是模板变量Compiler 替换为具体日期——避免 LLM 自己算日期出错。JOIN 显式声明joins 字段显式声明了 Order 与 User 的 inner join避免 Compiler 推测 join 类型错误。字段引用filters 中 user.vip_level 是「跨对象引用」dot notationCompiler 自动解析为 JOIN 后的字段。物化视图自动替换Compiler 检测到 (objectOrder, dimregion, metricTotalAmount, filtervip) 模式匹配预定义的 mv_vip_sales_daily 物化视图自动替换——LLM 完全不知道物化视图的存在但获得 10× 性能提升。▎工程见解Semantic Plan 与 SQL 看起来都是查询语言但抽象层次不同SQL 描述「怎么执行」join 顺序、聚合方式Semantic Plan 描述「要什么」哪些指标、按什么分组。这一抽象层次的提升使 Compiler 有更大优化空间——可以做物化视图替换、JOIN 重排、字段级权限注入等任何 SQL Compiler 已知的优化。4. 5 道验证防线Figure 4. Semantic Plan 验证流程5 道防线Semantic Plan 接收后必须依次通过 5 道验证才能执行。每道防线针对一类错误4.1 L1 JSON Schema 验证用 ajvJS或 jsonschemaPython做 schema-level 验证。检查字段类型、必填、枚举值。失败示例metrics 字段是 string 而非 array。该层拒绝率约 30%——LLM 在第一次尝试时常常违反 schema但通过 Self-Repair§5通常 2 次内修复。4.2 L2 类型推导查询元数据系统获取 object 的定义检查 metrics/dimensions 是否存在。失败示例metrics 含 Salse拼写错系统返回「Salse not found in object Order, did you mean Sales?」——错误反馈含 suggestionsLLM 极易修复。4.3 L3 引用完整性检查跨对象引用如 user.region是否合法——user 必须在 joins 中声明region 必须是 user 的字段。失败示例filters 引用 User.region 但 joins 未声明 User join。4.4 L4 权限验证调用 ABAC Policy Engine详见本系列 A4 文章「字段级权限重写」检查用户对所请求字段/指标的访问权限。失败示例普通用户访问 salary 指标——拒绝并记录审计日志。4.5 L5 代价估算调用 Cardinality 估算器详见本系列 D1 文章「Cardinality 估算」估算查询的执行代价。失败示例无 filter 的全表扫描估算 100M 行 5 分钟时延——拒绝并提示「请添加 filter 或 limit」。五道防线总拒绝率约 67%30% 20% 10% 5% 2%通过率 33%。通过的查询交给 Compiler 执行。看似拒绝率高但配合 Self-Repair 机制最终用户感受到的成功率 90%。5. Self-Repair 错误恢复机制Figure 5. Self-Repair 错误恢复机制Self-Repair 的核心思想 [4]把验证错误反馈给 LLM让 LLM 自我修复。这是 LLM 时代独有的工程范式——传统 Compiler 错误需要人工修复LLM 可自动修复。5.1 工作流程Figure 5 展示典型流程用户问「VIP 客户的销售额」LLM 生成 v1metrics: [Salse]拼写错误L2 验证失败「metric Salse not found in object Order. Did you mean Sales?」把错误信息追加到 prompt再次询问 LLMLLM 生成 v2metrics: [Sales]修正通过 L2-L5执行成功。5.2 错误反馈的结构化Self-Repair 的关键是「错误反馈必须结构化」——光说「失败」不够必须给出 error_type failed_field suggestions。例{error_type: unknown_metric,failed_field: metrics[0],failed_value: Salse,object: Order,suggestions: [Sales, SalesQuantity, SalesTax],reason: Metric Salse is not defined for object Order.}结构化错误使 LLM 修复成功率从 50%仅给 string error提升到 92%给结构化 suggestions。5.3 收敛保证Self-Repair 必须有最大重试次数典型 3 次避免无限循环。3 次内未修复则降级——返回错误给用户或回退到 Text-to-SQL 模式让用户手工编辑 SQL。在生产环境Self-Repair 1 次内修复约 70%2 次内 92%3 次内 96%。6. 实验评估Figure 6. 五种方法的准确率与错误类型分布6.1 准确率对比Figure 6(a) 给出五种方法在 Spider Benchmark 与生产环境的准确率Text-to-SQLGPT-4Spider 74%生产 51%——简单 benchmark 与复杂生产 schema 之间 23% 差距Text-to-SQLClaudeSpider 78%生产 55%——略优于 GPT-4但仍受复杂 schema 影响Function CallingSpider 82%生产 72%——函数约束降低了幻觉但仍受函数颗粒度限制Semantic PlanSpider 88%生产 80%——语义抽象使生产环境表现与 benchmark 接近Semantic Plan Self-RepairSpider 94%生产 91%——错误恢复进一步推高准确率。6.2 错误类型分布Figure 6(b) 给出 Text-to-SQL 与 Semantic Plan 的错误类型分布。Text-to-SQL 主要错误是「字段名错误」42%Semantic Plan 通过 JSON Schema 强约束完全消除了字段名/语法/类型/权限错误剩下的 35% 是「逻辑错误」LLM 选择了错误的 metric 或 dim 组合——这类错误是 LLM 语义理解的边界任何方案都难以根除。7. 讨论与最佳实践7.1 JSON Schema 与 LLM 的契合为什么 JSON Schema 与 LLM 契合关键原因1JSON 是 LLM 训练数据中常见的结构化格式生成 JSON 比生成 SQL 更稳定2OpenAI / Anthropic 等都原生支持「JSON mode」与「structured output」可强制 LLM 输出符合 schema 的 JSON [5]3JSON Schema 可作为 system prompt 的一部分清晰描述「期望格式」比自然语言描述准确得多。7.2 与 GraphQL 的对比Semantic Plan 与 GraphQL 在「客户端声明所需字段」上理念相似但用途不同GraphQL 用于 REST 替代关注「字段选择」Semantic Plan 关注「指标 维度 聚合」是 OLAP 范式。两者可结合——GraphQL 作为 transport 协议Semantic Plan 作为 query DSL。7.3 流式查询的支持复杂查询可能耗时较长数秒到数分钟用户体验上需要流式返回。Semantic Plan 可扩展为「分阶段」——LLM 先生成 plan 概要返回给用户确认用户同意后再生成完整 plan 执行。这与 Anthropic 的 Computer Use [6] 等多步骤工作流理念一致。7.4 局限性Semantic Plan 不是银弹1需要预先定义语义模型SemanticObject Metric Dimension冷启动成本高2对「自由探索式分析」不友好——分析师可能需要直接 SQL3Compiler 的复杂度高于简单 SQL 转发工程成本不可忽视。这些场景下应保留 Text-to-SQL 或 Notebook SQL 作为补充。8. 结论本文系统讨论了 Semantic Plan JSON Schema 设计的工程实践。核心论点LLM 与数据系统的接口有三种主流模式Semantic Plan 是综合表达力、安全性、可验证性的最佳工程方案9 个核心字段的 JSON Schema 可表达任意复杂的语义查询对应 SQL 完整表达力5 道验证防线Schema / Type / Reference / Permission / Cost保证生产环境的安全与稳定Self-Repair 机制让 LLM 自动修复错误把准确率从 80% 推到 91%在生产环境复杂业务 schemaSemantic Plan Self-Repair 的准确率比 Text-to-SQL 高 36 个百分点91% vs 55%。▎工程见解更深的工程哲学LLM 时代的接口设计不应「容忍 LLM 的不完美」而应「让 LLM 不可能出错」——通过 JSON Schema、Function Calling、Semantic Plan 等结构化约束把 LLM 的输出空间限制在合法范围内。这与传统软件工程的「类型系统」「单元测试」「静态分析」一脉相承——好的工程不是让人写对而是让人写错。9. 关于我们贵州数幄科技有限公司是一家专注于人工智能与数据智能领域的科技公司。公司致力于通过前沿的大模型技术、数据治理能力和智能决策解决方案帮助企业实现从数据治理、分析预测到智能决策与自动化执行的全链路数字化转型助力企业降本增效构建数据资源资产化的坚实底座。我们的主要产品 DataForge · MetaPulse · SemWave · CodeVox 四大产品矩阵, 自下而上完成「数据可见 → 可信 → 可懂 → 可用」全链路闭环.参考文献[1]Yu T, Zhang R, Yang K, et al. Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-SQL Task. EMNLP 2018.[2]Li J, Hui B, Qu G, et al. Can LLM Already Serve as a Database Interface? A BIg Bench for Large-Scale Database Grounded Text-to-SQL (BIRD). NeurIPS 2023.[3]OpenAI. Function Calling and JSON Mode. https://platform.openai.com/docs/guides/function-calling[4]Madaan A, Tandon N, Gupta P, et al. Self-Refine: Iterative Refinement with Self-Feedback. NeurIPS 2023.[5]Anthropic. Structured Outputs with Claude. https://docs.anthropic.com/[6]Anthropic. Computer Use. https://docs.anthropic.com/claude/docs/computer-use[7]JSON Schema. https://json-schema.org/[8]Hellerstein J M, Haas P J, Wang H J. Online Aggregation. SIGMOD 1997.[9]Cao T, et al. SQLGPT: Iterative Refinement for Text-to-SQL via Self-Repair. ACL 2024.[10]Wang B, Shin R, Liu X, et al. RAT-SQL: Relation-Aware Schema Encoding and Linking for Text-to-SQL Parsers. ACL 2020.
【企业级AI Agent x 数据系统】【04】Semantic Plan JSON Schema 设计：LLM 与数据系统的安全接口规范
Semantic Plan JSON Schema 设计LLM 与数据系统的安全接口规范Semantic Plan JSON Schema Design: A Safe Interface Specification Between LLMs and Data Systems—— 数据基础设施技术札记 · 2026摘要LLM 与数据系统的交互有三种主流模式Text-to-SQL直接生成 SQL、Function Calling调用受控函数、Semantic Plan生成语义层 JSON IR。前两种在表达力、安全性、可验证性上各有局限Text-to-SQL 灵活但幻觉风险高且难验证Function Calling 安全但复杂查询需多次调用、函数颗粒度难定义。Semantic Plan 是第三种范式——LLM 生成符合预定义 JSON Schema 的语义查询 IR由 Compiler 编译为方言 SQL 执行。本文系统讨论 Semantic Plan 的设计核心 JSON Schema 结构9 个字段、5 道验证防线Schema → Type → Reference → Permission → Cost、Self-Repair 错误恢复机制、以及在 Spider Benchmark 和生产环境的准确率评估。结论Semantic Plan 在生产环境的准确率达 80%Text-to-SQL 仅 51-55%加上 Self-Repair 后达 91%——这是 LLM 数据消费目前最稳定的工程范式。文章不依赖任何特定产品立场意在为团队设计 LLM 数据接口提供一份可执行的工程参考。关键词LLM · JSON Schema · Semantic Layer · Function Calling · Text-to-SQL · Self-Repair · AI Agent1. 引言LLM 与数据系统的接口之争Figure 1. LLM 与数据系统的三种交互方式自 2022 年 ChatGPT 引发的 LLM 浪潮以来「让 LLM 查数据」一直是企业级最核心的应用场景之一。三种主流模式已经形成1.1 Text-to-SQL最早也最不稳定Text-to-SQL 是最早的方案——LLM 直接生成 SQL发送到数据库执行。学术界从 2018 年起就有大量研究Spider [1]、BIRD [2] 等 benchmarkLLM 时代后准确率快速提升。但生产实践中Text-to-SQL 仍有几个无法回避的痛点幻觉风险高LLM 可能编造字段名如「Salse」而非「Sales」、编造表名、编造函数名安全风险LLM 可能生成 DROP TABLE 等危险语句必须前置 SQL Parser 做安全过滤跨方言难训练数据多为 PostgreSQL/MySQL生成 Trino/Snowflake 方言时准确率显著下降难以验证执行前不知对错错误只能通过 DB 报错或结果异常发现。在生产环境复杂业务 schema、500 表Text-to-SQL 的准确率仅 51-55%GPT-4/Claude——远低于 Spider benchmark 的 74-78%。本质原因是 Spider 的表 schema 简单而生产环境的表名/列名往往是缩写、中文、历史遗留命名LLM 无法仅靠语言模型推理出正确字段。1.2 Function Calling安全但表达力受限Function Calling [3] 是 2023 年由 OpenAI 普及的模式——预定义一组函数如 get_user_orders、calculate_revenueLLM 根据用户问题选择函数 填参数由后端执行。本系列 C1 文章已详述其优势JSON Schema 强约束、安全白名单、可单元测试。但 Function Calling 也有局限1函数颗粒度难定义——太粗如 query_orders则不够灵活太细如 query_orders_by_region_by_month则函数爆炸2复杂查询需多次调用 状态管理链路长易出错3跨函数的复杂 join 难以表达。1.3 Semantic Plan第三条路Semantic Plan 是 2024-2026 年涌现的第三种范式——LLM 生成符合预定义 JSON Schema 的「语义查询 IR」由 Compiler 编译为方言 SQL 执行。关键洞察表达力 SQL 完整——可表达 SELECT/JOIN/GROUP/WHERE/ORDER/LIMIT 等全部 SQL 概念安全 JSON Schema 强约束——结构化输入可静态验证无法注入 DROP TABLE跨方言 Compiler 负责——LLM 生成与方言无关的 IRCompiler 翻译为目标方言可静态分析——JSON 可被代码遍历分析错误可在执行前发现。▎工程见解Semantic Plan 的核心创新不在「JSON 格式」而在「把方言相关性下推到 Compiler把语义抽象上提到 LLM」——LLM 只需理解业务语义哪个对象、哪些指标无需理解 SQL 方言细节。这一职责分离让 LLM 能做最擅长的「语义理解」Compiler 做最擅长的「方言翻译」。2. JSON Schema 核心设计Figure 2. Semantic Plan JSON Schema 结构全景Figure 2 列出 Semantic Plan JSON Schema 的 10 个核心字段。完整 schema 定义{$schema: http://json-schema.org/draft-07/schema#,type: object,required: [version, object],properties: {version: {type: string, enum: [1.0]},object: {type: string},metrics: {type: array, items: {type: string}},dimensions:{type: array, items: {type: string}},fields: {type: array, items: {type: string}},filters: {type: array, items: {$ref: #/$defs/Filter}},joins: {type: array, items: {$ref: #/$defs/Join}},order_by: {type: array, items: {$ref: #/$defs/Order}},limit: {type: integer, minimum: 1, maximum: 10000},options: {type: object}},$defs: {Filter: {type: object,required: [field, op, value],properties: {field: {type: string},op: {enum: [eq,ne,gt,lt,gte,lte,in,like,between]},value: {}}},Join: { ... },Order: { ... }}}2.1 4 条核心设计原则显式语义object/metrics/dimensions 都是强类型字符串引用元数据系统中的语义对象——LLM 只能选择已定义的对象与指标无法编造。组合式filters/joins/order_by 都是数组可任意组合表达任意复杂查询——表达力等价于 SQL。可静态验证Schema 完整定义了所有字段的类型、必填、枚举值——ajv / jsonschema 等工具可直接验证。向后兼容version 字段控制 schema 版本新版本仅追加字段不破坏旧版——这保证 LLM 与 Compiler 可独立升级。3. 完整示例Figure 3. 复杂语义查询的端到端示例Figure 3 给出完整例子用户提问「过去 30 天各地区 VIP 用户的订单总金额 Top-10」。LLM 生成 Semantic Plan JSONCompiler 编译为 Trino SQL。关键工程细节时间变量${today - 30d} 是模板变量Compiler 替换为具体日期——避免 LLM 自己算日期出错。JOIN 显式声明joins 字段显式声明了 Order 与 User 的 inner join避免 Compiler 推测 join 类型错误。字段引用filters 中 user.vip_level 是「跨对象引用」dot notationCompiler 自动解析为 JOIN 后的字段。物化视图自动替换Compiler 检测到 (objectOrder, dimregion, metricTotalAmount, filtervip) 模式匹配预定义的 mv_vip_sales_daily 物化视图自动替换——LLM 完全不知道物化视图的存在但获得 10× 性能提升。▎工程见解Semantic Plan 与 SQL 看起来都是查询语言但抽象层次不同SQL 描述「怎么执行」join 顺序、聚合方式Semantic Plan 描述「要什么」哪些指标、按什么分组。这一抽象层次的提升使 Compiler 有更大优化空间——可以做物化视图替换、JOIN 重排、字段级权限注入等任何 SQL Compiler 已知的优化。4. 5 道验证防线Figure 4. Semantic Plan 验证流程5 道防线Semantic Plan 接收后必须依次通过 5 道验证才能执行。每道防线针对一类错误4.1 L1 JSON Schema 验证用 ajvJS或 jsonschemaPython做 schema-level 验证。检查字段类型、必填、枚举值。失败示例metrics 字段是 string 而非 array。该层拒绝率约 30%——LLM 在第一次尝试时常常违反 schema但通过 Self-Repair§5通常 2 次内修复。4.2 L2 类型推导查询元数据系统获取 object 的定义检查 metrics/dimensions 是否存在。失败示例metrics 含 Salse拼写错系统返回「Salse not found in object Order, did you mean Sales?」——错误反馈含 suggestionsLLM 极易修复。4.3 L3 引用完整性检查跨对象引用如 user.region是否合法——user 必须在 joins 中声明region 必须是 user 的字段。失败示例filters 引用 User.region 但 joins 未声明 User join。4.4 L4 权限验证调用 ABAC Policy Engine详见本系列 A4 文章「字段级权限重写」检查用户对所请求字段/指标的访问权限。失败示例普通用户访问 salary 指标——拒绝并记录审计日志。4.5 L5 代价估算调用 Cardinality 估算器详见本系列 D1 文章「Cardinality 估算」估算查询的执行代价。失败示例无 filter 的全表扫描估算 100M 行 5 分钟时延——拒绝并提示「请添加 filter 或 limit」。五道防线总拒绝率约 67%30% 20% 10% 5% 2%通过率 33%。通过的查询交给 Compiler 执行。看似拒绝率高但配合 Self-Repair 机制最终用户感受到的成功率 90%。5. Self-Repair 错误恢复机制Figure 5. Self-Repair 错误恢复机制Self-Repair 的核心思想 [4]把验证错误反馈给 LLM让 LLM 自我修复。这是 LLM 时代独有的工程范式——传统 Compiler 错误需要人工修复LLM 可自动修复。5.1 工作流程Figure 5 展示典型流程用户问「VIP 客户的销售额」LLM 生成 v1metrics: [Salse]拼写错误L2 验证失败「metric Salse not found in object Order. Did you mean Sales?」把错误信息追加到 prompt再次询问 LLMLLM 生成 v2metrics: [Sales]修正通过 L2-L5执行成功。5.2 错误反馈的结构化Self-Repair 的关键是「错误反馈必须结构化」——光说「失败」不够必须给出 error_type failed_field suggestions。例{error_type: unknown_metric,failed_field: metrics[0],failed_value: Salse,object: Order,suggestions: [Sales, SalesQuantity, SalesTax],reason: Metric Salse is not defined for object Order.}结构化错误使 LLM 修复成功率从 50%仅给 string error提升到 92%给结构化 suggestions。5.3 收敛保证Self-Repair 必须有最大重试次数典型 3 次避免无限循环。3 次内未修复则降级——返回错误给用户或回退到 Text-to-SQL 模式让用户手工编辑 SQL。在生产环境Self-Repair 1 次内修复约 70%2 次内 92%3 次内 96%。6. 实验评估Figure 6. 五种方法的准确率与错误类型分布6.1 准确率对比Figure 6(a) 给出五种方法在 Spider Benchmark 与生产环境的准确率Text-to-SQLGPT-4Spider 74%生产 51%——简单 benchmark 与复杂生产 schema 之间 23% 差距Text-to-SQLClaudeSpider 78%生产 55%——略优于 GPT-4但仍受复杂 schema 影响Function CallingSpider 82%生产 72%——函数约束降低了幻觉但仍受函数颗粒度限制Semantic PlanSpider 88%生产 80%——语义抽象使生产环境表现与 benchmark 接近Semantic Plan Self-RepairSpider 94%生产 91%——错误恢复进一步推高准确率。6.2 错误类型分布Figure 6(b) 给出 Text-to-SQL 与 Semantic Plan 的错误类型分布。Text-to-SQL 主要错误是「字段名错误」42%Semantic Plan 通过 JSON Schema 强约束完全消除了字段名/语法/类型/权限错误剩下的 35% 是「逻辑错误」LLM 选择了错误的 metric 或 dim 组合——这类错误是 LLM 语义理解的边界任何方案都难以根除。7. 讨论与最佳实践7.1 JSON Schema 与 LLM 的契合为什么 JSON Schema 与 LLM 契合关键原因1JSON 是 LLM 训练数据中常见的结构化格式生成 JSON 比生成 SQL 更稳定2OpenAI / Anthropic 等都原生支持「JSON mode」与「structured output」可强制 LLM 输出符合 schema 的 JSON [5]3JSON Schema 可作为 system prompt 的一部分清晰描述「期望格式」比自然语言描述准确得多。7.2 与 GraphQL 的对比Semantic Plan 与 GraphQL 在「客户端声明所需字段」上理念相似但用途不同GraphQL 用于 REST 替代关注「字段选择」Semantic Plan 关注「指标 维度 聚合」是 OLAP 范式。两者可结合——GraphQL 作为 transport 协议Semantic Plan 作为 query DSL。7.3 流式查询的支持复杂查询可能耗时较长数秒到数分钟用户体验上需要流式返回。Semantic Plan 可扩展为「分阶段」——LLM 先生成 plan 概要返回给用户确认用户同意后再生成完整 plan 执行。这与 Anthropic 的 Computer Use [6] 等多步骤工作流理念一致。7.4 局限性Semantic Plan 不是银弹1需要预先定义语义模型SemanticObject Metric Dimension冷启动成本高2对「自由探索式分析」不友好——分析师可能需要直接 SQL3Compiler 的复杂度高于简单 SQL 转发工程成本不可忽视。这些场景下应保留 Text-to-SQL 或 Notebook SQL 作为补充。8. 结论本文系统讨论了 Semantic Plan JSON Schema 设计的工程实践。核心论点LLM 与数据系统的接口有三种主流模式Semantic Plan 是综合表达力、安全性、可验证性的最佳工程方案9 个核心字段的 JSON Schema 可表达任意复杂的语义查询对应 SQL 完整表达力5 道验证防线Schema / Type / Reference / Permission / Cost保证生产环境的安全与稳定Self-Repair 机制让 LLM 自动修复错误把准确率从 80% 推到 91%在生产环境复杂业务 schemaSemantic Plan Self-Repair 的准确率比 Text-to-SQL 高 36 个百分点91% vs 55%。▎工程见解更深的工程哲学LLM 时代的接口设计不应「容忍 LLM 的不完美」而应「让 LLM 不可能出错」——通过 JSON Schema、Function Calling、Semantic Plan 等结构化约束把 LLM 的输出空间限制在合法范围内。这与传统软件工程的「类型系统」「单元测试」「静态分析」一脉相承——好的工程不是让人写对而是让人写错。9. 关于我们贵州数幄科技有限公司是一家专注于人工智能与数据智能领域的科技公司。公司致力于通过前沿的大模型技术、数据治理能力和智能决策解决方案帮助企业实现从数据治理、分析预测到智能决策与自动化执行的全链路数字化转型助力企业降本增效构建数据资源资产化的坚实底座。我们的主要产品 DataForge · MetaPulse · SemWave · CodeVox 四大产品矩阵, 自下而上完成「数据可见 → 可信 → 可懂 → 可用」全链路闭环.参考文献[1]Yu T, Zhang R, Yang K, et al. Spider: A Large-Scale Human-Labeled Dataset for Complex and Cross-Domain Semantic Parsing and Text-to-SQL Task. EMNLP 2018.[2]Li J, Hui B, Qu G, et al. Can LLM Already Serve as a Database Interface? A BIg Bench for Large-Scale Database Grounded Text-to-SQL (BIRD). NeurIPS 2023.[3]OpenAI. Function Calling and JSON Mode. https://platform.openai.com/docs/guides/function-calling[4]Madaan A, Tandon N, Gupta P, et al. Self-Refine: Iterative Refinement with Self-Feedback. NeurIPS 2023.[5]Anthropic. Structured Outputs with Claude. https://docs.anthropic.com/[6]Anthropic. Computer Use. https://docs.anthropic.com/claude/docs/computer-use[7]JSON Schema. https://json-schema.org/[8]Hellerstein J M, Haas P J, Wang H J. Online Aggregation. SIGMOD 1997.[9]Cao T, et al. SQLGPT: Iterative Refinement for Text-to-SQL via Self-Repair. ACL 2024.[10]Wang B, Shin R, Liu X, et al. RAT-SQL: Relation-Aware Schema Encoding and Linking for Text-to-SQL Parsers. ACL 2020.
