企业官网建设流程全解析

Semantic Plan JSON Schema 设计：LLM 与数据系统的安全接口规范

Semantic Plan JSON Schema Design: A Safe Interface Specification Between LLMs and Data Systems

—— 数据基础设施技术札记 · 2026

关键词：LLM · JSON Schema · Semantic Layer · Function Calling · Text-to-SQL · Self-Repair · AI Agent

1. 引言：LLM 与数据系统的接口之争

Figure 1. LLM 与数据系统的三种交互方式

自 2022 年 ChatGPT 引发的 LLM 浪潮以来，「让 LLM 查数据」一直是企业级最核心的应用场景之一。三种主流模式已经形成：

1.1 Text-to-SQL：最早也最不稳定

Text-to-SQL 是最早的方案——LLM 直接生成 SQL，发送到数据库执行。学术界从 2018 年起就有大量研究（Spider [1]、BIRD [2] 等 benchmark），LLM 时代后准确率快速提升。但生产实践中，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_revenue），LLM 根据用户问题选择函数 + 填参数，由后端执行。本系列 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 生成与方言无关的 IR，Compiler 翻译为目标方言；
• 可静态分析——JSON 可被代码遍历分析，错误可在执行前发现。

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 JSON，Compiler 编译为 Trino SQL。

关键工程细节：

• 时间变量：${today - 30d} 是模板变量，Compiler 替换为具体日期——避免 LLM 自己算日期出错。
• JOIN 显式声明：joins 字段显式声明了 Order 与 User 的 inner join，避免 Compiler 推测 join 类型错误。
• 字段引用：filters 中 user.vip_level 是「跨对象引用」（dot notation），Compiler 自动解析为 JOIN 后的字段。
• 物化视图自动替换：Compiler 检测到 (object=Order, dim=region, metric=TotalAmount, filter=vip) 模式匹配预定义的 mv_vip_sales_daily 物化视图，自动替换——LLM 完全不知道物化视图的存在，但获得 10× 性能提升。

4. 5 道验证防线

Figure 4. Semantic Plan 验证流程：5 道防线

Semantic Plan 接收后必须依次通过 5 道验证才能执行。每道防线针对一类错误：

4.1 L1 JSON Schema 验证

用 ajv（JS）或 jsonschema（Python）做 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'?」——错误反馈含 suggestions，LLM 极易修复。

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 生成 v1：metrics: ['Salse']（拼写错误）；
• L2 验证失败：「metric 'Salse' not found in object 'Order'. Did you mean 'Sales'?」；
• 把错误信息追加到 prompt，再次询问 LLM；
• LLM 生成 v2：metrics: ['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-SQL（GPT-4）：Spider 74%，生产 51%——简单 benchmark 与复杂生产 schema 之间 23% 差距；
• Text-to-SQL（Claude）：Spider 78%，生产 55%——略优于 GPT-4，但仍受复杂 schema 影响；
• Function Calling：Spider 82%，生产 72%——函数约束降低了幻觉，但仍受函数颗粒度限制；
• Semantic Plan：Spider 88%，生产 80%——语义抽象使生产环境表现与 benchmark 接近；
• Semantic Plan + Self-Repair：Spider 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 契合？关键原因：（1）JSON 是 LLM 训练数据中常见的结构化格式，生成 JSON 比生成 SQL 更稳定；（2）OpenAI / Anthropic 等都原生支持「JSON mode」与「structured output」，可强制 LLM 输出符合 schema 的 JSON [5]；（3）JSON 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）对「自由探索式分析」不友好——分析师可能需要直接 SQL；（3）Compiler 的复杂度高于简单 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%；
• 在生产环境（复杂业务 schema），Semantic Plan + Self-Repair 的准确率比 Text-to-SQL 高 36 个百分点（91% vs 55%）。

参考文献

[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.