Chuyển đến nội dung chính
Hướng dẫn AI

Hướng dẫn trợ lý CLI cục bộ đọc và chỉnh sửa bài báo: Triển khai Agent ưu tiên quyền riêng tư trên Linux

Bài viết hướng dẫn cài đặt và sử dụng trợ lý CLI cục bộ paperchecker để đọc và chỉnh sửa bài báo, bao gồm cấu hình mô hình, lập chỉ mục bài báo, đặt câu hỏi tương tác, chạy lệnh một lần, lưu phiên và xử lý sự cố.

Thời gian đọc khoảng 18 phút
Hướng dẫn trợ lý CLI cục bộ đọc và chỉnh sửa bài báo trên Linux

Giới thiệu dự án

Trợ lý cục bộ đọc và chỉnh sửa bài báo là một CLI Agent nhẹ dành cho Linux, hỗ trợ xử lý bài báo. Sau khi người dùng nhập câu hỏi, mô hình có thể gọi các công cụ cục bộ và khả năng tìm kiếm bài báo để hỗ trợ đọc, tóm tắt và phân tích nội dung bài báo cục bộ.

Dự án mặc định sử dụng Qwen3-14B-AWQ, với bộ trọng số mô hình khoảng 9.4 GB. Dự án phù hợp với người dùng có GPU NVIDIA, muốn chạy mô hình cục bộ và bảo vệ quyền riêng tư của bài báo cũng như câu hỏi. Theo mặc định, dự án không bật tìm kiếm trực tuyến; câu trả lời chủ yếu dựa trên năng lực của mô hình và cơ sở tri thức cục bộ do người dùng xây dựng.

Dự án hỗ trợ giao thức MCP và có thể tích hợp các dịch vụ MCP thông qua cơ chế đăng ký công cụ. Vì ngân sách đầu vào, system prompt và độ dài đầu ra của công cụ đều có thể cấu hình, phạm vi sử dụng của dự án không chỉ giới hạn ở việc hỗ trợ bài báo.

Tính năng chính

  • Chạy Agent hỗ trợ bài báo cục bộ trong môi trường Linux.
  • Mặc định sử dụng mô hình cục bộ Qwen3-14B-AWQ.
  • Hỗ trợ lập cơ sở tri thức tìm kiếm cục bộ từ các tệp PDF dạng văn bản, Markdown và TXT.
  • Hỗ trợ đặt câu hỏi tương tác và thực thi câu hỏi một lần qua dòng lệnh.
  • Hỗ trợ lưu bản ghi câu hỏi và câu trả lời ở định dạng Markdown.
  • Hỗ trợ giao thức MCP và cơ chế đăng ký công cụ.
  • Hỗ trợ checkpoint phiên LangGraph tùy chọn để tiếp tục phiên giữa các cửa sổ.
  • Cung cấp script kiểm tra môi trường, GPU và cấu hình mô hình.

Chuẩn bị trước khi cài đặt

Dự án hướng đến Linux và khuyến nghị sử dụng máy có GPU NVIDIA. Bộ trọng số mô hình khoảng 9.4 GB; khi chạy thực tế, cần dành đủ bộ nhớ GPU cho quá trình suy luận. Khi điều chỉnh mô hình, ngân sách đầu vào hoặc độ dài đầu ra, cũng cần đánh giá dựa trên dung lượng bộ nhớ GPU.

PDF dạng quét hiện chưa hỗ trợ OCR. Nếu cần tìm kiếm trong bài báo dạng quét, trước tiên hãy chuyển nội dung thành văn bản hoặc sử dụng PDF dạng văn bản, Markdown hay TXT được dự án hỗ trợ.

Tải xuống và cài đặt dự án

Trước tiên, hãy clone kho GitHub và đặt tên thư mục dự án là local-agent:

git clone https://github.com/Ayi914/paperchecker.git local-agent
cd local-agent

Nếu không sử dụng Git, bạn cũng có thể chọn Code → Download ZIP trên trang GitHub, giải nén rồi mở terminal trong thư mục dự án.

Sau khi vào thư mục dự án, thực thi script cài đặt:

bash scripts/install.sh

Sau khi cài đặt hoàn tất, chạy script khởi động:

bash scripts/start.sh

Ở lần khởi động đầu tiên, hãy chờ mô hình tải xong. Khi terminal xuất hiện dấu nhắc >>>, bạn có thể nhập câu hỏi. Ví dụ:

>>> Hãy giải thích kết nối dư giải quyết vấn đề gì

Trong những lần sau, sau khi vào thư mục dự án, thông thường chỉ cần chạy bash scripts/start.sh để khởi động.

Chạy lần đầu và cấu hình mô hình

Nếu thư mục mô hình chưa đầy đủ hoặc cần chọn lại mô hình, bạn có thể thực thi:

bash scripts/setup.sh

Khi tải mô hình thất bại, trước tiên hãy kiểm tra mạng. Bạn cũng có thể tải toàn bộ thư mục mô hình trên máy có mạng, sau đó sao chép sang máy đích và chọn mô hình có sẵn trong quá trình cấu hình.

Nếu mô hình khởi động thất bại, hãy xem tệp nhật ký được hiển thị trong terminal. Nhật ký thường nằm tại:

logs/cli-vllm-*.log

Đồng thời, hãy xác nhận bộ nhớ GPU không bị chương trình khác chiếm dụng.

Nhập bài báo của bạn và lập chỉ mục

Để Agent trả lời dựa trên bài báo của bạn, hãy đặt các tệp PDF dạng văn bản, Markdown hoặc TXT vào thư mục data/knowledge/. Ví dụ, thư mục có thể chứa nhiều bài báo và ghi chú liên quan.

Sau khi chuẩn bị tệp, hãy thực thi lệnh lập chỉ mục cơ sở tri thức:

bash scripts/start.sh rag-index

Lần đầu lập chỉ mục sẽ tải một mô hình tìm kiếm riêng, vì vậy cần có kết nối mạng. Sau khi lập chỉ mục hoàn tất, hãy khởi động lại Agent tương tác:

bash scripts/start.sh

Lúc này, bạn có thể đặt các câu hỏi dựa trên bài báo cục bộ, chẳng hạn:

Dựa trên các bài báo cục bộ, hãy tóm tắt những đổi mới cốt lõi của YOLOv1 và liệt kê nguồn.

Nếu chưa thêm bài báo hoặc chưa lập chỉ mục, câu trả lời sẽ chủ yếu đến từ kiến thức của mô hình thay vì nội dung bài báo cục bộ. Dự án mặc định không bật tìm kiếm trực tuyến.

Sử dụng tương tác

Sau khi khởi động, hãy nhập câu hỏi sau dấu nhắc >>> rồi nhấn Enter. Cách này phù hợp để hỏi tiếp, so sánh quan điểm trong các bài báo hoặc phân tích từng bước cùng một chủ đề.

Bạn có thể sử dụng các lệnh tích hợp sau để quản lý quá trình tương tác:

  • /help: Xem các lệnh hội thoại.
  • /new: Bắt đầu phiên mới.
  • /exit, /quit hoặc Ctrl+D: Thoát chương trình.

Mỗi câu hỏi và câu trả lời mặc định được lưu dưới dạng tệp Markdown, với định dạng đường dẫn:

output/tháng/ngày/thời_gian_microgiây.md

Thực thi tác vụ một lần qua dòng lệnh

Nếu không cần vào giao diện tương tác, bạn có thể truyền trực tiếp câu hỏi làm tham số cho script khởi động:

bash scripts/start.sh "Tóm tắt cơ chế chú ý"

Sử dụng --quiet để chỉ xuất câu trả lời:

bash scripts/start.sh "Tóm tắt cơ chế chú ý" --quiet

Nếu không muốn lưu tệp câu trả lời, hãy thêm --no-save:

bash scripts/start.sh "Câu hỏi" --no-save

Cấu hình ngân sách đầu vào, độ dài đầu ra và prompt

Ngân sách đầu vào và system prompt của Agent có thể được chỉnh sửa trong config/agent.yaml, vì vậy dự án cũng có thể được sử dụng cho các tình huống Agent cục bộ khác.

Cần phân biệt rõ hai tham số: tool_output_max_chars: 4000 trong tệp cấu hình là giới hạn cắt ngắn số ký tự của kết quả công cụ, không phải giới hạn token của câu trả lời mô hình. Độ dài đầu ra tối đa của mô hình do LOCAL_AGENT_MAX_TOKENS trong tệp môi trường kiểm soát; mặc định trong .env.example là 2048 token.

