# txtai: tìm kiếm ngữ nghĩa, RAG và agent AI trong một khung — hướng dẫn cài đặt và dùng

> txtai là framework mã nguồn mở viết bằng Python, gom cơ sở dữ liệu embeddings, tìm kiếm ngữ nghĩa, RAG, agent và workflow AI vào một chỗ. Bạn dùng nó để xây công cụ tìm kiếm theo nghĩa hoặc chat với dữ liệu riêng. Cài bằng một lệnh pip, chạy thử chỉ vài dòng Python.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-06-23 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/txtai-tim-kiem-ngu-nghia-rag-agent-ai-huong-dan

txtai là một framework AI tất cả-trong-một viết bằng Python, giúp bạn làm tìm kiếm theo ý nghĩa (semantic search), hỏi đáp trên dữ liệu riêng (RAG), agent tự giải quyết việc và các chuỗi xử lý bằng mô hình ngôn ngữ. Lõi của nó là một cơ sở dữ liệu embeddings, nơi gộp chỉ mục vector, đồ thị và cơ sở dữ liệu quan hệ.

Vấn đề nó giải quyết rất đời thường. Tìm kiếm truyền thống chỉ khớp từ khoá, nên gõ "tích cực" thì không ra tài liệu viết "rất tốt". Tìm theo ý nghĩa thì ra. Khi cần cho một mô hình ngôn ngữ (LLM) trả lời dựa trên tài liệu của bạn, txtai cung cấp luôn phần "kho tri thức" đó, bạn không phải ghép nhiều công cụ rời nhau.

Ai nên dùng? Lập trình viên mới biết chút Python, người làm dữ liệu, và nhân viên kỹ thuật muốn dựng công cụ nội bộ như tìm tài liệu, hỏi đáp theo quy trình công ty. Điểm đáng giá nhất: cài nhanh, ví dụ ngắn, chạy cục bộ không phải gửi dữ liệu sang nhiều dịch vụ từ xa. Repo hiện có khoảng 13.360 sao và khoảng 1.000 fork, dùng giấy phép Apache-2.0.

```repo
- repo | neuml/txtai
- kind | Framework
- desc | txtai là framework Python tất cả-trong-một cho tìm kiếm ngữ nghĩa, RAG, agent và workflow mô hình ngôn ngữ, chạy được trên máy bạn.
- stars | 13k
- lang | Python
- license | Apache-2.0
```

## txtai làm được gì

Dưới đây là những khả năng chính, kèm lợi ích thực tế.

- **Tìm kiếm vector kèm SQL, đồ thị, mô hình chủ đề.** Bạn tìm theo ý nghĩa chứ không chỉ theo từ khoá. Phù hợp khi kho tài liệu lớn mà người dùng hay diễn đạt mỗi người một kiểu.
- **Tạo embeddings cho nhiều loại dữ liệu.** Văn bản, tài liệu, âm thanh, hình ảnh và video đều có thể được lập chỉ mục. Ví dụ bạn có thể tìm ảnh bằng một câu mô tả.
- **Pipeline chạy bằng mô hình ngôn ngữ.** Có sẵn các việc như chạy prompt LLM, hỏi đáp, gán nhãn, chuyển giọng nói thành chữ, dịch, tóm tắt. Bạn không phải tự viết từng phần.
- **Workflow nối các pipeline lại.** Một quy trình có thể là microservice đơn giản hoặc chuỗi nhiều mô hình. Tài liệu nói rõ có những mô hình nhỏ chuyên biệt chạy nhanh và tốt hơn LLM lớn cho một số việc như tóm tắt hay dịch.
- **Agent.** Agent nối embeddings, pipeline, workflow và các agent khác để tự giải quyết việc phức tạp. Agent của txtai xây trên smolagents, hỗ trợ các LLM mà txtai hỗ trợ (Hugging Face, llama.cpp, OpenAI / Claude / AWS Bedrock qua LiteLLM). Nó cũng hỗ trợ prompt qua agents.md và skill.md.
- **RAG.** Giảm nguy cơ LLM "bịa" bằng cách ép câu trả lời dựa trên kho kiến thức của bạn. Thường dùng để "chat với dữ liệu của mình".
- **API web và MCP.** Bạn có thể dựng API rồi gọi từ ngôn ngữ khác. Có bản kết nối cho JavaScript, Java, Rust và Go.
- **Chạy cục bộ hoặc mở rộng bằng container.** Bắt đầu nhỏ, cần thì cài thêm phụ thuộc và nâng quy mô.

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

Tư liệu chỉ nêu những điều sau:

- **Python 3.11 trở lên.** Đây là phiên bản được hỗ trợ.
- **Môi trường ảo (virtual environment) của Python** được khuyến nghị dùng.
- **Kết nối mạng** để tải mô hình từ Hugging Face Hub khi bạn không chỉ định mô hình có sẵn trong máy. Tài liệu nói đường dẫn mô hình là tuỳ chọn, nếu bỏ trống thì txtai nạp mô hình mặc định.

Tư liệu không nêu yêu cầu cụ thể về hệ điều hành, RAM hay GPU, cũng không nói bắt buộc phải có API key. Nếu bạn dùng LLM của OpenAI, Claude hay AWS Bedrock thì tất nhiên cần tài khoản của nhà cung cấp đó, nhưng đó là việc riêng của dịch vụ. Hướng dẫn chi tiết về điều kiện theo từng môi trường nằm ở trang cài đặt trong tài liệu chính thức của dự án.

```note
Nếu bạn dùng LLM của bên thứ ba qua API, hãy giữ key ở biến môi trường hoặc file cấu hình riêng, đừng dán vào mã nguồn rồi đưa lên GitHub. Gọi API có thể phát sinh chi phí tính theo nhà cung cấp.
```

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

```steps
- Kiểm tra Python | Chắc chắn máy có Python 3.11 trở lên
- Tạo môi trường ảo | Tách thư viện của txtai khỏi các dự án khác
- Cài txtai | Chạy một lệnh pip
- Chạy thử vài dòng Python | Tạo chỉ mục và tìm kiếm
- (Tuỳ chọn) Dựng API | Viết file cấu hình rồi chạy uvicorn
```

### Kiểm tra phiên bản Python

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) rồi gõ lệnh dưới đây. Bạn cần thấy số phiên bản từ 3.11 trở lên.

```bash
python --version
```

Nếu ra số nhỏ hơn 3.11, bạn cần cài bản Python mới hơn trước khi tiếp tục. Chỗ người mới hay vấp: máy có nhiều bản Python và lệnh `python` trỏ vào bản cũ.

### Tạo môi trường ảo

Tư liệu khuyến nghị dùng môi trường ảo. Cách tạo phổ thông của Python như sau. Hãy đứng trong thư mục dự án của bạn rồi chạy:

```bash
python -m venv venv
```

Kích hoạt môi trường. Trên Windows (PowerShell):

```powershell
venv\Scripts\activate
```

Trên macOS/Linux:

```bash
source venv/bin/activate
```

Kích hoạt xong, đầu dòng lệnh thường hiện thêm chữ `(venv)`.

### Cài txtai

Đây là cách cài dễ nhất theo README, qua pip và PyPI:

```bash
pip install txtai
```

