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

> txtai là một framework AI mã nguồn mở viết bằng Python. Nó gom tìm kiếm ngữ nghĩa, RAG (hỏi đáp trên dữ liệu của bạn), agent và workflow mô hình ngôn ngữ vào một thư viện. Cài chỉ cần một lệnh pip, cần Python 3.11 trở lên, và có thể chạy thử chỉ với vài dòng code.

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

txtai là một framework AI "tất cả trong một" viết bằng Python. Nó giúp bạn làm tìm kiếm theo ý nghĩa, hỏi đáp trên dữ liệu riêng (RAG), xây agent tự giải quyết việc, và nối nhiều mô hình AI thành một quy trình. Phần lõi của nó là một cơ sở dữ liệu embeddings, tức là chỗ lưu và tìm dữ liệu theo nghĩa chứ không chỉ theo từ khoá.

Vấn đề mà repo giải quyết khá quen thuộc. Công cụ AI hiện nay mọc lên từng ngày: cơ sở dữ liệu vector một nơi, framework LLM một nơi, công cụ dịch hay phiên âm một nơi nữa. Ghép chúng lại rất mệt. txtai gom những mảnh đó vào một thư viện, có sẵn mặc định để bạn chạy được ngay. Nó phù hợp với lập trình viên mới, người làm dữ liệu, và dân văn phòng biết chút Python muốn tự dựng công cụ tìm kiếm hoặc trợ lý đọc tài liệu nội bộ.

Điểm đáng giá nhất là bạn chạy được cục bộ, không bắt buộc gửi dữ liệu lên nhiều dịch vụ từ xa. Cài đặt nhẹ, cần thêm tính năng thì mới cài thêm. Repo hiện có khoảng 13.360 sao và 1.000 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây.

```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 ngay trên máy bạn.
- stars | 13k
- lang | Python
- license | Apache-2.0
```

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

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

### Tìm kiếm ngữ nghĩa và cơ sở dữ liệu embeddings

Tìm kiếm kiểu cũ dựa vào từ khoá. Tìm kiểu ngữ nghĩa hiểu ngôn ngữ tự nhiên, nên nó trả về kết quả cùng ý nghĩa dù không trùng chữ. Ví dụ bạn gõ "positive" thì câu "Correct" vẫn được xếp lên đầu. README mô tả cơ sở dữ liệu embeddings của txtai là sự kết hợp của chỉ mục vector (thưa và dày), đồ thị mạng và cơ sở dữ liệu quan hệ. Nó cũng hỗ trợ truy vấn bằng SQL, lưu trữ đối tượng, mô hình hoá chủ đề và phân tích đồ thị.

### Embeddings cho nhiều loại dữ liệu

Bạn tạo embeddings không chỉ cho văn bản mà cả tài liệu, âm thanh, hình ảnh và video. Nhờ vậy bạn có thể làm những việc như tìm ảnh bằng một câu mô tả.

### Pipeline và workflow

Pipeline là các bước chạy bằng mô hình ngôn ngữ: chạy prompt LLM, hỏi đáp, gán nhãn, phiên âm, dịch, tóm tắt và nhiều việc khác. Workflow nối các pipeline lại để gom logic nghiệp vụ. README nhấn mạnh rằng nhiều mô hình nhỏ chuyên biệt có thể nhanh và hiệu quả hơn LLM lớn cho một tác vụ cụ thể, như tóm tắt hay dịch.

### Agent và RAG

Agent kết 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 framework smolagents. Chúng hỗ trợ các LLM mà txtai hỗ trợ: Hugging Face, llama.cpp, và OpenAI, Claude hay AWS Bedrock qua LiteLLM. README cũng nói txtai hỗ trợ viết prompt cho agent bằng agents.md và skill.md.

RAG (retrieval augmented generation) là cách giảm nguy cơ LLM "bịa": bạn bắt mô hình trả lời dựa trên kho kiến thức của mình. Đây là cách phổ biến để "chat với dữ liệu của bạn".

### API và các ngôn ngữ khác

