一天一个开源项目（第254篇）：NVIDIA Auto Ontology —— 给数据 Agent 搭一层「可认证的语义层」，答不了就老实说答不了

引言

「一个很快但算错的指标，没有任何价值。」

这是「一天一个开源项目」系列的第 254 篇。今天的项目是 NVIDIA 开源的 Auto Ontology。

让 Agent 去查企业数据，最常见的翻车方式不是 SQL 语法错，而是「语义错」：revenue 到底是含税还是不含税？active user 的口径是谁定的？两个系统里都叫 customer 的表是不是一回事？模型会自信地写出一条能跑通、数字却不对的 SQL。

Auto Ontology 的思路是在 Agent 和数据库之间加一层「上下文层」：先从元数据里自动抽出业务术语、可复用的 SQL 表达式和表间关系，再由人来测试、修正、认证，最后让 Agent 基于这些已认证的定义来回答。项目 README 把能力归为五个动词：Discover（发现）、Ground（落地）、Validate（校验）、Expose（暴露）、Learn（学习，认证过的修正和使用情况回流到本体）。

你将学到什么

• 本体里到底存什么：术语、SQL 属性、关系
• 「生成 → 认证 → 回答」三步流程与「答不了就说答不了」的机制
• 服务组成、端口与安全注意事项
• 如何通过 MCP / REST 把它接给 Agent
• 它和「确定性查询生成」的关系，以及几处需要留意的限制

前置知识

• 了解 Text-to-SQL 以及它在企业数据上常见的口径问题
• 会用 Docker Compose
• 可选：了解 MCP 与向量检索（pgvector）

---

项目背景

项目简介

官方定位：从企业元数据构建 AI Agent 的上下文层，调和不同系统里的定义，并通过 MCP、CLI 和 API 对外提供。它设计为与客户已有的语义模型并存，而不是取代它们。GitHub 仓库描述则强调：在数据之上构建语义化、基于图的推理层，以改善上下文检索，让 LLM 和 Agent 工作流更可解释。

项目数据

• ⭐ GitHub Stars：约 5,670
• 🍴 Forks：约 445
• 💻 语言：Python
• 📅 创建时间：2026-04-27
• 📄 许可证：Apache-2.0
• 🤝 不接受外部 Pull Request，但欢迎提交 Issue（缺陷、集成需求）
• 🏷️ 成熟度：README 未标注版本或稳定性状态

---

主要功能

核心作用

没有语义层时：
  Agent 看到的是裸表和列名
  ↓ 凭字面猜口径
  ↑ SQL 能跑，数字不对

Auto Ontology：
  元数据 → 术语 / SQL 属性 / 关系
  ↓ 人工测试并认证
  ↓ Agent 检索候选 → 写 SQL → 校验 → 返回答案和依据
  ↑ 候选撑不起查询时，明确说明而不是硬答

本体里存什么

内容	含义
术语（terms）	业务概念，带描述、同义词和列映射
SQL 属性	经过审核的表达式，比如毛利率怎么算
关系	表间连接（含桥接表），由键和数据推断

三步流程

1. Generate：读取数据源并对列做画像，逐表抽取术语；从查询历史推断关系、建议 SQL 属性；全部写入 PostgreSQL，向量存进 pgvector
2. Certify：人用真实问题测试、修正，并认证名称、描述和 SQL 属性
3. Answer：Agent 识别意图、抽取实体，用嵌入检索候选，写 SQL，校验过滤值和查询本身（失败则修复），最后连同 SQL 和步骤一起返回

候选不足时，它会说「答不了」。预测类问题可以转给第三方的 KumoRFM（需自行配置）。

快速开始

需要 Docker（Compose v2）、uv，以及一个 NVIDIA API Key（nvapi-...）。官方用 Wide World Importers 示例库演示：

git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env   # 填写 DEFAULT_MODELS_API_KEY、AUTH_SECRET、APP_URL、
                       # POSTGRES_PASSWORD、CONNECTION_STRINGS 及管理员/pgAdmin 密码
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='<password>' \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)

docker compose up -d --build

然后打开 http://localhost:3000，用管理员登录，在 Settings → Semantic Compilation 里启用，再到 Chat 里提问。

官方给了两个对照示例：

• 能答的：问某产品在某州某月的收入，返回 $588.80（来自 3 条发票行），同时给出 SQL 和解析步骤
• 答不了的：问广告支出回报率，check_answerable 覆盖度为 0.5，Agent 选择追问澄清而不是猜

