# AutoRAG: thủ thư AI tìm và hỏi đáp trong file máy tính — hướng dẫn cài đặt và dùng

> AutoRAG Agent (gói npm @autorag/librarian) là một trợ lý kiểu thủ thư: bạn hỏi bằng ngôn ngữ thường, nó tìm trong file, mail, chat, ghi chú trên máy rồi trả lời kèm nguồn. Cài bằng một lệnh npm hoặc bun, dùng qua terminal bằng lệnh autorag tui. Cái khó nhất với người mới là cần Node.js phiên bản 24 trở lên và một model AI để đăng nhập.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-09-09 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/autorag-thu-thu-ai-tim-file-trong-may-tinh

AutoRAG Agent là một “thủ thư AI” chạy trên máy tính của bạn. Bạn hỏi bằng câu bình thường, ví dụ “hợp đồng cloud quý 3 đổi những gì?”. Nó tự lục file, mail, tin nhắn, ghi chú rồi trả lời kèm nguồn: file nào, trang nào, đoạn nào. Gói cài đặt có tên `@autorag/librarian`.

Công cụ tìm kiếm thông thường chỉ đưa bạn danh sách đường dẫn. Bạn vẫn phải mở từng file, đọc, rồi tự tổng hợp. Repo này làm nốt phần đó: nó mở file thật để kiểm tra, rồi viết câu trả lời thành các ý đánh số, mỗi ý gắn nguồn. Nó hợp với người làm văn phòng, kinh doanh có nhiều tài liệu rải rác, và lập trình viên muốn đưa khả năng tìm kiếm này vào agent của mình.

Điểm đáng giá nhất là nó tìm dữ liệu ngay tại chỗ, không bắt bạn tải mọi thứ lên một kho vector riêng. Phần lập chỉ mục ngữ nghĩa chạy ngay trên máy bạn. Repo hiện có khoảng 5.743 sao và 505 fork, dùng giấy phép Apache-2.0, và vẫn được cập nhật trong vài tháng gần đây. Bạn có thể xem video ngắn bên dưới để thấy nó chạy trước khi cài.

```repo
- repo | Marker-Inc-Korea/AutoRAG
- kind | CLI
- desc | Thủ thư AI chạy trên máy bạn: hỏi bằng lời, nó tìm trong file, mail, chat, ghi chú rồi trả lời kèm nguồn trích dẫn.
- stars | 5.7k
- lang | TypeScript
- license | Apache-2.0
```

```video
- youtube | https://youtube.com/shorts/NlYoIT2xtzc
- facebook | https://www.facebook.com/reel/1485302333659382
- title | Video giới thiệu AutoRAG
```

## AutoRAG Agent làm được gì

Như vậy là đủ để hình dung. Giờ đi vào các tính năng chính, mỗi tính năng đi kèm lợi ích thực tế.

### Hỏi và nhận câu trả lời có nguồn

Bạn hỏi như hỏi đồng nghiệp. Câu trả lời được chia thành các ý đánh số, mỗi ý ghi rõ lấy từ file nào, trang nào hoặc dòng nào. Bạn không phải tin mù quáng: bấm vào nguồn là kiểm tra được ngay. Với người làm hợp đồng, báo cáo hay quy trình nội bộ, điều này quan trọng hơn việc “trả lời nghe hay”.

### Tìm nhiều kiểu cùng lúc

Nó kết hợp tìm theo từ khoá, tìm theo ý nghĩa và tìm kiểu lai (hybrid). Nó còn tìm theo tên file rất nhanh: trên Windows dùng công cụ Everything đi kèm, trên macOS/Linux dùng fsearch-cli nếu bạn có cài. Nhờ vậy bạn hỏi “file báo giá của khách A” hay hỏi “khách A đã đồng ý điều khoản gì” đều có đường đi.

### Tìm ở nhiều nơi, không chỉ thư mục

Ngoài file, nó nối được với Slack, KakaoTalk, Discord, Telegram, WhatsApp (chỉ đọc), mail, GitHub và Obsidian. Dữ liệu vẫn nằm ở nơi gốc. Mỗi kết quả giữ định danh nguồn riêng, ví dụ đường dẫn bắt đầu bằng `/slack/...`, nên quyền truy cập gốc không bị làm mất.

### Đọc nhiều loại tài liệu

