01 · 这件事

12,629 星买的是一层「定义」,不是更快的问答

GitHub 上 0 个 Release,12,629 星却仍在涨,这件事本身要先解释清楚。NVIDIA/auto-ontology 创建于 2026-04-27,Apache-2.0,主语言 Python。

核对日 2026-11-14 有 12,629 星、1,038 fork、121 个未结 issue,pushed_at 就在今天,最近一次提交也落在今天。

先说发布渠道,免得误读。仓库的 releases 接口返回空数组,latest 接口直接 404,tags 只有 1 个叫 pre-main-merge-backup 的备份标签。正式产物不在 GitHub Releases,而在 NGC 镜像仓库:三个容器镜像加一个 Helm chart。

仓库 description 写的是「在数据之上构建 semantic、graph-based 推理层」。README 开篇那句更直白:收入指标答得再快,数字错了也一文不值。它瞄准的是 agent 查数算错,不是查得慢。

字段核对值
仓库NVIDIA/auto-ontology · main 分支
星标 / fork / 未结 issue12,629 / 1,038 / 121
建库 / 最近推送2026-04-27 / 2026-11-14
许可证 / 语言Apache-2.0 / Python
Release / tag0 个 / 1 个备份标签
包版本 / Python 要求1.2.0 / >=3.12,<3.14
仓库体积 / 订阅者22,303 KB / 54

换句话说,这不是一个塞进 ~/.claude/skills 就能用的技能包。它是一套要起数据库、后端、前端和 MCP 服务的语义层,仓库自带的三个 skill 只是教 agent 怎么操作这套服务。本文只做文件级反查,未部署、未跑任何基准。

02 · 核心机制

生成、认证、回答三段流水线,人卡在中间那一段

最关键的机制不是检索,是「人必须先认证定义」。README 把流程写成三阶段:机器从数据库生成一版本体草稿,人把它改对并认证,agent 才被允许据此回答。自动生成的草稿不算数。

阶段谁做步骤产物
Generateingestion 服务4 步术语、关系、SQL 属性与 pgvector 向量
Certify人3 步认证过的名称、描述与度量表达式
Answeragent5 步答案、SQL、所用步骤

本体里存三类定义。Terms 是 Customer、Invoice Line 这类业务概念,带描述、同义词和映射列;SQL attributes 是审过的度量表达式,比如毛利率,agent 复用它,保证每次算同一个指标口径一致。

Relationships 是表怎么连,含桥表,由键和数据推断。Generate 阶段依次读 schema、逐表命名实体、推断 join、把三者写进 Postgres。README 给的示例里,一次编译 Wide World Importers 得到 31 个 terms。

示例问题是 2015 年 6 月宾州某商品的收入,答案回来 588.80 美元、3 条 invoice line,同时附上六表 join 的 SQL 和「解析了哪些 term、怎么连的表」的步骤。答案必须自带可回查的 SQL 和血缘,这是它比纯向量检索更硬的地方。

更值得写下来的是不回答的路径。README 演示问「广告支出回报率」,agent 先跑 check_answerable 得到 coverage 0.5,发现没有 term 覆盖 ad spend,于是反问是改问收入、还是去接另一个数据源。宁可承认不可答,也不硬编一个数字。

03 · 关键细节与数据

37 条依赖、6 个组件、4 个模型角色,都不是一个 skill 的体积

把 README 的软件组件表、模型表和 pyproject.toml 对起来,落地成本就藏不住了。它要同时起前端、后端、ingestion、MCP、Postgres 与可选的 Vault,还要一个 NVIDIA API key 供四个模型角色调用。

组件技术默认端口
FrontendNext.js 16 / React 19 / Better Auth / Prisma3000
BackendFastAPI(Python 3.12+)/ LangChain3001
Ingestion workerFastAPI3002
MCP serverFastMCP,只读3003
Postgres + pgvectorPostgreSQL 175432
HashiCorp Vault可选,存连接凭据—
模型角色.env.example 默认值干什么
REASONINGnemotron-3.5-lightning-30b-a3b建本体、写 SQL、判可答性
NON_REASONINGnemotron-3.5-lightning-30b-a3b意图、实体抽取、SQL 校验修复
EMBEDnemotron-3.5-embed-1b向量化列与术语
RERANKnemotron-3.5-rerank-8b给候选表排序

端点可以换成自托管 NIM 或任意 OpenAI 兼容接口,但有一条不能省:ingest 与 query 必须用同一个 embedding 模型。四个角色各由一组 ENDPOINT / API_KEY / MODEL 三元组配置,未填的字段回落到 DEFAULT_MODELS。

