Auto Ontology – NVIDIA 开源的语义图谱推理框架

Auto Ontology 是 NVIDIA 开源的语义层库，从企业元数据构建 ontology，通过 MCP、CLI、API 三种接口暴露给 agent harness。工作流分三步：自动生成 ontology、人工认证、Agent 基于 ontology 回答自然语言问题。简单说，它在数据库和 LLM 之间加了一层“语义翻译官”，把表名、字段名、SQL 关系翻译成 Agent 能理解的语言。

适合正在做 text-to-SQL 原型验证、需要给 Agent 统一数据语义层的团队。不适合想要开箱即用、不愿人工介入语义建模的场景；也不适合需要深度定制或社区支持的生产环境——项目当前不接受外部贡献，推理依赖 NVIDIA NIM 端点。

它解决什么问题

Auto Ontology 解决的具体问题是：LLM 直接面对数据库时，不理解业务术语。一张 FactInternetSales 表，LLM 不知道它代表什么，也不知道它和 DimCustomer 怎么关联。Auto Ontology 的做法是生成一个包含术语、SQL 属性、关系三类定义的 ontology 层，让 Agent 写 SQL 之前先理解数据模型。

关键设计是 ontology 需要人工认证。系统生成的 ontology 只是初稿，最终由人确认哪些定义准确。自动化和人工审核分开，避免完全依赖模型输出。

工作流分三阶段：

1. 生成阶段：扫描连接的数据库，自动生成 ontology，提取业务术语（比如“客户”对应哪张表）、SQL 属性（字段的语义含义）和关系（表之间的关联方式）。
2. 人工认证阶段：人审阅自动生成的 ontology，确认或修正定义。这是把关语义质量的关键节点。
3. 回答阶段：Agent 基于已认证的 ontology 回答自然语言问题，生成 SQL 查询。

MCP 服务器提供四个只读工具，对应实际使用路径：

• check_readiness：检查 ontology 是否就绪
• search_terms：搜索术语定义
• check_answerable：判断问题能否被当前 ontology 回答
• ask_question：向 Agent 提问并获取回答

调用顺序基本就是接入标准路径：先确认就绪，再查术语，然后判断问题可行性，最后提问。

快速开始：Docker Compose 跑通 Wide World Importers

本地启动需要 Docker Compose v2、uv 包管理器和 NVIDIA API key。示例使用 Microsoft 的 Wide World Importers 示例销售数据库，这是公开的 SQL Server 示例库，用来演示完整流程。

部署方式有两种：Kubernetes 用 Helm chart，本地开发用 Docker Compose。前者适合已有 K8s 基础设施的团队，后者适合试用。

Web UI 提供聊天、分析、数据目录、设置等功能。直接打开浏览器就能开始对话，不必先写代码接入。

三种接入方式

Auto Ontology 设计为给任何 agent harness 提供语义层，不是单机工具。接入路径有三条：

MCP（Model Context Protocol）：任何 MCP 客户端都可以接入。MCP 是 Anthropic 提出的开放协议，Claude Desktop、Cursor 等客户端都能直接使用语义查询能力。服务器提供只读工具，不会让 Agent 直接修改 ontology 或数据库；具体接入配置见仓库中的 mcp 子目录文档（文末链接）。

CLI：适合脚本化调用，比如在 CI/CD 流程中检查 ontology 状态或批量提问。

REST API：提供 POST /api/chat/completions 接口，API token 认证，响应采用 server-sent events 流式输出。接口格式兼容 OpenAI 的 chat completions API，已有 OpenAI SDK 集成的团队可以最小改动接入。

另外，Auto Ontology 与 Apache Ossie 兼容，支持通过 Ossie YAML 格式导入导出模型定义。可以把 ontology 定义当作代码管理，存到 Git 仓库，方便版本管理和跨环境迁移。

数据库覆盖与模型配置

支持十种数据引擎：PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Apache Kyuubi、HeavyDB、DuckDB、SQLite。覆盖主流 OLTP 和 OLAP，从轻量级 SQLite 到云数据仓库 Snowflake、Databricks 都有。

