# Auto Ontology: hỏi dữ liệu bằng tiếng người, ra SQL kiểm chứng được — hướng dẫn cài đặt và dùng

> Auto Ontology là framework 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, đơn hàng là gì, rồi trả lời câu hỏi kèm SQL và các bước đã làm. Cài bằng Docker Compose khá nhiều bước, cần Docker, uv và một khoá API NVIDIA.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-07 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/nvidia-auto-ontology-hoi-dap-du-lieu-sql-co-kiem-chung

Auto Ontology là một thư viện mã nguồn mở của NVIDIA, dùng để dựng một "lớp ngữ cảnh" nằm giữa AI và cơ sở dữ liệu của bạn. Lớp này ghi rõ dữ liệu nằm ở đâu, mỗi chỉ số nghĩa là gì, bảng nào nối với bảng nào. Nhờ vậy khi bạn hỏi bằng tiếng thường, AI không đoán mò mà tra theo định nghĩa đã được duyệt. Hiện repo có khoảng 12.388 sao và 1.017 fork.

Vấn đề nó giải quyết rất thực tế: một con số doanh thu trả lời nhanh nhưng sai thì không có giá trị gì. Nhiều công cụ hỏi đáp dữ liệu chỉ viết SQL theo cảm tính. Auto Ontology thì bắt AI phải đi qua danh sách thuật ngữ (term), công thức SQL đã duyệt và quan hệ giữa các bảng. Mỗi câu trả lời đều kèm SQL và các bước đã làm để bạn đối chiếu.

Repo hợp với dev, kỹ sư dữ liệu, hoặc người làm phân tích muốn cho AI hỏi đáp trên database nội bộ một cách đáng tin. Người làm kinh doanh vẫn dùng được phần giao diện web, nhưng việc cài đặt cần chút quen tay với terminal và Docker. Điểm đáng giá nhất là khả năng kiểm chứng: câu trả lời luôn đi kèm SQL, và khi dữ liệu không đủ để trả lời thì hệ thống nói thẳng là không trả lời được.

```repo
- repo | NVIDIA/auto-ontology
- kind | Framework
- desc | Thư viện mã nguồn mở của NVIDIA dựng lớp ngữ nghĩa trên cơ sở dữ liệu, để AI hỏi đáp bằng ngôn ngữ thường và trả lời kèm SQL, bước làm, nguồn gốc.
- stars | 12k
- lang | Python
- license | Apache-2.0
```

## Auto Ontology làm được gì

Theo README, thư viện xoay quanh năm việc: khám phá, neo nghĩa, kiểm tra, mở ra cho agent và học lại. Dưới đây là những gì có lợi nhất khi dùng thật.

- **Hỏi dữ liệu bằng ngôn ngữ thường.** Bạn gõ câu hỏi, hệ thống dịch thành SQL, chạy trên database đã kết nối rồi trả kết quả. Phần suy luận chạy bằng các model của NVIDIA NIM.
- **Tự dựng ontology từ metadata.** Hệ thống đọc schema, thống kê cột, lấy mẫu giá trị, rồi tự rút ra các thuật ngữ như Khách hàng hay Dòng hoá đơn và ánh xạ chúng vào đúng cột. Bạn không phải ngồi viết tay từ đầu.
- **Ba loại định nghĩa rõ ràng.** Term là khái niệm kinh doanh. SQL attribute là biểu thức SQL đã duyệt (ví dụ biên lợi nhuận, tổng luỹ kế). Relationship là cách các bảng nối nhau. Vì AI dùng lại biểu thức đã duyệt, cùng một chỉ số luôn được tính cùng một cách.
- **Con người chứng nhận (certify).** Bản nháp do máy sinh ra, bạn thử bằng câu hỏi thật rồi sửa mô tả, thuật ngữ, công thức. Khi đúng thì chứng nhận lại.
- **Biết từ chối khi không đủ dữ liệu.** Nếu câu hỏi không có thuật ngữ nào khớp, agent báo không trả lời được thay vì bịa.
- **Giao diện web.** Có Chat, phân tích, danh mục dữ liệu, thống kê và cài đặt. Có đăng nhập và phân quyền (RBAC) dùng Better Auth.
- **Nhiều cách nối vào agent.** Có máy chủ MCP (chỉ đọc), REST API và ba skill dành cho agent lập trình.
- **Trao đổi mô hình ngữ nghĩa.** Tương thích Apache Ossie. Bạn nhập/xuất định nghĩa dưới dạng Ossie YAML ở Settings → Import / Export.

