返回博客列表

NVIDIA Auto Ontology:让 agent 先证明能回答,再写 SQL

2026-11-10T18:40:00+08:00
NVIDIAAuto OntologyText-to-SQL知识图谱MCP开源项目

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 这些现有方案怎么分工。

本文提纲

  1. 是什么:agent 的语义上下文层,不是又一个 text-to-SQL
  2. 怎么用:Compose 起步、模型三元组、MCP 与 agent skills
  3. 值得学习的四个设计
  4. 同类比较: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-mcp

Cursor 直接填 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人工智能时代,转载请注明出处。

分享给朋友