NVIDIA / auto-ontology
本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。
NVIDIA / auto-ontology
Auto Ontology Agents can retrieve documents and query databases, but reliability gates agentic analytics: a revenue metric answered faster is worth nothing if the number is wrong. Agents need a context layer that tells them where data lives, what it means, whether to use it, how to use it, where it came from, and what is similar. NVIDIA Auto Ontology is an open library that builds that layer from enterprise metadata, reconciles definitions across systems, and exposes it to any agent harness through MCP, CLI, and API. It complements the semantic models customers already own.
自动本体代理（Auto Ontology Agents）能够检索文档并查询数据库，但可靠性是代理分析的关键门槛：如果数据结果是错误的，那么即便收入指标的查询速度再快也毫无意义。代理需要一个上下文层来告知它们数据存储的位置、含义、是否应该使用、如何使用、来源以及相似性。NVIDIA Auto Ontology 是一个开源库，它利用企业元数据构建该层，协调跨系统的定义，并通过 MCP、CLI 和 API 将其暴露给任何代理工具。它能够补充客户现有的语义模型。
It enables developers to: Discover: generate enterprise ontologies from metadata; connect existing ontologies and semantic models; build AI-ready knowledge graphs. Ground: give agents trusted business meaning for metrics, entities, and relationships; reconcile inconsistent definitions across systems. Validate: check generated queries against certified definitions and lineage; return provenance with every answer. Expose: serve context to any agent harness through MCP, CLI, and API. Learn: fold certified corrections and usage back into the ontology, so shared context improves with every question.
它使开发者能够：发现：从元数据生成企业本体；连接现有的本体和语义模型；构建 AI 就绪的知识图谱。落地：为代理提供指标、实体和关系的受信任业务含义；协调跨系统的不一致定义。验证：根据认证的定义和血缘关系检查生成的查询；在每次回答时返回来源信息。暴露：通过 MCP、CLI 和 API 为任何代理工具提供上下文。学习：将经过认证的修正和使用情况反馈回本体，从而使共享上下文随着每次提问而不断改进。
Benchmarks: To run a text-to-SQL benchmark such as BIRD, refer to the ontology SQL evaluation repository. Licensing & contributions: Auto Ontology is distributed under the Apache License 2.0. Third-party open-source components bundled, linked, or otherwise used by this project are listed in THIRD_PARTY_NOTICES.md. This project is currently not accepting external contributions.
基准测试：若要运行诸如 BIRD 之类的文本转 SQL 基准测试，请参考本体 SQL 评估存储库。许可与贡献：Auto Ontology 基于 Apache License 2.0 分发。本项目捆绑、链接或以其他方式使用的第三方开源组件列在 THIRD_PARTY_NOTICES.md 中。本项目目前不接受外部贡献。
Key Features: Natural-language querying of structured data — questions are translated to SQL and executed against connected databases, powered by NVIDIA NIM. Semantic catalog / ontology layer over relational sources, stored in Postgres alongside the catalog it describes. Authentication & RBAC — using Better Auth. Web UI for chat, analysis, data catalog, analytics, and settings. Flexible deployment — Helm chart for Kubernetes or Docker Compose for a local stack.
主要功能：结构化数据的自然语言查询——问题被翻译成 SQL 并在连接的数据库上执行，由 NVIDIA NIM 提供支持。关系源之上的语义目录/本体层，与所描述的目录一起存储在 Postgres 中。身份验证与 RBAC——使用 Better Auth。用于聊天、分析、数据目录、分析和设置的 Web UI。灵活部署——支持 Kubernetes 的 Helm chart 或用于本地堆栈的 Docker Compose。
Software Components:
| Component | Technology | Role | Default port |
|---|---|---|---|
| Frontend | Next.js 16 (React 19, TypeScript, Tailwind CSS 4), Better Auth, Prisma | Web UI, authentication, API gateway | 3000 |
| Backend | FastAPI (Python 3.12+), LangChain | Chat / NL-to-SQL, catalog, datasource APIs | 3001 |
| Ingestion worker | FastAPI (Python 3.12+) | Ingests tabular data and writes embeddings | 3002 |
| Postgres + pgvector | Relational Database | App metadata, the catalog and ontology, vector store | 5432 |
| HashiCorp Vault | Optional | Secure storage of connection credentials | - |
软件组件：
| 组件 | 技术 | 角色 | 默认端口 |
|---|---|---|---|
| 前端 | Next.js 16 (React 19, TypeScript, Tailwind CSS 4), Better Auth, Prisma | Web UI、身份验证、API 网关 | 3000 |
| 后端 | FastAPI (Python 3.12+), LangChain | 聊天 / NL-to-SQL、目录、数据源 API | 3001 |
| 摄取工作进程 | FastAPI (Python 3.12+) | 摄取表格数据并写入嵌入 | 3002 |
| Postgres + pgvector | 关系数据库 | 应用元数据、目录和本体、向量存储 | 5432 |
| HashiCorp Vault | 可选 | 连接凭据的安全存储 | - |
NVIDIA NIM Auto Ontology uses NVIDIA NIM endpoints for inference — either the hosted NVIDIA API catalog (integrate.api.nvidia.com) or self-hosted NIMs. The defaults in .env.example are: LLM: nvidia/nemotron-3.5-lightning-30b-a3b; Embeddings: nvidia/nemotron-3-embed-1b; Reranking: nvidia/llama-nemotron-rerank-vl-1b-v2. The endpoints and models are configured via the DEFAULT_MODELS_ENDPOINT, DEFAULT_MODELS_MODEL, EMBED_ENDPOINT, and EMBED_MODEL environment variables and require a DEFAULT_MODELS_API_KEY.
NVIDIA NIM Auto Ontology 使用 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。
Model triplets: Each model role is configured by a triplet of environment variables —
模型三元组：每个模型角色由一组三元环境变量配置——
Quickstart: This runs Auto-Ontology with Docker Compose against Wide World Importers, Microsoft’s sample sales database. You need Docker with Compose v2, uv, and an NVIDIA API key (nvapi-…) from build.nvidia.com. Clone the repository and create .env. Then set these values in .env: DEFAULT_MODELS_API_KEY=nvapi-…, AUTH_SECRET, APP_URL, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD, PGADMIN_PASSWORD. Compose publishes Postgres, pgAdmin, and the web app on the host, so replace each default password before you start it.
快速入门：此操作使用 Docker Compose 针对微软的示例销售数据库 Wide World Importers 运行 Auto-Ontology。您需要安装带有 Compose v2 的 Docker、uv，以及来自 build.nvidia.com 的 NVIDIA API 密钥 (nvapi-…)。克隆存储库并创建 .env 文件。然后在 .env 中设置这些值：DEFAULT_MODELS_API_KEY=nvapi-…, AUTH_SECRET, APP_URL, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD, PGADMIN_PASSWORD。Compose 会将 Postgres、pgAdmin 和 Web 应用发布到主机上，因此请在启动前替换每个默认密码。
Start Postgres and load the sample database. The seed script lives in auto-ontology-eval; pass it the Postgres password you set. Build and start the rest of the stack: docker compose up -d —build. Open http://localhost:3000 and sign in with AUTO_ONTOLOGY_ADMIN_EMAIL and AUTO_ONTOLOGY_ADMIN_PASSWORD from .env. Go to Settings → Semantic Compilation and turn it on. Ingestion runs at startup; compilation starts immediately and reports “Semantic compilation is ready” when it finishes.
启动 Postgres 并加载示例数据库。种子脚本位于 auto-ontology-eval 中；将您设置的 Postgres 密码传递给它。构建并启动其余堆栈：docker compose up -d —build。打开 http://localhost:3000 并使用 .env 中的 AUTO_ONTOLOGY_ADMIN_EMAIL 和 AUTO_ONTOLOGY_ADMIN_PASSWORD 登录。转到 Settings → Semantic Compilation 并将其开启。摄取在启动时运行；编译立即开始，并在完成后报告“Semantic compilation is ready”。
Ask a question in Chat: “What was revenue for the USB food flash drive - sushi roll in Pennsylvania in June 2015?” The agent resolves revenue, product, and state to terms in the ontology, follows their relationships to the joins it needs, and runs the query. The answer comes back with its SQL and the steps that produced it, so you can check.
在聊天中提问：“2015 年 6 月宾夕法尼亚州 USB 食品闪存盘 - 寿司卷的收入是多少？”代理将收入、产品和州解析为本体中的术语，跟踪它们的关系以进行所需的连接，并运行查询。答案会连同其 SQL 和生成步骤一起返回，以便您进行核对。