Auto Ontology

에이전트는 문서를 검색하고 데이터베이스를 쿼리할 수 있지만, 신뢰성 장벽(reliability gates)이 에이전트 분석을 막습니다. 숫자가 틀리면 아무리 빠르게 답변한 수익 지표도 가치가 없습니다. 에이전트는 데이터가 어디에 있는지, 무엇을 의미하는지, 사용해야 하는지, 어떻게 사용해야 하는지, 어디서 왔는지, 그리고 무엇과 유사한지를 알려주는 컨텍스트 레이어가 필요합니다. NVIDIA Auto Ontology는 기업 메타데이터로부터 이 레이어를 구축하고, 시스템 전반의 정의를 조정하며, MCP, CLI, API를 통해 모든 에이전트 하네스(agent harness)에 노출하는 오픈 라이브러리입니다. 이는 고객이 이미 소유하고 있는 시맨틱 모델을 보완합니다.

이를 통해 개발자는 다음 작업을 수행할 수 있습니다:

발견 (Discover): 메타데이터로부터 기업 온톨로지(enterprise ontologies)를 생성하고; 기존 온톨로지와 시맨틱 모델을 연결하며; AI 준비가 된 지식 그래프(knowledge graphs)를 구축합니다.
접지/근거 마련 (Ground): 에이전트에게 지표, 개체, 관계에 대한 신뢰할 수 있는 비즈니스 의미를 제공하고; 시스템 전반의 불일치한 정의를 조정합니다.
검증 (Validate): 생성된 쿼리를 인증된 정의 및 계보(lineage)와 비교 검사하고; 모든 답변과 함께 출처(provenance)를 반환합니다.
노출 (Expose): MCP, CLI, API를 통해 모든 에이전트 하네스에 컨텍스트를 제공합니다.

학습 (Learn): 인증된 수정 사항 및 사용 사례를 온톨로지에 다시 통합하여, 공유되는 컨텍스트가 질문할 때마다 개선되도록 합니다.

벤치마크 (Benchmarks)

BIRD와 같은 text-to-SQL 벤치마크를 실행하려면 ontology SQL evaluation repository를 참조하십시오.

라이선싱 및 기여. Auto Ontology는 Apache License 2.0에 따라 배포됩니다. 이 프로젝트에서 번들링, 링크되거나 사용되는 제3자 오픈 소스 구성 요소는 THIRD_PARTY_NOTICES.md에 나열되어 있습니다. 현재 본 프로젝트는 외부 기여를 받지 않습니다.

<p> <img src=

구조화된 데이터의 자연어 질의(Natural-language querying) — 질문을 SQL로 번역하여 연결된 데이터베이스에서 실행하며, NVIDIA NIM이 구동합니다.
관계형 소스 위에 구축된 의미론적 카탈로그/온톨로지 계층(Semantic catalog / ontology layer)으로, 설명하는 카탈로그와 함께 Postgres에 저장됩니다.
인증 및 RBAC (Role-Based Access Control) — Better Auth를 사용합니다.
채팅, 분석, 데이터 카탈로그, 분석 기능 및 설정을 위한 웹 UI(Web UI).
유연한 배포(Flexible deployment) — Kubernetes용 Helm 차트 또는 로컬 스택을 위한 Docker Compose를 지원합니다.

소프트웨어 구성 요소 (Software Components)

구성 요소 (Component)	기술 (Technology)	역할 (Role)	기본 포트 (Default port)
Frontend	Next.js 16 (React 19, TypeScript, Tailwind CSS 4), Better Auth, Prisma	웹 UI, 인증, API 게이트웨이	3000
...

NVIDIA NIM

