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 SQL chính xác — hướng dẫn cài đặt và dùng

10 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 SQL chính xác — hướng dẫn cài đặt và dùng

Tóm tắt nhanh

Auto Ontology là framework Python mã nguồn mở của NVIDIA, dựng một lớp ngữ nghĩa (ontology) từ metadata của cơ sở dữ liệu để AI hiểu đúng 'doanh thu', 'khách hàng' nghĩa là gì và truy vấn SQL chính xác hơn. Bạn có thể hỏi bằng ngôn ngữ tự nhiên qua giao diện web, MCP hoặc REST API. Cài bằng Docker Compose, khá nhiều bước nhưng README hướng dẫn rõ từng lệnh.

Auto Ontology là một thư viện mã nguồn mở của NVIDIA, dùng để dựng "lớp ngữ nghĩa" cho dữ liệu doanh nghiệp. Nói đơn giản: nó đọc cấu trúc cơ sở dữ liệu của bạn, tự đặt tên và mô tả các khái niệm kinh doanh (khách hàng, hóa đơn, doanh thu…), rồi để AI dựa vào đó mà viết câu SQL đúng thay vì đoán mò.

Vấn đề nó giải quyết rất đời thường. AI có thể trả lời nhanh một câu hỏi về doanh thu, nhưng nếu con số sai thì nhanh cũng vô nghĩa. Lý do thường là AI không biết bảng nào chứa dữ liệu nào, cột nào mang nghĩa gì, và phép tính nào là chuẩn của công ty. Auto Ontology làm cầu nối: nó lưu định nghĩa, quan hệ giữa các bảng, rồi trả lời kèm câu SQL và các bước đã làm để bạn kiểm tra lại.

Repo hiện có khoảng 12.388 sao và 1.017 fork, giấy phép Apache-2.0, được cập nhật trong 3 tháng gần đây. Phù hợp với nhóm dữ liệu, lập trình viên làm trợ lý AI cho dữ liệu nội bộ, và người làm kinh doanh muốn hỏi dữ liệu bán hàng bằng tiếng thường. Điểm đáng giá nhất: mỗi câu trả lời đều có SQL và nguồn gốc, nên bạn không phải tin mù quáng.

Framework

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 đúng nghĩa, có SQL và nguồn gốc đi kèm mỗi câu trả lời.

★ 12kPythonApache-2.0
Xem repo trên GitHub

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

Dựng ontology tự động 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à gắn với cột thật trong cơ sở dữ liệu. Bạn có bản nháp ngay mà không phải ngồi viết tay từng định nghĩa.

Ba loại định nghĩa. Term là khái niệm kinh doanh kèm mô tả và từ đồng nghĩa. SQL attribute là biểu thức SQL đã được duyệt, ví dụ biên lợi nhuận hay tổng lũy kế, để mọi câu trả lời tính cùng một cách. Relationship là cách các bảng nối với nhau, kể cả bảng trung gian.

Hỏi đáp bằng ngôn ngữ tự nhiên. Bạn gõ câu hỏi trong màn hình Chat. Hệ thống tìm các term liên quan, viết SQL, kiểm tra giá trị lọc với dữ liệu, tự sửa nếu kiểm tra lỗi, rồi chạy và trả kết quả cùng SQL. Bạn có thể xem các dòng dữ liệu, tải CSV hoặc xem dạng biểu đồ.

Biết khi nào không trả lời được. Nếu dữ liệu không có thứ bạn hỏi (ví dụ chi phí quảng cáo trong một cơ sở dữ liệu bán hàng), agent nói thẳng là không tính được và hỏi lại, thay vì bịa ra con số.

Người duyệt, ontology tốt dần. Bạn thử bằng câu hỏi thật, chỉnh term và mô tả, rồi "certify" (xác nhận) những gì đúng. Phần đã xác nhận trở thành chuẩn cho các câu hỏi sau.

