NVIDIA/auto-ontology

来源：https://github.com/NVIDIA/auto-ontology

Auto Ontology

Agent 可以检索文档、查询数据库，但 agentic 分析的可靠性才是关键：一个回答得更快的收入指标，如果数字是错的，就毫无价值。Agent 需要一个上下文层，告诉它们数据在哪里、含义是什么、是否该用它、如何使用它、来自哪里，以及哪些数据与之相似。

NVIDIA Auto Ontology 是一个开源库，用于从企业元数据构建这个上下文层，在各系统之间对齐指标定义，并通过 MCP、CLI 和 API 将其提供给任意 agent 框架。它与客户已有的语义模型互补，使开发者能够：

• 发现（Discover）：从元数据生成企业本体；连接现有本体和语义模型；构建面向 AI 的知识图谱。
• 接地（Ground）：为指标、实体和关系提供可信的业务语义；对齐各系统间不一致的定义。
• 校验（Validate）：依据经过认证的定义与数据血缘检查生成的查询；每个答案都附带来源溯源。
• 暴露（Expose）：通过 MCP、CLI 和 API 将上下文提供给任意 agent 框架。
• 学习（Learn）：将经过认证的修正和使用反馈回流到本体中，使共享上下文随每一次提问不断改进。

基准测试

要运行 BIRD 等 text-to-SQL 基准测试，请参考 ontology SQL 评估仓库（https://github.com/NVIDIA/ontology-sql-eval/）。

许可与贡献。 Auto Ontology 以 Apache License 2.0 发布。 本项目打包、链接或以其他方式使用的第三方开源组件列在 THIRD_PARTY_NOTICES.md 中。 本项目目前不接受外部贡献。

核心特性

• 自然语言查询结构化数据 —— 将问题转换为 SQL 并在已连接的数据库上执行，由 NVIDIA NIM 驱动。
• 关系型数据源之上的语义目录 / 本体层，存储在与其描述的目录相同的 Postgres 中。
• 认证与 RBAC —— 使用 Better Auth（https://github.com/better-auth/better-auth）。
• Web UI，涵盖聊天、分析、数据目录、分析看板与设置。
• 灵活部署 —— 提供 Kubernetes 的 Helm chart，或使用 Docker Compose 在本地运行整套服务。

软件组件

NVIDIA NIM

Auto Ontology 使用 NVIDIA NIM 端点进行推理 —— 可以是托管的 NVIDIA API 目录（https://build.nvidia.com）（integrate.api.nvidia.com），也可以是自托管的 NIM。.env.example 中的默认值为：

• LLM： nvidia/nemotron-3-nano-30b-a3b
• Embeddings： nvidia/nemotron-3-embed-1b
• Reranking： nvidia/llama-nemotron-rerank-vl-1b-v2

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

模型三元组

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

你可以设置完整的三元组、仅设置其中部分字段，或完全不设置 —— 任何未设置的字段都会回退到对应的 DEFAULT_MODELS_。因此最简单的配置方式是填写 DEFAULT_MODELS_*，仅在有差异时覆盖单个三元组的字段（例如 EMBED_MODEL、NON_REASONING_MODEL）。*_API_KEY 也会出于向后兼容回退到旧的 NVIDIA_API_KEY。

部署

前置条件

• Docker 及 Docker Compose v2（例如 macOS/Windows 上的 Docker Desktop，Linux 上的 Docker Engine），用于本地运行整套服务。Kubernetes 部署请参见 DEPLOYMENT.md。
• 一个 NVIDIA API key（nvapi-...），用于 NVIDIA NIM（聊天与摄取），可从 NVIDIA API 目录获取。
• 你要查询的源数据库的连接信息（Databricks、Postgres、Snowflake 或 DuckDB）。

安装

Kubernetes

在 Kubernetes 集群上部署 Auto Ontology，请参见 DEPLOYMENT.md。

本地（Docker Compose）