PDF, DOCX, XLSX/XLS và cả HWP/HWPX (định dạng văn bản Hàn Quốc) được xử lý ngay trong chương trình, không cần cài Java. Phần tìm kiếm cũng hiểu các biến thể từ của tiếng Hàn. README không nói gì riêng về tiếng Việt, nên bạn hãy thử trên tài liệu của mình trước khi tin cậy.

### Máy tính chính xác

Con số và ngày tháng là chỗ AI hay sai. Repo có công cụ `calculator` tính số thập phân chính xác (40 chữ số có nghĩa), tính số ngày giữa hai mốc, ngày làm việc, tuần ISO, đổi múi giờ. Hệ thống ra lệnh cho model dùng công cụ này thay vì tính nhẩm.

### Nhớ lại những gì đã tìm

Sau mỗi câu trả lời, bằng chứng đã được xác nhận được lưu vào tệp `~/.autorag/memory.json`. Các lần tìm sau nhận thông tin này làm gợi ý tham khảo. Nó không đổi thứ tự kết quả và không đè lên bằng chứng hiện tại.

### Nhiều cách dùng cùng một lõi

Bạn có thể dùng giao diện terminal (`autorag tui`), nhắn qua Telegram/WhatsApp/Discord, gọi bằng CLI trong script, nối vào Claude Code hay Codex qua MCP server, hoặc nhúng vào ứng dụng TypeScript. Ngoài ra còn có ứng dụng desktop tên Dazzi, mã nguồn ở một repo riêng và theo giấy phép khác (FSL-1.1-MIT). Bài này tập trung vào bản dòng lệnh.

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

Theo tư liệu, bạn cần:

- **Node.js từ phiên bản 24 trở lên**, hoặc dùng Bun. File `package.json` của repo yêu cầu `>=24.0.0`.
- **Một model AI** để đăng nhập hoặc điền key. README cho biết có hai hướng: gói Dazzi Models do nhóm tác giả cung cấp, hoặc tự dùng key của nhà cung cấp model và trả tiền trực tiếp cho họ.
- **Không cần Java** để đọc PDF, Word, Excel, HWP.
- **Không cần key embedding từ xa.** Phần lập chỉ mục ngữ nghĩa dùng engine nhúng chạy cục bộ (Qwen3-Embedding-0.6B qua MinSync).
- Windows: công cụ Everything đi kèm để tìm theo tên file. macOS/Linux: nên cài thêm fsearch-cli, nếu không việc tìm theo tên sẽ chậm.

Phần “System Prerequisites” trong README bị cắt ở tư liệu mình có, nên các yêu cầu khác (dung lượng ổ đĩa, RAM, chi tiết từng hệ điều hành) mình chưa có thông tin. Bạn mở README trên GitHub và file `docs/minsync-setup.md` để xem đầy đủ.

```note
Một số tính năng cho phép model đọc, sửa, đổi tên, di chuyển file khi bạn yêu cầu. Hãy thử trên một thư mục sao lưu trước, và đọc kỹ những gì nó định làm trước khi đồng ý. Nếu dùng key của nhà cung cấp model, mỗi câu hỏi có thể tốn tiền theo bảng giá của họ.
```

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

```steps
- Mở terminal | Dùng PowerShell trên Windows, Terminal trên macOS/Linux
- Kiểm tra Node.js | Chắc chắn phiên bản từ 24 trở lên
- Cài gói | Chạy một lệnh npm hoặc bun để cài lệnh autorag
- Mở giao diện | Gõ autorag tui rồi đăng nhập model
- Hỏi thử | Đặt một câu hỏi về thư mục của bạn
```

### Mở terminal

Terminal là cửa sổ nhập lệnh. Trên Windows, bấm Start, gõ PowerShell rồi mở. Trên macOS, mở ứng dụng Terminal. Bạn không cần đứng trong thư mục đặc biệt nào, vì cài kiểu toàn cục (global) chạy được ở bất cứ đâu.

### Kiểm tra Node.js

Gõ lệnh dưới đây để xem phiên bản Node.

```bash
node --version
```

Nếu kết quả là `v24` trở lên thì ổn. Nếu thấp hơn hoặc báo không tìm thấy lệnh, bạn cần cài hoặc nâng cấp Node.js trước. Đây là chỗ người mới hay vấp nhất, vì nhiều máy còn Node đời cũ.

### Cài gói