Kết nối với agent khác. Có máy chủ MCP (công cụ chỉ đọc), REST API, và ba skill cho agent lập trình. Ngoài ra có giao diện web có đăng nhập và phân quyền, triển khai bằng Docker Compose hoặc Helm chart cho Kubernetes.

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

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

  • Docker có Compose v2.
  • uv, công cụ quản lý Python của Astral, dùng để chạy script nạp dữ liệu mẫu.
  • Khóa API của NVIDIA dạng nvapi-..., lấy ở build.nvidia.com. Auto Ontology gọi các mô hình qua NVIDIA NIM, có thể dùng dịch vụ trên đám mây của NVIDIA hoặc NIM tự chạy.
  • Git để tải mã nguồn.

Nếu chạy mã Python trực tiếp (không qua Docker), file pyproject.toml yêu cầu Python từ 3.12 đến dưới 3.14. Với cách Docker bên dưới, bạn không cần cài Python này cho ứng dụng chính.

README không nói rõ yêu cầu RAM hay GPU. Vì mô hình gọi qua endpoint NIM, bạn chưa thấy yêu cầu GPU trong phần Quickstart. Nếu định tự chạy NIM, hãy xem docs/ và DEPLOYMENT.md trong repo.

Khóa API và mật khẩu là thứ nhạy cảm. Đừng đưa file .env lên GitHub hay gửi cho người khác. README cũng nhắc: Docker Compose mở cổng Postgres, pgAdmin và web ra máy chủ, nên phải đổi hết mật khẩu mặc định trước khi chạy.

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

  1. Tải mã nguồnClone repo và tạo file .env từ mẫu
  2. Điền cấu hìnhNhập khóa NVIDIA, mật khẩu và chuỗi kết nối vào .env
  3. Nạp dữ liệu mẫuChạy Postgres rồi nạp cơ sở dữ liệu Wide World Importers
  4. Khởi động toàn bộBuild và chạy các dịch vụ bằng Docker Compose
  5. Bật biên dịch ngữ nghĩaĐăng nhập web, bật Semantic Compilation

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

Mở terminal (PowerShell trên Windows, Terminal trên Mac/Linux) ở thư mục bạn muốn lưu dự án, rồi chạy lệnh trong README:

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à vào thư mục. Lệnh thứ hai sao chép file mẫu thành .env, là file cấu hình thật. Trên PowerShell, cp cũng chạy được vì là bí danh của Copy-Item.

B.Điền cấu hình vào .env

Mở file .env bằng trình soạn thảo và đặt các giá trị sau (README ghi y nguyên):

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:

  • DEFAULT_MODELS_API_KEY là khóa nvapi-... của bạn.
  • POSTGRES_PASSWORD và mật khẩu trong CONNECTION_STRINGS phải giống hệt nhau (chỗ <the same password>).
  • File .env.example còn có khóa riêng cho từng vai trò mô hình, mặc định là 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. Cách thứ hai gọn hơn.
  • README không nói cách tạo AUTH_SECRET nên mình không đoán; hãy xem .env.example và docs/ trong repo.

Các biến mô hình hoạt động theo bộ ba _ENDPOINT, _API_KEY, _MODEL cho từng vai trò (DEFAULT_MODELS, REASONING, NON_REASONING, EMBED, RERANK). Trường nào bỏ trống sẽ lấy giá trị từ DEFAULT_MODELS. Riêng mô hình embedding phải giống nhau giữa lúc nạp dữ liệu và lúc hỏi.

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

Dữ liệu mẫu là Wide World Importers, cơ sở dữ liệu bán hàng mẫu của Microsoft. Script nạp nằm ở repo khác tên auto-ontology-eval. Thay <the same password> bằng mật khẩu Postgres bạn đã đặt:

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 khởi động riêng Postgres và chờ nó sẵn sàng. Dòng hai tải repo chứa script nạp, đặt ngang hàng với thư mục hiện tại. Khối trong ngoặc đơn chuyển sang thư mục đó, cài phụ thuộc bằng uv sync, rồi nạp cơ sở dữ liệu. Cờ --drop xóa cơ sở dữ liệu cùng tên (nếu có) để nạp lại từ đầu, nên đừng dùng tên cơ sở dữ liệu thật của bạn ở đây. Các dấu \ là xuống dòng của bash; trên PowerShell bạn nên gộp thành một dòng và đặt biến môi trường theo cú pháp PowerShell, hoặc chạy trong Git Bash/WSL.

D.Build và khởi động cả hệ thống

Terminal
docker compose up -d --build

