Lớp ngữ nghĩa Auto Ontology giữa database doanh nghiệp và AI agent

NVIDIA Auto Ontology: lớp ngữ nghĩa cho AI agent hỏi dữ liệu doanh nghiệp

Buổi họp đầu tháng, phòng kinh doanh hỏi AI agent nội bộ: “Doanh thu tháng 6 là bao nhiêu?” Agent trả lời ngay: 4,2 tỷ. Cuối tuần, kế toán đối chiếu và phát hiện con số đúng là 3,7 tỷ: agent tính doanh thu gộp chưa trừ hoàn trả, lại lấy theo ngày xuất hóa đơn thay vì ngày giao hàng. Agent đọc đúng database — chỉ là nó tự đoán định nghĩa của từ “doanh thu” và tự đoán cách JOIN các bảng. Lỗi nằm ở kiến trúc: giữa database và agent không có lớp định nghĩa chung nào. NVIDIA Auto Ontology lấp đúng khoảng trống đó: lớp ngữ nghĩa được con người chứng nhận, để agent chỉ trả lời từ định nghĩa đã kiểm chứng, kèm SQL và nguồn gốc dữ liệu.

Auto Ontology là gì?

Auto Ontology là thư viện mã nguồn mở của NVIDIA (repo NVIDIA/auto-ontology, Apache 2.0, khoảng 6.469 sao) dựng lớp ngữ nghĩa từ metadata doanh nghiệp rồi phơi bày cho mọi agent qua MCP, CLI và API. Một ontology gồm Terms (khái niệm nghiệp vụ gắn với các cột dữ liệu), SQL attributes (biểu thức SQL đã được con người review, ví dụ công thức tính margin) và Relationships (cách các bảng JOIN, kể cả qua bridge table). Năm khả năng: Discover, Ground, Validate, Expose, Learn — sinh ontology từ metadata, gắn nghĩa nghiệp vụ, kiểm tra truy vấn, phơi bày qua MCP/CLI/API, và đưa correction đã chứng nhận trở lại ontology.

Quy trình có ba bước. Generate: ingestion quét database nguồn rồi đề xuất terms, relationships và SQL attributes, lưu bản nháp vào Postgres. Trong ví dụ của dự án, một lần biên dịch database mẫu Wide World Importers sinh ra 31 terms. Certify: con người xem xét từng định nghĩa trong web UI, sửa nếu cần, rồi chứng nhận — chỉ định nghĩa đã chứng nhận mới được dùng để trả lời. Độ tin cậy nằm ở kỷ luật chứng nhận, không phải model mạnh hay yếu. Answer: agent sinh SQL chỉ từ định nghĩa đã chứng nhận, trả đáp án kèm SQL và các bước phân giải. Câu hỏi ngoài phạm vi bị từ chối thay vì bịa số — ví dụ hỏi “return on ad spend” trên database không có dữ liệu quảng cáo, check_answerable báo độ phủ 0.5, không term nào phủ “ad spend”, nên agent hỏi lại.

Phù hợp với sysadmin, DevOps/SRE, backend/full-stack developer, người self-host, và đội BI/data muốn chuẩn hóa định nghĩa metric. Ngược lại, nếu chỉ cần hỏi đáp nhanh trên một bảng SQLite nhỏ, chưa cần chuẩn hóa định nghĩa, hoặc chưa bố trí được người certify ontology, công cụ này sẽ nặng hơn giá trị nó mang lại.

Kiến trúc và cơ chế sinh SQL có kiểm chứng

Stack gồm năm dịch vụ: frontend Next.js 16 (React 19, TypeScript, Tailwind 4) dùng Better Auth và Prisma, cổng 3000, là điểm vào duy nhất; backend FastAPI (Python 3.12+, LangChain), cổng 3001, lo chat, NL-to-SQL và catalog; ingestion worker cũng FastAPI, cổng 3002, lo ingestion và biên dịch ontology; MCP server FastMCP, cổng 3003, phơi các tool chỉ đọc; Postgres 17 kèm pgvector, cổng 5432, là kho metadata, ontology và vector store. Có thể gắn HashiCorp Vault để lưu credential; triển khai bằng Docker Compose hoặc Helm chart.

