Bỏ qua tới nội dung
Ông T.vn

Auto Ontology: lớp ngữ nghĩa giúp AI hỏi đáp dữ liệu chính xác — hướng dẫn cài đặt và dùng

11 phút đọcCập nhật

Bài này là một góc nhìn khác về NVIDIA/auto-ontology — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: Auto Ontology: lớp ngữ nghĩa giúp AI hỏi đáp dữ liệu SQL chính xác — hướng dẫn cài đặt và dùng →

Auto Ontology: lớp ngữ nghĩa giúp AI hỏi đáp dữ liệu chính xác — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

Auto Ontology là thư viện mã nguồn mở của NVIDIA, tạo một "ontology" (bản đồ ý nghĩa dữ liệu) từ metadata cơ sở dữ liệu để AI trả lời câu hỏi bằng SQL đúng và kiểm chứng được. Bạn dùng qua giao diện web, MCP, CLI hoặc API. Cài bằng Docker Compose, cần khóa API NVIDIA; các bước khá nhiều nên hợp với người đã quen terminal.

Auto Ontology là một thư viện mã nguồn mở của NVIDIA, dùng để dựng một "lớp ngữ nghĩa" nằm giữa AI và cơ sở dữ liệu của bạn. Lớp này nói cho AI biết dữ liệu nằm ở đâu, mỗi chỉ số nghĩa là gì, có nên dùng không, và các bảng nối với nhau thế nào. Nhờ vậy khi bạn hỏi bằng tiếng thường, AI viết ra câu SQL đúng thay vì đoán mò.

Vấn đề nó giải quyết rất thực tế. AI có thể truy vấn database, nhưng nếu con số doanh thu trả về nhanh mà sai thì vô nghĩa. Repo này giúp AI hiểu "doanh thu", "khách hàng", "dòng hóa đơn" theo định nghĩa đã được người kiểm duyệt. Nó phù hợp với lập trình viên, người làm dữ liệu, hoặc nhóm muốn cho nhân viên hỏi số liệu bằng ngôn ngữ tự nhiên mà vẫn kiểm tra được kết quả.

Điểm đáng giá nhất: mỗi câu trả lời đi kèm câu SQL và các bước đã làm, nên bạn đối chiếu được với dữ liệu gốc. Khi dữ liệu không đủ để trả lời, hệ thống nói rõ là không trả lời được thay vì bịa. Repo hiện có khoảng 12.388 sao và 1.017 fork, dùng giấy phép Apache-2.0, viết chủ yếu bằng Python và vẫn được cập nhật trong 3 tháng gần đây.

Framework

NVIDIA/auto-ontology

Auto Ontology của NVIDIA dựng lớp ngữ nghĩa từ metadata để AI hỏi đáp dữ liệu SQL chính xác, trả kèm câu SQL và các bước suy luận.

★ 12kPythonApache-2.0
Xem repo trên GitHub

I.Auto Ontology làm được gì