Lệnh này build và chạy các dịch vụ còn lại ở chế độ nền. Lần đầu sẽ hơi lâu vì phải build image.

E.Đă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 và bật lên. Việc nạp dữ liệu chạy ngay khi khởi động; biên dịch 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, bạn đăng nhập được, và mục Semantic Compilation báo Semantic compilation is ready.

Sau đó thử một câu hỏi trong Chat:

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

Kết quả mong đợi là câu trả lời có con số doanh thu, kèm câu SQL đã chạy và các bước: xác định term (Invoice Line, Stock Item, State Province…), nối bảng, kiểm tra giá trị lọc rồi mới thực thi. Con số cụ thể phụ thuộc điều kiện bạn hỏi.

Nếu sau khi khởi động lại mà giao diện mất thanh điều hướng bên trái, đó là 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

A.Chủ cửa hàng hỏi doanh thu bằng tiếng thường

Bạn quản lý một cơ sở dữ liệu bán hàng và không rành SQL. Sau khi bật Semantic Compilation, bạn mở Chat và hỏi trực tiếp, ví dụ "doanh thu của sản phẩm X ở bang Y là bao nhiêu". Hệ thống tự tìm khái niệm doanh thu, sản phẩm, bang và nối các bảng cần thiết. Bạn nhận con số cùng SQL và các bước, có thể xem từng dòng dữ liệu hoặc tải CSV.

Con số nhanh mà không kiểm chứng được thì chỉ là phỏng đoán; có SQL đi kèm mới là câu trả lời.

Ông T

B.Nhân viên dữ liệu chuẩn hóa định nghĩa chung

Phòng ban nào cũng tính "biên lợi nhuận" một kiểu. Bạn vào giao diện, xem các term được sinh ra, chỉnh mô tả và SQL attribute, rồi certify khi đúng. Từ đó agent dùng lại đúng biểu thức đã duyệt, nên cùng một câu hỏi luôn ra cùng một cách tính. Kết quả là một bộ định nghĩa chung mà cả nhóm tin được.

C.Lập trình viên cắm vào Claude Desktop hoặc Cursor qua MCP

Bạn muốn trợ lý AI trong công cụ quen thuộc hỏi được dữ liệu. Chạy máy chủ MCP 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 (dùng cầu nối mcp-remote):