Model chạy qua NVIDIA NIM (hosted tại integrate.api.nvidia.com hoặc tự host), cấu hình bằng bộ ba <ROLE>_ENDPOINT / <ROLE>_API_KEY / <ROLE>_MODEL, fallback DEFAULT_MODELS_*. Bốn vai trò: REASONING (chat, NL-to-SQL), NON_REASONING (trích entity, kiểm tra và sửa SQL), EMBED và RERANK. Model suy luận mặc định là nvidia/nemotron-3.5-lightning-30b-a3b. Lưu ý: tài liệu của dự án không thống nhất về model mặc định cho embed và rerank — phần giới thiệu NIM ghi theo .env.example là nvidia/nemotron-3-embed-1b và nvidia/llama-nemotron-rerank-vl-1b-v2, bảng Models ghi nvidia/nemotron-3.5-embed-1b và nvidia/nemotron-3.5-rerank-8b. Theo mình, lấy .env.example làm chuẩn khi triển khai. Model embedding cũng phải giống nhau giữa ingestion và truy vấn.

flowchart TD
    User["Người dùng / AI agent bên ngoài\n(Cursor, Claude Desktop, script qua API)"]
    UI["Web UI Next.js 16 — cổng 3000\nĐiểm vào duy nhất, Better Auth + RBAC"]
    Backend["Backend FastAPI — cổng 3001\nSinh câu trả lời, điều phối"]
    Worker["Ingestion worker FastAPI — cổng 3002\nQuét metadata, biên dịch ontology"]
    MCP["MCP server FastMCP — cổng 3003\n9 tool chỉ đọc: check_readiness, search_terms,\nget_term, check_answerable, ask_question..."]
    OntologyDB["Postgres 17 + pgvector — cổng 5432\nKho Terms, SQL attributes đã chứng nhận, Relationships"]
    SourceDBs["Database nguồn\nPostgreSQL, MySQL, Snowflake, ClickHouse,\nTrino, DuckDB, SQLite... — 10 engines"]
    NIM["NVIDIA NIM\nSuy luận nemotron-3.5-lightning-30b-a3b,\nembed, rerank"]
    Gate["Cổng kiểm tra check_answerable\nQuyết định trả lời / từ chối"]
    Answer["Đáp án kèm SQL + provenance"]

    User --> UI
    User --> MCP
    MCP --> Backend
    UI --> Backend
    Backend --> OntologyDB
    Backend --> NIM
    Worker --> SourceDBs
    Worker --> NIM
    Worker --> OntologyDB
    UI -->|con người review & chứng nhận| OntologyDB
    Backend --> Gate
    Gate --> Answer
    Gate -->|không trả lời được — hỏi lại, không bịa số| User
    Backend --> SourceDBs
    SourceDBs --> Answer

Ba nhánh trong diagram: Generate — worker quét metadata, nhờ NIM đề xuất terms, lưu ontology chờ chứng nhận vào Postgres. Certify — con người review và chứng nhận qua UI. Answer — backend kiểm tra độ phủ qua check_answerable, sinh SQL chỉ từ attributes đã chứng nhận, chạy trên database nguồn, trả đáp án kèm SQL và provenance; không đủ độ phủ thì bị từ chối. Cổng 3001/3002 phải ở mạng private — chỉ UI 3000 là điểm vào người dùng.

Ba giới hạn: tính đúng đắn phụ thuộc vào chất lượng certify — ontology lỗi thời khi schema đổi mà không biên dịch và certify lại; dự án chưa có release chính thức (0 release, 1 tag) và không nhận external pull request — nên pin commit đã kiểm tra; và bài này không trích số benchmark BIRD vì tài liệu không đưa số nào.

Triển khai bằng Docker Compose