推理使用 NVIDIA NIM 端点。模型配置采用三元组环境变量模式：每个模型有三个变量（_ENDPOINT、_API_KEY、_MODEL），未设置的字段回退到 DEFAULT_MODELS_* 默认值。默认 LLM 是 nvidia/nemotron-3.5-lightning-30b-a3b，embeddings 和 rerank 也有对应默认配置。

官方文档中默认模型命名存在不一致：NVIDIA NIM 部分列出 embeddings 为 nvidia/nemotron-3-embed-1b、rerank 为 nvidia/llama-nemotron-rerank-vl-1b-v2，Models 部分则列出 EMBED 为 nvidia/nemotron-3.5-embed-1b、RERANK 为 nvidia/nemotron-3.5-rerank-8b。另外，REASONING 和 NON_REASONING 的默认模型相同（都是 nemotron-3.5-lightning-30b-a3b），与文档中对后者 “lighter model” 的描述矛盾。配置环境变量时建议显式指定模型名，不要依赖默认值。

预测性问题（比如“预测哪些客户会流失”）可以路由到 KumoRFM 服务，通过 KUMO_RFM_API_KEY 配置，上传表数据有上限。相当于在 text-to-SQL 之外接入了预测分析能力。

安全边界：3001/3002 端口不要暴露

官方文档明确警告：端口 3001 和 3002 应保持在私有网络。原因有两个：

1. FastAPI 信任前端转发的 x-auto-ontology-user-id 头。服务暴露到公网后，攻击者可以伪造请求头冒充任意用户。
2. ingestion 服务端点没有自己的认证机制。数据接入服务不带鉴权，依赖网络隔离保证安全。

这个设计适合内网部署或 VPN 环境，不适合直接暴露到互联网。对外提供服务需要在前置层加认证网关（API Gateway 或反向代理），不能依赖 Auto Ontology 自身的鉴权。

效果验证：auto-ontology-eval

单独的仓库 auto-ontology-eval 用于衡量 Auto Ontology 对 text-to-SQL 准确率的提升，支持 BIRD、BEAVER、FDABench-Lite、Wide World Importers 等基准。覆盖这些基准，说明 NVIDIA 在尝试用标准数据集验证语义层的效果。

官方尚未公布具体准确率数值。评测仓库提供了自行复现的路径，效果数据需要自己运行才能得到。

限制与选型判断

Auto Ontology 采用 Apache License 2.0，可以自由使用和修改，但项目明确不接受外部贡献。即使发现 bug 或想要新增功能，也不能通过 PR 回馈上游。适合企业内部使用，不适合希望参与开源项目的开发者。

推理依赖 NVIDIA NIM 端点，意味着需要使用 NVIDIA 的模型服务，整体设计围绕 NIM 生态构建。虽然可以通过环境变量配置模型端点，但云服务依赖是存在的。

选型时需要注意几个信息缺口：项目没有正式发布日期和版本号，生产环境的性能、稳定性、社区活跃度和维护频率只能通过实测判断。如果业务涉及中文问数，需要先在测试环境验证；长期维护节奏存在不确定性，使用周期较长的核心业务场景要重点关注。

Auto Ontology 的定位是 Text-to-SQL 链路上的语义中间层，解决“模型不理解数据模型”的问题，不负责数据库连接或查询执行。如果你正在用 MCP 作为 Agent 接入协议，需要统一语义层理解企业数据，它值得做原型验证。开箱提供 Web UI、MCP 工具、API 三种使用方式，还有独立评测仓库可以量化语义层带来的准确率提升。

生产环境部署前，需要先解决两个问题：NIM 端点依赖是否可接受，3001/3002 端口的认证缺失能否用额外网关弥补。考虑到项目不接受外部贡献，如果开发方向与内部需求不一致，你无法影响上游演进。

资料来源与项目地址

• 产品仓库：https://github.com/NVIDIA/auto-ontology.git
• 评估仓库：https://github.com/NVIDIA/auto-ontology-eval.git
• MCP 服务器文档：https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp