NVIDIA Auto Ontology:让 agent 先证明能回答,再写 SQL
NVIDIA Auto Ontology:让 agent 先证明能回答,再写 SQL
agent 分析数据,答得快但答错了等于零。这个项目把"对不对"放在"快不快"前面。
让 LLM 直接对着数据库 schema 写 SQL,最大的问题不是写不出来,是写出来你不敢信:同一个"收入",五张表有五种口径,agent 挑了哪张、join 路径对不对、过滤条件合不合理,全凭模型一次发挥。NVIDIA/auto-ontology 想在数据库和 agent 之间插一层可认证的语义本体,把"数据在哪、什么意思、该不该用、怎么用、从哪来"变成显式管理的对象。
这个仓库 2026-04-27 才创建,到 2026-11-10 半年时间攒了 10,153 star、821 fork、87 个未关闭 issue,Apache-2.0 协议,Python 后端版本 1.1.0,最后一次代码推送在 2026-11-07。我通读了 README、AGENTS.md、pyproject.toml 和后端模块结构,按四个问题展开:它是什么、怎么跑起来、哪些设计值得做 agent 数据层的人参考、以及它和 Vanna、WrenAI、dbt 这些现有方案怎么分工。
本文提纲
- 是什么:agent 的语义上下文层,不是又一个 text-to-SQL
- 怎么用:Compose 起步、模型三元组、MCP 与 agent skills
- 值得学习的四个设计
- 同类比较:Vanna、WrenAI、dbt Semantic Layer、GraphRAG 怎么选
是什么:agent 的语义上下文层,不是又一个 text-to-SQL
一句话定位:Auto Ontology 是一个从企业元数据自动构建语义本体(ontology)的 Python 框架,本体存成图结构放在 Postgres 里,agent 通过 MCP、CLI 或 API 查询这层上下文,再生成可验证的 SQL。它不是 text-to-SQL 工具本身,text-to-SQL 只是这层本体的消费方式之一;它也不是向量数据库,pgvector 在里面只承担检索;更不是 BI 仪表盘,它没有自己的可视化产品定位,Web UI 是给建模和认证用的。
README 开头把问题定义得很直接:agent 能检索文档、能查数据库,但卡住 agentic analytics 的是可靠性,一个收入指标答错了,再快也没有价值。它的工作流分三个阶段,人的位置被刻意安排在中间:
flowchart LR
DB[("Relational sources
Postgres / Snowflake /
Databricks / MySQL / Trino")]:::blue
ING["Ingestion service
profile, extract terms,
infer joins + embeddings"]:::teal
ONT[("Ontology in Postgres
Terms + SQL attributes
+ Relationships + pgvector")]:::sage
HUMAN["Human certification
review, refine, certify"]:::yellow
AGENT["Agent via MCP / API
answerability check,
validated NL-to-SQL"]:::red
DB --> ING --> ONT
ONT --> HUMAN
HUMAN -->|certified definitions| ONT
ONT --> AGENT
AGENT -->|SQL + steps + provenance| USER["Chat answer"]:::mint
classDef red fill:#FF6B6B,stroke:#764ba2,color:#000
classDef teal fill:#4ECDC4,stroke:#764ba2,color:#000
classDef blue fill:#45B7D1,stroke:#764ba2,color:#000
classDef sage fill:#96CEB4,stroke:#764ba2,color:#000
classDef yellow fill:#FFEAA7,stroke:#764ba2,color:#000
classDef mint fill:#98D8C8,stroke:#764ba2,color:#000本体里装三类定义,这个划分是理解整个项目的钥匙。第一类是 Terms,业务概念比如 Customer、Invoice Line,带描述、同义词,映射到具体的列。第二类是 SQL attributes,挂在 term 下面、经过人工审核的 SQL 表达式,比如毛利率、滚动合计,agent 每次算同一个指标都复用同一段表达式。第三类是 Relationships,表和表怎么 join,包括桥接表,从主键外键和数据分布推断出来。
实际部署是五个协作的服务,不是一个能 pip install 完就 import 的轻量库:
| 组件 | 技术 | 职责 | 端口 |
|---|---|---|---|
| Frontend | Next.js 16、React 19、Better Auth、Prisma | Web UI、认证、API 网关 | 3000 |
| Backend | FastAPI、Python 3.12+、LangChain、LangGraph | Chat、NL-to-SQL、目录 API | 3001 |
| Ingestion worker | FastAPI | 表数据摄入、embedding 写入、语义编译 | 3002 |
| MCP server | FastMCP | 只读 agent 工具 | 3003 |
| Postgres + pgvector | PostgreSQL 17 | 目录、本体、向量存储 | 5432 |
| HashiCorp Vault | 可选 | 连接凭据保管 | 无 |
后端包 auto_ontology/ 下有 11 个业务模块目录(另有独立的 tests),命名能直接读出职责分层:connectors(数据源连接)、catalog(元数据目录)、ingestion_service(摄入)、semantic(本体建模)、retrieval(检索)、vdb(向量库)、pii_detection(敏感数据识别)、dal(数据访问)、server(API),加上 infra 和 utils 两个支撑模块。
两件事要先讲明。一是 README 明确写着当前不接受外部贡献,开源的是代码和标准,治理上仍是 NVIDIA 单方主导,提 PR 前要有预期。二是它的数据源全部是关系型,pyproject.toml 里的连接器是 Postgres、Snowflake、Databricks、MySQL、Trino、Hive、HeavyDB、DuckDB 这一路,非结构化文档、对象存储、图数据库不在目标范围内。
怎么用:Compose 起步、模型三元组、MCP 与 agent skills
本地跑通:Docker Compose 加样例库
官方 quickstart 用微软的 Wide World Importers 示例销售库,前置条件是 Docker Compose v2、uv 和一个 NVIDIA API key。第一步克隆仓库配 .env,必填项包括模型 key、认证 secret、Postgres 密码和管理员密码:
git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env
# 编辑 .env:DEFAULT_MODELS_API_KEY、AUTH_SECRET、POSTGRES_PASSWORD 等然后起 Postgres、从配套的 auto-ontology-eval 仓库跑种子脚本灌样例数据,最后构建整个栈:
docker compose up -d --wait postgres
git clone https://github.com/NVIDIA/auto-ontology-eval.git ../auto-ontology-eval
(cd ../auto-ontology-eval && uv sync && cp .env.example .env && \
POSTGRES_PASSWORD='' \
uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)
docker compose up -d --build 打开 http://localhost:3000 登录,在 Settings 里打开 Semantic Compilation,等它提示编译完成。README 给的真实例子里,WWI 这个库一次编译产出 31 个 terms。之后在 Chat 里问"2015 年 6 月宾州寿司卷 U 盘的收入是多少",返回不只是答案,还带完整 SQL 和推理步骤:
Answer: Revenue ... was $588.80, from 3 invoice lines.
SQL: SELECT SUM(il.extendedprice) AS revenue, COUNT(*) AS invoice_lines
FROM sales.invoicelines il
JOIN sales.invoices i ON il.invoiceid = i.invoiceid
JOIN warehouse.stockitems si ON il.stockitemid = si.stockitemid
JOIN sales.customers c ON i.customerid = c.customerid
JOIN application.cities ct ON c.deliverycityid = ct.cityid
JOIN application.stateprovinces sp ON ct.stateprovinceid = sp.stateprovinceid
WHERE si.stockitemname = 'USB food flash drive - sushi roll'
AND sp.stateprovincename = 'Pennsylvania'
AND i.invoicedate >= '2015-06-01' AND i.invoicedate < '2015-07-01'
Steps: Resolved terms -> followed relationships to joins ->
validated filter values against data, then executed模型配置:每个角色一组三元组
推理依赖 NVIDIA NIM,可以是 build.nvidia.com 的托管端点,也可以是自托管 NIM。配置方式值得单独说,每个模型角色由三个环境变量组成:<PREFIX>_ENDPOINT、<PREFIX>_API_KEY、<PREFIX>_MODEL。角色分五个,默认值都指向 Nemotron 家族:
| Prefix | 角色 | 默认模型 |
|---|---|---|
| DEFAULT_MODELS | 共享兜底 | 所有未单独配置的角色回退到它 |
| REASONING | 主 Chat / NL-to-SQL | nemotron-3.5-lightning-30b-a3b |
| NON_REASONING | 轻量实体抽取 | 未单列,回退 DEFAULT_MODELS |
| EMBED | 文本向量 | nemotron-3-embed-1b |
| RERANK | 检索重排 | llama-nemotron-rerank-vl-1b-v2 |
只填 DEFAULT_MODELS_* 就能跑,哪个角色需要换模型再单独覆盖。有个硬约束文档点了名:EMBED 模型在摄入和查询两端必须一致,否则向量检索直接失配。这套三元组抽象的实际好处是,整套系统可以从托管 API 切到内网自托管 NIM,代码不用改,只换 endpoint。
接入 agent:MCP 只读,写入走另一条路
MCP server 暴露的工具按职责分四组:check_readiness 看部署是否就绪,search_terms/get_term/get_term_columns 查本体,check_answerable 做可答性检查,ask_question 出答案带 SQL 和数据行。本地启动方式:
AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcpCursor 直接填 HTTP URL,Claude Desktop 用 mcp-remote 桥接,配置都是标准 MCP 写法。关键设计是 MCP 全程只读,每次调用带着登录用户的权限执行;任何修改本体的操作都必须走 Next.js 的 /api/... 表面。AGENTS.md 把这条写得很死:MCP 不能写,写路径在管理 skill 里,实时工具列表以握手时返回的为准。
仓库还自带三个 agent skills,构成完整生命周期:nvidia-ontology-setup 管安装排障,nvidia-ontology-management 管建模、认证、发布和回滚,nvidia-ontology-query 管查询与 SQL 校验。这些 skill 会同步到 NVIDIA 的公共 skill 目录。
开放标准与部署选项
本体定义兼容 Apache Ossie,这是个交换语义模型的开放标准,官方提供 Ossie YAML 的双向转换器,UI 里 Settings → Import/Export 或调 /api/model/import、/api/model/export 都行,避免模型定义被锁死在这个项目里。生产部署官方推荐 Helm chart,本地开发用 Compose。
部署时有个安全细节 README 专门提醒:3001 和 3002 两个 FastAPI 服务没有独立认证,后端信任前端转发的 x-auto-ontology-user-id 头,摄入服务的 ingest/delete/reset/compile 接口完全裸奔。这两个端口必须放私网,所有客户端走 3000 的 Web 应用,不能图省事直接暴露。
值得学习的四个设计
1. 人在回路的认证门:LLM 起草,人签字,agent 才执行
自动生成本体不稀奇,稀奇的是它没让 LLM 的输出直接进生产链路。摄入服务产出的 term、关系、SQL 属性全部是草稿状态,UI 上要经过人工 test、refine、certify 三步,认证之后 agent 才能引用。这等于把 LLM 的不确定性挡在查询发生之前:模型负责把人工梳理几百张表的成本压下来,人负责对业务口径拍板。
配套的权限分层把同一个原则落到 API 上:agent 走 MCP 只有读权限,建模和认证这种写操作走带 RBAC 的 Web 表面(认证用 Better Auth)。读多写少、写必有责任人,这比给 agent 一个全功能数据库账号稳得多。
2. answerability 前置:答不了就明说,不硬编 SQL
常规 text-to-SQL 的失败模式是拿到问题就拼 SQL,拼出来跑通就算成功,至于数据到底支不支持这个问题,没人检查。Auto Ontology 在写 SQL 之前先跑 check_answerable。README 的例子很说明问题:问广告支出回报率(ROAS),而 WWI 库里根本没有广告数据,agent 返回 coverage 0.5,明确说"没有 term 覆盖 ad spend,算不了 ROAS,要不要改问收入",并提示数据可能在另一个需要接入的源里。
这个设计把"拒答"做成了一等公民。企业场景里,一个自信的错误数字比"我不知道"危险得多;先判可答性、再谈生成,顺便还能发现数据治理的缺口(哪些业务问题没有数据支撑)。
3. SQL attributes:把指标口径收敛成单一事实源
同一个"毛利率",财务写一段 SQL、运营写一段、临时分析再写一段,三套结果对不上是企业数据团队的日常。Auto Ontology 的做法是让度量本身成为本体里的认证对象:SQL attribute 是挂在 term 下、经过审核的 SQL 表达式,agent 生成查询时复用而不是重新发明。
这和 dbt metric、Cube 的思路同源,但落点不同:那些工具服务 BI 和报表,SQL attributes 服务的是 agent 的即时查询,保证 agent 算出来的数和认证过的口径一致。关系推断也围绕这个目标,join 路径(含桥接表)从键和数据里推断后存入本体,agent 沿着认证过的关系走,不会每次凭感觉选 join。
4. 推理层完全可替换:三元组抽象加自托管退路
很多 AI 应用把模型供应商焊死在代码里。Auto Ontology 的五元角色加三元组配置,让推理、抽取、embedding、重排各自可换,而且官方同时支持托管 API 和自托管 NIM。对金融、医疗这类数据不能出内网的行业,这条是准入条件:embedding 和 LLM 全部跑在自己的 GPU 上,数据不出域,只把框架本身开源化。
pyproject.toml 里还有个工程细节能看出严肃项目的依赖管理方式:openai 包精确钉在 2.44.0、langchain-openai 钉了区间、pandas 限制在 3 以下,每个钉版本旁边都有注释解释原因(上游兼容、eval 对齐),还有 nSpect 安全扫描驱动的 constraint-dependencies。依赖为什么是这个版本,半年后的维护者能直接读懂。
同类比较:Vanna、WrenAI、dbt Semantic Layer、GraphRAG 怎么选
先声明口径:Auto Ontology 没有在 README 给出 benchmark 分数,BIRD 等 text-to-SQL 评测要跑它单独拆出的 ontology-sql-eval 仓库。下面只比架构定位和适用场景,不编造准确率数字。
| 维度 | Auto Ontology | Vanna | WrenAI | dbt Semantic Layer | GraphRAG/Neo4j |
|---|---|---|---|---|---|
| 核心定位 | agent 的认证本体层 | text-to-SQL 库 | 开源语义层 + text-to-SQL | BI 指标层 | 通用知识图谱问答 |
| 语义建模 | 自动生成 + 人工 certify | 训练式 schema 记忆 | 模型定义(MDL) | metrics 定义 | 实体关系图 |
| 拒答机制 | check_answerable 前置 | 无内建 | 部分 | 不适用 | 取决于实现 |
| agent 入口 | 只读 MCP + 3 个 skills | Python API/Flask | MCP/API | 面向 BI 工具 | Cypher/自定义 |
| 部署形态 | 五服务 + Postgres,偏重 | 库形态,轻 | 服务化,中等 | 依附 dbt 项目 | 图库 + 管线 |
| 数据源 | 关系型为主,8 种连接器 | 多数据库 | 多连接器 | 数据仓库 | 非结构化为主 |
| 推理绑定 | NIM/自托管,可换 | 任意 LLM | 任意 LLM | 无 LLM | 任意 LLM |
逐个说分工。Vanna 是最常见的轻量选择,pip 装完就能给单个应用加 text-to-SQL,靠 RAG 记 schema 和历史 SQL,但它没有认证流程、没有可答性检查,答得对不对主要靠 prompt 和样本质量,适合内部工具、容忍试错的场景。WrenAI 是最接近的开源竞品,同样做语义层加 text-to-SQL 也支持 MCP,区别在 WrenAI 的 MDL 更偏查询引擎和 BI 对接,Auto Ontology 把人工认证、provenance、企业 RBAC 做得更重,且深度绑定 NIM 生态。
dbt Semantic Layer 和 Cube 不是竞品而是互补:它们解决的是报表和 BI 的指标一致性,消费者是人看的仪表盘;Auto Ontology 的消费者是 agent,SQL attributes 的思路借鉴了指标层,但运行时围绕 NL-to-SQL 和 MCP 组织。已经重度使用 dbt 的团队,更现实的路径是评估两者通过 Ossie 之类标准共存,而不是二选一。
GraphRAG、Neo4j 加 LLM 处理的是文档、知识实体这类非结构化或半结构化数据,Auto Ontology 的连接器全是 SQL 系,目标是让关系型库里的表结构对 agent 可解释。要做跨文档和数据库的统一问答,得两条管线并存。
我的选型判断:数据治理要求高、多表多源、需要审计每个数字怎么算出来的企业 agent 场景,Auto Ontology 的认证门和只读 MCP 是目前开源里少见的完整答案,代价是接受五个服务的运维重量和 NIM 生态绑定;单库加个自然语言查询、团队小、迭代快,Vanna 的性价比高得多;已经在 dbt 上建了指标层,先看 WrenAI 或等 Auto Ontology 的 Ossie 生态成熟;非结构化知识问答别用它,选图方案。
参考文档与链接
- NVIDIA/auto-ontology(GitHub) — 仓库主体,Apache-2.0,10,153 star / 821 fork / 87 open issue(2026-11-10 GitHub API 快照),当前不接受外部贡献
- README — 三阶段工作流、五服务架构、模型三元组、完整 quickstart 与真实问答示例
- AGENTS.md — 三个 agent skills 的职责边界、MCP 只读约束、生命周期与事实源划分
- pyproject.toml — v1.1.0、Python 3.12-3.13、8 种数据库连接器、LangGraph/sqlglot 依赖与版本钉扎注释
- NVIDIA/ontology-sql-eval — 官方 BIRD 等 text-to-SQL 评测仓库,benchmark 独立于主项目
- Apache Ossie — 语义模型交换开放标准,Auto Ontology 通过 ossie-converters 支持 YAML 导入导出
- ossie-converters(nvidia 目录) — Auto Ontology 与 Ossie 互转的官方转换器
- NVIDIA API Catalog(NIM) — 托管推理端点,默认 Nemotron 模型与 API key 申请入口
- docs/mcp.md — MCP server 登录、配置与排障
- DEPLOYMENT.md — Helm 官方安装与部署细节
- Vanna — 轻量 text-to-SQL 库,库形态对照
- WrenAI — 开源语义层加 text-to-SQL,最接近的服务化竞品
- dbt Semantic Layer — BI 指标层,与 agent 本体层互补
- Microsoft GraphRAG — 非结构化知识图谱问答路线对照
你们的 text-to-SQL 栽过哪些指标口径不一致的坑?或者上线后怎么验证 agent 写的 SQL 对不对?评论区聊聊实战经验。觉得有帮助点个赞,让更多做数据 agent 的人看到。
作者: itech001
来源: 公众号:AI人工智能时代(the-ai-era)
网站: https://www.theaiera.top/
关注每日最新AI新闻和技术博客,主页有更多的文章的AI 技术参考:https://www.theaiera.top
本文首发于 AI人工智能时代,转载请注明出处。