Cần Docker với Compose v2, uv, và NVIDIA API key (dạng nvapi-...) lấy từ build.nvidia.com. Clone repo từ https://github.com/NVIDIA/auto-ontology.git. Các biến bắt buộc trong .env (sao từ .env.example): DEFAULT_MODELS_API_KEY, AUTH_SECRET, APP_URL=http://localhost:3000, POSTGRES_PASSWORD, CONNECTION_STRINGS, AUTO_ONTOLOGY_ADMIN_PASSWORD, PGADMIN_PASSWORD. Đổi mọi mật khẩu mặc định trước khi mở stack ra ngoài localhost; không commit file .env.

Bước 1 — Clone repo và tạo .env:

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

Điền các biến trên; thay từng nvapi-your-api-key-here bằng key thật hoặc xóa để fallback về DEFAULT_MODELS_API_KEY. CONNECTION_STRINGS cho quickstart trỏ tới database mẫu: postgresql://postgres:<mật khẩu đã đặt>@postgres:5432/wideworldimporters.

Bước 2 — Khởi động Postgres và seed database mẫu (script seed nằm ở repo riêng NVIDIA/auto-ontology-eval):

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=<mật khẩu đã đặt> \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)

Bước 3 — Build và chạy toàn bộ stack, mở http://localhost:3000, đăng nhập bằng tài khoản admin trong .env, bật Settings → Semantic Compilation và đợi báo ready.

docker compose up -d --build

Kiểm chứng sau cài đặt

Chạy docker compose ps để xác nhận các container đang chạy. Đăng nhập web UI, Semantic Compilation báo sẵn sàng và sinh terms. Hỏi thử trong Chat: “What was revenue for the USB food flash drive - sushi roll in Pennsylvania in June 2015?” Kết quả kỳ vọng: $588.80, từ 3 invoice lines, kèm SQL và các bước phân giải. Hỏi thêm một câu ngoài phạm vi (ví dụ về chi phí quảng cáo) và xác nhận agent từ chối qua check_answerable thay vì bịa số.

Lỗi thường gặp

Sai NVIDIA API key: biên dịch hoặc chat báo lỗi gọi model. Kiểm tra DEFAULT_MODELS_API_KEY có bắt đầu bằng nvapi- không.
Thiếu biến .env: backend hoặc worker crash khi khởi động. Kiểm tra log và đối chiếu với .env.example.
Postgres chưa sẵn sàng trước khi build: ingestion thất bại, ontology trống. Đợi Postgres healthy (docker compose up -d --wait postgres) rồi mới seed và build.
Seed Wide World Importers thất bại: database wideworldimporters trống hoặc không tồn tại. Kiểm tra uv, tên database và POSTGRES_PASSWORD trong .env.
Semantic Compilation không bật: Chat trả lời chung chung, không có terms. Bật Settings → Semantic Compilation và đợi báo ready.

Kết nối database của bạn và dùng qua MCP, API, agent skills

Auto Ontology nối được PostgreSQL, MySQL, Databricks, Snowflake, ClickHouse, Trino, Apache Kyuubi, HeavyDB, DuckDB, SQLite — qua Settings → Connections hoặc CONNECTION_STRINGS; DuckDB và SQLite chỉ cần connection string. Theo mình nên dùng tài khoản chỉ đọc.

MCP server phơi 9 tool chỉ đọc: check_readiness, search_terms, get_term, get_term_columns, get_term_sql_attributes, get_sql_attribute, describe_table, check_answerable và ask_question. Tính chỉ đọc quan trọng: agent hỏi đáp được nhưng không sửa ontology qua MCP. Chạy MCP server:

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