数据源 README 列了十个,其中 DuckDB 与 SQLite 只支持连接串方式接入。按类型分成三组:

把规模数字拆开看,比一句「依赖不少」更有用:

目录条目数关键内容
根目录35AGENTS.md / CLAUDE.md / Dockerfile / helm / vendor
auto_ontology/15catalog、connectors、semantic、vdb 等子包
skills/3setup / management / query 三个技能
mcp/12独立 pyproject、uv.lock、tools.py
docs/64 篇 md 加 assets 与 openapi/
docs/openapi/4主 spec 437,217 字节
数据核对:全部数字来自 api.github.com 的仓库、目录、标签、提交接口与仓库内文件原文,文件数为单层目录接口计数,未用递归树。

核对时间 2026-11-14,星标与 issue 为实时值。

04 · 怎么用

先把六个组件起起来,再让 agent 通过 MCP 只读地问

agent 侧的接口是只读的,写操作一律走 Web 应用的 /api 路由。AGENTS.md 把这条写成硬规定:MCP 不能写,术语、关系与认证的修改由 management 技能走 Next.js 的 API 面,每个调用都带上登录用户的权限。

用途README 列出的 MCP 工具
就绪check_readiness
查术语与表search_terms、get_term、get_term_columns、get_term_sql_attributes、get_sql_attribute、describe_table
可答性check_answerable
提问ask_question

本地 quickstart 的顺序是固定的。先克隆仓库并复制 .env.example,填好 NVIDIA API key 与几个密码;再起 Postgres,用另一个仓库的 seed 脚本灌入 Wide World Importers 示例库,然后执行 docker compose up -d --build。

接着要在 Settings → Semantic Compilation 里手动打开编译,等它报 ready,才能在 Chat 提问。这一步不是自动的,也意味着「开箱即用」并不准确:示例数据库、灌数脚本与管理动作都散在别处。

仓库里三个 skill 各管一段,入口是根目录的 AGENTS.md:

每个 skill 目录 7 个条目,含 SKILL.md、evals 与 references,还有 BENCHMARK.md 和 skill.oms.sig。AGENTS.md 特别注明后两份由 NVSkills CI 生成、禁止手改;三份技能还会同步到 nvidia/skills 目录仓库。

不走 MCP 可以直接 POST /api/chat/completions,响应是 SSE 流,result 事件带答案,[DONE] 收尾。模型定义还能通过 Apache Ossie 的 YAML 导入导出,避免把语义层锁死在这一套实现里。

05 · 冷思考

12,629 星里,能直接拿走的是流程,不是一套能跑的服务

最该先读的不是功能列表,是 CONTRIBUTING.md 的第一行:本项目不接受外部 PR。代码由 NVIDIA 维护团队改,外部只能通过 issue 提集成请求和 bug。Apache-2.0 给了你可读、可改、可分发的权利,但没给参与协作的通道。

版本口径也值得留意。GitHub 上 0 个 Release、1 个备份 tag,pyproject 却写着 1.2.0;version.py 优先读环境变量 APP_VERSION,值由 Helm chart 版本注入。

想复现某个具体版本,得先找到 NGC 上对应的 chart version,而不是来 GitHub 找 tag。

基准同样不在这个仓库。README 的 Benchmarks 一节只有一句:跑 BIRD 这类 text-to-SQL 评测请参考另一个仓库 ontology-sql-eval。主仓库没有一个准确率数字;三个 skill 里的 BENCHMARK.md 是技能签名流程的产物,不是查询效果。

边界条款比功能表更该先读,下面几条都写在 README 或 SECURITY.md 里:

还有一个容易被星标盖过去的成本:四个模型角色默认全部指向 NVIDIA NIM,需要 nvapi- key;六个组件、31 个 term 的人工认证,对一个人维护的小项目远超过它能省下的返工。这 12,629 星衡量的是「企业数据语义层」这个议题的曝光,不是这套栈的可用性。

所以别把它当「给 agent 装个记忆插件」来比。真正可以白拿的是那条流程判断:先判问题可不可答,再把解析到的定义、连表路径和 SQL 一起交回来,让人能对着源数据复核。要不要为此起六个组件、交四个模型的 key,取决于你错一个数字的代价有多大——代价小,这套栈就是负债。

去看原始仓库

NVIDIA 开源的语义 / 图谱推理层,Apache-2.0,Python 3.12+,通过 MCP、CLI 与 API 把业务定义交给 agent

前往 GitHub

相关平台

#Skill #NVIDIA #Agent #开源 #语义层