txtai có API web và API theo chuẩn Model Context Protocol (MCP). README liệt kê thư viện kết nối cho JavaScript, Java, Rust và Go. Bạn có thể xây ứng dụng bằng ngôn ngữ quen thuộc mà vẫn dùng txtai làm phần "não" ở phía sau.

### Chạy cục bộ hoặc mở rộng

Bạn có thể chạy trên máy mình, hoặc mở rộng bằng điều phối container (Docker).

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

Theo README, bạn chỉ cần những thứ sau:

- **Python 3.11 trở lên.** README ghi rõ phiên bản này được hỗ trợ.
- **Môi trường ảo Python (virtual environment).** README khuyên dùng để tránh lẫn thư viện với các dự án khác.
- **Kết nối mạng khi chạy lần đầu.** README nói mô hình được nạp từ Hugging Face Hub (hoặc từ thư mục trên máy). Nếu bạn không chỉ định đường dẫn mô hình, txtai dùng mô hình mặc định. Vì vậy lần đầu có thể phải tải mô hình về.
- **Tài khoản và API key:** README không yêu cầu cho phần cơ bản. Nếu bạn dùng LLM của OpenAI, Claude hay AWS Bedrock qua LiteLLM thì sẽ cần key của nhà cung cấp đó. Chi tiết thiết lập key README không ghi, bạn xem trong tài liệu chính thức.
- **Phần cứng, hệ điều hành:** README không nêu yêu cầu cụ thể. Mô hình LLM lớn thì chắc chắn nặng hơn mô hình nhỏ, nhưng con số cụ thể thì tư liệu chưa có. README có nhắc phần "environment specific prerequisites" (điều kiện riêng cho từng môi trường) trong tài liệu cài đặt.

```note
Nếu bạn dùng LLM trả phí qua nhà cung cấp bên ngoài, API key là bí mật của bạn. Đừng dán key vào file code rồi đưa lên GitHub, và hãy theo dõi chi phí sử dụng ở trang quản lý của 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à thử tìm kiếm
- (Tuỳ chọn) Chạy API | Viết file app.yml và bật máy chủ bằng uvicorn
```

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

Mở terminal (PowerShell hoặc Command Prompt trên Windows, Terminal trên macOS/Linux) rồi gõ lệnh dưới đây. Kết quả cần là phiên bản 3.11 trở lên. Nếu thấp hơn, bạn cần cài Python mới trước. Chỗ này người mới hay vấp: có máy cài sẵn Python cũ, và lệnh có thể là `python3` thay vì `python`.

```bash
python --version
```

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

README khuyên dùng môi trường ảo nhưng không chép sẵn lệnh. Đây là cách phổ thông của Python. Hãy chạy trong thư mục làm việc của bạn.

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

Sau đó kích hoạt nó. Trên Windows (PowerShell):

```powershell
.venv\Scripts\Activate.ps1
```

Trên macOS hoặc Linux:

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

Khi thành công, đầu dòng terminal sẽ có chữ `(.venv)`. Nếu PowerShell báo bị chặn chạy script, bạn đọc phần lỗi thường gặp ở dưới.

### Cài txtai

Đây là lệnh cài chính thức trong README, lấy từ PyPI:

```bash
pip install txtai
```

Lệnh này tải txtai cùng các thư viện nền như Transformers. Có thể mất vài phút. README nói bản cài mặc định có "low footprint" (gọn), và bạn cài thêm phụ thuộc khi cần. Cách cài thêm gói tuỳ chọn, cài từ mã nguồn, dùng conda, cài bản tối giản hoặc chạy bằng container đều có trong tài liệu cài đặt chính thức của dự án, README chỉ trỏ tới đó.

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

Tạo một file, ví dụ `thu.py`, rồi dán đoạn mã 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 mã làm ba việc. Dòng `txtai.Embeddings()` tạo cơ sở dữ liệu embeddings. Dòng `index` đưa hai câu vào chỉ mục. Dòng `search("positive", 1)` tìm 1 kết quả gần nghĩa nhất với từ "positive". Lần chạy đầu sẽ tải mô hình mặc định nên chậm hơn.

