auto-ontology

书到用时方恨少，事非经过不知难。——陆游

数字错了，快也没用：Auto Ontology 想给 agent 补上「这词到底指什么」

一句很扎心的开场

一份文档的第一段，通常用来讲产品多好。

这份文档的第一段，用来讲一件事有多没用：

agent 能检索文档，也能查数据库，但可靠性卡住了 agentic analytics 的脖子——一个收入指标，答得再快，只要数字是错的，就一文不值。

这句话放在 2026 年，几乎是对整个行业的一记耳光。

过去两年，所有人都在比谁的 agent 跑得快、谁的工具调用更花哨、谁能一次读更多文档。而真正让企业不敢把报表交给 agent 的原因，从来不是速度，是那句没人敢问出口的话：你这个「营收」，和我财务系统里的「营收」，是同一个东西吗？

项目地址：https://github.com/NVIDIA/auto-ontology

Auto Ontology 就是冲这个问题来的。它的描述写得很技术：一个 Python 框架，用于在数据之上构建语义的、基于图的推理层，从而实现确定性的查询生成、更好的上下文检索，以及更可解释的 AI。

翻译一下：给 agent 装一层「词典 + 地图 + 户口本」。

它要回答的六个问题

文档把这一层的职责列成六个问题，值得一字不改地念一遍：

数据在哪。

它是什么意思。

该不该用它。

怎么用它。

它从哪来。

以及，和什么相似。

这六个问题，恰好覆盖了 agent 在企业数据上翻车的全部方式。

不知道数据在哪，它就去猜表名。不知道什么意思，它就把「客户数」和「活跃客户数」混着用。不知道能不能用，它会把三年前的快照当今天的口径。不知道怎么用，它会写出一个语法正确但逻辑荒谬的 SQL。不知道从哪来，它给你的数字没法审计。不知道和什么相似，它每次都要从零开始找。

而这六件事，人在公司里是靠什么解决的？靠一个干了八年的数据工程师，靠一份没人读完的数据字典，靠开会时有人喊一句「等等，这个指标是财务口径还是业务口径」。

Auto Ontology 的野心，是把这套口口相传的默契，变成一份能被机器读、能被校验、能被继承的东西。

而且它说得很清楚：它补充客户已有的语义模型，不取代它们。

这句话很重要。企业里的语义层通常已经存在了——dbt 的模型、LookML、某个 BI 工具里的指标定义。一个新工具如果要求你先把这些扔掉，那它第一天就会被否掉。

五个动词

它把自己的能力拆成五个动词。

发现。 从元数据生成企业本体；连接已有的本体和语义模型；构建 AI 就绪的知识图谱。

落地。 给 agent 一份可信的业务含义——指标、实体、关系都算；同时把不同系统里互相矛盾的定义对齐。

校验。 拿生成的查询去对照已认证的定义和血缘；每个答案都带上出处。

暴露。 通过 MCP、CLI 和 API，把这份上下文递给任何 agent harness。

学习。 把经过认证的修正和使用痕迹折回本体，让共享的上下文随着每一次提问变好。

这五个词里，最容易被低估的是第三个和第五个。

校验之所以重要，是因为它把「对不对」从主观判断变成了机械比对。查询里用了哪个指标、那个指标的定义是谁认证的、数据经过了哪几层转换——这些都能查。

而学习之所以难得，是因为大多数「知识库」是只写的：你往里灌，它不往回长。而这里说的是「把认证过的修正折回去」——注意「认证过」这三个字。不是 agent 说什么就信什么，是有人签过字的修正才进本体。

一个会遗忘的系统不可怕，一个会乱学的系统才可怕。这条限定，说明设计者知道区别。

组件：五个进程，五个端口

架构表列得很干脆：

组件	技术	职责	默认端口
前端	Next.js 16、React 19、TypeScript、Tailwind 4、Better Auth、Prisma	Web UI、认证、API 网关	3000
后端	FastAPI、Python 3.12+、LangChain	对话与自然语言转 SQL、目录、数据源 API	3001
摄取 worker	FastAPI、Python 3.12+	摄取表格数据并写入向量	3002
Postgres + pgvector	关系数据库	应用元数据、目录与本体、向量库	5432
HashiCorp Vault	可选	安全存放连接凭证	无

后面还有一张更细的表，多了一个 MCP server，用 FastMCP 写，跑在 3003，只提供只读工具，走公开 API。

这里有个很务实的选择：本体和目录都放在 Postgres 里，和它们描述的数据放在同一个库。

为什么不单独搞一个图数据库？因为要解决的是「定义在哪、谁改的、和谁冲突」，这类问题的查询模式并不复杂，而多引入一个存储就多一套备份、监控、权限和故障模式。用 pgvector 顺手把向量也放进去，整个栈就只剩一个数据库要运维。

工程上的克制，往往比架构图上的漂亮更值钱。

模型三元组：一个值得抄的配置设计

推理那一节，藏着一个我很喜欢的设计。

默认用 NVIDIA NIM 的端点——可以是托管的 API 目录，也可以是自己部署的 NIM。默认模型是三个：一个 Nemotron 3.5 Lightning 做对话，一个 Nemotron 3 embed 做向量，一个 Llama Nemotron rerank 做重排。

而配置方式是这样的：每个模型角色由一组三元组决定——<PREFIX>_ENDPOINT、<PREFIX>_API_KEY、<PREFIX>_MODEL。