README đưa hai cách. Dùng cách nào cũng được, chỉ cần chọn một.

```bash
# Install CLI globally
bun install -g @autorag/librarian
# or with npm:
npm install -g @autorag/librarian
```

Chữ `-g` nghĩa là cài toàn cục để gọi lệnh `autorag` từ mọi nơi. Người chưa có Bun thì cứ dùng dòng `npm`. Nếu bạn là lập trình viên muốn dùng như thư viện trong dự án, README ghi thêm lệnh sau (chạy trong thư mục dự án của bạn):

```bash
bun add @autorag/librarian
```

Nếu cài xong mà gõ `autorag` báo không tìm thấy, hãy đóng terminal rồi mở lại. Xem thêm mục lỗi thường gặp bên dưới.

### Mở giao diện và đăng nhập model

Chạy lệnh sau để mở giao diện terminal:

```bash
autorag tui
```

Giao diện này chạy trên nền Pi. Theo README, các lệnh bắt đầu bằng dấu `/` như `/login`, `/logout`, `/model`, `/resume`, `/new`, `/settings` đều dùng được ngay từ lần mở đầu tiên, kể cả khi bạn chưa cấu hình model nào. Vì vậy, nếu chưa có model, hãy gõ `/login` để đăng nhập nhà cung cấp, rồi `/model` để chọn model.

Cách lập chỉ mục cho thư mục của bạn (chọn thư mục nào, tần suất làm mới) nằm ở phần README bị cắt. README chưa có trong tư liệu mình có, nên bạn xem `docs/minsync-setup.md` và phần CLI Command Reference trong repo.

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

Sau khi gõ `autorag tui`, một phiên mới mở ra bằng màn hình chào riêng của AutoRAG: logo, số phiên bản và ba mẹo xoay vòng. Trên terminal hẹp, logo thu nhỏ hoặc chỉ còn tên chữ. Nếu bạn thấy màn hình này, lệnh đã cài thành công.

Tiếp theo hãy gõ một câu hỏi thật về thư mục của bạn. Ngay khi gửi câu hỏi, một bảng tiến trình hiện phía trên ô nhập: có biểu tượng quay, thời gian đã chạy và mỗi bước một dòng (định tuyến, chia câu hỏi, từng nguồn tìm kiếm kèm số kết quả, xếp hạng, câu trả lời đầu tiên, bước kiểm chứng). Nguồn nào lỗi sẽ hiện nguyên văn thông báo lỗi. Khi xong bạn nhận danh sách ý đánh số, kèm nguồn.

Một vài phím hữu ích trong lúc nó đang tìm:

- **Enter**: sửa hướng khi thấy nó đi sai, ví dụ “chỉ tìm trong thư mục Hợp đồng”.
- **Alt+Enter**: xếp một câu hỏi mới chạy sau khi câu hiện tại xong.
- **Esc**: dừng tìm kiếm.

Nếu không muốn công cụ kiểm tra bản mới mỗi lần mở, README cho biết đặt biến môi trường `AUTORAG_NO_UPDATE_CHECK=1`.

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

Dưới đây là các tình huống bám đúng những gì README mô tả. Câu hỏi mẫu mình tự đặt để bạn dễ hình dung, không phải lệnh có sẵn.

### Nhân viên văn phòng cần tra lại điều khoản hợp đồng

Bạn có một thư mục đầy hợp đồng PDF và Word, cộng thêm vài kênh chat trao đổi với pháp chế. Sếp hỏi “quý này điều khoản chiết khấu thay đổi thế nào?”. Mở `autorag tui` và gõ:

```text
Các điều khoản chiết khấu trong hợp đồng cloud đã thay đổi gì trong quý 3?
```

Kết quả có dạng các ý đánh số, mỗi ý kèm tên file và trang hoặc dòng, giống ví dụ trong README (hợp đồng PDF trang 4, một trao đổi trong Slack, một phụ lục SLA). Bạn mở đúng nguồn để đối chiếu rồi gửi sếp. Việc đó nhanh hơn nhiều so với lần lượt mở từng file.

> Công cụ tìm kiếm cho bạn đường dẫn, còn thủ thư thì đưa bạn câu trả lời kèm nguồn để tự kiểm tra.
>
> — Ông T

### Chủ shop dọn các bản file trùng