Auto Ontology는 추론(inference)을 위해 NVIDIA NIM 엔드포인트를 사용합니다. 이는 호스팅된 NVIDIA API 카탈로그 (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가 필요합니다.

모델 삼중항 (Model triplets)

각 모델 역할은 세 가지 환경 변수(triplet)로 구성됩니다 — <PREFIX>_ENDPOINT (URL), <PREFIX>_API_KEY, 및 <PREFIX>_MODEL:

Prefix	Role
`DEFAULT_MODELS`	공유 기본값; 아래의 모든 필드는 이 값으로 폴백합니다.
...
<br>전체 삼중항(triplet)을 설정하거나, 그 중 일부만 설정하거나, 아예 아무것도 설정하지 않을 수 있습니다. 설정되지 않은 모든 필드는 일치하는 `DEFAULT_MODELS_<FIELD>`로 폴백됩니다. 따라서 가장 간단한 설정은 `DEFAULT_MODELS_`를 채우고, 차이가 나는 트립렛별 필드(예: `EMBED_MODEL`, `NON_REASONING_MODEL`)만 덮어쓰는 것입니다. 또한 `_API_KEY`도 하위 호환성을 위해 레거시인 `NVIDIA_API_KEY`로 폴백됩니다.<br><br>## 배포 (Deployment)<br><br>### 전제 조건 (Prerequisites)<br><br>- 로컬 스택용 Docker와 Docker Compose v2 (예: macOS/Windows의 Docker Desktop, Linux의 Docker Engine)가 필요합니다. Kubernetes 배포는 `DEPLOYMENT.md`를 참조하십시오.<br>- NVIDIA NIM(채팅 및 수집)용 NVIDIA API 키 (`nvapi-...`)가 필요하며, 이는 https://build.nvidia.com의 NVIDIA API 카탈로그에서 얻을 수 있습니다.<br>- 쿼리하려는 소스 데이터베이스(Databricks, Postgres, Snowflake 또는 DuckDB)에 대한 연결 세부 정보가 필요합니다.<br><br>### 설치 (Installation)<br><br>Kubernetes<br><br>Auto Ontology를 Kubernetes 클러스터에 배포하려면 `DEPLOYMENT.md`를 참조하십시오.<br><br>로컬 (Docker Compose)<br><br>1. 저장소를 복제합니다:<br><br>```bash
git clone <repo-url> auto_ontology && cd auto_ontology
<br><br>2. 템플릿에서 환경 파일(.env)을 생성하고 값(Postgres 자격 증명, `DEFAULT_MODELS_API_KEY`, `CONNECTION_STRINGS` 등)을 채웁니다. 변수 전체 목록은 [`.env.example`](./.env.example)를 참조하십시오:<br><br>bash
cp .env.example .env

.env 편집

```<br><br>참고:<br>- AUTH_SECRET과 APP_URL은 필수입니다. 이것들이 없으면 모든 페이지가 Better Auth

이미지 빌드 및 스택 시작:

docker compose up -d --build

이 명령어는 백엔드(auto_ontology)와 프론트엔드(auto-ontology-frontend) 이미지를 빌드하고, Postgres와 pgAdmin을 실행하며, 데이터베이스 스키마 동기화를 위해 일회성 frontend-migrate 작업을 수행한 후, 애플리케이션(백엔드, 수집 서비스 및 프론트엔드)을 시작합니다.

http://localhost:3000에서 UI를 엽니다 (백엔드 API는 :3001, pgAdmin은 :5050에 있습니다).

문제 해결: 만약 UI가 왼쪽 탐색 패널 없이 로드되거나(또는 재시작 후 다른 방식으로 깨져 보인다면), 브라우저가 오래된 세션 쿠키를 가지고 있는 것입니다. 이는 AUTH_SECRET이 변경되거나 데이터베이스가 초기화되었을 때 발생합니다. localhost:3000의 사이트 데이터를 지우거나(better-auth.session_token 쿠키 삭제) 다시 로그인하십시오.

연결 관리 (Connections Management)

Auto Ontology는 연결하는 소스 데이터베이스를 두 가지 출처에서 해결합니다:

UI를 통해 추가: 앱 내에서 생성된 연결입니다. 이 옵션을 사용하면, Vault가 구성되지 않은 경우 연결 자격 증명은 Postgres에 평문(plaintext)으로 저장됩니다:

Vault 미사용 시: 전체 연결 객체(비밀번호 포함)는 암호화되지 않은 상태로 JSON 직렬화되어 카탈로그의 데이터베이스 행에 저장됩니다.
Vault 사용 시: 자격 증명은 데이터베이스 이름으로 키가 지정되어 Vault에 작성되고, 카탈로그 행에는 자격 증명이 저장되지 않습니다 (데이터베이스 이름이 조회 키이며 별도의 참조 필드는 없습니다).

Vault는 VAULT_ADDR, VAULT_NAMESPACE, VAULT_ROLE_ID, 그리고 VAULT_SECRET_ID가 모두 설정된 경우에만 활성화됩니다 (VAULT_AUTH_MOUNT 및 VAULT_KV_MOUNT는 선택적 재정의입니다). 기본적으로 비활성화되어 있으며, 부분적인 구성은 경고와 함께 무시되고 평문 저장소로 폴백(fallback)합니다.

CONNECTION_STRINGS 환경 변수 — 배포 시 제공되는 쉼표로 구분된 연결 문자열 목록(예: Helm의 --set connectionStrings=<CONNECTION-STRINGS> 플래그). 이는 폴백 방식입니다. UI를 통해 추가된 연결이 없는 경우에만 사용됩니다.

인증 (Authentication)

Auto Ontology는 SSO(Single Sign-On)를 지원합니다. 리디렉트 URI는 IdP에서 다음과 같이 구성해야 합니다: APP_URL/api/auth/sso/callback

API 토큰 (스크립팅)

브라우저가 로그인하여 세션 쿠키를 얻지만, 스크립트는 이를 얻을 수 없습니다. 스크립트, 노트북 및 예약된 작업의 경우 대신 API 토큰을 생성하십시오:

사용자 메뉴(오른쪽 상단) → API 토큰 (API Tokens) → **새 토큰 (New token)**으로 이동합니다.
이름을 지정하고, 선택적으로 만료일을 설정한 후 (기본값: 없음), 토큰을 복사합니다. Auto Ontology는 이 토큰의 SHA-256 해시만 저장하므로 정확히 한 번만 표시됩니다. 이를 잃어버리면 새 토큰을 생성해야 합니다.

이를 모든 /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

...

알아두면 좋은 점:

토큰은 소유자 역할을 합니다. 자체 권한을 가지지 않으며, 모든 호출은 브라우저에서와 마찬가지로 소유자의 역할에 따라 승인됩니다. 뷰어의 토큰으로는 관리자 작업을 수행할 수 없습니다.
전체 API 표면이 이를 수용합니다. 인증은 모든 경로(frontend/auth/resolve-user.ts)에서 한 곳에서 처리되므로, docs/openapi/auto-ontology-api.json에 있는 withPublic이 아닌 모든 엔드포인트가 토큰으로 작동합니다.
취소는 즉각적입니다. UI에서 토큰을 삭제하거나, 소유 사용자를 삭제/차단하면 다음 요청은 401 오류를 반환합니다.
토큰은 토큰을 관리할 수 없습니다. 생성 및 취소를 위해서는 로그인된 세션이 필요하므로, 유출된 토큰으로는 스스로 후속 토큰을 발행할 수 없습니다.

에이전트 API 대화 (Agent API conversations)

Public 클라이언트는 인증된 Next.js 게이트웨이의 POST /api/chat/completions 엔드포인트로 호출합니다. 응답은 step, result, 또는 error 이벤트를 포함하는 SSE 스트림이며, 이후 [DONE]으로 마무리됩니다.

conversation_id는 선택 사항입니다:

상태 비저장(stateless)의 일회성 요청을 위해 생략할 수 있습니다.
대화를 생성하거나 계속하려면 클라이언트가 생성한 UUID를 제공해야 합니다.
스레드의 모든 턴에 동일한 UUID를 재사용합니다. 다음 턴을 보내기 전에 반드시 [DONE]을 기다려야 하며, 하나의 대화에 대해 요청이 중복되면 409 Conversation in progress 오류가 반환됩니다.

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

대화형 요청의 경우, FastAPI는 최대 5개의 가장 최근에 완료된 턴(최대 12,000자로 제한)을 로드하고, "What about August?"와 같은 문맥적 입력은 기존의 text-to-SQL 그래프를 실행하기 전에 독립적인 질문으로 재작성합니다. 독립적인 질문은 변경 없이 전달됩니다. 내부 에이전트 사고 과정(agent thoughts), 차트 페이로드(chart payloads), 오류, 및 원시 SQL 결과 세트는 컨텍스트로 재사용되지 않습니다.

대화 기록은 인증된 Auto Ontology 사용자에게 범위가 한정됩니다. 브라우저 및 서비스 호출자는 Next.js 게이트웨이를 사용해야 하며, 이 게이트웨이가 사용자를 식별하고 내부 x-auto-ontology-user-id 헤더를 FastAPI로 전달합니다. FastAPI 포트는 신뢰할 수 있는 내부 서비스 경계이므로, 해당 헤더가 FastAPI에 의해 독립적으로 검증되지 않기 때문에 외부에 노출되어서는 안 됩니다. conversation_id 없이 직접 FastAPI에 요청하는 경우 상태 비저장(stateless)으로 유지되며, conversation_id를 포함하여 직접 요청하려면 신뢰할 수 있는 ID 헤더가 필요합니다.

웹 UI에서 UUID를 자동으로 관리합니다. API로 생성된 대화는 로그인한 사용자에게 속할 경우 /chat?focus=<conversation_id> 경로에서 UI를 통해 열 수 있습니다.

Agent skills

코딩 에이전트(Coding agents): AGENTS.md에서 시작하세요. 스킬은 skills/ 디렉터리(nvidia-ontology-setup, nvidia-ontology-management, nvidia-ontology-query)에 있습니다. 유지 관리자는 계속해서 CLAUDE.md를 사용해야 합니다.

MCP server

에이전트(Agent)는 Cursor나 Claude Desktop 같은 도구를 활용하여 Auto Ontology의 MCP 서버를 통해 사용자의 데이터에 질의할 수 있습니다. 실행은 mcp/에서, 상세 내용은 docs/mcp.md에서 확인하세요.

라이선스 (License)

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가 사용하는 제3자 오픈 소스 구성 요소는 해당 상위 라이선스와 프로젝트 URL과 함께 THIRD_PARTY_NOTICES.md에 열거되어 있습니다. 컨테이너 이미지로 추가된 구성 요소는 CONTAINER_THIRD_PARTY_NOTICES.md에서 별도로 나열됩니다.

NVIDIA Auto Ontology

요약

핵심 포인트