Ngân sách đầu vào mặc định của Agent là 4096 token. Khi điều chỉnh ngân sách đầu vào, system prompt, độ dài đầu ra của công cụ hoặc số token đầu ra tối đa, cần cân nhắc tổng thể độ dài ngữ cảnh và bộ nhớ GPU khả dụng để tránh cấu hình quá cao khiến mô hình không thể hoạt động bình thường.

Lưu và khôi phục phiên giữa các cửa sổ

Theo mặc định, ngữ cảnh phiên chỉ được lưu trong tiến trình hiện tại. Sau khi đóng CLI, chương trình sẽ không tự động khôi phục ngữ cảnh; các tệp câu trả lời Markdown đã tạo cũng không được tự động đọc lại.

Nếu cần tiếp tục cùng một phiên giữa các cửa sổ, hãy đổi run.checkpoint_enabled thành true trong config/agent.yaml và luôn sử dụng cùng một ID phiên:

bash scripts/start.sh -i --thread-id my-paper

Trạng thái phiên sẽ được lưu tại:

data/checkpoints/langgraph.sqlite

Nhập /new hoặc khởi động một cửa sổ tương tác mới mà không chỉ định ID phiên đều sẽ tạo phiên mới. Mỗi lần gọi mô hình mặc định sử dụng 4 lượt hội thoại gần nhất và vẫn chịu giới hạn ngân sách đầu vào 4096 token.

Kiểm tra môi trường và xử lý sự cố

Khi gặp vấn đề, trước tiên nên chạy script kiểm tra môi trường:

bash scripts/doctor.sh

Script này kiểm tra môi trường, GPU và cấu hình mô hình nhưng không tải mô hình lớn cũng không bắt đầu suy luận, nên phù hợp để sử dụng trước khi khởi động chính thức hoặc trong quá trình xử lý sự cố.

  • Không có GPU: Khuyến nghị sử dụng máy Linux có GPU NVIDIA.
  • Thư mục mô hình chưa đầy đủ: Chạy bash scripts/setup.sh để chọn lại mô hình hoặc tiếp tục tải xuống.
  • Tải mô hình thất bại: Kiểm tra mạng hoặc tải toàn bộ thư mục mô hình trên máy có mạng rồi sao chép sang môi trường đích.
  • Mô hình khởi động thất bại: Xem logs/cli-vllm-*.log và xác nhận bộ nhớ GPU không bị chương trình khác chiếm dụng.
  • Bài báo cục bộ không được sử dụng: Xác nhận tệp nằm trong data/knowledge/ và đã thực thi bash scripts/start.sh rag-index.

Gợi ý sử dụng thực tế

  • Trước lần sử dụng đầu tiên, hãy chạy bash scripts/doctor.sh để sớm phát hiện vấn đề về GPU, thư mục mô hình hoặc cấu hình.
  • Tập trung các bài báo cần trích dẫn và phân tích vào data/knowledge/, sau đó lập chỉ mục rồi mới đặt câu hỏi.
  • Khi đặt câu hỏi, hãy nêu rõ phạm vi tóm tắt, định dạng đầu ra hoặc yêu cầu liệt kê nguồn để dễ đối chiếu nội dung bài báo cục bộ hơn.
  • Nếu không đủ bộ nhớ GPU, không nên tùy tiện tăng ngân sách đầu vào, giới hạn đầu ra của công cụ hoặc số token đầu ra tối đa.
  • Khi cần xử lý liên tục cùng một chủ đề nghiên cứu, hãy bật checkpoint và cố định --thread-id.
  • PDF dạng quét không thể trực tiếp dựa vào dự án hiện tại để thực hiện OCR; trước tiên cần chuẩn bị nội dung văn bản có thể tìm kiếm.

Tổng kết

paperchecker cung cấp quy trình hoàn chỉnh từ khởi động mô hình cục bộ, lập chỉ mục bài báo đến hỏi đáp qua CLI. Sau khi cài đặt dự án, bạn có thể sử dụng mô hình mặc định để phân tích các câu hỏi thông thường, hoặc đưa bài báo dạng văn bản của mình vào cơ sở tri thức và lập chỉ mục để Agent trả lời dựa trên tài liệu cục bộ. Thông qua agent.yaml, biến môi trường và checkpoint phiên, bạn cũng có thể điều chỉnh thêm cách quản lý ngữ cảnh, đầu ra và phiên.

Mã nguồn dự án sử dụng giấy phép MIT. Nếu gặp vấn đề khi khởi động hoặc với mô hình, hãy ưu tiên chạy script chẩn đoán và kiểm tra nhật ký.