Theo README, repo gom năm việc chính: khám phá, nền tảng hóa, kiểm tra, cung cấp và học lại. Dưới đây là phần bạn sẽ cảm nhận rõ nhất khi dùng.

  • Hỏi đáp dữ liệu bằng ngôn ngữ tự nhiên. Câu hỏi được chuyển thành SQL rồi chạy trên cơ sở dữ liệu đã kết nối, dùng các endpoint NVIDIA NIM. Người không biết SQL vẫn hỏi được.
  • Tự dựng ontology từ metadata. Hệ thống đọc schema, lấy mẫu giá trị cột, đặt tên các khái niệm (ví dụ Customer, Invoice Line), suy ra cách các bảng nối với nhau, rồi lưu vào Postgres kèm vector trong pgvector để tìm kiếm.
  • Ba loại định nghĩa. Thuật ngữ (kèm mô tả, từ đồng nghĩa, cột tương ứng), thuộc tính SQL đã duyệt (như biên lợi nhuận, tổng lũy kế) và quan hệ giữa các bảng. Thuộc tính SQL được dùng lại, nên cùng một chỉ số luôn được tính cùng một cách.
  • Người duyệt trước khi tin. Bạn thử bằng câu hỏi thật, chỉnh mô tả, rồi "certify" (chứng nhận) những định nghĩa đúng.
  • Kiểm tra khả năng trả lời. Qua MCP có công cụ check_answerable để biết ontology có bao phủ câu hỏi hay không, rồi mới trả lời.
  • Giao diện web đầy đủ. Có chat, phân tích, danh mục dữ liệu, thống kê và cài đặt. Mỗi câu trả lời cho xem SQL, xem các dòng kết quả, tải CSV hoặc xem dạng biểu đồ.
  • Đăng nhập và phân quyền bằng Better Auth.
  • Kết nối với agent khác qua MCP server, REST API và ba skill dành cho coding agent.
  • Tương thích Apache Ossie, chuẩn mở để trao đổi mô hình ngữ nghĩa. Bạn nhập hoặc xuất định nghĩa dạng YAML.

II.Cần chuẩn bị gì

Theo README phần Quickstart, bạn cần:

  • Docker với Compose v2.
  • uv, công cụ quản lý Python (trang hướng dẫn: docs.astral.sh/uv). Nó dùng để nạp dữ liệu mẫu.
  • Khóa API NVIDIA dạng nvapi-..., lấy tại build.nvidia.com.
  • Git, để tải mã nguồn.

Về phiên bản Python, pyproject.toml yêu cầu Python từ 3.12 đến dưới 3.14. Backend và ingestion service đều dùng Python 3.12 trở lên. Phần giao diện dùng Next.js nhưng khi chạy bằng Docker Compose bạn không phải tự cài Node.

README không nêu yêu cầu phần cứng, cũng không nói rõ hệ điều hành nào được hỗ trợ. Các lệnh trong Quickstart viết theo kiểu shell Unix (như cp và dấu &&), nên nếu dùng Windows bạn nên chạy trong Git Bash hoặc WSL. Đây là gợi ý của mình, README không khẳng định.

Khóa API NVIDIA là thông tin riêng tư. Chỉ điền vào file .env trên máy bạn, không dán vào chat, không đưa lên GitHub. Cũng nên kiểm tra điều khoản và hạn mức dùng của build.nvidia.com vì README chưa nói về chi phí.

III.Cài đặt từng bước

  1. Chuẩn bị công cụCó Docker Compose v2, uv, git và khóa nvapi-
  2. Tải mã và tạo .envClone repo, sao chép .env.example thành .env rồi điền giá trị
  3. Nạp dữ liệu mẫuChạy Postgres, tải auto-ontology-eval và nạp database Wide World Importers
  4. Khởi động toàn bộBuild và chạy các dịch vụ còn lại bằng Docker Compose
  5. Đăng nhập và bật biên dịch ngữ nghĩaMở localhost:3000, bật Semantic Compilation

Các bước dưới đây là bản Quickstart trong README, chạy với Wide World Importers, cơ sở dữ liệu bán hàng mẫu của Microsoft.

A.Tải mã nguồn và tạo file .env

Mở terminal ở thư mục bạn muốn đặt dự án, rồi chạy:

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

Lệnh đầu tải repo về và đi vào thư mục. Lệnh thứ hai tạo file .env từ file mẫu. Đây là file cấu hình thật của bạn.

Mở .env bằng trình soạn thảo và đặt các giá trị sau:

ENV / INI
DEFAULT_MODELS_API_KEY=nvapi-...
AUTH_SECRET=

APP_URL=http://localhost:3000
POSTGRES_PASSWORD=

CONNECTION_STRINGS=postgresql://postgres:<the same password>@postgres:5432/wideworldimporters
AUTO_ONTOLOGY_ADMIN_PASSWORD=

PGADMIN_PASSWORD=

