# 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 (bản 2.0, gói @autorag/librarian) là một agent thủ thư cá nhân: bạn hỏi, nó tìm trong file, mail, tin nhắn và ghi chú trên máy rồi trả lời có đánh số nguồn. Cài bằng một lệnh npm hoặc bun, cần Node 24 trở lên. Phần cài thì dễ, phần nối mô hình AI và nguồn dữ liệu cần đọc thêm tài liệu trong repo.

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

AutoRAG Agent (bản 2.0 của repo AutoRAG, gói npm `@autorag/librarian`) là một “thủ thư cá nhân” chạy bằng AI. Bạn hỏi bằng câu bình thường, nó tự tìm trong file, thư, tin nhắn, ghi chú trên máy bạn, mở tài liệu gốc ra kiểm tra, rồi trả lời kèm nguồn đánh số rõ ràng. Nó còn có thể sắp xếp, đổi tên, di chuyển hay sửa file khi bạn nhờ, và ghi lại từng thay đổi.

Repo này hợp với người làm văn phòng có hàng đống hợp đồng, báo giá, biên bản nằm rải rác. Nó cũng hợp với lập trình viên muốn cắm khả năng tìm kiếm vào Claude Code hay các agent khác qua MCP. Hiện repo có khoảng 5.699 sao và 502 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong 3 tháng gần đây.

Điểm đáng giá nhất: dữ liệu của bạn **không phải chuyển đi đâu để tìm kiếm**. Nó tìm ngay tại chỗ và có sẵn bộ nhúng (embedding) chạy trên máy. Bạn có thể xem video ngắn bên dưới để thấy nó chạy thế nào, rồi quay lại đây làm theo.

```note
Lưu ý để khỏi nhầm: repo AutoRAG cũ (công cụ AutoML tối ưu pipeline RAG viết bằng Python, cài bằng pip) giờ nằm trong thư mục legacy/ của repo và vẫn được bảo trì. Bài này nói về AutoRAG Agent 2.0, cài bằng npm hoặc bun.
```

