自动本体

自动本体

智能体可以检索文档和查询数据库，但可靠性是智能体分析的关键：如果数字错误，即使回答速度更快，收入指标也没有价值。智能体需要一个上下文层，告诉它们数据在哪里，它的含义是什么，是否可以使用它，如何使用它，它来自哪里，以及什么是相似的。NVIDIA Auto Ontology 是一个开源库，它从企业元数据构建这一层，在系统间协调定义，并通过 MCP、CLI 和 API 向任何智能体工具提供这一层。它补充了客户已经拥有的语义模型。

它使开发者能够：

• 发现：从元数据生成企业本体；连接现有的本体和语义模型；构建 AI 准备的知识图谱。
• 归一化：为指标、实体和关系提供智能体可信赖的业务含义；协调系统间不一致的定义。
• 验证：将生成的查询与认证的定义和来源进行核对；每个答案都返回来源。
• 暴露：通过 MCP、CLI 和 API 向任何智能体工具提供上下文。 学习：将认证的纠正和用法反馈到本体中，以便每个问题都能提高共享上下文。

基准测试

要运行文本到 SQL 的基准测试，如 BIRD，请参考本体 SQL 评估存储库。

许可和贡献。 Auto Ontology 在 Apache License 2.0 下分发。该项目捆绑、链接或以其他方式使用的第三方开源组件列在 THIRD_PARTY_NOTICES.md 中。 该项目目前不接受外部贡献。

关键特性

• 自然语言查询 结构化数据 — 问题被转换为 SQL 并在连接的数据库上执行，由 NVIDIA NIM 提供支持。
• 语义目录/本体层 在关系源上，存储在描述的目录旁边的 Postgres 中。
• 身份验证 & RBAC —使用 Better Auth。
• Web UI 用于聊天、分析、数据目录、分析和设置。
• 灵活部署 — Helm 图表用于 Kubernetes 或 Docker Compose 用于本地堆栈。

软件组件

NVIDIA NIM

自动本体使用 NVIDIA NIM 端点进行推理——无论是托管 NVIDIA API 目录（integrate.api.nvidia.com）还是自托管 NIM。在 .env.example 中的默认设置是：

• LLM: nvidia/nemotron-3.5-lightning-30b-a3b
• 嵌入: nvidia/nemotron-3-embed-1b
• 重排序: nvidia/llama-nemotron-rerank-vl-1b-v2

端点和模型通过 DEFAULT_MODELS_ENDPOINT、DEFAULT_MODELS_MODEL、EMBED_ENDPOINT 和 EMBED_MODEL 环境变量进行配置，并需要一个 DEFAULT_MODELS_API_KEY。

模型三元组

每个模型角色由一个 三元组 环境变量配置——<PREFIX>_ENDPOINT（URL）、<PREFIX>_API_KEY 和 <PREFIX>_MODEL：

您可以设置完整的三元组，仅设置其部分字段，或完全不设置——任何未设置的字段都将回退到匹配的 DEFAULT_MODELS_<FIELD>。因此，最简单的设置是填写 DEFAULT_MODELS_*，并仅覆盖三元组中不同的字段（例如 EMBED_MODEL、NON_REASONING_MODEL）。*_API_KEY 也回退到向后兼容的 NVIDIA_API_KEY。

快速入门

此操作使用 Docker Compose 运行 Auto-Ontology，针对微软的示例销售数据库 Wide World Importers。您需要 Docker 和 Compose v2、uv 以及从 build.nvidia.com 获取的 NVIDIA API 密钥（nvapi-...）。

1. 克隆存储库并创建 .env:

   git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
   cp .env.example .env
   

   然后在 .env 中设置这些值：

   DEFAULT_MODELS_API_KEY=nvapi-...
   AUTH_SECRET=<a long random string, e.g. from openssl rand -base64 32>
   APP_URL=http://localhost:3000
   POSTGRES_PASSWORD=<a new password>
   CONNECTION_STRINGS=postgresql://postgres:<the same password>@postgres:5432/wideworldimporters
   AUTO_ONTOLOGY_ADMIN_PASSWORD=<a new password>
   PGADMIN_PASSWORD=<a new password>
   

   Compose 在主机上发布 Postgres、pgAdmin 和 Web 应用程序，因此在启动之前，请替换每个默认密码。 .env.example 还为每个模型角色设置一个 API 密钥：将每个 nvapi-your-api-key-here 替换为您自己的密钥，或者删除这些行，以便它们回退到 DEFAULT_MODELS_API_KEY。