Chỗ người mới hay vấp:

  • <the same password> trong CONNECTION_STRINGS phải đúng bằng mật khẩu bạn đặt ở POSTGRES_PASSWORD.
  • README nhắc Compose mở cổng Postgres, pgAdmin và web ra máy chủ, nên hãy thay mọi mật khẩu mặc định trước khi chạy.
  • .env.example còn đặt sẵn khóa API cho từng vai trò mô hình, giá trị nvapi-your-api-key-here. Bạn thay bằng khóa thật, hoặc xóa các dòng đó để chúng tự dùng DEFAULT_MODELS_API_KEY.
  • Đăng nhập web sẽ dùng AUTO_ONTOLOGY_ADMIN_EMAIL và AUTO_ONTOLOGY_ADMIN_PASSWORD trong file này. README không nói cách tạo giá trị cho AUTH_SECRET, nên bạn xem thêm DEPLOYMENT.md hoặc docs/ trong repo.

Về mô hình, mỗi vai trò (REASONING, NON_REASONING, EMBED, RERANK) có bộ ba biến _ENDPOINT, _API_KEY, _MODEL. Trường nào để trống sẽ lấy từ DEFAULT_MODELS_*. Cách đơn giản nhất là chỉ điền DEFAULT_MODELS_*.

B.Chạy Postgres và nạp dữ liệu mẫu

Terminal
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='<the same password>' \
  uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)

Dòng đầu bật riêng dịch vụ Postgres và đợi nó sẵn sàng. Dòng hai tải repo auto-ontology-eval ra thư mục ngang hàng, vì script nạp dữ liệu nằm ở đó. Khối trong ngoặc đi vào repo kia, cài phụ thuộc bằng uv sync, tạo .env rồi chạy script nạp database wideworldimporters. Thay <the same password> bằng mật khẩu Postgres của bạn. Cờ --drop có nghĩa là xóa database cùng tên nếu đã có, nên đừng dùng tên database đang chứa dữ liệu thật.

C.Build và chạy toàn bộ hệ thống

Terminal
docker compose up -d --build

Lệnh này build và khởi động phần còn lại: giao diện web, backend, ingestion worker và MCP server. Lần đầu có thể mất một lúc vì phải build image.

D.Đăng nhập và bật Semantic Compilation

Mở http://localhost:3000, đăng nhập bằng AUTO_ONTOLOGY_ADMIN_EMAIL và AUTO_ONTOLOGY_ADMIN_PASSWORD trong .env. Vào Settings → Semantic Compilation rồi bật lên. Việc nạp dữ liệu chạy lúc khởi động, còn biên dịch ngữ nghĩa bắt đầu ngay và báo Semantic compilation is ready khi xong.

IV.Kiểm tra đã chạy được chưa

Dấu hiệu thành công theo README:

  • Trang http://localhost:3000 mở được và bạn đăng nhập được.
  • Trong Settings, phần biên dịch ngữ nghĩa báo Semantic compilation is ready.
  • Trong Chat, bạn hỏi một câu về dữ liệu mẫu và nhận câu trả lời kèm SQL cùng các bước đã làm. README mô tả đáp án gồm các mục Answer, SQL và Steps, trong đó SQL nối các bảng như invoice lines, invoices, customers, cities, state provinces.

Ví dụ câu hỏi bạn thử:

What was revenue for the USB food flash drive - sushi roll in Pennsylvania?

README còn gợi ý bản ví dụ có kèm một khoảng thời gian cụ thể, bạn xem nguyên văn trong README. Con số của bạn có thể khác ví dụ, cái cần thấy là có đủ ba phần: câu trả lời, SQL, các bước.

Nếu giao diện mở lên mà thiếu thanh điều hướng bên trái sau khi khởi động lại, README giải thích là trình duyệt đang giữ cookie phiên cũ. Hãy xóa dữ liệu trang của localhost:3000 rồi đăng nhập lại.