Thư mục báo giá của bạn có `bao-gia-final`, `bao-gia-v3`, `bao-gia (1)` và bạn không biết bản nào mới nhất. README cho biết repo có chức năng phát hiện file trùng và gần giống, xếp chúng lại thành một nhóm, bản mới nhất được gắn nhãn **Latest**, các bản khác là **Similar** hoặc **Identical**. Với bản dòng lệnh, lệnh tương ứng là:

```bash
autorag duplicates
```

Mình chưa có thông tin về các cờ lệnh đi kèm, nên bạn xem CLI Command Reference của repo trước khi chạy trên thư mục thật. Với thao tác đổi tên, di chuyển hay xoá, hãy sao lưu trước.

### Hỏi thủ thư từ điện thoại qua Telegram

Bạn đang đi gặp khách và cần số liệu trong file ở máy văn phòng. README cho biết bạn có thể nối Telegram vào một phiên `autorag tui` đang chạy, rồi nhắn câu hỏi cho bot và nhận cùng kiểu trả lời hai giai đoạn như trên terminal:

```bash
autorag tui --telegram
```

Máy tính phải đang bật và phiên đang chạy thì bot mới trả lời được. Cách tạo bot, các lệnh và giữ cho nó chạy liên tục nằm trong `docs/telegram.md`. WhatsApp (`autorag tui --whatsapp`, bản không chính thức) và Discord (`autorag tui --discord`) hoạt động theo cách tương tự.

### Lập trình viên cho agent mã hoá khả năng tìm tài liệu

Bạn dùng Claude Code hoặc Codex và muốn agent biết tìm trong tài liệu nội bộ, không chỉ trong code. README liệt kê hai hướng: chạy AutoRAG như một MCP server (mục “AutoRAG Lite MCP Server”) hoặc nhúng bằng TypeScript API (mục “Programmatic usage”). Phần hướng dẫn chi tiết của hai mục này nằm ở nửa README bị cắt trong tư liệu, nên mình không chép lệnh ở đây. Bạn mở README của repo và tìm đúng hai tiêu đề đó.

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

### Cài xong nhưng gõ autorag báo không tìm thấy lệnh

Thường là do terminal cũ chưa nạp lại đường dẫn. Hãy đóng hẳn terminal, mở cửa sổ mới rồi thử lại. Nếu vẫn lỗi, kiểm tra Node bằng `node --version` và chạy lại lệnh cài. Đừng chạy lệnh cài bằng quyền quản trị nếu không thật cần.

### Lệnh cài báo lỗi phiên bản Node

Phiên bản Node quá cũ (dưới 24) là nguyên nhân thường gặp, vì `package.json` yêu cầu `>=24.0.0`. Hãy nâng Node lên bản 24 trở lên rồi cài lại.

### Hỏi nhưng không có câu trả lời, hoặc báo chưa có model

Bạn chưa đăng nhập hoặc chưa chọn model. Trong `autorag tui`, gõ `/login` rồi `/model`. Nếu dùng key riêng, hãy kiểm tra key còn hiệu lực và tài khoản nhà cung cấp còn hạn mức.

### Tìm theo tên file chậm trên macOS/Linux

README cho biết nếu không cài fsearch-cli thì việc này chuyển sang duyệt hệ thống file khá chậm. Cài fsearch-cli (README dẫn tới repo `NomaDamas/fsearch-mac`) hoặc thu hẹp thư mục tìm kiếm.

### Tìm đúng mã số, mã hoá đơn nhưng kết quả lẫn lộn

Tác giả ghi thẳng rằng tìm từ khoá dùng SPLADE, và với mã định danh chính xác giữa nhiều file na ná nhau thì độ tin cậy có thể kém hơn BM25 cũ. Bạn hãy thêm ngữ cảnh vào câu hỏi (tên khách, tháng, loại chứng từ) hoặc dùng tìm theo tên file cho các mã này.

### Nhầm với AutoRAG bản cũ

Repo này hiện là AutoRAG 2.0, tức thủ thư AI. Công cụ AutoRAG đời đầu (tối ưu pipeline RAG bằng Python, cài bằng `pip install AutoRAG`) đã chuyển vào thư mục `legacy/` và vẫn được bảo trì. Nếu bạn muốn công cụ cũ thì xem README trong `legacy/`, đừng làm theo bài này.

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