前缀有五个：DEFAULT_MODELS、REASONING、NON_REASONING、EMBED、RERANK。

规则是：你可以设一整组，也可以只设其中几个字段，也可以一个都不设——任何没设的字段，都会回落到 DEFAULT_MODELS 里对应的那个。

于是最简单的部署方式变成了：把 DEFAULT_MODELS_* 填好，然后只在需要不同的地方覆盖，比如只改 EMBED_MODEL、只改 NON_REASONING_MODEL。

还有一条向后兼容：*_API_KEY 会回落到旧的 NVIDIA_API_KEY。

这套设计的妙处在于它承认了一个现实：大多数部署里，五个角色用同一个端点、同一个 key，只有模型名不同。

如果配置系统要求你为每个角色写满三行，那它就是在逼用户复制粘贴五遍同样的 URL。而「回落」这两个字，把这五遍变成了一遍。

配置系统的成熟度，往往体现在它允许你少写多少行。

安全：三段必须读的话

这是我在这份文档里最想推荐的部分，因为它写得比很多安全公告都直接。

第一段：端口。

3001 和 3002 要放在私有网络里。

理由在下一句：FastAPI 信任前端在 x-auto-ontology-user-id 头里转发的用户身份。

这句话翻成大白话：后端自己不做身份校验，它相信前面那个人已经校验过了。所以一旦 3001 能从公网访问，任何人只要伪造一个 header，就能变成任何用户。

第二段：摄取服务没有自己的鉴权。

摄取、删除、重置、编译这四个端点，本身不带认证。

这四个动词凑在一起，是一个完整的破坏链：能摄取就能塞数据，能删除就能清库，能重置就能推倒重来，能编译就能改本体。

所以文档的结论是：客户端一律走 3000 那个 Web 应用。

第三段：KumoRFM。

设了 KUMO_RFM_API_KEY 之后，agent 会把预测类问题路由到 KumoRFM。而它是一个托管服务——为了回答问题，agent 会把连接的表上传上去。

上传量有上限：KUMO_MAX_TABLES 默认 20 张表，KUMO_MAX_ROWS_PER_TABLE 不设就是无限。

然后是一句很轻但很重的话：先看清楚这会发出去什么，完成你们组织的数据审查，再启用它。

三段话，三种风险，一个共同的品质：它没有把「安全」写成一个形容词，而是写成了具体的端口号、具体的 header 名、具体的环境变量。

一个工具愿意告诉你「我在哪里信任了别人」，比它承诺「我很安全」有用一百倍。

和 Ossie 互通

有一节讲互操作：Auto Ontology 兼容 Apache Ossie，那是交换语义模型的开放标准。Ossie 自带一个 Auto Ontology 的转换器，而 Auto Ontology 用它来导入导出 Ossie YAML。

入口有两个：设置里的导入导出，或者两个 POST 接口。

这一条看着像技术细节，其实是这类工具能不能在企业里活下来的关键。语义模型是资产，资产最怕被锁死在一个工具里。能导出成标准格式，意味着你今天试它，明天换掉它，那部分投入不会全部沉没。

反过来说，一个不肯导出语义模型的工具，本质上是在拿你的资产做人质。

一件得说清楚的事：它不收外部 PR

文档里有两处提到了同一件事，措辞几乎一样：这个项目目前不接受外部贡献；团队维护代码，不接受外部 pull request。

但同一段里又写着：集成请求和 bug 报告欢迎以 issue 形式提交。

这个组合挺有意思。它没有假装开放，也没有关上门——它把「你可以提问题」和「你不能改代码」分得很清楚。

对一个 Apache-2.0 的项目来说，这个选择有点反直觉。许可允许你 fork、允许你改、允许你商用，但官方渠道不接你的补丁。

这不矛盾。许可管的是法律权利，维护模式管的是工程节奏。很多公司内部维护的项目都会这么干：代码给你，方向盘不给你。

对使用者来说，这意味着两件事：你可以放心读代码、放心 fork；但别指望你提的修复会被合并。

它没有在文档里报分数

整份文档里，关于「效果」的部分只有一小段，标题是 Benchmarks，内容两行：要跑 BIRD 这类 text-to-SQL 基准，请参考那个本体 SQL 评测的仓库。

没有柱状图，没有「提升百分之多少」，没有「业界第一」。

对一个卖「准确性」的产品来说，这几乎是反常的克制。

但仔细想想，这个选择很合理。文字转 SQL 的基准分数，受模型、提示词、数据子集、评测脚本影响极大，谁都能在自己挑的切片上报一个漂亮的数字。与其报一个注定被质疑的分数，不如把评测代码放出去，让人自己跑。

这跟它开头那句话是一个逻辑：数字对不对，比说得多快重要。

最后

回到那句开场。

「一个收入指标，答得再快，只要数字是错的，就一文不值。」

这句话之所以成立，是因为企业数据的问题从来不在计算，而在共识。同一个词，财务有一套定义，业务有一套定义，三年前的数据仓库里还有第三套。人靠开会吵出共识，agent 没得吵——它只能拿到一份写死的定义，然后照着执行。

Auto Ontology 想做的，是把那份共识变成一份可以版本化、可以校验、可以带着出处一起交出去的东西。

它叫「本体」，这个词听起来很学术。但它要解决的事很土：让所有人和所有 agent 在说「营收」的时候，说的是同一件事。

这件事做成了，agent 的分析才谈得上可信。做不成，再快的模型也只是在更快地说错话。