```repo
- repo | Marker-Inc-Korea/AutoRAG
- kind | CLI
- desc | AutoRAG Agent là trợ lý thủ thư chạy trên máy bạn: hỏi bằng tiếng thường, nó tìm trong file, mail, chat 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ì

Theo README, đây là những việc chính, mình diễn giải theo lợi ích thực tế.

### Hỏi như hỏi đồng nghiệp

Các công cụ tìm kiếm thường chỉ ném cho bạn đường dẫn file và vài dòng khớp. Bạn vẫn phải mở từng file ra đọc. AutoRAG thì đọc giúp, rồi viết câu trả lời, mỗi ý gắn với đoạn gốc (ví dụ file nào, trang nào, dòng nào). Bạn kiểm chứng nhanh mà không phải lục lại.

### Tìm ở nhiều nơi cùng lúc

Ngoài file trên máy, README liệt kê các nguồn dữ liệu có thể nối vào: Slack, KakaoTalk, Discord, Telegram, WhatsApp (chỉ đọc), thư (mail), GitHub (repo, issue, PR) và Obsidian. Các nguồn này được tìm “tại chỗ”, nên kết quả vẫn mang mã nguồn gốc kiểu `/slack/...` hay `/kakao/...`.

### Tìm theo từ khoá lẫn theo ý nghĩa

Nó có tìm kiếm thưa (từ khoá, dùng SPLADE), tìm kiếm vector (theo ý nghĩa) và tìm kết hợp cả hai. Bạn không cần nhớ chính xác tên file hay từ trong tài liệu. README cũng nói rõ một hạn chế: khi có rất nhiều file na ná nhau, việc tìm đúng một mã định danh chính xác có thể kém tin cậy hơn so với BM25 trước đây.

### Tìm tên file rất nhanh

Trên Windows, nó dùng công cụ Everything đi kèm để tìm file theo tên, đuôi, đường dẫn, kích thước, ngày. Trên macOS/Linux dùng `fsearch-cli`; nếu chưa có công cụ này thì nó vẫn chạy nhưng chậm hơn vì phải duyệt thư mục.

### Đọc nhiều loại tài liệu, không cần Java

HWP/HWPX/HWPML, PDF, DOCX, XLSX/XLS được đọc ngay trong tiến trình qua thư viện `kordoc`, không cần cài Java.

### Máy tính bỏ túi chính xác

Con số và ngày tháng được giao cho công cụ `calculator` tính (số thập phân chính xác, tính số ngày giữa hai mốc, ngày làm việc, múi giờ…) thay vì để mô hình “nhẩm”. Với người làm hợp đồng, báo cáo thì đây là chi tiết đáng tiền.

### Trí nhớ và dọn file trùng

Sau mỗi câu trả lời, bằng chứng được cho là thật sự ủng hộ câu trả lời sẽ được lưu vào `~/.autorag/memory.json`, dùng làm gợi ý cho lần tìm sau (chỉ tham khảo, không ghi đè bằng chứng mới). Lệnh `autorag duplicates` quét file trùng hoặc gần trùng, kiểu `proposal-final`, `proposal-v3`, `proposal (1)`.

### Nhiều cách dùng

Cùng một “bộ máy” có thể dùng qua giao diện terminal (`autorag tui`), nhắn qua Telegram, WhatsApp, Discord, dòng lệnh CLI, MCP server, API TypeScript, hoặc ứng dụng desktop riêng. Ứng dụng desktop (tên Dazzi) có mã nguồn ở repo khác của nhóm tác giả, không nằm trong repo này.

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

Theo phần README mình có, bạn cần:

- **Node.js từ phiên bản 24 trở lên** (package.json yêu cầu `>=24.0.0`), hoặc dùng Bun.
- **Một mô hình AI.** README nói bạn có thể dùng gói Dazzi Models do tác giả cung cấp, hoặc nối khoá (key) của nhà cung cấp mô hình riêng và trả tiền trực tiếp cho họ. Trong terminal, các lệnh `/login` và `/model` giúp đăng nhập và chọn mô hình ngay lần đầu.
- **Không cần khoá embedding từ xa.** Bộ nhúng chạy trên máy (Qwen3-Embedding-0.6B qua MinSync). Nội dung file chỉ bị gửi đến bộ nhúng từ xa nếu chính bạn cấu hình `minSync.embedder`.
- **Không cần Java** để đọc HWP, PDF, Office.
- Hệ điều hành: README nhắc cả Windows (Everything), macOS và Linux (fsearch-cli). Yêu cầu phần cứng cụ thể (RAM, GPU) trong phần README mình có **chưa ghi**.

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

```steps
- Kiểm tra Node | Chạy node -v, cần phiên bản 24 trở lên
- Cài gói | Cài @autorag/librarian toàn cục bằng npm hoặc bun
- Mở giao diện terminal | Chạy autorag tui
- Đăng nhập, chọn mô hình | Dùng /login và /model trong phiên
- Hỏi thử | Gõ một câu hỏi về file của bạn
```

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

Mở terminal (trên Windows: PowerShell hoặc Windows Terminal; trên Mac: Terminal) và chạy:

```bash
node -v
```

Nếu số hiện ra nhỏ hơn 24 (ví dụ v20), bạn cần nâng Node lên trước, nếu không gói có thể không chạy. Hoặc bạn dùng Bun thay cho Node, README cho phép cả hai.

### Cài gói toàn cục

Dùng một trong hai lệnh, đúng như README:

```bash
# Cài CLI toàn cục bằng bun
bun install -g @autorag/librarian
# hoặc bằng npm:
npm install -g @autorag/librarian
```

Chữ `-g` nghĩa là cài toàn cục, để gõ `autorag` ở bất kỳ thư mục nào cũng chạy. Bạn chỉ cần chọn **một** trong hai lệnh. Nếu bạn là lập trình viên muốn nhúng vào dự án của mình, README còn có lệnh thêm thư viện:

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

Lệnh này chạy trong thư mục dự án của bạn, không dành cho người chỉ muốn dùng như một công cụ.

### Mở giao diện terminal

Sau khi cài xong, chạy:

```bash
autorag tui
```

Đây là giao diện tương tác trong terminal. README cho biết nó chạy trên nền Pi, và các lệnh `/login`, `/logout`, `/model`, `/resume`, `/new`, `/tree`, `/compact`, `/settings` đều dùng được ngay từ lần mở đầu, kể cả khi chưa cấu hình mô hình AutoRAG nào.

### Đăng nhập và chọn mô hình

Trong phiên `autorag tui`, gõ `/login` để đăng nhập nhà cung cấp mô hình, rồi `/model` để chọn mô hình. Chỗ người mới hay vấp: các lệnh có dấu `/` này gõ **bên trong** giao diện AutoRAG, không gõ ở dấu nhắc lệnh PowerShell hay Terminal bên ngoài.

```note
Khoá API và token đăng nhập được README mô tả là lưu trong kho mã hoá của hệ điều hành, không nằm trong file cấu hình. Dù vậy, bạn đừng dán khoá vào câu hỏi, vào chat hay chụp màn hình gửi người khác.
```

### Chỉ cho nó thư mục cần tìm

Phần README mình có **chưa ghi** từng bước chọn thư mục để lập chỉ mục (index) hay cấu hình các nguồn như Slack, mail. Bạn xem thư mục `docs/` trong repo, đặc biệt `docs/minsync-setup.md`, và các file `docs/telegram.md`, `docs/whatsapp.md`, `docs/discord.md` nếu muốn nối chat. Phần “CLI Command Reference” và “For AI Agents” trong README cũng là nơi nên đọc tiếp.

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

Cách đơn giản nhất theo tư liệu: chạy `autorag tui`. Một phiên mới sẽ mở ra màn hình chào riêng của AutoRAG, gồm logo AutoRAG, số phiên bản và ba mẹo xoay vòng. Nếu thấy màn hình đó, gói đã cài đúng và chạy được. Trên cửa sổ hẹp, logo sẽ thu nhỏ hoặc chỉ còn chữ.

Bước thứ hai: gõ một câu hỏi thật. Khi bạn gửi câu hỏi, phía trên ô nhập sẽ có bảng tiến trình: vòng quay chờ, thời gian đã trôi, và mỗi dòng cho một bước (định tuyến, từng nguồn tìm kiếm kèm số kết quả và thời gian, xếp hạng, câu trả lời đầu, kiểm chứng). Nguồn nào lỗi sẽ hiện nguyên văn lỗi. Nếu bạn thấy bảng này chạy là tìm kiếm đang hoạt động.

Nếu `autorag` báo không tìm thấy lệnh, xem mục lỗi bên dưới.

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

Các tình huống dưới đây bám đúng khả năng có trong README. Chi tiết cấu hình nguồn dữ liệu bạn cần xem thêm ở `docs/`.

### Nhân viên pháp chế tìm thay đổi trong hợp đồng

Bối cảnh: bạn có hàng chục hợp đồng PDF và file Markdown, cộng thêm thảo luận trên Slack. Sếp hỏi: hợp đồng hạ tầng đám mây quý 3 đổi những gì?

Bạn mở `autorag tui` và hỏi gần như câu ví dụ trong README:

```text
What changes were made to the cloud infrastructure contract in Q3?
```

Bạn có thể hỏi bằng tiếng Việt như hỏi người, nhưng README chỉ minh hoạ bằng tiếng Anh nên mình khuyên bạn thử vài câu để xem kết quả. Kết quả là danh sách đánh số, mỗi mục một ý ngắn kèm nguồn, ví dụ `contracts/cloud-2026.pdf:p.4` hay `/slack/legal-ops/chunks/318`. Bạn bấm mở đúng trang để đối chiếu.

> Nó không đưa bạn một danh sách file, nó đưa bạn câu trả lời và chỉ đúng trang nó lấy ra.
>
> — Ông T

### Chủ shop dọn file báo giá trùng

Bối cảnh: thư mục báo giá có `bao-gia-final`, `bao-gia-v3`, `bao-gia (1)`, không biết bản nào mới nhất. Chạy lệnh:

```bash
autorag duplicates
```

README cho biết lệnh này chạy cùng bộ quét với ứng dụng desktop, gom các bản trùng hoặc gần trùng thành một nhóm, bản mới nhất được gắn nhãn Latest, các bản còn lại là Similar hoặc Identical. Bạn nên xem kỹ nhãn trước khi xoá bất cứ thứ gì. README chưa nêu các tuỳ chọn của lệnh này trong phần mình đọc, nên hãy xem phần “CLI Command Reference”.

### Nhân viên văn phòng tính ngày làm việc và hạn thanh toán

Bối cảnh: hợp đồng ghi “thanh toán trong 30 ngày làm việc kể từ ngày nghiệm thu”. Bạn hỏi AutoRAG đúng như vậy kèm tên file. Theo README, hệ thống được ra lệnh phải tính mọi con số và ngày tháng bằng công cụ `calculator` (có tính ngày làm việc kèm ngày nghỉ lễ, tuần ISO, múi giờ), chứ không để mô hình tự nhẩm. Kết quả là ngày cụ thể cùng nguồn trích. Bạn vẫn nên tự đối chiếu danh sách ngày nghỉ lễ nếu cần chính xác tuyệt đối.

### Lập trình viên nối thủ thư vào agent lập trình

Bối cảnh: bạn dùng Claude Code hoặc Codex và muốn agent tra cứu tài liệu nội bộ. README nêu hai hướng: dùng MCP server (mục “AutoRAG Lite MCP Server”) để cấp kết quả tìm kiếm cho các agent, hoặc dùng API TypeScript để nhúng vào ứng dụng của bạn. Lệnh cụ thể của MCP server không có trong phần README mình có, nên hãy đọc đúng mục đó trong repo. Nếu muốn nhờ agent tự cài, repo có mục “For AI Agents” và thư mục `skills/`.

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

Bối cảnh: bạn đang đi ngoài, cần tra nhanh một số liệu trong file ở máy văn phòng. Bạn chạy trên máy:

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

Câu hỏi gửi cho bot Telegram sẽ được xử lý như trong terminal (cùng cách định tuyến và tìm hai giai đoạn). Máy phải đang bật và phiên đang chạy. Cách tạo bot và giữ chạy liên tục nằm ở `docs/telegram.md`. WhatsApp (`--whatsapp`, dùng client không chính thức) và Discord (`--discord`, chưa hỗ trợ “steer”) làm tương tự.

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

### Gõ autorag báo không tìm thấy lệnh

Thường do cài xong nhưng terminal chưa nhận đường dẫn của npm/bun toàn cục. Hãy đóng terminal, mở lại. Nếu vẫn lỗi, kiểm tra gói đã cài chưa bằng `npm ls -g` và xem thư mục cài toàn cục của npm hoặc bun đã nằm trong biến PATH chưa. Đừng chạy lệnh cài bằng quyền quản trị chỉ để “cho chạy được” nếu chưa hiểu nguyên nhân.

### Cài lỗi hoặc báo phiên bản Node không phù hợp

Gói yêu cầu Node 24 trở lên. Chạy `node -v` để xem. Nếu thấp hơn, nâng cấp Node (hoặc dùng Bun) 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ó mô hình

Nghĩa là bạn chưa đăng nhập hay chọn mô hình. Trong `autorag tui`, dùng `/login` rồi `/model`. Nếu dùng khoá nhà cung cấp riêng, nhớ rằng chi phí tính trực tiếp theo gói của họ, hãy kiểm tra hạn mức trước khi hỏi hàng loạt.

### Tìm không ra file đã biết chắc là có

Có thể thư mục đó chưa nằm trong phạm vi tìm kiếm hoặc chưa được lập chỉ mục. Xem `docs/minsync-setup.md` để biết cách thiết lập. Với macOS/Linux, nếu chưa có `fsearch-cli`, việc tìm theo tên sẽ chậm hơn. Nếu bạn tìm một mã định danh chính xác giữa nhiều file na ná nhau, hãy thử diễn đạt thêm ngữ cảnh, vì README thừa nhận trường hợp này kém tin cậy hơn BM25 cũ.

### Bị làm phiền bởi thông báo cập nhật hoặc nhầm với AutoRAG cũ

`autorag tui` tự kiểm tra bản mới của `@autorag/librarian`. Muốn tắt, đặt biến môi trường `AUTORAG_NO_UPDATE_CHECK=1`. Còn nếu bạn cần công cụ AutoML tối ưu pipeline RAG kiểu cũ, đừng cài gói này; hãy xem thư mục `legacy/` và README của nó.

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

**Điểm mạnh:** tìm tại chỗ, không buộc bạn đưa dữ liệu lên kho vector bên ngoài; bộ nhúng chạy trên máy; câu trả lời có nguồn để kiểm chứng; đọc được cả HWP, PDF, Office; nối được nhiều kênh như Slack, mail, Telegram; mã nguồn mở Apache-2.0; cài chỉ bằng một lệnh.

**Giới hạn:**

- Cần Node 24 trở lên, khá mới, nhiều máy phải nâng cấp.
- Phải có một mô hình AI (gói của tác giả hoặc khoá riêng) và có thể phát sinh chi phí theo nhà cung cấp.
- Phần cấu hình nguồn dữ liệu và lập chỉ mục không đơn giản “cài là chạy hết”; bạn sẽ phải đọc thêm tài liệu trong `docs/`.
- Một số kênh còn hạn chế: Slack làm kênh nhắn chưa được hỗ trợ, Discord chưa có “steer”, WhatsApp dùng client không chính thức.
- Nó có thể sửa, đổi tên, di chuyển file khi bạn nhờ. Hãy giữ bản sao lưu và đọc kỹ nhật ký thay đổi.
- Giao diện chính là terminal; nếu bạn muốn một cửa sổ quản lý file có sẵn, ứng dụng desktop nằm ở repo khác và theo giấy phép Fair Source, không phải Apache-2.0.

Nếu bạn chỉ cần tìm tên file nhanh, Everything (Windows) hay công cụ tìm kiếm có sẵn của hệ điều hành là đủ. AutoRAG đáng thử khi bạn cần câu trả lời tổng hợp từ nhiều tài liệu và nhiều nguồn, hoặc muốn một lớp tìm kiếm cho các agent lập trình của mình.

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

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

Bản thân gói @autorag/librarian là mã nguồn mở, giấy phép Apache-2.0. Tuy nhiên bạn cần một mô hình AI: README nói có thể dùng gói Dazzi Models do tác giả cung cấp, hoặc nối khoá nhà cung cấp riêng và trả tiền trực tiếp cho họ. Giá cụ thể chưa có trong tư liệu mình đọc.

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

Phần README mình có chưa nêu yêu cầu về GPU hay RAM. Nó chỉ nói bộ nhúng Qwen3-Embedding-0.6B chạy trên máy qua MinSync. Nếu máy yếu, bạn nên thử trên một thư mục nhỏ trước.

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

README có nhắc đến Windows: công cụ Everything đi kèm giúp tìm file theo tên. macOS và Linux dùng fsearch-cli. Yêu cầu chung là Node.js 24 trở lên hoặc Bun.

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

README cho biết nội dung file không bị gửi tới bộ nhúng từ xa trừ khi bạn tự cấu hình minSync.embedder, và khoá đăng nhập được lưu trong kho mã hoá của hệ điều hành. Lưu ý rằng câu hỏi và đoạn trích dẫn vẫn đi qua mô hình AI bạn chọn, nên hãy xem chính sách của nhà cung cấp đó.

### AutoRAG 2.0 khác AutoRAG cũ thế nào?

AutoRAG cũ là công cụ AutoML tìm pipeline RAG tối ưu, viết bằng Python, cài bằng pip install AutoRAG. Bản 2.0 là agent thủ thư cá nhân viết bằng TypeScript, cài qua npm hoặc bun. Bản cũ vẫn được bảo trì trong thư mục legacy/ của repo.

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

Có. README liệt kê MCP server (AutoRAG Lite MCP Server) để cấp kết quả tìm kiếm cho Claude Code, Codex và các agent khác, cùng API TypeScript. Lệnh cụ thể của MCP server không nằm trong phần README mình có, bạn cần xem mục đó trong repo.

### Có ứng dụng giao diện đồ hoạ không?

Có ứng dụng desktop tên Dazzi, dùng cùng bộ máy này. Mã nguồn của nó nằm ở một repo riêng của nhóm tác giả (Electron + React, giấy phép Fair Source FSL-1.1-MIT), không nằm trong repo này.