## Cần chuẩn bị gì

Theo README quickstart, bạn cần:

- **Docker kèm Compose v2.** Toàn bộ hệ thống chạy bằng Docker Compose.
- **uv** (trình quản lý Python), dùng để nạp dữ liệu mẫu. Gói server của repo yêu cầu Python từ 3.12 đến dưới 3.14.
- **Khoá API NVIDIA** dạng `nvapi-...`, lấy tại build.nvidia.com. Mặc định repo gọi các endpoint NVIDIA NIM (có thể là NIM tự host).
- **Mật khẩu do bạn tự đặt** cho Postgres, tài khoản quản trị Auto Ontology và pgAdmin.

Bản mặc định dùng ba model: LLM `nvidia/nemotron-3.5-lightning-30b-a3b`, embedding `nvidia/nemotron-3-embed-1b` và reranker `nvidia/llama-nemotron-rerank-vl-1b-v2`. README không nói gì về yêu cầu GPU hay cấu hình máy tối thiểu khi dùng endpoint NVIDIA đặt sẵn, nên mình không khẳng định thêm. Về hệ điều hành, README cũng không nêu rõ, và các lệnh mẫu viết theo kiểu shell bash.

```note
Khoá API và mật khẩu là thứ nhạy cảm. Docker Compose của repo mở Postgres, pgAdmin và web ra máy chủ, nên README yêu cầu thay hết mật khẩu mặc định trước khi chạy. Đừng đưa file .env lên chỗ công khai. Việc gọi model qua NVIDIA API có thể phát sinh giới hạn hoặc chi phí theo tài khoản của bạn, hãy xem điều khoản ở build.nvidia.com.
```

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

Bản quickstart chạy Auto Ontology bằng Docker Compose trên Wide World Importers, một database bán hàng mẫu của Microsoft. Cách này an toàn để thử vì bạn chưa phải nối dữ liệu thật.

```steps
- Chuẩn bị công cụ | Cài Docker (Compose v2), uv và lấy khoá nvapi từ build.nvidia.com
- Tải repo, tạo .env | Clone repo và sao chép .env.example thành .env
- Điền .env | Đặt khoá API, mật khẩu và chuỗi kết nối
- Nạp dữ liệu mẫu | Chạy Postgres rồi nạp Wide World Importers
- Chạy cả hệ thống | Build và khởi động toàn bộ bằng Docker Compose
- Đăng nhập và bật biên dịch | Mở localhost:3000, bật Semantic Compilation
```

### Chuẩn bị Docker, uv và khoá API

Mở build.nvidia.com, tạo khoá dạng `nvapi-...` và lưu lại. Kiểm tra Docker đã chạy và có Compose v2. Cài uv theo hướng dẫn trên trang chủ của nó. Bước này chưa có lệnh nào của repo.

### Tải repo và tạo file .env

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

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

Dòng đầu tải mã nguồn và đi vào thư mục. Dòng sau sao chép file mẫu thành file cấu hình thật. Nếu bạn dùng Windows PowerShell bản cũ không hiểu `&&`, hãy chạy `git clone` và `cd auto-ontology` thành hai dòng riêng.

### Điền giá trị vào .env

Mở file `.env` vừa tạo bằng trình soạn thảo và đặt các giá trị theo README:

```dotenv
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:

- Mật khẩu trong `CONNECTION_STRINGS` phải đúng bằng `POSTGRES_PASSWORD` bạn vừa đặt.
- File `.env.example` còn đặt khoá riêng cho từng vai trò model, với giá trị `nvapi-your-api-key-here`. Bạn hoặc thay từng chỗ bằng khoá thật, hoặc xoá các dòng đó để chúng tự dùng `DEFAULT_MODELS_API_KEY`.
- Cách cấu hình model theo bộ ba `_ENDPOINT`, `_API_KEY`, `_MODEL`. Trường nào để trống sẽ lấy giá trị từ `DEFAULT_MODELS_*`. Cách đơn giản nhất là chỉ điền `DEFAULT_MODELS_*`.
- README có nhắc đăng nhập bằng `AUTO_ONTOLOGY_ADMIN_EMAIL`. Hãy kiểm tra biến này trong `.env`.

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

Bước này khởi động Postgres trước, rồi tải repo `auto-ontology-eval` (chứa script nạp dữ liệu) và nạp database mẫu:

```bash
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)
```

Thay `<the same password>` bằng mật khẩu Postgres bạn đã đặt. Đoạn lệnh trong ngoặc tròn chạy ở thư mục anh em `../auto-ontology-eval`, nên đừng đổi thư mục lung tung giữa chừng. Cờ `--drop` có sẵn trong lệnh của README. Lệnh này viết theo bash, nếu dùng Windows hãy chạy trong một terminal bash như Git Bash hoặc WSL.

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

```bash
docker compose up -d --build
```

Lệnh này dựng và chạy các dịch vụ còn lại (web, backend, ingestion...). Lần đầu build sẽ mất một lúc.

### Đă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 bắt đầu ngay và báo **Semantic compilation is ready** khi xong.

## 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à thông báo **Semantic compilation is ready** hiện ra sau khi bật biên dịch. Sau đó vào **Chat** và hỏi thử:

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

Kết quả mong đợi: câu trả lời cho biết doanh thu khoảng 588,80 đô la từ 3 dòng hoá đơn, kèm đoạn SQL và các bước (xác định thuật ngữ, nối bảng, kiểm tra giá trị lọc rồi mới chạy). Nếu nhận được cả câu trả lời lẫn SQL thì hệ thống đã chạy đúng.

Nếu giao diện lên mà thiếu thanh điều hướng bên trái sau khi khởi động lại, đó là cookie phiên cũ, xem phần lỗi bên dưới.

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

### Chủ cửa hàng hỏi doanh thu mà không biết SQL

Bạn quản lý bán hàng và có database đơn hàng. Thay vì nhờ bộ phận kỹ thuật viết truy vấn, bạn vào Chat và gõ câu hỏi bằng ngôn ngữ thường, ví dụ như câu về doanh thu của một sản phẩm ở một bang trong một tháng. Agent xác định các thuật ngữ như doanh thu, sản phẩm, bang, theo quan hệ giữa các bảng để nối cho đúng rồi chạy truy vấn. Kết quả là con số kèm SQL và các bước. Bạn có thể xem các dòng dữ liệu, tải về CSV hoặc xem dạng biểu đồ.

> Con số nhanh mà sai thì không có giá trị. Điều đáng tin ở đây là câu trả lời nào cũng kèm SQL để bạn tự kiểm.
>
> — Ông T

### Biết trước câu hỏi nào dữ liệu không trả lời được

Nhân viên phân tích hỏi về lợi tức trên chi phí quảng cáo, nhưng database chỉ có dữ liệu bán hàng. Qua MCP, agent gọi `check_answerable` trước. Theo README, nó báo độ phủ 0,5 và nói rõ không có thuật ngữ nào ứng với chi phí quảng cáo. Sau đó nó đề xuất hỏi doanh thu thay thế, hoặc hỏi bạn có nguồn dữ liệu quảng cáo khác cần kết nối không. Giá trị ở đây là tránh được những con số nghe hợp lý nhưng bịa.

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

Máy chủ MCP cho client các công cụ chỉ đọc như `check_readiness`, `search_terms`, `get_term`, `check_answerable` và `ask_question`. Mỗi người dùng đăng nhập qua Auto Ontology và mọi lệnh gọi chạy với quyền của người đó. Chạy máy chủ MCP theo README:

```bash
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, thêm vào `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"]
    }
  }
}
```

Sau khi sửa cấu hình, khởi động lại client rồi đăng nhập khi được yêu cầu. Từ đó bạn có thể nhờ agent hỏi dữ liệu ngay trong khung chat quen thuộc.

### Dev đưa câu hỏi dữ liệu vào ứng dụng của mình qua REST API

Bạn muốn một ứng dụng nội bộ tự hỏi dữ liệu. Tạo API token ở menu người dùng → **API Tokens**, rồi gọi `POST /api/chat/completions` trên địa chỉ của web app:

```bash
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à một luồng server-sent event. Sự kiện `result` mang câu trả lời và `data: [DONE]` báo kết thúc. Phần còn lại của README bị cắt trong tư liệu mình có, nên chi tiết khác của API hãy xem thêm trong repo.

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

**Giao diện lên nhưng mất 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ũ. Xoá dữ liệu trang (site data) của localhost:3000 rồi đăng nhập lại.

**Không đăng nhập được hoặc không kết nối được database.** Kiểm tra mật khẩu trong `CONNECTION_STRINGS` có khớp `POSTGRES_PASSWORD` không, và các giá trị trong `.env` đã được điền đủ chưa. Sau khi sửa `.env`, chạy lại `docker compose up -d --build`.

**Model không trả lời hoặc báo lỗi xác thực.** Thường do khoá sai hoặc chưa thay các dòng `nvapi-your-api-key-here` còn sót trong `.env`. Hãy thay bằng khoá thật hoặc xoá các dòng đó để dùng `DEFAULT_MODELS_API_KEY`. README cũng lưu ý model embedding phải giống nhau giữa lúc nạp dữ liệu và lúc truy vấn, nên đừng đổi `EMBED_MODEL` giữa chừng mà không nạp lại.

**Client MCP không thấy công cụ.** Đảm bảo máy chủ MCP đang chạy ở cổng 3003 và bạn đã khởi động lại client sau khi sửa file cấu hình. Chi tiết đăng nhập và xử lý sự cố nằm trong docs/mcp.md của repo.

**Mở cổng nội bộ ra ngoài.** Cổng 3001 và 3002 phải nằm trong mạng riêng. README cảnh báo backend tin vào header danh tính do frontend gửi, và dịch vụ ingestion không có xác thực riêng. Hãy cho người dùng đi qua cổng 3000.

Với các lỗi cài đặt khác, README chỉ tới hướng dẫn xử lý sự cố trong skill setup của repo.

## 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ó bước con người chứng nhận định nghĩa. Có phân quyền theo người dùng. Có nhiều cách nối vào agent (web, MCP, API, skill). Giấy phép Apache-2.0 và repo được cập nhật trong vài tháng gần đây.

**Giới hạn.** Cài đặt khá nặng: Docker, nhiều dịch vụ, Postgres kèm pgvector, nhiều biến môi trường. Mặc định phụ thuộc vào endpoint NVIDIA NIM và cần khoá API. README chỉ nói rõ về dữ liệu quan hệ (SQL), không nói về dữ liệu dạng khác. Dự án hiện không nhận đóng góp từ bên ngoài. Các vấn đề như yêu cầu phần cứng khi tự host, hay hiệu năng trên database lớn, tư liệu mình có chưa đề cập.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần hỏi nhanh một file Excel hoặc CSV nhỏ, công cụ nhẹ hơn sẽ đỡ công cài hơn. Còn nếu bạn có database thật, nhiều bảng, nhiều định nghĩa chỉ số cần thống nhất và cần câu trả lời giải thích được, thì Auto Ontology đáng để thử trước trên dữ liệu mẫu như hướng dẫn rồi mới nối dữ liệu của mình.

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

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

Mã nguồn phát hành theo giấy phép Apache-2.0 nên dùng và chạy tự do. Tuy nhiên mặc định nó gọi các endpoint NVIDIA NIM và cần khoá API từ build.nvidia.com. Tư liệu chưa nói rõ về hạn mức hay chi phí của khoá, bạn nên xem điều khoản bên NVIDIA.

### Có cần GPU không?

README không yêu cầu GPU cho quickstart. Phần suy luận chạy qua endpoint NVIDIA NIM (hosted hoặc tự host). Nếu bạn tự host NIM thì yêu cầu phần cứng, tư liệu chưa có thông tin.

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

README không nêu rõ danh sách hệ điều hành hỗ trợ. Cách chạy chính là Docker Compose, còn các lệnh mẫu viết theo kiểu bash. Trên Windows bạn nên chạy lệnh trong terminal bash như Git Bash hoặc WSL.

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

README nói mỗi người dùng đăng nhập riêng và các lệnh gọi MCP chạy với quyền của người đó. Có phân quyền RBAC và tuỳ chọn dùng HashiCorp Vault để lưu thông tin kết nối. Bạn nên giữ cổng 3001 và 3002 trong mạng riêng và đổi hết mật khẩu mặc định.

### Khác gì việc cho AI tự viết SQL?

Thay vì để AI đoán, Auto Ontology cho nó tra thuật ngữ, công thức SQL đã duyệt và quan hệ giữa các bảng. Mỗi câu trả lời kèm SQL và các bước, và hệ thống báo không trả lời được khi dữ liệu không phủ câu hỏi. Tư liệu không so sánh trực tiếp với một công cụ cụ thể nào khác.

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

Có. Repo có máy chủ MCP, README hướng dẫn cấu hình cho Cursor và cho Claude Desktop (qua mcp-remote). Ngoài ra có ba skill cho agent lập trình và REST API.

### Có kết nối được database của riêng tôi không?

Mục tiêu của repo là xây lớp ngữ nghĩa trên các nguồn dữ liệu quan hệ và có skill nvidia-ontology-setup để kết nối nguồn. Quickstart trong tư liệu chỉ hướng dẫn với database mẫu, nên chi tiết nối nguồn của bạn hãy xem skill và tài liệu trong repo.
