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
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 →

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.
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.
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
- Chuẩn bị công cụCó Docker Compose v2, uv, git và khóa nvapi-
- Tải mã và tạo .envClone repo, sao chép .env.example thành .env rồi điền giá trị
- Nạp dữ liệu mẫuChạy Postgres, tải auto-ontology-eval và nạp database Wide World Importers
- Khởi động toàn bộBuild và chạy các dịch vụ còn lại bằng Docker Compose
- Đă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:
git clone https://github.com/NVIDIA/auto-ontology.git && cd auto-ontology
cp .env.example .envLệ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:
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>trongCONNECTION_STRINGSphả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.examplecò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ùngDEFAULT_MODELS_API_KEY.- Đăng nhập web sẽ dùng
AUTO_ONTOLOGY_ADMIN_EMAILvàAUTO_ONTOLOGY_ADMIN_PASSWORDtrong file này. README không nói cách tạo giá trị choAUTH_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
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
docker compose up -d --buildLệ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,SQLvà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:
AUTO_ONTOLOGY_API_URL=http://localhost:3000 \
uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcpVới Cursor, thêm vào ~/.cursor/mcp.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:
{
"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:
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:3000trong 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_STRINGSkhácPOSTGRES_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_KEYcó đúng dạngnvapi-...không, và các dòng khóa riêng từng vai trò còn chứa giá trị mẫunvapi-your-api-key-herehay 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.
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.