V.Dùng vào việc thật

Các tình huống dưới đây bám theo khả năng README mô tả. Mình lấy dữ liệu mẫu làm ví dụ, còn kết nối database của bạn thì xem thêm trong docs/ và skill nvidia-ontology-setup.

A.Chủ shop muốn hỏi số liệu bán hàng mà không biết SQL

Bạn có database bán hàng và muốn biết doanh thu theo sản phẩm hoặc theo bang. Sau khi biên dịch ngữ nghĩa xong, bạn mở Chat và gõ câu hỏi bằng tiếng Anh như ví dụ ở trên. Agent gắn "revenue", "product", "state" với các thuật ngữ trong ontology, đi theo quan hệ giữa các bảng để biết cần nối những bảng nào, rồi chạy truy vấn. Bạn nhận con số cùng câu SQL, có thể xem các dòng kết quả, tải CSV hoặc xem biểu đồ.

Con số trả về nhanh mà sai thì còn tệ hơn không có con số.

Ông T

B.Nhân viên dữ liệu chứng nhận định nghĩa để cả nhóm dùng chung

Trong công ty, mỗi phòng hay hiểu "doanh thu" một kiểu. Người phụ trách dữ liệu mở giao diện, xem thuật ngữ mà hệ thống tự sinh (như Order, với mô tả, thuật ngữ liên quan, cột và thuộc tính SQL), sửa mô tả cho đúng, rồi certify. Từ đó mọi câu hỏi đều tính chỉ số theo cùng một thuộc tính SQL đã duyệt. Kết quả là cả nhóm nhận số liệu nhất quán.

C.Dev nối Auto Ontology vào Cursor hoặc Claude Desktop

MCP server cung cấp công cụ chỉ đọc như search_terms, get_term, describe_table, check_answerable và ask_question. Chạy MCP server theo README:

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

Với Cursor, thêm vào ~/.cursor/mcp.json:

JSON
{
  "mcpServers": {
    "auto-ontology": { "url": "http://localhost:3003/mcp" }
  }
}

Với Claude Desktop, sửa claude_desktop_config.json, cầu nối bằng mcp-remote:

JSON
{
  "mcpServers": {
    "auto-ontology": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:3003/mcp"]
    }
  }
}

Khởi động lại ứng dụng sau khi sửa cấu hình, rồi đăng nhập khi được yêu cầu. Mỗi cuộc gọi chạy với quyền của chính người dùng đó. Khi bạn hỏi về thứ dữ liệu không có (README lấy ví dụ chi tiêu quảng cáo trong cơ sở dữ liệu bán hàng), agent kiểm tra check_answerable trước, rồi giải thích dữ liệu không có chi tiêu quảng cáo và hỏi bạn muốn đổi sang câu khác không.

D.Dev gọi từ ứng dụng của mình qua REST API

Tạo API token ở menu người dùng → API Tokens, rồi gọi:

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

Kết quả trả về dưới dạng luồng sự kiện (server-sent events): sự kiện result chứa câu trả lời và data: [DONE] báo kết thúc. Cách này hợp khi bạn muốn nhúng hỏi đáp dữ liệu vào một ứng dụng nội bộ.