2. 启动 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='<the same password>' \
     uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)
   

3. 构建并启动其余的堆栈：

   docker compose up -d --build
   

4. 打开 http://localhost:3000 并使用 AUTO_ONTOLOGY_ADMIN_EMAIL 和 AUTO_ONTOLOGY_ADMIN_PASSWORD 从 .env 登录。转到 设置 → 语义编译 并将其打开。在启动时运行摄取；编译立即开始，并在完成后报告 语义编译就绪。

5. 在 聊天 中提出问题：

   2015年6月宾夕法尼亚州USB食品闪存盘-寿司卷的收入是多少？

   代理将 收入、产品 和 州 解析为本体中的术语，根据它们的关系跟踪到所需的连接，并运行查询。答案将带有其 SQL 和生成它的步骤返回，因此您可以检查结果与源数据的一致性：

   Answer:  Revenue for USB food flash drive - sushi roll in Pennsylvania in
            June 2015 was $588.80, from 3 invoice lines.
   
   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'
   
   Steps:   Resolved terms: Invoice Line (revenue), Stock Item, State Province, Invoice
            Joined: invoice line -> invoice -> customer -> city -> state province
            Validated the filter values against the data, then executed
   

6. 提出数据无法回答的问题。Wide World Importers 没有广告数据，因此关于广告支出的问题没有可以解析的内容。通过 MCP 连接的代理首先检查可回答性，并要求您澄清：

   You:    What was return on ad spend for the sushi roll flash drive in June 2015?
   Agent:  check_answerable -> coverage 0.5; no term covers "ad spend"
   Agent:  I can find revenue for that product, but this data has no
           advertising spend, so I can't compute return on ad spend. Do you
           want June 2015 revenue instead, or is ad spend tracked in another
           source I should connect?
   

如果重启后 UI 加载时没有左侧导航，则浏览器正在保留一个过期的会话 cookie。清除 localhost:3000 的站点数据并重新登录。对于其他设置故障，请参阅设置技能的故障排除指南。

工作原理

Auto-Ontology 在三个阶段工作：它生成本体，人们对其进行认证，代理回答相关问题。

本体包含三种类型的定义：

• 术语。 如 客户 或 发票行 这样的业务概念，每个术语都有一个描述和同义词，映射到存储它们的列。
• SQL 属性。 在术语下的审查过的 SQL 表达式，例如利润或滚动总计。代理重用它们，因此答案以相同的方式计算每个度量。
• 关系。 表如何连接，包括从键和数据中推断出的桥接表。

生成。 数据摄取服务从源数据库构建一个初步草案：

1. 读取源：从目录中提取模式、配置列和样本值。
2. 命名实体：逐表提取术语，并将每个术语映射到列。
3. 解析关系：推断表和桥接表之间的连接，并从查询历史中建议 SQL 属性。
4. 写入本体：将术语、关系和 SQL 属性存储在 Postgres 中，使用 pgvector 进行嵌入以进行检索。

结果是您可以在 UI 中探索的语义图。在这个例子中，Wide World Importers 的一次编译产生了 31 个术语；选择 订单 显示其描述、相关术语、映射列和 SQL 属性：

认证。 人们使草案变得可信：

1. 在 Chat 中使用真实问题进行测试，或在 check_answerable 和 ask_question 上通过 MCP 进行测试。
2. 在 UI 或通过 API 中精炼术语、描述和 SQL 属性。
3. 一旦正确，就认证名称、描述和 SQL 属性。

回答。 对于每个问题，代理：

1. 对意图进行分类并提取问题中命名的实体。
2. 通过嵌入搜索检索候选术语、列和 SQL 属性。
3. 从这些候选者中编写 SQL。
4. 检查过滤器值和查询与数据库，当检查失败时修复 SQL。
5. 运行查询并返回答案，包括其 SQL 和所采取的步骤。

当候选者无法支持查询时，代理报告说无法从这些数据中回答该问题。当配置了 KumoRFM 时，预测性问题会发送到 KumoRFM（请参阅预测）。

在 Chat 中，每个答案都会显示其 SQL，您可以查看行、将其下载为 CSV 或以图表形式读取：

Auto-Ontology 与 Apache Ossie 兼容，这是交换语义模型的开标准。Ossie 包含一个用于 Auto-Ontology 的转换器， Auto-Ontology 使用它来导入和导出模型定义作为 Ossie YAML。使用 设置 → 导入/导出，或 POST /api/model/import 和 POST /api/model/export。

