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 Python mã nguồn mở của NVIDIA. Nó dựng một lớp ngữ nghĩa (ontology) từ metadata cơ sở dữ liệu để AI hiểu đúng "doanh thu", "khách hàng"… rồi sinh SQL kiểm chứng được. Cài bằng Docker Compose, khá nhiều bước nhưng README có sẵn quickstart với CSDL mẫu.
Auto Ontology là một thư viện mã nguồn mở của NVIDIA, dùng để dựng "lớp hiểu nghĩa dữ liệu" cho AI. Bạn nối nó với cơ sở dữ liệu, nó tự đọc cấu trúc bảng, đặt tên các khái niệm kinh doanh (khách hàng, hoá đơn, doanh thu…), rồi cho AI hỏi đáp bằng tiếng người và trả về câu trả lời kèm câu SQL đã chạy.
Vấn đề repo giải quyết khá quen thuộc: AI có thể truy vấn database, nhưng nếu nó hiểu sai "doanh thu" nghĩa là cột nào thì con số ra nhanh mấy cũng vô nghĩa. Auto Ontology đặt giữa AI và dữ liệu một lớp định nghĩa đã được người duyệt, để mọi câu trả lời tính theo cùng một cách và có thể kiểm lại.
Repo hợp với dev, nhóm dữ liệu, hoặc người làm phân tích muốn thử hỏi đáp dữ liệu bằng AI một cách nghiêm túc. Hiện có khoảng 12.239 sao và 1.008 fork, giấy phép Apache-2.0, vẫn được cập nhật trong vài tháng gần đây. Điểm đáng giá nhất: mỗi câu trả lời đều có SQL và các bước suy luận đi kèm, nên bạn đối chiếu được với dữ liệu gốc.
NVIDIA/auto-ontology
Thư viện mã nguồn mở của NVIDIA dựng ontology 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ì
Hỏi đáp dữ liệu bằng ngôn ngữ tự nhiên. Bạn gõ câu hỏi, hệ thống dịch sang SQL và chạy trên database đã kết nối. Phần suy luận dùng các mô hình qua NVIDIA NIM. Lợi ích: người không biết SQL vẫn lấy được số liệu.
Tự sinh ontology từ metadata. Hệ thống đọc schema, thống kê cột, lấy mẫu giá trị, rồi đặt tên các khái niệm (gọi là term) và ánh xạ vào cột tương ứng. Bạn có bản nháp ngay, không phải ngồi viết từ điển dữ liệu bằng tay.
Ba loại định nghĩa. Ontology gồm term (khái niệm kinh doanh, có mô tả và từ đồng nghĩa), SQL attribute (biểu thức SQL đã duyệt như biên lợi nhuận hay tổng luỹ kế) và relationship (cách các bảng nối với nhau, kể cả bảng cầu nối). Nhờ vậy cùng một số đo luôn được tính cùng một cách.
Người duyệt rồi mới tin. Bản nháp do máy sinh ra, bạn thử bằng câu hỏi thật, chỉnh mô tả, rồi "certify" (xác nhận) các định nghĩa đúng.
Biết nói "không trả lời được". Khi dữ liệu không có thứ bạn hỏi (ví dụ hỏi chi phí quảng cáo trên database chỉ có bán hàng), agent báo rõ thay vì bịa số.
Nhiều cách dùng. Có giao diện web (chat, danh mục dữ liệu, cài đặt), máy chủ MCP cho các công cụ AI, REST API, và ba skill cho agent lập trình. Đăng nhập và phân quyền do Better Auth đảm nhiệm.
Nhập/xuất định nghĩa. Repo tương thích chuẩn Apache Ossie, nhập xuất mô hình dưới dạng YAML trong Settings → Import / Export.
II.Cần chuẩn bị gì
Theo README phần Quickstart, bạn cần:
- Docker với Compose v2. Cả hệ thống chạy bằng Docker Compose trên máy bạn.
- uv (trình quản lý Python), dùng để nạp dữ liệu mẫu.
- Khoá NVIDIA API dạng
nvapi-..., lấy ở build.nvidia.com. Repo dùng các endpoint NVIDIA NIM, hoặc bản NIM tự dựng. - Python từ 3.12 đến dưới 3.14 nếu bạn chạy phần Python ngoài Docker (theo pyproject.toml).
README không nói rõ yêu cầu RAM, GPU hay hệ điều hành. Vì mô hình chạy qua endpoint NVIDIA nên chưa thấy tư liệu yêu cầu GPU cục bộ. Phần này bạn nên xem thêm DEPLOYMENT.md trong repo.
Các thành phần chạy trong stack: giao diện web (cổng 3000), backend FastAPI (3001), dịch vụ nạp dữ liệu (3002), máy chủ MCP (3003) và Postgres kèm pgvector (5432). HashiCorp Vault là tuỳ chọn, để cất thông tin kết nối.
Khoá API và mật khẩu: README dặn đổi hết mật khẩu mặc định trước khi chạy, vì Compose mở cổng Postgres, pgAdmin và web ra máy chủ. Đừng đưa file .env lên chỗ công khai. Gọi mô hình qua NVIDIA API có thể phát sinh chi phí tuỳ gói của bạn, README chưa nói rõ phần này.
III.Cài đặt từng bước
- Chuẩn bị công cụCó Docker Compose v2, uv và khoá nvapi- từ build.nvidia.com
- Tải repo, tạo .envClone repo, sao chép .env.example thành .env rồi điền giá trị
- Nạp database mẫuBật Postgres, tải repo auto-ontology-eval và chạy script seed
- Khởi động cả hệ thốngBuild và chạy toàn bộ bằng docker compose
- Đăng nhập và bật biên dịchMở localhost:3000, bật Semantic Compilation
A.Tải repo 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 mã nguồn về và đi vào thư mục. Lệnh thứ hai tạo file .env từ file mẫu. Trên Windows PowerShell, cp cũng chạy được vì là bí danh của Copy-Item.
Mở .env bằng trình soạn thảo và điền 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 trùng đúng vớiPOSTGRES_PASSWORDbạn vừa đặt..env.examplecòn có khoá API riêng cho từng vai trò mô hình (mỗi dòng ghinvapi-your-api-key-here). Bạn có thể thay từng dòng bằng khoá của mình, hoặc xoá các dòng đó để chúng tự dùngDEFAULT_MODELS_API_KEY. Cách xoá đơn giản hơn.- README không hướng dẫn cách tạo giá trị cho
AUTH_SECRET. Hãy xem DEPLOYMENT.md hoặc docs trong repo. - Tài khoản đăng nhập dùng
AUTO_ONTOLOGY_ADMIN_EMAILvàAUTO_ONTOLOGY_ADMIN_PASSWORDtrong.env, nên nhớ điền hai giá trị này.
B.Bật Postgres và nạp database mẫu
Quickstart dùng Wide World Importers, một database bán hàng mẫu của Microsoft. Script nạp dữ liệu nằm ở repo riêng tên 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='<the same password>' \
uv run python scripts/seed/seed_wwi.py --database-name wideworldimporters --drop)Dòng 1 bật riêng Postgres và đợi nó sẵn sàng. Dòng 2 tải repo chứa script, đặt cạnh thư mục hiện tại. Dòng 3 vào thư mục đó, cài phụ thuộc bằng uv sync, tạo .env, rồi chạy script nạp dữ liệu với mật khẩu Postgres của bạn. Cờ --drop có trong README, nghĩa là xoá database cùng tên nếu đã tồn tại, nên chỉ dùng với database mẫu.
Cú pháp (cd ... && ...) và dấu \ xuống dòng là kiểu bash. Nếu dùng PowerShell, bạn nên chạy trong Git Bash hoặc WSL cho khỏi lỗi cú pháp. README không có bản PowerShell.
C.Build và chạy toàn bộ
Quay lại thư mục auto-ontology và chạy:
docker compose up -d --buildLệnh này dựng image và khởi động các dịch vụ còn lại ở chế độ nền. Lần đầu có thể mất một lúc để tải và build.
D.Đăng nhập và bật Semantic Compilation
Mở trình duyệt vào http://localhost:3000, đăng nhập bằng AUTO_ONTOLOGY_ADMIN_EMAIL và AUTO_ONTOLOGY_ADMIN_PASSWORD trong .env. Vào Settings → Semantic Compilation và bật lên. Việc nạp dữ liệu chạy khi 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: giao diện web ở cổng 3000 mở được, bạn đăng nhập được, và mục Semantic Compilation hiện thông báo Semantic compilation is ready.
Sau đó vào Chat và hỏi một câu về doanh thu của một sản phẩm ở một bang. README dùng ví dụ sản phẩm "USB food flash drive - sushi roll" ở bang Pennsylvania. Kết quả mong đợi gồm ba phần:
- Answer: con số doanh thu và số dòng hoá đơn.
- SQL: câu truy vấn nối các bảng hoá đơn, khách hàng, thành phố, bang.
- Steps: các thuật ngữ đã nhận diện, chuỗi nối bảng, và bước kiểm tra giá trị lọc trước khi chạy.
Nếu thấy đủ ba phần này, hệ thống đã chạy đúng. Bạn cũng có thể xem đồ thị ontology trong giao diện: README nói một lần biên dịch Wide World Importers cho ra 31 term.
V.Dùng vào việc thật
A.Chủ shop muốn hỏi nhanh số liệu bán hàng
Bối cảnh: bạn có database bán hàng và không muốn chờ người viết báo cáo. Sau khi kết nối nguồn và bật biên dịch, bạn vào Chat và gõ câu hỏi bình thường, ví dụ:
Doanh thu của sản phẩm X ở bang Y trong tháng vừa rồi là bao nhiêu?Agent nhận ra các khái niệm doanh thu, sản phẩm, bang, đi theo quan hệ giữa các bảng để nối cho đúng, rồi chạy truy vấn. Bạn nhận câu trả lời kèm SQL và các bước, có thể xem các dòng dữ liệu, tải CSV hoặc xem dạng biểu đồ.
Con số trả lời nhanh chưa quý bằng con số bạn kiểm lại được.
Ông T
B.Nhân viên dữ liệu duyệt định nghĩa trước khi cả nhóm dùng
Bối cảnh: trong công ty, mỗi phòng hiểu "doanh thu" một kiểu. Bạn thử bằng câu hỏi thật trong Chat, rồi sửa tên, mô tả và SQL attribute trong giao diện, đến khi đúng thì certify. Từ đó mọi câu hỏi dùng cùng một cách tính. README cũng cho thấy hệ thống có thể gợi ý SQL attribute từ lịch sử truy vấn, nên bạn có sẵn nền để duyệt.
C.Dev nối trợ lý AI qua MCP
Bối cảnh: bạn dùng Cursor hoặc Claude Desktop và muốn trợ lý hỏi được dữ liệu công ty. Chạy máy chủ MCP trỏ vào bản triển khai của bạn:
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, thêm vào 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 rồi đăng nhập khi được hỏi. Trợ lý sẽ có các công cụ chỉ-đọc như search_terms, check_answerable và ask_question. Mỗi lệnh gọi chạy với quyền của chính người dùng đã đăng nhập. Nếu bạn hỏi thứ dữ liệu không có (như chi phí quảng cáo), agent dùng check_answerable để báo độ phủ và hỏi lại bạn thay vì đoán.
D.Dev tích hợp vào ứng dụng bằng REST API
Bối cảnh: bạn muốn app nội bộ gọi hỏi đáp. Tạo 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ề là 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.
VI.Lỗi hay gặp và cách xử lý
Giao diện mất thanh điều hướng bên trái sau khi khởi động lại. README nói nguyên nhân là trình duyệt giữ cookie phiên cũ. Cách xử lý: xoá dữ liệu trang (site data) của localhost:3000 rồi đăng nhập lại.
Không kết nối được database mẫu. Thường do CONNECTION_STRINGS có mật khẩu không khớp POSTGRES_PASSWORD, hoặc quên điền. Kiểm tra lại hai giá trị phải giống nhau, rồi chạy lại docker compose up -d --build.
Lệnh nạp dữ liệu lỗi cú pháp trên Windows. Đoạn lệnh trong README viết cho bash. Hãy chạy trong Git Bash hoặc WSL thay vì PowerShell thuần.
Gọi mô hình bị từ chối hoặc báo thiếu khoá. Kiểm tra DEFAULT_MODELS_API_KEY đã điền khoá dạng nvapi-... chưa. Nếu còn các dòng nvapi-your-api-key-here cho từng vai trò mô hình, hãy thay bằng khoá thật hoặc xoá đi để chúng dùng khoá mặc định.
Trợ lý MCP không thấy công cụ. Hãy đảm bảo đã khởi động lại ứng dụng sau khi sửa file cấu hình, và máy chủ MCP ở cổng 3003 đang chạy. Chi tiết đăng nhập và xử lý sự cố nằm trong docs/mcp.md của repo.
Về an toàn, README dặn giữ cổng 3001 và 3002 trong mạng nội bộ. Dịch vụ nạp dữ liệu không có xác thực riêng, nên chỉ cho người dùng đi qua web ở cổng 3000.
VII.Có nên dùng không
Điểm mạnh. Câu trả lời đi kèm SQL và các bước, nên kiểm chứng được. Có quy trình người duyệt định nghĩa, có phân quyền, có MCP và API, và tương thích chuẩn Ossie. Mã nguồn mở Apache-2.0 và còn được cập nhật.
Giới hạn. Hệ thống khá nặng: nhiều dịch vụ (web, backend, ingestion, MCP, Postgres), cần Docker và khoá NVIDIA API. README chưa nói yêu cầu phần cứng hay chi phí gọi mô hình. Quickstart chỉ hướng dẫn một database mẫu, còn việc kết nối nguồn của bạn nên xem thêm skill setup và tài liệu trong repo. Dự án hiện không nhận đóng góp từ bên ngoài.
Khi nên chọn cách khác. Nếu bạn chỉ cần vài câu SQL đơn giản trên một file nhỏ, một công cụ chat với dữ liệu nhẹ hơn sẽ đỡ công cài đặt. Auto Ontology đáng thử khi dữ liệu nhiều bảng, nhiều định nghĩa dễ lệch nhau, và bạn cần câu trả lời kiểm chứng được.
Câu hỏi thường gặp
Auto Ontology có miễn phí không?
Mã nguồn mở theo giấy phép Apache-2.0 nên dùng và chạy trên máy bạn không mất phí bản quyền. Tuy nhiên hệ thống gọi mô hình qua NVIDIA NIM bằng khoá API, và README chưa nói rõ về chi phí hay hạn mức. Bạn nên kiểm tra điều khoản ở build.nvidia.com.
Có cần GPU không?
Tư liệu không yêu cầu GPU trên máy bạn. Suy luận, embedding và rerank chạy qua endpoint NVIDIA NIM, hoặc NIM tự dựng nếu bạn muốn. Yêu cầu RAM và CPU README chưa ghi.
Chạy được trên Windows không?
README chỉ nói cần Docker với Compose v2 và uv, không nêu hệ điều hành cụ thể. Các đoạn lệnh trong README viết kiểu bash, nên trên Windows bạn nên dùng Git Bash hoặc WSL.
Dữ liệu của tôi có an toàn không?
Hệ thống chạy trên máy hoặc máy chủ của bạn, có đăng nhập và phân quyền, và MCP chạy với quyền của từng người dùng. README dặn giữ cổng 3001 và 3002 trong mạng riêng và đổi hết mật khẩu mặc định. Câu hỏi và schema vẫn được gửi tới endpoint mô hình bạn cấu hình, nên hãy cân nhắc nếu dùng API đám mây.
Khác gì việc cho AI tự viết SQL?
Thay vì để AI đoán, Auto Ontology có lớp ontology gồm term, quan hệ và SQL attribute đã được người duyệt. Câu trả lời trả kèm SQL và các bước, và nếu dữ liệu không đủ thì agent nói là không trả lời được. Đây là điểm README nhấn mạnh về độ tin cậy.
Có kết nối được với Claude Desktop hay Cursor không?
Có. Repo có máy chủ MCP, README đưa sẵn cấu hình cho Cursor và Claude Desktop (qua mcp-remote). Sau khi sửa cấu hình, bạn khởi động lại ứng dụng và đăng nhập.
Có dùng được với database của tôi thay vì database mẫu không?
Có, README mô tả việc kết nối nguồn dữ liệu quan hệ và biên dịch ontology, nhưng phần Quickstart chỉ hướng dẫn database mẫu. Các bước chi tiết cho nguồn của bạn nằm trong skill setup và tài liệu của repo, tư liệu ở đây chưa đủ để mô tả.