1. 克隆仓库：

   git clone auto_ontology && cd auto_ontology
   

2. 根据模板创建环境文件（.env）并填写各项值（Postgres 凭据、DEFAULT_MODELS_API_KEY、CONNECTION_STRINGS 等）。完整变量列表请参见 .env.example：

   cp .env.example .env
   # 编辑 .env
   

   注意：

   • AUTH_SECRET 和 APP_URL 是必需的 —— 缺少它们会导致每个页面都因 Better Auth 的 “default secret” 错误而失败。
   • POSTGRES_PORT 仅更改宿主机侧的端口映射（如果你机器上 5432 已被占用可设置它）；容器始终通过内部网络端口访问 Postgres。

3. 构建镜像并启动整套服务：

   docker compose up -d --build
   

   这会构建后端（auto_ontology）和前端（auto-ontology-frontend）镜像，启动 Postgres 和 pgAdmin，运行一次性的 frontend-migrate 任务以同步数据库 schema，并启动应用（后端、摄取服务和前端）。

4. 打开 UI（后端 API 位于 :3001，pgAdmin 位于 :5050）。

故障排查： 如果 UI 加载后缺少左侧导航面板 （或重启后看起来不正常），说明浏览器持有一个过期的会话 cookie —— 这通常发生在 AUTH_SECRET 变更或数据库被重置之后。 清除 localhost:3000 的站点数据（或删除 better-auth.session_token cookie）后重新登录即可。

连接管理

Auto Ontology 从两个来源解析其连接的源数据库：

1. 通过 UI 添加 —— 在应用内部创建的连接。使用此选项时，连接凭据以明文存储在 Postgres 中，除非配置了 Vault：

   • 未配置 Vault： 完整的连接对象（包括密码）会被 JSON 序列化后未加密地存储在目录的数据库行上。
   • 配置了 Vault： 凭据会以数据库名称为键写入 Vault，目录行中不存储任何凭据（数据库名称即查找键 —— 没有单独的引用字段）。Vault 仅在 VAULT_ADDR、VAULT_NAMESPACE、VAULT_ROLE_ID 和 VAULT_SECRET_ID 全部设置时才会启用（VAULT_AUTH_MOUNT 和 VAULT_KV_MOUNT 是可选的覆盖项）。默认关闭；配置不完整时会给出警告并忽略，回退到明文存储。

2. CONNECTION_STRINGS 环境变量 —— 部署时提供的以逗号分隔的连接字符串列表（例如 Helm 的 --set connectionStrings= 参数）。这是一种回退机制：仅在没有通过 UI 添加的连接时才会使用。

认证

Auto Ontology 支持 SSO 认证。重定向 URI 应在 IdP 中配置为：

APP_URL/api/auth/sso/callback

API token（脚本用途）

浏览器登录后会获得会话 cookie，而脚本无法获取它。对于脚本、notebook 和定时任务，请改用API token：

1. 打开用户菜单（右上角）→ API Tokens → New token。
2. 为其命名，可选择过期时间（默认：永不过期），然后复制该 token。

Auto Ontology 只存储其 SHA-256 哈希值，因此 token 只会显示一次。丢失后只能重新生成。在任何 /api/... 调用中通过 x-api-key 发送它 —— Authorization: Bearer 也同样可用：

curl -H "x-api-key: $AUTO_ONTOLOGY_API_TOKEN" https://auto_ontology.example.com/api/terms

import os
import requests

session = requests.Session()
session.headers["x-api-key"] = os.environ["AUTO_ONTOLOGY_API_TOKEN"]

terms = session.get("https://auto_ontology.example.com/api/terms").json()

answer = session.post(
    "https://auto_ontology.example.com/api/chat/completions",
    json={"question": "How many orders shipped last week?"},
).json()

值得注意的几点：

