10 个关键问题Q&A
-
Q：Auto-Ontology 是做什么的？ A：给查询企业数据的 AI 智能体提供统一语义本体，减少 Text-to-SQL 错误回答。 -
Q：它和直接把数据库 Schema 放进提示词有什么区别？ A：只加载问题相关术语，有业务定义、认证指标、预解析关联，还能提前判断问题能不能回答。 -
Q：本体包含哪三类核心内容？ A：业务术语、经过审核的 SQL 指标、表之间关联关系。 -
Q：支持哪些数据库？ A：PostgreSQL、MySQL、Snowflake、Databricks、ClickHouse、Trino、Kyuubi、HeavyDB、DuckDB、SQLite。 -
Q：怎么接入自己的 Agent？ A：MCP 服务、REST API、内置三套 Agent 技能三种方式。 -
Q：MCP 有什么作用？ A：标准化只读工具集，Cursor、Claude 等 MCP 客户端可直接调用本体检索、可答性检查、问答。 -
Q：模型是否必须用 NVIDIA Nemotron？ A：默认 Nemotron，也支持 OpenAI 兼容的私有 NIM 端点，四类角色模型可单独配置。 -
Q：评测怎么开展？ A：配套 auto-ontology-eval 仓库，在 BIRD、BEAVER 等数据集做对照实验，对比 “原始 Schema” 和 “本体” 两条链路准确率。 -
Q：是否兼容其他语义模型？ A：支持 Apache Ossie 标准，可导入导出 Ossie YAML 语义模型。 -
Q：开源协作规则？ A：Apache2.0 许可，不接收外部 PR，Bug、集成需求提交 Issue。 附录 英伟达uto-Ontology
Auto-Ontology：一套开放上下文层，助力智能体在企业数据场景下减少错误回答。
为什么需要 Auto-Ontology
智能体固然可以检索文档、查询数据库，但可靠性才是智能分析能否落地的关键：就算营收数据返回得再快，如果结果是错的，这份数据就毫无价值。智能体在发起查询前，需要清楚数据存放在哪里、数据代表什么含义、是否可以使用、该如何使用、数据来源，以及哪些数据是相似的。
Auto-Ontology 是一套可和数据库配套部署的服务，用来给智能体提供上述上下文信息。它会把数据库元数据编译成本体（ontology）：业务术语与数据表字段的映射、经过人工复核的指标 SQL，以及表与表之间的关联关系。智能体基于这套本体发起查询，业务人员可以在网页界面对本体内容审核管理。它可以和你现有的语义模型协同使用。
借助 Auto-Ontology，开发人员可以实现这些能力：
- 发现
从数据库元数据自动生成本体、导入已有语义模型，并以语义图的形式浏览成果。 - 锚定
为同一个业务概念提供唯一标准定义，打通跨表、跨库的映射关系。 - 认证
在网页 UI 或者 API 里审阅、编辑、认证术语定义。 - 校验
在执行查询前先判断问题是否可回答；每次返回结果时，附带生成的 SQL 以及智能体完整推理步骤。 - 对外暴露能力
通过 MCP、智能体技能、REST API，向上游任意智能体框架提供语义上下文。
以往常见的简易方案，是直接把数据表结构塞进智能体上下文窗口。二者对比如下：
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
评估
配套仓库：auto-ontology-eval，用于在各类基准集上衡量本体能力、开展评测。
支持 BIRD、BEAVER、FDABench-Lite、Wide World Importers 数据集。每一条评测样本都包含自然语言问题与标准答案 SQL。评测时，用同一个模型分别走两条对照链路：
-
对照组：模型提示词中直接放入数据库表结构 -
实验组：由 Auto-Ontology 的问答智能体，基于编译好的本体回答问题
由确定性校验器比对两条链路输出 SQL 的执行结果，按照基准集官方规则打分。评测报告会给出准确率差值，同时列出本体修复了哪些问题、新增了哪些错误。 BIRD-Interact 是支持多轮对话、智能体需要主动追问澄清的基准集，使用独立评测框架运行。
如果你想基于 BIRD 数据集复现对比实验，先部署 auto-ontology-eval，然后执行：
uv run python main.py --database-name bird
快速上手
本方案使用 Docker Compose，对接微软示例销售数据库 Wide World Importers。前置要求：带 Compose v2 的 Docker、uv 工具，以及来自 build.nvidia.com 的 NVIDIA API Key（前缀 nvapi-）。
拉取代码并配置环境变量：
git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env
在 .env里填写这些配置项：
DEFAULT_MODELS_API_KEY=nvapi-...
AUTH_SECRET=<一串随机长字符串，例如 openssl rand -base64 32 生成>
APP_URL=http://localhost:3000
POSTGRES_PASSWORD=<自定义新密码>
CONNECTION_STRINGS=postgresql://postgres:<上面同一个密码>@postgres:5432/wideworldimporters
AUTO_ONTOLOGY_ADMIN_PASSWORD=<自定义管理员密码>
PGADMIN_PASSWORD=<pgadmin密码>
Compose 会把 Postgres、pgAdmin、Web 应用暴露到主机端口，务必修改全部默认密码。 .env.example 支持为每一类模型角色单独配置密钥；如果你不需要单独配置，可以删掉对应行，自动回退使用 DEFAULT_MODELS_API_KEY。
启动 Postgres 并导入示例数据集，初始化脚本在 auto-ontology-eval 仓库，传入你刚才设置的 Postgres 密码：
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='<和上面一致的密码>' \
uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)
构建并启动其余服务：
docker compose up -d --build
访问 http://localhost:3000/，使用 .env 中配置的 AUTO_ONTOLOGY_ADMIN_EMAIL 和 AUTO_ONTOLOGY_ADMIN_PASSWORD 登录。进入【设置 → 语义编译】并开启该功能。服务启动时会自动执行数据摄入，编译就绪后会提示 Semantic compilation is ready。
在对话页面提问示例：
What was revenue for the USB food flash drive - sushi roll in Pennsylvania in June 2015? 2015 年 6 月，宾夕法尼亚州，寿司卷造型 USB 闪存盘的营收是多少？
智能体会把「营收」「产品」「州」解析成本体里的标准术语，沿着预定义关联找到表连接关系，执行查询。返回结果附带 SQL 和推理步骤，方便核对数据源：
答案：2015 年 6 月宾夕法尼亚州，寿司卷造型 USB 闪存盘营收为 588.80 美元，共 3 条发票明细。 SQL：
SELECT SUM(il.extendedprice) AS revenue, COUNT(*) AS invoice_lines
FROM sales.invoicelines il
JOIN sales.invoices i ON il.invoiceid = i.invoiceid
JOIN warehouse.stockitems si ON il.stockitemid = si.stockitemid
JOIN sales.customers c ON i.customerid = c.customerid
JOIN application.cities ct ON c.deliverycityid = ct.cityid
JOIN application.stateprovinces sp ON ct.stateprovinceid = sp.stateprovinceid
WHERE si.stockitemname = 'USB food flash drive - sushi roll'
AND sp.stateprovincename = 'Pennsylvania'
AND i.invoicedate >= '2015-06-01' AND i.invoicedate < '2015-07-01'
推理步骤： 解析术语：发票明细（营收）、库存商品、省 / 州、发票 关联链路：发票明细 → 发票 → 客户 → 城市 → 省 校验过滤条件合法性，随后执行查询
你也可以问一份当前数据无法回答的问题：Wide World Importers 没有广告投放数据。通过 MCP 接入的智能体会先做可答性校验，主动澄清：
用户：寿司卷 U 盘在 2015 年 6 月的广告投入回报率是多少？ 智能体：执行 check_answerable → 覆盖度 0.5；本体没有 “广告投入” 相关术语 智能体：我可以查到该产品的营收，但当前数据集没有广告投放数据，无法计算广告回报率。您需要我直接给出 2015 年 6 月营收吗？还是广告数据保存在其他数据源，需要我接入？
如果重启服务后网页左侧导航栏消失，是浏览器缓存了过期会话 Cookie。清空 localhost:3000 的站点数据，重新登录即可。其他部署故障，参考文档 skills/nvidia-ontology-setup/references/troubleshooting.md。
工作原理
Auto-Ontology 分为三大阶段：生成本体、人工认证本体、智能体基于本体回答问题。
本体包含三类定义：
- 术语（Terms）
业务概念，例如客户、发票明细，附带描述、同义词，映射到对应数据表字段。 - SQL 属性（SQL attributes）
绑定在术语下、经过复核的 SQL 表达式，例如毛利率、滚动汇总指标。智能体可复用，保证同一个指标计算口径统一。 - 关联关系（Relationships）
表之间的连接规则，包含中间桥接表，从主键、数据内容自动推断。
1. 生成本体（Generate）
摄入服务从源数据库自动生成初稿本体：
-
读取数据源：提取表结构、字段画像、采样值，存入数据目录 -
识别实体：逐表提取业务术语，映射到字段 -
解析关联：推断表连接、桥接表，也可以从历史查询记录中推荐指标 SQL -
写入本体：术语、关联、指标 SQL 存入 Postgres；向量存入 pgvector 用于检索
产出的语义图可以在 UI 上浏览。示例中 Wide World Importers 编译后一共生成 31 个术语；选中【订单】，可以查看描述、关联术语、绑定字段、绑定指标 SQL。
2. 人工认证（Certify）
人工审核，让初稿本体可信可用：
-
在对话界面测试真实业务问题，或者通过 MCP 调用 check_answerable、ask_question -
在 UI 或者 API 中优化术语、描述、指标 SQL -
内容确认无误后，对名称、描述、SQL 指标打上认证标记
3. 问答（Answer）
收到用户问题后，智能体执行流程：
-
识别意图，提取问题里的实体 -
向量检索匹配候选术语、字段、指标 SQL -
基于候选内容生成 SQL -
校验过滤值与 SQL 合法性，发现问题自动修复 SQL -
执行查询，返回答案、SQL、完整推理步骤
如果候选本体信息不足以支撑查询，智能体直接告知当前数据无法回答该问题。如果配置了 KumoRFM，预测类问题会路由到该服务。
对话界面每条回答都附带 SQL，支持查看原始行、导出 CSV、展示图表。
Auto-Ontology 兼容 Apache Ossie（语义模型交换开源标准）。Ossie 提供 NVIDIA 转换器，Auto-Ontology 支持导入、导出 Ossie YAML 格式模型。入口：【设置 → 导入 / 导出】，或者调用接口 POST /api/model/import、POST /api/model/export。
组件、技术栈、端口
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
3001、3002 端口建议仅在内网开放。前端向后透传
x-auto-ontology-user-id身份头给后端 FastAPI；摄入服务接口（摄入、删除、重置、编译）本身没有鉴权，外部调用必须走 3000 前端网关。
在你的智能体里接入MCP Server
遵循 Model Context Protocol 标准，MCP 服务为所有 MCP 客户端提供本体只读工具。用户先在 Auto-Ontology 登录，每次调用继承该用户权限。
可用工具清单：
-
就绪检测： check_readiness：检查实例是否可正常提供服务 -
术语相关： search_terms、get_term、get_term_columns、get_term_sql_attributes、get_sql_attribute、describe_table -
可答性： check_answerable：判断本体是否覆盖当前问题 -
问答： ask_question：返回答案、SQL、原始数据行
启动 MCP 服务：
AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp
Cursor 配置（~/.cursor/mcp.json）
{
"mcpServers": {
"auto-ontology": { "url": "http://localhost:3003/mcp" }
}
}
Claude Desktop 配置，借助 mcp-remote 桥接：
{
"mcpServers": {
"auto-ontology": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:3003/mcp"]
}
}
}
修改配置后重启客户端，按提示登录。登录、配置、排错文档：docs/mcp.md
Agent Skills（智能体技能包）
三套技能，教会编码智能体使用 Auto-Ontology，入口文档 AGENTS.md
-
nvidia-ontology-setup：安装、连接数据源、编译、验证就绪状态 -
nvidia-ontology-management：查看、建模、认证、导入导出、发布本体 -
nvidia-ontology-query：提问、校验 SQL、校验结果
REST API
调用问答接口：POST /api/chat/completions，在用户菜单【API Tokens】生成访问令牌。接口返回 SSE 流式事件，result事件承载答案，data: [DONE]标记流结束。
curl 示例：
curl -N http://localhost:3000/api/chat/completions \
-H "x-api-key: $AUTO_ONTOLOGY_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"question": "How many orders shipped last week?"}'
Python 示例：
import json
import os
import requests
response = requests.post(
"http://localhost:3000/api/chat/completions",
headers={"x-api-key": os.environ["AUTO_ONTOLOGY_API_TOKEN"]},
json={"question": "How many orders shipped last week?"},
stream=True,
timeout=900,
)
response.raise_for_status()
for line in response.iter_lines(decode_unicode=True):
if not line or not line.startswith("data:"):
continue
payload = line.removeprefix("data:").strip()
if payload == "[DONE]":
break
event = json.loads(payload)
if event["type"] == "result":
print(event["answer"]["response"])
print(event["answer"]["sql_code"])
elif event["type"] == "error":
raise RuntimeError(event["message"])
事件类型、多轮对话、网关信任边界见 docs/conversation-api.md。其余全部接口定义见 docs/openapi/auto-ontology-api.json。
连接器、模型、预测能力
数据源支持
Auto-Ontology 可对接 10 种数据库引擎： PostgreSQL、MySQL、Databricks、Snowflake、ClickHouse、Trino、Apache Kyuubi、HeavyDB、DuckDB、SQLite
连接配置入口：【设置 → Connections】，也可以写在 CONNECTION_STRINGS 环境变量。DuckDB、SQLite 仅支持连接字符串方式配置。连接地址格式、权限隔离、凭据存储：docs/connections.md
模型角色
一共 4 类模型角色；配置 nvapi 密钥时，默认使用 NVIDIA NIM（build.nvidia.com）
|
|
|
|
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
你可以使用私有化部署 NIM，或是任意兼容 OpenAI 协议的端点：配置 <ROLE>_ENDPOINT、<ROLE>_API_KEY、<ROLE>_MODEL。未单独配置的角色自动回退 DEFAULT_MODELS_*。 要求模型支持结构化输出；摄入阶段和查询阶段必须使用同一个 Embedding 模型。所有环境变量说明在 .env.example。
预测能力
配置 KUMO_RFM_API_KEY后，预测类问题会转发到 KumoRFM 托管服务。转发时会上传关联数据表，默认上限：KUMO_MAX_TABLES=20，KUMO_MAX_ROWS_PER_TABLE 不限制。开启前请审阅数据上传范围，完成企业数据合规审查。
集成对接
如果你要对接智能体平台、应用、存储厂商，新建 Issue，选择 integration.yml 模板提交。
项目由 NVIDIA 团队维护，不接受外部 Pull Request；Bug 反馈、集成需求欢迎提 Issue。安全漏洞按照 SECURITY.md 里的方式上报。维护者开发流程文档：CONTRIBUTING.md
参考文档索引
-
Helm 部署 K8s：DEPLOYMENT.md -
数据源连接、权限隔离、Vault 凭据：docs/connections.md -
认证、SSO、API 令牌：docs/authentication.md -
对话流式 API：docs/conversation-api.md -
MCP 服务：docs/mcp.md -
OpenAPI 接口规范：docs/openapi/auto-ontology-api.json
许可证
Auto-Ontology 使用 Apache-2.0 协议。SPDX 标识：Apache-2.0 NVIDIA 编写的源码文件头部都带有 SPDX 声明：
SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. SPDX-License-Identifier: Apache-2.0
项目用到的第三方开源组件清单与上游许可证见 THIRD_PARTY_NOTICES.md；容器镜像内额外依赖见 CONTAINER_THIRD_PARTY_NOTICES.md
声明与免责声明
NOTICE AND DISCLAIMER: 本软件会自动读取、访问外部资源。这些外部资源不随本软件分发，受对应服务方协议约束。您需要自行审阅、遵守相关条款，并独立核验所有外部资源的安全性、完整性、适用性。 本软件按现状提供，不附带任何明示或默示担保。作者不对您使用本软件、无法使用本软件造成的损失、损害承担任何责任。您自行承担使用风险。
运行时会交互的外部资源：
-
你配置的模型端点，默认是 NVIDIA API 目录（integrate.api.nvidia.com、ai.api.nvidia.com），遵循对应服务商协议 -
仅配置 KUMO_RFM_API_KEY 时才会访问 KumoRFM，遵循 Kumo 协议 -
你接入的业务数据库，遵循你和数据库服务商的协议
安全
安全漏洞上报方式，见 SECURITY.md