跪拜 Guibai
← Back to the summary

NVIDIA Auto Ontology Puts a Human-Certified Semantic Layer Between Agents and Enterprise Data

One Open Source Project a Day (#254): NVIDIA Auto Ontology — A Certifiable Semantic Layer for Data Agents, and an Honest "I Don't Know" When It Can't Answer Author: 冬奇Lab Tags: Artificial Intelligence

Introduction

"A metric that is fast but wrong is worthless."

This is the 254th piece in the "One Open Source Project a Day" series. Today's project is NVIDIA's open-source Auto Ontology.

When agents query enterprise data, the most common failure is not SQL syntax but semantic mismatch: Is revenue with or without tax? Who defined the active user metric? Are the two customer tables in different systems the same thing? Models will confidently write SQL that runs but returns wrong numbers.

Auto Ontology's approach is to put a "context layer" between the agent and the database: first, it automatically extracts business terms, reusable SQL expressions, and table relationships from metadata; then humans test, correct, and certify them; finally, agents answer based on those certified definitions. The project README describes the capability in five verbs: Discover, Ground, Validate, Expose, Learn (certified corrections and usage flow back into the ontology).

What you will learn

Prerequisites

Project Background

Project Overview

Official positioning: build a context layer for AI agents from enterprise metadata, reconcile definitions across different systems, and expose it via MCP, CLI, and API. It is designed to coexist with customers' existing semantic models, not replace them. The GitHub repository description emphasizes building a semantic, graph-based reasoning layer on top of data to improve context retrieval and make LLM and agent workflows more explainable.

Project Data

Main Features

Core Role

Without a semantic layer:
  Agent sees raw tables and column names
  ↓ Infers metrics from the literal names
  ↑ SQL runs, numbers are wrong

Auto Ontology:
  Metadata → Terms / SQL attributes / Relationships
  ↓ Humans test and certify
  ↓ Agent retrieves candidates → writes SQL → validates → returns answer and evidence
  ↑ When candidates cannot support the query, it explicitly says so instead of guessing

What the Ontology Stores

Content Meaning
Terms Business concepts with descriptions, synonyms, and column mappings
SQL attributes Reviewed expressions, e.g., how gross margin is calculated
Relationships Table joins (including bridge tables), inferred from keys and data

Three-Step Flow

  1. Generate: Read the data source, profile columns, extract terms per table; infer relationships from query history, suggest SQL attributes; write everything to PostgreSQL, with vectors in pgvector
  2. Certify: Humans test with real questions, correct, and certify names, descriptions, and SQL attributes
  3. Answer: Agent identifies intent, extracts entities, retrieves candidates via embeddings, writes SQL, validates filter values and the query itself (repairing if it fails), and finally returns the SQL and reasoning steps together

When candidates are insufficient, it says "can't answer". Predictive questions can be offloaded to third-party KumoRFM (requires configuration).

Quick Start

Requirements: Docker (Compose v2), uv, and an NVIDIA API Key (nvapi-...). The official demo uses the Wide World Importers sample database:

git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .env   # fill in DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL,
                       # POSTGRES_PASSWORD, CONNECTION_STRINGS, and admin/pgAdmin passwords
docker compose up -d --wait postgres

# Seed sample data
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='<password>' \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)

docker compose up -d --build

Then open http://localhost:3000, log in as admin, enable it in Settings → Semantic Compilation, and ask questions in the Chat.

The official docs give two contrasting examples:

Compiling the sample library produced 31 terms.

Detailed Project Analysis

Service Composition

Component Technology Port
Frontend Next.js, Better Auth, Prisma 3000
Backend FastAPI, LangChain 3001
Data ingestion FastAPI 3002
MCP service FastMCP 3003
Database PostgreSQL 17 + pgvector 5432
Keystore HashiCorp Vault (optional) —

Important: ports 3001 and 3002 should stay private because the ingestion endpoint has no authentication. Compose publishes services to the host, so all default passwords must be changed. The repo also has DEPLOYMENT.md for deploying to Kubernetes with Helm.

Data Sources and Models

Three Ways to Connect Agents

Also supports import/export in YAML format with Apache Ossie for interoperability with existing semantic models.

On "Deterministic Query Generation"

The GitHub repository description mentions deterministic query generation, but the README itself does not describe it that way: it actually relies on LLM-written SQL, plus certified definitions and validation steps. A more accurate understanding: definitions are deterministic (human-certified), while SQL generation is still done by the model, then validated and repaired. If your scenario requires fully reproducible results, you need to verify this yourself.

Limitations and Notes

  1. No external PRs accepted; the only community contribution path is filing issues
  2. Using KumoRFM for predictions uploads related tables to a hosted service (limited by KUMO_MAX_TABLES, default 20); assess data leakage risk before enabling
  3. The software contacts external model endpoints and is provided "AS IS"
  4. After restart, stale session cookies may cause UI navigation issues
  5. The README has two inconsistencies in the default values for embedding and reranking models; configure based on what you actually use

Project Links and Resources

Summary and Outlook

Key Points Recap

  1. Problem: The main risk when agents query data is semantic mismatch, not syntax errors
  2. Approach: Automatically generate terms, SQL attributes, and relationships, have humans certify them, then let agents use them
  3. Honest refusal: When candidates are insufficient, explicitly say can't answer and provide coverage
  4. Integration: MCP (read-only), REST, Skills; supports 10 databases and OpenAI-compatible models
  5. Cautions: Ingestion interface has no auth, change default passwords, no external PRs, take "deterministic" with a grain of salt

Who It's For

Learning Suggestions

First run through the Wide World Importers example, observe how the 31 terms are generated, then deliberately ask a question that cannot be answered and see how check_answerable responds. Before connecting your own test database, change the default passwords and restrict ports 3001 and 3002 to the internal network.

Visit PrimeSkills — a curated marketplace of AI agents and skills, all verified in real enterprise workflows. No gimmicks, just what actually works.

For more practical knowledge and interesting products, visit my personal homepage