• token 以其所有者的身份行事。 它本身不携带任何权限 —— 每次调用都依据所有者的角色进行授权，与在浏览器中完全一致。viewer 的 token 无法执行管理操作。
• 整个 API 面都接受它。 认证在一处统一解析（frontend/auth/resolve-user.ts），适用于所有路由，因此 docs/openapi/auto-ontology-api.json 中任何非 withPublic 的端点都可以使用 token。
• 吊销即时生效。 在 UI 中删除该 token，或删除/封禁其所属用户，下一个携带该 token 的请求就会收到 401。
• token 不能管理 token。 创建和吊销需要已登录的会话，因此泄露的 token 无法为自己签发后继者。

Agent API 会话

公开客户端调用经过认证的 Next.js 网关：POST /api/chat/completions。响应是一个 SSE 流，包含 step、result 或 error 事件，最后以 [DONE] 结束。

conversation_id 是可选的：

• 省略它表示无状态的一次性请求。
• 提供客户端生成的 UUID 可创建或继续一个会话。
• 在同一线程的每一轮中复用相同的 UUID。

在发送下一轮之前请等待 [DONE]；对同一会话的重叠请求会返回 409 Conversation in progress。

{
  "question": "What about last month?",
  "conversation_id": "d61d8aa3-d496-4fa7-97ce-4f831c162e7f"
}

对于会话式请求，FastAPI 会加载最近最多五个已完成的轮次（上限 12,000 字符），并在运行现有的 text-to-SQL 图之前，将 “What about August?” 这类上下文输入改写为独立问题。独立问题则原样传递。内部 agent 思考、图表负载、错误以及原始 SQL 结果集不会被复用为上下文。会话历史按已认证的 Auto Ontology 用户隔离。

浏览器和服务端调用方应使用 Next.js 网关，它会解析用户身份并将内部的 x-auto-ontology-user-id 头转发给 FastAPI。FastAPI 端口是一个受信任的内部服务边界：它不得对外暴露，因为该请求头不会被 FastAPI 独立验证。不带 conversation_id 的直接 FastAPI 请求仍是无状态的；带 conversation_id 的直接请求则需要受信任的身份头。Web UI 会自动管理 UUID。API 创建的会话，如果属于当前登录用户，可在 UI 中通过 /chat?focus= 打开。

Agent 技能

编码 agent 请从 AGENTS.md 开始。技能位于 skills/（nvidia-ontology-setup、nvidia-ontology-management、nvidia-ontology-query）。维护者继续使用 CLAUDE.md。

MCP server

Cursor 和 Claude Desktop 等 agent 框架可以通过 Auto Ontology 的 MCP（https://modelcontextprotocol.io）server 查询你的数据。运行方式参见 mcp/，详细信息参见 docs/mcp.md。

许可

Auto Ontology 以 Apache License, Version 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

Auto Ontology 使用的第三方开源组件（含其上游许可证和项目 URL）列在 THIRD_PARTY_NOTICES.md 中。容器镜像额外添加的组件单独列在 CONTAINER_THIRD_PARTY_NOTICES.md 中。

声明与免责声明

声明与免责声明：本软件会自动检索、访问或与外部材料交互。这些检索到的材料不随本软件分发，仅受各自的条款、条件和许可证约束。您有责任自行查找、审查并遵守所有适用的条款、条件和许可证，并验证任何检索到的材料针对您特定用例的安全性、完整性和适用性。本软件按 “AS IS” 提供，不附带任何明示或暗示的保证。作者对任何检索到的材料不作任何陈述或保证，也不对您使用或无法使用本软件或任何检索材料所导致的任何损失、损害、责任或法律后果承担责任。使用本软件和检索到的材料的风险由您自行承担。

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

贡献

本项目目前不接受外部贡献。 来自 Auto Ontology 维护团队之外提交的 issue、pull request 和补丁不会被审查或合并。安全相关报告请遵循 SECURITY.md 中描述的流程。维护者工作流程见 CONTRIBUTING.md。