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 / 未结 issue | 12,629 / 1,038 / 121 |
| 建库 / 最近推送 | 2026-04-27 / 2026-11-14 |
| 许可证 / 语言 | Apache-2.0 / Python |
| Release / tag | 0 个 / 1 个备份标签 |
| 包版本 / Python 要求 | 1.2.0 / >=3.12,<3.14 |
| 仓库体积 / 订阅者 | 22,303 KB / 54 |
换句话说,这不是一个塞进 ~/.claude/skills 就能用的技能包。它是一套要起数据库、后端、前端和 MCP 服务的语义层,仓库自带的三个 skill 只是教 agent 怎么操作这套服务。本文只做文件级反查,未部署、未跑任何基准。
生成、认证、回答三段流水线,人卡在中间那一段
最关键的机制不是检索,是「人必须先认证定义」。README 把流程写成三阶段:机器从数据库生成一版本体草稿,人把它改对并认证,agent 才被允许据此回答。自动生成的草稿不算数。
| 阶段 | 谁做 | 步骤 | 产物 |
|---|---|---|---|
| Generate | ingestion 服务 | 4 步 | 术语、关系、SQL 属性与 pgvector 向量 |
| Certify | 人 | 3 步 | 认证过的名称、描述与度量表达式 |
| Answer | agent | 5 步 | 答案、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,于是反问是改问收入、还是去接另一个数据源。宁可承认不可答,也不硬编一个数字。
37 条依赖、6 个组件、4 个模型角色,都不是一个 skill 的体积
把 README 的软件组件表、模型表和 pyproject.toml 对起来,落地成本就藏不住了。它要同时起前端、后端、ingestion、MCP、Postgres 与可选的 Vault,还要一个 NVIDIA API key 供四个模型角色调用。
| 组件 | 技术 | 默认端口 |
|---|---|---|
| Frontend | Next.js 16 / React 19 / Better Auth / Prisma | 3000 |
| Backend | FastAPI(Python 3.12+)/ LangChain | 3001 |
| Ingestion worker | FastAPI | 3002 |
| MCP server | FastMCP,只读 | 3003 |
| Postgres + pgvector | PostgreSQL 17 | 5432 |
| HashiCorp Vault | 可选,存连接凭据 | — |
| 模型角色 | .env.example 默认值 | 干什么 |
|---|---|---|
| REASONING | nemotron-3.5-lightning-30b-a3b | 建本体、写 SQL、判可答性 |
| NON_REASONING | nemotron-3.5-lightning-30b-a3b | 意图、实体抽取、SQL 校验修复 |
| EMBED | nemotron-3.5-embed-1b | 向量化列与术语 |
| RERANK | nemotron-3.5-rerank-8b | 给候选表排序 |
端点可以换成自托管 NIM 或任意 OpenAI 兼容接口,但有一条不能省:ingest 与 query 必须用同一个 embedding 模型。四个角色各由一组 ENDPOINT / API_KEY / MODEL 三元组配置,未填的字段回落到 DEFAULT_MODELS。
数据源 README 列了十个,其中 DuckDB 与 SQLite 只支持连接串方式接入。按类型分成三组:
- PostgreSQL、MySQL、DuckDB、SQLite
- Databricks、Snowflake、ClickHouse
- Trino、Apache Kyuubi、HeavyDB
把规模数字拆开看,比一句「依赖不少」更有用:
- pyproject.toml:主依赖 37 条,requires-python >=3.12,<3.14,openai 钉在 2.44.0。
- 两份 uv.lock:根目录 435,985 字节,mcp/ 目录 261,144 字节。
- .env.example:219 行,逐个模型角色给出三元组示例。
- Apache Ossie 转换器:以 git 依赖直接引用,用于 YAML 导入导出。
| 目录 | 条目数 | 关键内容 |
|---|---|---|
| 根目录 | 35 | AGENTS.md / CLAUDE.md / Dockerfile / helm / vendor |
| auto_ontology/ | 15 | catalog、connectors、semantic、vdb 等子包 |
| skills/ | 3 | setup / management / query 三个技能 |
| mcp/ | 12 | 独立 pyproject、uv.lock、tools.py |
| docs/ | 6 | 4 篇 md 加 assets 与 openapi/ |
| docs/openapi/ | 4 | 主 spec 437,217 字节 |
- 身份:12,629 星 / 1,038 fork / 121 未结 / 建库 2026-04-27 / pushed 11-14 / Apache-2.0。
- 版本:releases 空、latest 404、tag 1 个(pre-main-merge-backup);pyproject 写 1.2.0;正式镜像发 NGC。
- 规模:37 条主依赖、6 组件、4 模型角色、10 数据源、3 个 skill 各 7 个条目。
- 边界:README 的 Benchmarks 指向外部仓库;本文未安装、未跑分、未复现任何示例答案。
核对时间 2026-11-14,星标与 issue 为实时值。
先把六个组件起起来,再让 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:
- nvidia-ontology-setup:Helm 安装、Compose 本地栈、连接数据源、编译与排障。
- nvidia-ontology-management:检查、建模、认证、导入导出与发布,是唯一覆盖写路径的技能。
- nvidia-ontology-query:MCP 优先、REST 兜底,校验 SQL、结果行与答案。
每个 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 导入导出,避免把语义层锁死在这一套实现里。
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 里:
- 网络边界:3001 与 3002 须置于私有网络,FastAPI 信任前端转发的 x-auto-ontology-user-id 头。
- 无自身鉴权:ingestion 的 ingest / delete / reset / compile 四个端点没有独立认证。
- 数据外发:开启 KumoRFM 后预测问题会上传连接的表,KUMO_MAX_TABLES 默认 20,每表行数默认不限。
- 口径不齐:NIM 小节与 Models 表给出的 embed / rerank 默认模型名不一致,与 .env.example 对齐的是后者。
- 漏洞披露:不走 GitHub issue,走 NVIDIA PSIRT 表单或 psirt@nvidia.com,目前无 bug bounty。
还有一个容易被星标盖过去的成本:四个模型角色默认全部指向 NVIDIA NIM,需要 nvapi- key;六个组件、31 个 term 的人工认证,对一个人维护的小项目远超过它能省下的返工。这 12,629 星衡量的是「企业数据语义层」这个议题的曝光,不是这套栈的可用性。
所以别把它当「给 agent 装个记忆插件」来比。真正可以白拿的是那条流程判断:先判问题可不可答,再把解析到的定义、连表路径和 SQL 一起交回来,让人能对着源数据复核。要不要为此起六个组件、交四个模型的 key,取决于你错一个数字的代价有多大——代价小,这套栈就是负债。