Lệnh này tải txtai và các phụ thuộc cơ bản. Tài liệu nói txtai có "dung lượng nhẹ": cần tính năng nào thì cài thêm phụ thuộc cho tính năng đó. README chưa liệt kê tên các nhóm phụ thuộc tuỳ chọn ngay trong trang chính, bạn xem mục Optional dependencies trong trang install của tài liệu dự án (https://neuml.github.io/txtai/install). Repo cũng có hướng dẫn cài từ mã nguồn, conda, bản cài tối giản và chạy bằng container (thư mục docker/ trong repo).

### Chạy thử vài dòng Python

Tạo file, ví dụ `thu.py`, rồi dán đoạn sau (chép từ README):

```python
# Get started in a couple lines
import txtai

embeddings = txtai.Embeddings()
embeddings.index(["Correct", "Not what we hoped"])
embeddings.search("positive", 1)
#[(0, 0.29862046241760254)]
```

Đoạn này tạo một đối tượng embeddings, lập chỉ mục hai câu, rồi tìm câu gần nghĩa nhất với từ "positive". Lần chạy đầu có thể lâu hơn vì phải tải mô hình mặc định. Bạn chạy file bằng `python thu.py` (nhớ thêm lệnh in kết quả nếu muốn thấy trên màn hình, ví dụ bọc `embeddings.search(...)` trong `print(...)`).

### (Tuỳ chọn) Dựng API

Nếu muốn gọi txtai từ ngôn ngữ khác, tạo file `app.yml` có nội dung:

```yaml
# app.yml
embeddings:
    path: sentence-transformers/all-MiniLM-L6-v2
```

Rồi chạy (cú pháp bash trong README), rồi gọi thử bằng curl:

```bash
CONFIG=app.yml uvicorn "txtai.api:app"
curl -X GET "http://localhost:8000/search?query=positive"
```

Dòng đầu khởi động máy chủ API đọc cấu hình từ `app.yml`. Dòng sau hỏi máy chủ với từ khoá "positive". Trên PowerShell không dùng được kiểu `CONFIG=... lệnh` ở đầu dòng, bạn đặt biến môi trường trước bằng `$env:CONFIG = "app.yml"` rồi chạy `uvicorn "txtai.api:app"`. Nếu báo thiếu uvicorn hoặc thành phần API, hãy xem mục phụ thuộc tuỳ chọn trong trang install của tài liệu, README chưa ghi tên gói cần thêm.

## Kiểm tra đã chạy được chưa

Với đoạn Python ở trên, kết quả mong đợi theo README là một danh sách có một cặp (số thứ tự, điểm tương đồng), dạng `[(0, 0.29862046241760254)]`. Số thứ tự `0` nghĩa là câu "Correct" (vị trí đầu tiên) được xem là gần nghĩa với "positive" nhất. Điểm số của bạn có thể lệch đôi chút tuỳ mô hình tải về.

Với API, nếu `curl` trả về dữ liệu JSON thay vì lỗi kết nối thì máy chủ đang chạy. Khi lỗi `Connection refused`, thường là máy chủ chưa khởi động xong hoặc bạn gọi sai cổng.

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

Các tình huống dưới đây bám theo khả năng được tư liệu nêu. README không cho sẵn từng đoạn mã cho các tình huống này, nên mình chỉ mô tả hướng làm và chỉ nơi có ví dụ chính thức trong repo.

### Chủ shop muốn tìm đơn hàng và câu hỏi khách theo ý nghĩa

Bạn có một bảng vài trăm câu hỏi khách hay gặp. Khách viết "hàng chưa tới", nhưng câu mẫu của bạn ghi "đơn giao chậm". Tìm theo từ khoá sẽ trượt. Bạn dùng `Embeddings` để lập chỉ mục các câu mẫu rồi `search` bằng câu của khách, như ví dụ ở bước chạy thử. Kết quả là câu mẫu gần nghĩa nhất, bạn có thể gửi kèm câu trả lời đã soạn. Repo có sổ tay mẫu tên "Build a QA database" nói đúng về việc ghép câu hỏi bằng tìm kiếm ngữ nghĩa.

### Nhân viên văn phòng muốn hỏi đáp trên tài liệu nội bộ

Công ty có nhiều file quy trình, bạn muốn hỏi "quy trình hoàn tiền gồm mấy bước?" và nhận câu trả lời dựa trên đúng tài liệu. Đây là RAG: txtai tìm đoạn liên quan rồi đưa cho LLM làm ngữ cảnh. Repo có sẵn file `examples/rag_quickstart.py` làm điểm xuất phát, và sổ tay "Build RAG pipelines with txtai" hướng dẫn cả cách tạo trích dẫn nguồn.

> Tìm theo ý nghĩa thay vì theo từ khoá là bước đầu tiên để dữ liệu của bạn trả lời được người thật.
>
> — Ông T

### Dev mới muốn nối nhiều bước xử lý thành một quy trình

Bạn có file ghi âm cuộc họp, cần chuyển thành chữ, tóm tắt, rồi dịch. Mỗi việc đã có pipeline riêng (transcription, summary, translation), và workflow nối chúng lại thành một chuỗi. Kết quả là một quy trình chạy từ đầu đến cuối mà bạn không phải tự viết keo dán giữa các mô hình. Xem `examples/workflow_quickstart.py` và các sổ tay "Transcribe audio to text", "Building abstractive text summaries".

### Người muốn thử agent tự xử lý việc

Bạn muốn một agent biết dùng kho tri thức và công cụ để tự tìm câu trả lời qua nhiều bước. txtai hỗ trợ agent xây trên smolagents, và có thể đọc các file skill.md. Bắt đầu từ `examples/agent_quickstart.py`, sau đó xem sổ tay "Agent Tools" và "TxtAI got skills". Hãy thử trên dữ liệu không nhạy cảm trước để quen hành vi của agent.

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

- **Báo không tìm thấy gói hoặc lỗi cài đặt.** Thường do Python cũ hơn 3.11. Kiểm tra lại bằng `python --version`, và dùng đúng môi trường ảo đã kích hoạt khi chạy `pip install txtai`.
- **Chạy lần đầu rất lâu hoặc báo lỗi tải mô hình.** Mô hình mặc định được tải từ Hugging Face Hub. Hãy kiểm tra kết nối mạng, đợi tải xong. Nếu mạng bị chặn, bạn có thể dùng mô hình trong thư mục cục bộ vì tài liệu nói đường dẫn mô hình có thể là thư mục trên máy.
- **Báo thiếu module khi dùng tính năng như API, âm thanh, agent.** Vì txtai cài "nhẹ" nên một số tính năng cần phụ thuộc thêm. Xem mục Optional dependencies trong trang cài đặt của tài liệu và cài đúng nhóm cần dùng, đừng đoán tên gói.
- **Lệnh `CONFIG=app.yml uvicorn ...` báo lỗi trên Windows PowerShell.** Cú pháp gán biến ở đầu dòng là của bash. Dùng Git Bash, hoặc đặt biến trong PowerShell bằng `$env:CONFIG = "app.yml"` rồi chạy `uvicorn "txtai.api:app"`.
- **Kết quả tìm kiếm không như ý.** Mô hình embeddings mặc định chọn cho tốc độ và gọn nhẹ. Bảng "Model guide" của dự án liệt kê mô hình được khuyến nghị, và có thể đổi bằng tham số `path` như trong `app.yml`. Hãy thử đổi mô hình rồi lập chỉ mục lại.

## Có nên dùng không

**Điểm mạnh.** Cài nhanh, khởi động chỉ vài dòng, có sẵn nhiều thành phần (tìm kiếm, RAG, agent, workflow, API) trong một khung. Chạy cục bộ nên bạn kiểm soát dữ liệu. Có hơn 70 sổ tay ví dụ và ứng dụng mẫu, repo vẫn được cập nhật trong vài tháng gần đây. Giấy phép Apache-2.0, bảng mô hình khuyến nghị đều cho phép dùng thương mại.

**Giới hạn.** Đây là thư viện cho người viết được ít nhiều code Python, không phải ứng dụng bấm là dùng. README chưa nêu yêu cầu phần cứng, nên với mô hình lớn bạn cần tự kiểm tra máy có đủ sức không. Tài liệu chính thức nằm ở trang riêng, README chỉ là phần giới thiệu, nên bạn sẽ phải đọc thêm khi dùng sâu.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần tìm kiếm từ khoá đơn giản trong vài file, một công cụ tìm kiếm thông thường là đủ. Nếu bạn không biết lập trình và chỉ muốn giao diện hỏi đáp có sẵn, hãy tìm một ứng dụng đóng gói sẵn. Một lựa chọn là ứng dụng RAG của chính nhóm tác giả, được liệt kê trong mục "Powered by txtai" của README. Còn nếu bạn muốn học cách các thành phần AI ghép lại với nhau và dựng công cụ của riêng mình, txtai là điểm bắt đầu hợp lý.

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

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

txtai là mã nguồn mở theo giấy phép Apache-2.0, cài bằng pip không mất phí. Nếu bạn dùng LLM của bên thứ ba qua API thì chi phí thuộc nhà cung cấp đó. README cũng nhắc tới dịch vụ tư vấn và nền tảng hosted txtai.cloud của NeuML, nhưng đây là tuỳ chọn riêng.

### txtai cần Python phiên bản nào?

README ghi txtai được xây với Python 3.11 trở lên và Python 3.11+ là phiên bản được hỗ trợ. Dự án khuyến nghị dùng môi trường ảo của Python khi cài.

### Có cần GPU để chạy txtai không?

Tư liệu không nêu yêu cầu GPU hay phần cứng cụ thể. README chỉ nói txtai chạy được với từ mô hình nhỏ (micromodel) đến mô hình ngôn ngữ lớn, nên yêu cầu máy phụ thuộc vào mô hình bạn chọn.

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

README nhấn mạnh txtai chạy cục bộ, bạn không cần gửi dữ liệu sang nhiều dịch vụ từ xa. Tuy vậy nếu bạn chọn LLM qua API bên thứ ba thì dữ liệu gửi đi sẽ theo chính sách của nhà cung cấp đó, nên hãy kiểm tra trước khi dùng với dữ liệu nhạy cảm.

### Dùng trên Windows được không?

Tư liệu không nêu riêng hệ điều hành nào, chỉ nói cài qua pip với Python 3.11+. Trang cài đặt chính thức có mục về yêu cầu theo từng môi trường, bạn nên xem ở đó. Lưu ý lệnh đặt biến CONFIG kiểu bash trong README cần chuyển sang cú pháp PowerShell.

### txtai khác gì một cơ sở dữ liệu vector thông thường?

Theo README, lõi của txtai là cơ sở dữ liệu embeddings gộp chỉ mục vector, đồ thị và cơ sở dữ liệu quan hệ. Ngoài ra txtai còn có pipeline, workflow, agent và API trong cùng một framework. README không so sánh trực tiếp với một sản phẩm cụ thể nào.

### Có thể gọi txtai từ ngôn ngữ khác ngoài Python không?

Có. txtai có API web và API theo chuẩn MCP, cùng các bản kết nối cho JavaScript, Java, Rust và Go theo README. Bạn dựng API bằng file cấu hình YAML rồi gọi qua HTTP.