**Điểm mạnh.** Cài nhanh bằng một lệnh. Trả lời có nguồn nên kiểm tra được. Tìm ngay tại chỗ, không phải đưa dữ liệu lên kho khác. Lập chỉ mục ngữ nghĩa chạy trên máy, khoá đăng nhập lưu trong kho mã hoá của hệ thống theo mô tả của tác giả. Có nhiều cách dùng: terminal, tin nhắn, MCP, thư viện TypeScript.

**Giới hạn.** Cần Node.js 24 trở lên và một model AI (trả phí tuỳ nhà cung cấp). Giao diện chính là terminal, hơi xa lạ với người chưa từng dùng. Nguồn dữ liệu và ngôn ngữ ưu tiên có màu sắc Hàn Quốc (KakaoTalk, HWP, tiếng Hàn); README không nói gì về hiệu quả với tiếng Việt. Bạn nên thử trên bộ tài liệu thật của mình. Tìm mã chính xác có thể kém hơn tìm kiểu cũ. Phần mô tả chi tiết cấu hình nằm trong tài liệu của repo, không nằm hết trong bài này.

**Khi nào chọn cách khác.** Nếu bạn chỉ cần tìm tên file, một công cụ tìm tên file như Everything hay FSearch là đủ. Nếu bạn muốn ứng dụng có cửa sổ như Finder, hãy xem bản desktop Dazzi ở repo riêng (lưu ý giấy phép khác). Nếu mục tiêu là tối ưu pipeline RAG bằng Python cho dữ liệu của mình, hãy dùng bản AutoRAG cũ trong `legacy/`.

Với người cần tra cứu tài liệu hằng ngày, đây là một công cụ đáng thử vì chi phí thử thấp: cài một lệnh, hỏi vài câu, xem nó có tìm đúng không rồi hãy quyết định.

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

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

Mã nguồn dùng giấy phép Apache-2.0, nên dùng tự do. Tuy nhiên để trả lời được bạn cần một model AI: README nêu hai hướng là gói Dazzi Models do tác giả cung cấp, hoặc dùng key của nhà cung cấp riêng và trả tiền trực tiếp cho họ. Giá cụ thể mình chưa có thông tin.

### Có cần GPU hay máy cấu hình cao không?

README mô tả engine embedding cục bộ (Qwen3-Embedding-0.6B) do MinSync cài và chạy, nhưng tư liệu mình có không nêu yêu cầu GPU hay RAM. Phần System Prerequisites bị cắt nên mình chưa có thông tin cụ thể. Bạn xem README và docs/minsync-setup.md trong repo.

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

Có dấu hiệu là được: README nhắc công cụ Everything đi kèm dành cho Windows để tìm theo tên file. Bạn cần Node.js 24 trở lên rồi cài bằng npm install -g @autorag/librarian. Các chi tiết riêng cho Windows ngoài phần này mình chưa có thông tin.

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

Theo README, nội dung file không gửi đến embedder từ xa trừ khi bạn tự cấu hình embedder từ xa. Token đăng nhập và API key lưu trong kho mã hoá của hệ thống, không nằm trong file cấu hình. Tuy nhiên nội dung đoạn văn có liên quan vẫn được gửi cho model AI bạn chọn để trả lời, nên hãy cân nhắc với tài liệu nhạy cảm.

### AutoRAG Agent khác gì AutoRAG cũ?

Repo này hiện là AutoRAG 2.0: thủ thư AI tìm và trả lời trong file, mail, chat của bạn. AutoRAG cũ, công cụ AutoML tìm pipeline RAG tối ưu bằng Python, nằm trong thư mục legacy/ và cài bằng pip install AutoRAG. Bản cũ vẫn được bảo trì.

### Có dùng được với tiếng Việt không?

README nói tới tiếng Hàn, Anh, Nhật, Trung giản thể (ở ứng dụng desktop) và việc tìm khớp biến thể từ tiếng Hàn. Tư liệu không nói gì về tiếng Việt, nên mình chưa có thông tin chắc chắn. Bạn nên thử với một thư mục tài liệu tiếng Việt nhỏ trước.

### Có dùng với Claude Code hay agent khác được không?

Có. README liệt kê MCP server để đưa kết quả tìm kiếm cho Claude Code, Codex và các agent khác, cùng với TypeScript API và agent skills. Lệnh cài đặt chi tiết của các mục này nằm ở phần README bị cắt trong tư liệu, nên bạn xem trực tiếp trong repo.