Cấu hình Cursor (~/.cursor/mcp.json, URL http://localhost:3003/mcp) hoặc Claude Desktop (npx mcp-remote http://localhost:3003/mcp). Khởi động lại client và đăng nhập khi được hỏi. Luồng điển hình: search_terms → get_term_sql_attributes → check_answerable → ask_question.

Hỏi đáp qua POST /api/chat/completions, kèm header x-api-key (token tạo trong user menu → API Tokens). Response là SSE stream: event result mang đáp án, data: [DONE] kết thúc stream:

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

Ba skill cho coding agent, bắt đầu từ AGENTS.md: nvidia-ontology-setup, nvidia-ontology-management, nvidia-ontology-query. Import/export chuẩn Apache Ossie qua Settings → Import/Export hoặc POST /api/model/import|export.

Đánh giá: ưu điểm, nhược điểm, bảo mật và vận hành

Ưu điểm. Mọi câu trả lời kèm SQL và provenance, câu hỏi ngoài phạm vi bị từ chối thay vì bịa số. Định nghĩa tách khỏi prompt và model. Hệ mở: Apache 2.0, MCP/CLI/API, import/export Ossie, 10 connector, triển khai Compose hoặc Helm.

Nhược điểm. Chi phí lớn nhất là certify: ontology càng lớn càng tốn công duy trì và càng dễ lỗi thời khi schema đổi. Phụ thuộc NVIDIA NIM và API key — cần phương án tự host NIM nếu muốn độc lập. Độ trưởng thành còn thấp: 0 release, không nhận external PR — nên pin commit đã kiểm tra (2a24f5d, ngày 2026-11-04) khi dùng production.

Bảo mật. Auth và RBAC qua Better Auth, nhưng điểm quan trọng nhất là ranh giới mạng: giữ cổng 3001 và 3002 trên mạng private. Backend FastAPI tin header x-auto-ontology-user-id do frontend chuyển tiếp, và các endpoint ingestion (ingest, delete, reset, compile) không có auth riêng — client chỉ được đi qua web app cổng 3000. Đổi mọi mật khẩu mặc định trong .env, dùng tài khoản database chỉ đọc, và review kỹ trước khi bật Predictions (KumoRFM): khi bật, agent upload các bảng đã nối lên dịch vụ hosted (mặc định tối đa 20 bảng, KUMO_MAX_TABLES). Predictions là opt-in — không đặt KUMO_RFM_API_KEY thì nó không chạy.

Vận hành. Không có số benchmark để trích; yếu tố ảnh hưởng: kích thước schema, số terms, model NIM hosted hay tự host, pgvector. Đo thực tế bằng thời gian biên dịch Wide World Importers và thời gian trả lời câu hỏi mẫu. Backup Postgres và export Ossie YAML định kỳ; sau mỗi lần schema đổi thì biên dịch lại, certify lại, rồi mới publish. Trước mỗi lần biên dịch lại hoặc import ontology mới, export Ossie YAML và snapshot Postgres — nếu ontology mới sai, restore bản đó thay vì sửa tay từng term.

So sánh với các lựa chọn cùng phạm vi

So sánh theo sáu tiêu chí: ai định nghĩa “đúng”, câu hỏi ngoài phạm vi xử lý ra sao, có SQL và provenance không, tích hợp agent bằng gì, chi phí duy trì, tự host được không.

Text-to-SQL thô — LLM sinh SQL trực tiếp từ schema, không có semantic layer. Thử nghiệm nhanh, không tốn công certify, nhưng model tự đoán JOIN và công thức, không có cổng từ chối — phù hợp demo, không phù hợp cho số liệu ra quyết định.

Graphify — bài đã có trên blog (Graphify: knowledge graph cho AI agent). Graphify biến codebase, tài liệu và schema SQL thành knowledge graph cho coding agent. Auto Ontology khác hẳn: semantic layer đã chứng nhận trên database nghiệp vụ để analytics agent trả số đúng, với check_answerable, provenance, RBAC, MCP và web UI.

Semantic layer BI truyền thống — các semantic layer BI cũng tập trung định nghĩa metric một lần để dùng chung. Auto Ontology khác ở chỗ sinh ontology tự động từ metadata và phơi bày trực tiếp cho agent qua MCP. Theo mình, nếu chỉ cần dashboard và đã có semantic layer BI tốt, chưa chắc đã cần thêm Auto Ontology.

Use case thực tế

Doanh nghiệp: “Doanh thu”, “khách hàng active”, “margin” được định nghĩa và chứng nhận một lần, dùng chung cho mọi agent và báo cáo; khi định nghĩa đổi, đội dữ liệu chỉ review một chỗ.

Homelab: chạy stack bằng Docker Compose với Postgres, MySQL, DuckDB hoặc SQLite tại nhà, dùng tài khoản chỉ đọc, giữ stack trên mạng nội bộ.

AI workflow: gắn Auto Ontology vào coding agent hoặc agent đa bước qua MCP — agent gọi search_terms → get_term_sql_attributes → check_answerable → ask_question, và SQL kèm provenance trở thành bằng chứng đính kèm trong workflow.

DevOps / IT admin: triển khai bằng Compose hoặc Helm, backup bằng Postgres snapshot và export Ossie YAML; khi schema đổi thì biên dịch lại → certify lại → publish; rollback bằng bản export trước đó.

Kết luận

Đáng dùng khi đội bạn có database nghiệp vụ, có người chịu trách nhiệm định nghĩa metric, cần agent trả số liệu có kiểm chứng, và chấp nhận chi phí certify. Chưa nên dùng khi chỉ cần hỏi đáp nhanh trên một database nhỏ, chưa cần chuẩn hóa định nghĩa, hoặc chưa bố trí được người certify.

Bước tiếp theo: clone repo, chạy Quickstart với Wide World Importers, hỏi câu mẫu để thấy đáp án $588.80 kèm SQL và provenance, rồi mới nối database thật bằng tài khoản chỉ đọc và certify một nhóm term nhỏ trước khi mở rộng.

Bài học rút ra

Số liệu sai thường không do model yếu mà do thiếu định nghĩa chung đã chứng nhận — sửa ở lớp ontology.
Giá trị nằm ở cổng từ chối (check_answerable): một câu “không trả lời được” đúng lúc đáng tin hơn một con số bịa.
Chứng nhận của con người là nút thắt cổ chai — chi phí duy trì ontology, không phải chi phí inference, quyết định dự án có sống được sau tuần đầu hay không.
Lớp ngữ nghĩa chỉ đáng tin khi ranh giới mạng đúng: phơi cổng backend và worker ra ngoài phá đúng cam kết bảo mật của nó.
Đừng mở rộng trước khi chứng minh được một nhóm term nhỏ chạy đúng end-to-end: hỏi mẫu → SQL → provenance → số liệu đối chiếu được.

Phạm vi xác minh

Kiểm tra ngày 2026-11-05 theo tài liệu chính thức và GitHub API của repo NVIDIA/auto-ontology (6.469 sao, 510 fork, commit 2a24f5d, 0 release). Các bước cài đặt trích từ tài liệu chính thức, chưa chạy thử trong lab của blog. Các con số 31 terms và $588.80 là ví dụ của tài liệu dự án, không tự tái hiện; không trích điểm benchmark BIRD vì tài liệu không đưa số. Mâu thuẫn về model mặc định embed/rerank đã nêu trong bài — khi triển khai, lấy .env.example làm chuẩn. Dự án không nhận external pull request; Predictions qua KumoRFM là opt-in, mặc định tắt; giới hạn 20 bảng (KUMO_MAX_TABLES) là cấu hình mặc định, không phải số đo hiệu năng.

Tài liệu tham khảo

NVIDIA Auto Ontology — repo chính thức: https://github.com/NVIDIA/auto-ontology
Tài liệu MCP server: https://github.com/NVIDIA/auto-ontology/blob/main/docs/mcp.md
Tài liệu kết nối nguồn dữ liệu: https://github.com/NVIDIA/auto-ontology/blob/main/docs/connections.md
NVIDIA API catalog (lấy API key nvapi-...): https://build.nvidia.com/
Bài liên quan trên phamnam.me — Graphify: knowledge graph cho AI agent: https://phamnam.me/posts/graphify-knowledge-graph-cho-ai-agent/

Tìm kiếm

Auto Ontology: lớp ngữ nghĩa cho AI agent hỏi dữ liệu