请将端口3001和3002保持在私有网络中。FastAPI信任前端在x-auto-ontology-user-id头中转发的用户身份，摄取服务的端点（摄取、删除、重置、编译）没有自己的身份验证。客户端通过端口3000上的Web应用程序进行访问。

从您的代理使用

MCP服务器

MCP服务器为任何MCP客户端提供对本体的只读工具。每个用户通过Auto-Ontology登录，每个调用都使用该用户的权限运行。

在您的部署上运行服务器：

AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
  uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp

光标（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "auto-ontology": { "url": "http://localhost:3003/mcp" }
  }
}

Claude桌面（claude_desktop_config.json），通过mcp-remote桥接：

{
  "mcpServers": {
    "auto-ontology": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3003/mcp"]
    }
  }
}

编辑配置后重新启动客户端，然后根据提示登录。登录、配置和故障排除在docs/mcp.md中。

代理技能

三个技能教导编码代理与Auto-Ontology一起工作。从AGENTS.md开始。

REST API

在Web应用程序的原地使用POST /api/chat/completions提问。在用户菜单→ API令牌下创建API令牌。响应是一个服务器发送的事件流：一个result事件携带答案，而data: [DONE]结束流。

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?"}'

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中。其他所有操作都在OpenAPI规范中。

连接器、模型和预测

来源

Auto-Ontology 连接到十个引擎：

• PostgreSQL
• MySQL
• Databricks
• Snowflake
• ClickHouse
• Trino
• Apache Kyuubi
• HeavyDB
• DuckDB
• SQLite

在 设置 → 连接 下添加连接，或在 CONNECTION_STRINGS 中列出它们。DuckDB 和 SQLite 只需连接字符串。有关 URL 方案、作用域和凭据存储，请参阅 docs/connections.md。

模型

Auto-Ontology 使用四个模型角色。使用 nvapi- 密钥，每个默认为 build.nvidia.com 上的 NVIDIA NIM：

要使用自托管 NIM 或任何与 OpenAI 兼容的端点，设置 <ROLE>_ENDPOINT、<ROLE>_API_KEY 和 <ROLE>_MODEL。任何未设置的字段都将回退到 DEFAULT_MODELS_<FIELD>，因此最简单的设置只填写 DEFAULT_MODELS_* 并覆盖不同的部分。使用支持结构化输出的模型，并保持嵌入模型在摄入和查询中相同。 .env.example 记录每个变量。

预测

设置 KUMO_RFM_API_KEY，代理将预测性问题路由到 KumoRFM。 KumoRFM 是一个托管服务：为了回答，代理将连接的表上传到它，上限为 KUMO_MAX_TABLES（默认为 20）和 KUMO_MAX_ROWS_PER_TABLE（除非设置，否则为无限）。在启用它之前，请检查它发送的内容，并完成您组织的资料审查。

与我们集成

要将代理平台、应用程序或存储提供商与 Auto-Ontology 集成，请提交集成请求。

Auto-Ontology 团队维护代码，不接受外部拉取请求。集成请求和错误报告作为问题欢迎。通过 SECURITY.md 报告安全漏洞。维护者工作流程在 CONTRIBUTING.md 中。

参考

注意事项和免责声明

注意事项和免责声明：本软件自动检索、访问或与外部材料交互。检索到的材料不随本软件分发，并仅受单独的条款、条件和许可证的约束。您负责自行查找、审查和遵守所有适用的条款、条件和许可证，并验证任何检索到的材料对您特定用例的安全性、完整性和适用性。本软件按“原样”提供，不提供任何类型的保证。作者不对任何检索到的材料做出任何陈述或保证，也不对您使用或无法使用本软件或任何检索到的材料造成的任何损失、损害、责任或法律后果承担任何责任。自行承担使用本软件和检索到的材料的风险。

运行时 Auto-Ontology 交互的外部材料：

• 您配置的模型端点，默认为 NVIDIA API 目录（integrate.api.nvidia.com、ai.api.nvidia.com），在各个提供商和模型的条款下。
• 当 KUMO_RFM_API_KEY 设置时，仅与 KumoRFM 服务交互，在 Kumo 的条款下。
• 您的源数据库，在您与这些系统的协议下。

安全

按照 SECURITY.md 中描述的方式报告安全漏洞。

原文：auto-ontology（机器翻译，仅供参考）