VI.Lỗi hay gặp và cách xử lý

  • Giao diện mất thanh điều hướng sau khi khởi động lại. Đây là lỗi README tự nêu: cookie phiên cũ. Xóa dữ liệu trang của localhost:3000 trong trình duyệt rồi đăng nhập lại.
  • Không kết nối được database mẫu. Thường do mật khẩu trong CONNECTION_STRINGS khác POSTGRES_PASSWORD, hoặc quên chạy bước nạp dữ liệu. Kiểm tra hai giá trị khớp nhau, rồi chạy lại script nạp.
  • Lỗi khóa API hoặc mô hình không trả lời. Kiểm tra DEFAULT_MODELS_API_KEY có đúng dạng nvapi-... không, và các dòng khóa riêng từng vai trò còn chứa giá trị mẫu nvapi-your-api-key-here hay không. Thay bằng khóa thật hoặc xóa các dòng đó.
  • Chat không trả lời được câu hỏi. Có thể biên dịch ngữ nghĩa chưa xong, hoặc dữ liệu thực sự không có thông tin đó. Đợi dòng Semantic compilation is ready, và nhớ rằng hệ thống được thiết kế để từ chối khi dữ liệu không đủ.
  • Mở cổng nội bộ ra ngoài. README cảnh báo cổng 3001 và 3002 phải để trong mạng riêng, vì ingestion service không có xác thực riêng. Người dùng chỉ nên đi qua web ở cổng 3000. Với các lỗi cài đặt khác, README chỉ đến phần hướng dẫn xử lý sự cố của skill setup trong repo.

VII.Có nên dùng không

Điểm mạnh. Câu trả lời kiểm chứng được vì có SQL và các bước đi kèm. Định nghĩa chỉ số được người duyệt rồi dùng lại, nên số liệu nhất quán. Có đủ đường vào: web, MCP, API, skill cho coding agent. Giấy phép Apache-2.0, repo còn được cập nhật.

Giới hạn. Cài đặt không nhẹ: cần Docker, uv, khóa NVIDIA và nhiều biến môi trường. README mặc định dùng endpoint NVIDIA NIM, nên bạn phụ thuộc dịch vụ đó (hoặc tự dựng NIM). README chưa nói rõ về Windows, về phần cứng hay chi phí gọi API. Dự án hiện không nhận đóng góp từ bên ngoài. Hãy cẩn thận khi dùng với dữ liệu nhạy cảm vì câu hỏi và metadata sẽ đi qua mô hình bạn cấu hình. Phần này mình chưa thấy tư liệu nói chi tiết, bạn nên đọc SECURITY.md và DEPLOYMENT.md trong repo.

Khi nào nên chọn cách khác. Nếu bạn chỉ cần hỏi nhanh một file Excel nhỏ, một công cụ đơn giản hơn là đủ. Auto Ontology đáng công nhất khi bạn có database nhiều bảng, nhiều người dùng và cần số liệu đáng tin. Nên thử với dữ liệu mẫu trước, rồi mới kết nối dữ liệu thật.

5.0/5 · Ông T chấm

Chưa có độc giả chấm

Bài này có ích với bạn không?

Câu hỏi thường gặp

Auto Ontology có miễn phí không?

Mã nguồn dùng giấy phép Apache-2.0, nên dùng miễn phí. Tuy nhiên hệ thống cần khóa API NVIDIA (`nvapi-...`) để gọi mô hình. README không nói về chi phí hay hạn mức, nên bạn xem điều khoản tại build.nvidia.com.

Cần GPU để chạy không?

README không yêu cầu GPU hay nêu phần cứng. Mô hình chạy qua endpoint NVIDIA NIM, có thể là dịch vụ đám mây của NVIDIA hoặc NIM tự dựng. Nếu tự dựng, yêu cầu phần cứng nằm ngoài thông tin mình có.

Chạy được trên Windows không?

README chưa khẳng định hỗ trợ Windows. Quickstart dùng Docker Compose cùng các lệnh kiểu shell Unix như `cp`. Nếu dùng Windows, bạn có thể thử Git Bash hoặc WSL, nhưng đó là gợi ý chứ không phải cam kết của tác giả.

Dữ liệu của tôi có an toàn không?

Hệ thống có đăng nhập, phân quyền, và MCP server chạy theo quyền của từng người dùng. README khuyên giữ cổng 3001 và 3002 trong mạng riêng vì ingestion service không tự xác thực. Việc dữ liệu đi qua mô hình nào tùy cấu hình của bạn; chi tiết khác hãy xem SECURITY.md trong repo.

Cần những gì để cài?