Lưu ý: dòng cuối trong README chỉ là chú thích về kết quả mong đợi. Nếu bạn muốn thấy kết quả khi chạy file, hãy bọc lệnh tìm kiếm trong `print(...)`.

### Chạy API (tuỳ chọn)

Nếu muốn gọi txtai từ ứng dụng viết bằng ngôn ngữ khác, tạo file `app.yml` với nội dung sau:

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

Rồi bật máy chủ và gọi thử. Lệnh dưới đây là dạng Linux/macOS, đúng như trong README:

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

Dòng đầu bật máy chủ với cấu hình trong `app.yml`. Dòng sau, chạy trong một cửa sổ terminal khác, gửi yêu cầu tìm kiếm tới máy chủ. Cú pháp `CONFIG=app.yml` đứng trước lệnh chỉ chạy trong bash. Trên PowerShell, README chưa ghi cách đặt biến này; bạn có thể dùng Git Bash hoặc WSL, hoặc xem tài liệu chính thức. README cũng chưa nói máy chủ cần gói tuỳ chọn nào, nên nếu báo thiếu `uvicorn` hãy xem phần optional dependencies trong tài liệu cài đặt.

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

Cách đơn giản nhất là chạy lại file `thu.py` ở trên. Theo README, kết quả mong đợi có dạng:

```python
[(0, 0.29862046241760254)]
```

Nghĩa là câu ở vị trí số 0 (câu "Correct") được chọn, kèm điểm giống nhau khoảng 0,3. Con số có thể lệch chút tuỳ mô hình và phiên bản, nhưng điều quan trọng là kết quả trả về là câu "Correct" chứ không phải câu kia. Nếu bạn thấy vậy, txtai đã hoạt động.

Nếu bạn có chạy API, mở địa chỉ `http://localhost:8000/search?query=positive` trên trình duyệt hoặc dùng lệnh `curl` ở trên. Có dữ liệu JSON trả về là máy chủ đang chạy. Lưu ý: nếu bạn chưa nạp dữ liệu vào chỉ mục thì kết quả có thể rỗng, và README không mô tả chi tiết bước nạp dữ liệu qua API.

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

README không đưa nhiều công thức dùng sẵn trong phần chính. Nó đưa các ví dụ trong thư mục `examples/` của repo (hơn 70 notebook và ứng dụng). Các tình huống dưới đây bám đúng khả năng được liệt kê.

### Chủ shop tìm câu trả lời trong kho câu hỏi khách hàng

Bạn có vài trăm câu hỏi khách hay gửi: đổi trả, phí ship, bảo hành. Khách hỏi "hàng lỗi thì sao" nhưng trong kho chữ viết là "chính sách hoàn tiền". Tìm theo từ khoá sẽ trượt, tìm theo ngữ nghĩa thì ra.

Cách làm: dùng đúng mẫu ở phần cài đặt, thay hai câu mẫu bằng danh sách câu hỏi của bạn.

```python
import txtai

embeddings = txtai.Embeddings()
embeddings.index(["danh sách câu hỏi 1", "danh sách câu hỏi 2"])
embeddings.search("câu khách vừa hỏi", 1)
```

Kết quả là chỉ số và điểm của câu gần nghĩa nhất, để bạn lấy ra câu trả lời tương ứng. README dùng mô hình tiếng Anh làm mặc định; chất lượng với tiếng Việt thì tư liệu chưa nói, bạn nên thử với dữ liệu thật trước. README có ví dụ "Build a QA database" cho kiểu việc này.

> Tìm theo nghĩa, không phải theo chữ: khách hỏi một kiểu, kho tài liệu viết một kiểu, vẫn gặp nhau.
>
> — Ông T

### Nhân viên văn phòng "chat với tài liệu nội bộ"

Bạn muốn hỏi "quy trình xin nghỉ phép thế nào" và nhận câu trả lời lấy từ đúng tài liệu công ty, thay vì để AI tự đoán. Đó là RAG. README có sẵn một file mẫu trong repo là `examples/rag_quickstart.py`, cùng notebook "Build RAG pipelines with txtai" hướng dẫn cả cách tạo trích dẫn nguồn.

