# 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

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

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-05 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/auto-ontology-lop-ngu-nghia-giup-ai-hoi-dap-du-lieu

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.

```repo
- repo | NVIDIA/auto-ontology
- kind | Framework
- desc | 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.
- stars | 12k
- lang | Python
- license | Apache-2.0
```

## 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.

## 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.

```note
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í.
```

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

```steps
- Chuẩn bị công cụ | Có Docker Compose v2, uv, git và khóa nvapi-
- Tải mã và tạo .env | Clone repo, sao chép .env.example thành .env rồi điền giá trị
- Nạp dữ liệu mẫu | Chạ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ĩa | Mở 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.

### 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:

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

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

- `<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_*`.

### Chạy Postgres và nạp dữ liệu 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)
```

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.

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

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

### Đă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.

## 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.

## 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`.

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

### 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.

### 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:

```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, 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.

### 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:

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

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ộ.

## 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.

## 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.