示例库编译一次产生了 31 个术语。

---

项目详细剖析

服务组成

组件	技术	端口
前端	Next.js、Better Auth、Prisma	3000
后端	FastAPI、LangChain	3001
数据摄取	FastAPI	3002
MCP 服务	FastMCP	3003
数据库	PostgreSQL 17 + pgvector	5432
密钥库	HashiCorp Vault（可选）	—

要特别留意：3001 和 3002 应保持私有，因为摄取接口自身没有认证。Compose 会把服务发布到宿主机，所以默认密码必须全部改掉。仓库里另有 DEPLOYMENT.md，说明如何用 Helm 部署到 Kubernetes。

数据源与模型

• 数据库（10 种）：PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Apache Kyuubi、HeavyDB、DuckDB、SQLite（后两者仅支持连接串）
• 模型：NVIDIA NIM（托管或自建）或任何 OpenAI 兼容端点。按 REASONING、NON_REASONING、EMBED、RERANK 四种角色分别配置端点、密钥和模型，缺省回落到 DEFAULT_MODELS_*。默认 LLM 是 nvidia/nemotron-3.5-lightning-30b-a3b
• 模型必须支持结构化输出；摄取与查询时用的嵌入模型必须一致

给 Agent 接入的三种方式

• MCP（只读）：提供 check_readiness、search_terms、get_term、get_term_columns、get_term_sql_attributes、get_sql_attribute、describe_table、check_answerable、ask_question。可用 uvx 运行，在 Cursor 或 Claude Desktop（通过 mcp-remote）里配置
• REST：POST /api/chat/completions，带 x-api-key，以 SSE 流返回
• Skills：nvidia-ontology-setup、-management、-query

另外支持与 Apache Ossie 的 YAML 格式导入导出，便于和已有语义模型互通。

关于「确定性查询生成」

GitHub 仓库描述里提到 deterministic query generation（确定性查询生成），但 README 本身并没有这样描述：它实际依赖的是 LLM 写 SQL，外加认证过的定义和校验步骤。更准确的理解是：定义是确定的（人认证过），SQL 的生成仍由模型完成，再经过校验与修复。 如果你的场景要求结果完全可复现，需要自己验证这一点。

局限与注意事项

1. 不接受外部 PR，社区贡献路径只有提 Issue
2. 使用 KumoRFM 做预测会把关联表上传到托管服务（受 KUMO_MAX_TABLES 限制，默认 20），启用前要评估数据外泄风险
3. 软件会联系外部模型端点，并按「AS IS」提供
4. 重启后陈旧的会话 Cookie 可能导致界面导航异常
5. README 中嵌入与重排模型的默认值有两处写法不一致，配置时以你实际使用的为准

---

项目地址与资源

• 🌟 GitHub：github.com/NVIDIA/auto…
• 🧪 示例与评测数据：NVIDIA/auto-ontology-eval
• 📊 基准评测：NVIDIA ontology-sql-eval（BIRD 风格）
• 📄 许可证：Apache-2.0

---

总结与展望

核心要点回顾

1. 问题：Agent 查数的主要风险是口径错，而不是语法错
2. 做法：自动生成术语、SQL 属性、关系，人工认证后再让 Agent 使用
3. 诚实拒答：候选不足时明确说答不了，并给出覆盖度
4. 接入：MCP（只读）、REST、Skills，支持 10 种数据库和 OpenAI 兼容模型
5. 注意：摄取接口无认证、默认密码要改、不接受外部 PR、「确定性」要打折扣理解

适用人群

• 正在做企业数据问答 / 分析 Agent，被口径不一致困扰的团队
• 已有语义模型，想补一层供 Agent 消费的上下文层的人
• 想研究「人工认证 + 检索 + 校验」这类可靠性设计的开发者

学习建议

先按示例跑通 Wide World Importers，观察 31 个术语是怎么生成的，再故意问一个答不了的问题，看 check_answerable 的反应。之后接自己的测试库前，先把默认密码换掉、把 3001 和 3002 端口限制在内网。

---

欢迎访问 PrimeSkills —— 一个精心策划的 AI Agent 与技能市场，所有内容均经过真实企业级工作流验证。没有噱头，只有真正有效的东西。

更多实用知识和有趣产品，欢迎访问我的个人主页