Cách làm: clone repo, mở file `examples/rag_quickstart.py`, đọc rồi thay dữ liệu mẫu bằng nội dung của bạn.

```bash
git clone https://github.com/neuml/txtai.git
cd txtai
```

Kết quả là câu trả lời được LLM soạn ra từ ngữ cảnh tìm được trong kho của bạn, giảm nguy cơ trả lời sai so với hỏi LLM trơn. Nhớ rằng nếu bạn dùng LLM của nhà cung cấp bên ngoài thì nội dung tài liệu sẽ được gửi đi, nên hãy cân nhắc với tài liệu nhạy cảm.

### Dev mới dựng agent biết dùng công cụ

Bạn muốn thử một agent tự quyết định tìm gì, gọi công cụ nào để trả lời một câu hỏi nhiều bước. README chỉ tới `examples/agent_quickstart.py`. Ngoài ra có các notebook "Granting autonomy to agents" (agent tự lặp để giải quyết vấn đề), "Agent Tools" (bộ công cụ cho agent) và "TxtAI got skills" (tích hợp file skill.md).

Cách làm: chạy thử file quickstart trước, rồi đọc notebook "Agent Tools" để biết có thể gắn thêm công cụ gì. Kết quả là một agent chạy trên LLM bạn chọn, dựa trên smolagents.

### Làm quy trình xử lý âm thanh hoặc văn bản hàng loạt

Giả sử bạn có file ghi âm các cuộc họp và muốn phiên âm thành chữ, rồi tóm tắt, thậm chí dịch. README liệt kê các pipeline cho phiên âm (Whisper là mô hình khuyên dùng), tóm tắt (DistilBART) và dịch (dòng OPUS), cùng workflow để nối chúng lại. Mẫu nằm ở `examples/workflow_quickstart.py` và các notebook "Transcribe audio to text", "Building abstractive text summaries", "Translate text between languages".

Kết quả là một chuỗi tự động: âm thanh vào, văn bản đã tóm tắt hoặc đã dịch ra, không cần bạn làm tay từng bước. Mô hình tóm tắt và dịch mà README nêu chủ yếu cho tiếng Anh hoặc đa ngôn ngữ chung; chất lượng với tiếng Việt chưa có thông tin trong tư liệu.

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

### Báo phiên bản Python không phù hợp

txtai cần Python 3.11 trở lên. Nếu pip báo không tìm thấy phiên bản phù hợp thì rất có thể Python của bạn quá cũ. Hãy chạy `python --version`, cài Python mới hơn rồi tạo lại môi trường ảo.

### PowerShell chặn kích hoạt môi trường ảo

Trên Windows, lệnh `Activate.ps1` có thể bị chặn bởi chính sách chạy script. Cách an toàn là mở Command Prompt và dùng file `.venv\Scripts\activate.bat` thay thế, thay vì hạ thấp chính sách bảo mật cho cả máy.

### Chạy lần đầu rất chậm hoặc báo lỗi mạng

Mô hình được tải từ Hugging Face Hub ở lần dùng đầu, nên cần mạng ổn định và có thể chiếm dung lượng ổ đĩa. Cứ để nó tải xong. Nếu lỗi kết nối, kiểm tra mạng rồi chạy lại.

### Báo thiếu module khi dùng tính năng nâng cao

Bản `pip install txtai` mặc định là gọn, và README nói bạn cài thêm phụ thuộc khi cần mở rộng. Nếu một pipeline hay API báo thiếu thư viện (ví dụ không tìm thấy `uvicorn`), hãy xem mục optional dependencies trong tài liệu cài đặt của dự án rồi cài đúng gói được chỉ dẫn. Đừng đoán tên gói.

### Lệnh CONFIG=app.yml không chạy trên Windows