JSON
{
  "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 yêu cầu. Agent có các công cụ chỉ đọc như search_terms, check_answerable và ask_question. Công cụ check_answerable cho biết ontology có phủ được câu hỏi hay không trước khi trả lời, nên agent biết hỏi lại khi dữ liệu thiếu.

D.Tích hợp vào ứng dụng qua REST API

Bạn đang làm một công cụ nội bộ và cần gọi hỏi đáp từ mã. Tạo API token ở menu người dùng → API Tokens, rồi gọi theo README:

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

Phản hồi 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à cookie phiên cũ. Xóa dữ liệu trang cho localhost:3000 rồi đăng nhập lại.

Không kết nối được cơ sở dữ liệu. Thường do mật khẩu trong POSTGRES_PASSWORD khác mật khẩu trong CONNECTION_STRINGS, hoặc quên truyền mật khẩu khi chạy script nạp. Kiểm tra hai chỗ này khớp nhau, rồi chạy lại.

Mô hình không trả lời hoặc báo lỗi xác thực. Rất có thể khóa nvapi-... sai hoặc còn sót giá trị nvapi-your-api-key-here ở các vai trò mô hình. Thay bằng khóa thật hoặc xóa các dòng đó để dùng DEFAULT_MODELS_API_KEY.

Hỏi xong không ra kết quả vì chưa biên dịch. Hãy chắc chắn đã bật Semantic Compilation và thấy dòng "Semantic compilation is ready" trước khi hỏi.

Lỗi lạ khác khi cài. README chỉ tới troubleshooting guide trong skill setup và docs/mcp.md cho phần MCP. Xem hai chỗ này trong repo trước khi tự sửa.

Cổng 3001 (backend) và 3002 (ingestion) chỉ nên nằm trong mạng riêng. README cảnh báo dịch vụ ingestion không có xác thực riêng, và backend tin vào thông tin người dùng do giao diện web chuyển tới. Người dùng nên truy cập qua cổng 3000.

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

Điểm mạnh: câu trả lời kèm SQL và các bước nên kiểm chứng được; có cơ chế certify để định nghĩa chung ổn định; biết từ chối khi dữ liệu không đủ; kết nối được qua giao diện web, MCP và API; giấy phép Apache-2.0; tương thích chuẩn Apache Ossie để nhập và xuất mô hình ngữ nghĩa.

Giới hạn: cài đặt khá nặng so với một công cụ dòng lệnh đơn lẻ, vì gồm frontend, backend, worker nạp dữ liệu, Postgres và có thể cả Vault. Mặc định dựa vào NVIDIA NIM và khóa API của NVIDIA. README nêu rõ dự án hiện không nhận đóng góp từ bên ngoài. Chuyện chi phí gọi mô hình và yêu cầu phần cứng khi tự chạy NIM thì README chưa nói rõ.

Khi nên chọn cách khác: nếu bạn chỉ cần hỏi nhanh một file CSV nhỏ, một công cụ đơn giản hơn là đủ. Auto Ontology đáng dùng khi bạn có cơ sở dữ liệu quan hệ thật, nhiều bảng, nhiều người cùng hỏi, và quan trọng nhất là cần con số đáng tin để ra quyết định.

4.8/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 tải và dùng miễn phí. Tuy nhiên bạn cần khóa API của NVIDIA để gọi mô hình qua NIM. README chưa nêu chi phí cụ thể của dịch vụ này, bạn nên xem trang build.nvidia.com.

Cài Auto Ontology có cần GPU không?

Phần Quickstart của README dùng endpoint NIM (đám mây của NVIDIA) nên không thấy yêu cầu GPU trên máy bạn. Nếu muốn tự chạy NIM thì README chưa nêu cấu hình phần cứng; hãy xem DEPLOYMENT.md và docs/ trong repo.

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

Cách cài trong README dùng Docker Compose và uv, vốn có trên Windows. Tuy nhiên một số lệnh mẫu viết theo cú pháp bash (có dấu \ xuống dòng), nên trên Windows bạn nên dùng Git Bash hoặc WSL. README không có hướng dẫn riêng cho Windows.

Dữ liệu của mình có an toàn không?

Hệ thống có đăng nhập và phân quyền (Better Auth), và có tùy chọn HashiCorp Vault để lưu thông tin kết nối. README cũng dặn giữ cổng 3001 và 3002 trong mạng riêng và đổi mọi mật khẩu mặc định. Khi dùng NIM đám mây, câu hỏi và ngữ cảnh được gửi tới endpoint đó; chính sách xử lý dữ liệu chưa có trong tư liệu.

Auto Ontology khác gì việc để ChatGPT hay LLM tự viết SQL?

LLM thuần chỉ dựa vào tên bảng và cột nên dễ hiểu sai nghĩa. Auto Ontology thêm lớp định nghĩa đã duyệt (term, SQL attribute, relationship), kiểm tra câu truy vấn với dữ liệu, và trả về SQL cùng các bước để bạn đối chiếu. Nó cũng báo không trả lời được khi dữ liệu không có thông tin.

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

Có. Repo có máy chủ MCP chỉ đọc, README hướng dẫn cấu hình cho cả 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 khi được yêu cầu.

Có kết nối được với cơ sở dữ liệu của riêng mình không?

README mô tả việc kết nối nguồn dữ liệu quan hệ thông qua chuỗi kết nối và các skill như nvidia-ontology-setup, nhưng phần Quickstart chỉ hướng dẫn với cơ sở dữ liệu mẫu Wide World Importers. Chi tiết nối nguồn của bạn cần xem thêm docs/ và skill setup trong repo.

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.Điền cấu hình vào .env
    3. C.Chạy Postgres và nạp dữ liệu mẫu
    4. D.Build và khởi động cả hệ thống
    5. E.Đă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ủ cửa hàng hỏi doanh thu bằng tiếng thường
    2. B.Nhân viên dữ liệu chuẩn hóa định nghĩa chung
    3. C.Lập trình viên cắm vào Claude Desktop hoặc Cursor qua MCP
    4. D.Tích hợp vào ứng dụng 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ỏ.