Docker với Compose v2, uv, git và khóa API NVIDIA. Python phải từ 3.12 đến dưới 3.14 nếu bạn chạy phần Python ngoài Docker. Bạn cũng cần điền các biến như mật khẩu Postgres và mật khẩu quản trị vào file .env.

Khác gì việc cho AI tự viết SQL trực tiếp?

Auto Ontology thêm lớp ngữ nghĩa: thuật ngữ, thuộc tính SQL đã duyệt và quan hệ giữa các bảng. Agent tìm các thành phần này trước khi viết SQL, kiểm tra giá trị lọc với dữ liệu, rồi trả câu trả lời kèm SQL và các bước. Khi dữ liệu không đủ, nó báo không trả lời được.

Dùng được với Claude Desktop hoặc Cursor không?

Có. README có hướng dẫn cấu hình MCP cho cả Cursor và Claude Desktop (qua `mcp-remote`). Sau khi sửa file cấu hình, bạn khởi động lại ứng dụng và đăng nhập khi được hỏi.

Chuyển nhanh tới mục

  1. I.Auto Ontology làm được gì
  2. II.Cần chuẩn bị gì
  3. III.Cài đặt từng bước
    1. A.Tải mã nguồn và tạo file .env
    2. B.Chạy Postgres và nạp dữ liệu mẫu
    3. C.Build và chạy toàn bộ hệ thống
    4. D.Đăng nhập và bật Semantic Compilation
  4. IV.Kiểm tra đã chạy được chưa
  5. V.Dùng vào việc thật
    1. A.Chủ shop muốn hỏi số liệu bán hàng mà không biết SQL
    2. B.Nhân viên dữ liệu chứng nhận định nghĩa để cả nhóm dùng chung
    3. C.Dev nối Auto Ontology vào Cursor hoặc Claude Desktop
    4. D.Dev gọi từ ứng dụng của mình qua REST API
  6. VI.Lỗi hay gặp và cách xử lý
  7. VII.Có nên dùng không

Repo & Skill · 13/11/2026 · 11 phút đọc

Garden Skills: bộ skill thiết kế web, tạo ảnh, làm video cho AI — hướng dẫn cài đặt và dùng

Garden Skills là bộ sưu tập Agent Skills (kỹ năng cho AI) của tác giả ConardLi, dùng được với Claude Code, Cursor, Codex và các AI coding agent khác. Mỗi skill dạy agent làm tốt một việc như thiết kế trang web, tạo ảnh, làm video bằng code, biến tài liệu thành bài viết đẹp. Cài không khó, nhưng README có nhiều cách cài nên bạn cần chọn một cách hợp với công cụ đang dùng.

Repo & Skill · 13/11/2026 · 15 phút đọc

thesysdev/openui: xây giao diện AI dạng streaming — hướng dẫn cài đặt và dùng

OpenUI là framework full-stack, độc lập framework, giúp mô hình AI sinh giao diện có cấu trúc và hiển thị dần khi dữ liệu streaming về. Bạn có thể dựng nhanh một ứng dụng chat bằng CLI hoặc cài từng gói cho React, Vue, Svelte, Angular và LangChain. Việc bắt đầu khá đơn giản nếu máy có đúng phiên bản Node; README chưa ghi đầy đủ lệnh chạy ứng dụng sau khi scaffold.

Repo & Skill · 13/11/2026 · 11 phút đọc

Ruflo: điều phối nhóm agent AI cho Claude Code và Codex — hướng dẫn cài đặt và dùng

Ruflo (trước đây là Claude Flow) là một agent harness: lớp công cụ bao quanh Claude Code và Codex, bổ sung nhiều agent chuyên biệt, bộ nhớ qua các phiên và khả năng chia việc cho nhóm agent. Cài bằng một lệnh `npx ruflo@latest init` trong thư mục dự án, cần Node 20 trở lên. Cài khá dễ, nhưng hệ thống rất rộng nên bạn nên bắt đầu từ một tác vụ nhỏ.