Cách đặt biến ngay trước lệnh như README là cú pháp bash. Trong PowerShell nó sẽ báo lỗi. Bạn dùng Git Bash hoặc WSL để chạy đúng như README, hoặc tra tài liệu chính thức để tìm cách đặt cấu hình phù hợp với môi trường của mình.

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

**Điểm mạnh.** txtai gom nhiều mảng (tìm kiếm vector, RAG, agent, workflow, API) vào một thư viện, nên bạn không phải ghép nhiều công cụ. Lệnh cài chỉ một dòng, ví dụ khởi động chỉ vài dòng code. Nó chạy cục bộ được, hỗ trợ từ mô hình nhỏ đến LLM lớn, giấy phép Apache-2.0 rõ ràng. Kho ví dụ trên 70 notebook là chỗ học rất tốt. README cũng cho biết các mô hình được khuyên dùng đều cho phép dùng thương mại.

**Giới hạn.** Đây là thư viện cho người viết code, không phải ứng dụng bấm là chạy. Bạn cần biết chút Python hoặc ít nhất biết chạy file `.py`. README chưa ghi yêu cầu phần cứng cụ thể, và chưa nói về chất lượng với tiếng Việt, nên bạn nên tự thử trên dữ liệu thật. Cài đặt nâng cao (gói tuỳ chọn, từng môi trường) nằm ở tài liệu chính thức chứ không có trong README.

**Khi nào nên chọn cách khác.** Nếu bạn chỉ cần một công cụ hỏi đáp tài liệu có giao diện, không muốn viết code, hãy tìm ứng dụng làm sẵn. Còn nếu bạn là dev, hoặc người làm kinh doanh có người biết code hỗ trợ, và muốn tự dựng tìm kiếm thông minh, RAG hay agent chạy trên dữ liệu của mình, thì txtai là một điểm xuất phát gọn và đáng thử.

## 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 và cài qua pip nên bản thân thư viện không tính phí. Tuy nhiên nếu bạn dùng LLM của nhà cung cấp bên ngoài như OpenAI, Claude hay AWS Bedrock thì chi phí theo nhà cung cấp đó. Tư liệu chưa có thông tin về giá của các dịch vụ này.

### Cần Python phiên bản nào để cài txtai?

README ghi txtai hỗ trợ Python 3.11 trở lên. README cũng khuyên nên dùng môi trường ảo (virtual environment) để tránh lẫn thư viện với các dự án khác.

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

README không nêu yêu cầu GPU. Tư liệu chỉ nói txtai làm việc được với mô hình nhỏ đến LLM lớn và có thể chạy cục bộ. Yêu cầu phần cứng cụ thể cho từng mô hình thì chưa có thông tin, nên bạn xem trang mô hình tương ứng.

### Dữ liệu của tôi có phải gửi lên dịch vụ bên ngoài không?

README nói txtai chạy cục bộ, không cần gửi dữ liệu tới nhiều dịch vụ từ xa riêng lẻ. Nếu bạn chủ động chọn LLM qua OpenAI, Claude hay AWS Bedrock thì nội dung gửi tới LLM sẽ đi qua nhà cung cấp đó. Bạn nên cân nhắc khi xử lý tài liệu nhạy cảm.

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

README không nêu hệ điều hành cụ thể, chỉ nói cài bằng pip và cần Python 3.11+. Lệnh chạy API trong README dùng cú pháp bash nên trên Windows bạn có thể cần Git Bash hoặc WSL. Mục điều kiện riêng cho từng môi trường nằm trong tài liệu cài đặt chính thức.

### 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 kết hợp chỉ mục vector, đồ thị mạng và cơ sở dữ liệu quan hệ. Ngoài tìm kiếm, nó còn có pipeline, workflow, agent và API đi kèm. So sánh chi tiết với từng công cụ cụ thể thì README chưa có.

### Có dùng được với ngôn ngữ ngoài Python không?

Có. txtai có API web và API theo chuẩn MCP. README liệt kê các thư viện kết nối cho JavaScript, Java, Rust và Go. Bạn bật máy chủ API rồi gọi từ ngôn ngữ mình quen.
