RetainPDF

1. RetainPDF là gì?

RetainPDF là ứng dụng dịch file PDF mà vẫn giữ nguyên bố cục: công thức toán, bảng, nhiều cột, hình ảnh vẫn nằm đúng chỗ. Thông thường các công cụ dịch chỉ nhả ra một khối chữ thô và làm vỡ hết công thức lẫn trang trí. RetainPDF nhắm tới bài báo khoa học, sách giáo trình và tài liệu kỹ thuật, kể cả PDF dạng ảnh chụp hoặc bản scan. Kết quả là file PDF đã dịch, bản Markdown, hoặc gói ZIP, và có trình đọc đặt bản gốc cạnh bản dịch để đối chiếu.

Phần mềm miễn phí và mã nguồn mở (giấy phép MIT), chạy như ứng dụng máy tính (Windows, macOS, Linux) hoặc dựng thành một trang web trên máy bạn bằng Docker.

Điều cần biết trước khi cài: RetainPDF không tự dịch được. Nó gọi hai dịch vụ trực tuyến bên ngoài, và bạn phải tự có khóa truy cập (token, API key) của chúng: một dịch vụ nhận dạng chữ trong PDF (OCR) và một mô hình AI để dịch. Các dịch vụ đó có thể tính phí theo mức dùng, không phải của dự án. Ngoài ra, theo tài liệu và mã nguồn, ngôn ngữ đích mặc định của bản dịch là tiếng Trung giản thể. Tài liệu không nói rõ có chọn được tiếng Việt hay ngôn ngữ khác hay không, nên hãy thử với một file nhỏ trước.

Hợp với bạn nếu:

• Bạn đọc nhiều bài báo hoặc sách kỹ thuật bằng tiếng nước ngoài và cần bản dịch giữ được công thức, bố cục.
• Bạn có hoặc chịu tạo tài khoản ở các dịch vụ OCR và AI được liệt kê ở mục 2.
• Bạn chấp nhận dùng giao diện có nhãn tiếng Trung (mã nguồn cho thấy các nút và nhãn chủ yếu bằng tiếng Trung).

Chưa hợp nếu:

• Bạn muốn dịch hoàn toàn offline. Phần OCR và phần dịch đều dùng dịch vụ trực tuyến.
• Bạn chỉ cần dịch vài câu hoặc một đoạn chữ. Dùng công cụ dịch thông thường sẽ nhanh hơn.
• Bạn cần bản dịch sang tiếng Việt và không muốn thử nghiệm để kiểm tra.

2. Cần chuẩn bị gì?

Máy tính:

• Windows, macOS hoặc Linux (file .deb, dùng cho Ubuntu/Debian). Phiên bản mới nhất lúc viết bài là v4.2.5 (19/9/2026).
• Dung lượng file cài: khoảng 235 MB (Windows), 290 MB (macOS), 237 MB (Linux).
• Tài liệu không nêu cấu hình tối thiểu cho ứng dụng desktop. Nếu chạy bằng Docker, dự án khuyên ít nhất 4 nhân CPU, 8 GB RAM, 10 GB ổ cứng trống; không cần card đồ họa.
• Bản macOS được dựng trên nền chip Apple. Tài liệu không cam kết chạy trên Mac đời Intel.

Khóa truy cập (cần có trước khi dịch):

Dịch vụ	Dùng để	Lấy ở đâu
PaddleOCR (mặc định) qua Baidu AI Studio	Nhận dạng chữ và bố cục trong PDF	Access Token tại https://aistudio.baidu.com/account/accessToken
Hoặc MinerU	Thay thế cho Paddle	API Token tại https://mineru.net/apiManage/docs
Một mô hình AI tương thích OpenAI, ví dụ DeepSeek	Dịch văn bản	API key, ví dụ tại https://platform.deepseek.com/api_keys

Ứng dụng có sẵn cấu hình nhanh cho các nhà cung cấp DeepSeek, Qwen, Anthropic, OpenAI và Zhipu. Trang lấy khóa của các dịch vụ này có thể bằng tiếng Trung hoặc yêu cầu đăng ký tài khoản và nạp tiền. Hãy xem điều khoản và giá ở trang chính thức của từng dịch vụ trước khi dùng.

Phần mềm cài thêm (chỉ khi chạy bằng Docker):

• Docker (công cụ chạy ứng dụng trong "container" biệt lập, để không phải cài từng thành phần): https://docs.docker.com/get-started/get-docker/
• Git (công cụ tải mã nguồn): https://git-scm.com/downloads

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

Cách dễ nhất là cài ứng dụng desktop (Bước 1 đến 3). Docker ở Bước 4 dành cho người muốn chạy thành dịch vụ web.

Bước 1: Tải bản cài đặt

Mở https://github.com/wxyhgk/retain-pdf/releases/latest và tải file đúng hệ điều hành:

• Windows: RetainPDF-Windows-4.2.5-Setup.exe
• macOS: RetainPDF-Mac-4.2.5.dmg
• Linux: RetainPDF-Linux-4.2.5.deb

Trang còn có file SHA256SUMS.txt để kiểm tra file tải về có nguyên vẹn không.

Bước 2: Cài trên từng hệ điều hành

Windows: bấm đúp file RetainPDF-Windows-4.2.5-Setup.exe và làm theo bộ cài. Mở RetainPDF từ menu Start.

macOS:

1. Bấm đúp file .dmg và kéo RetainPDF vào thư mục Applications.
2. Mở RetainPDF. Nếu macOS báo ứng dụng "đã hỏng" (theo README, đây là cách macOS phản ứng với ứng dụng tải từ Internet), mở Terminal và chạy:

sudo xattr -r -d com.apple.quarantine /Applications/RetainPDF.app

Gõ mật khẩu máy khi được hỏi, rồi mở lại ứng dụng.

Linux (Ubuntu/Debian): mở Terminal ở thư mục chứa file vừa tải và chạy:

sudo apt install ./RetainPDF-Linux-4.2.5.deb

Thấy gì là đúng: ứng dụng RetainPDF xuất hiện trong danh sách ứng dụng của máy và mở được cửa sổ chính, có thư viện (bookshelf) để quản lý các file.

Bước 3: Nhập khóa truy cập

Ứng dụng cần khóa OCR và khóa mô hình AI trước khi dịch. Trên bản web, hộp thoại này nằm ở góc trên bên phải, có nhãn "API 配置" (cấu hình API); trên bản desktop, ứng dụng cũng có phần nhập tương tự. Bạn điền:

1. Nhà cung cấp OCR: để mặc định PaddleOCR và dán Access Token, hoặc chọn MinerU và dán API Token.
2. Mô hình dịch: chọn nhà cung cấp (ví dụ DeepSeek), dán API key. Địa chỉ và tên mô hình được điền sẵn theo nhà cung cấp (DeepSeek dùng https://api.deepseek.com/v1).
3. Bấm nút kiểm tra bên cạnh mỗi ô (các nút có nhãn "检测", nghĩa là kiểm tra) để chắc khóa dùng được.

Thấy gì là đúng: mỗi lần kiểm tra báo kết nối thành công. Nếu báo khóa không hợp lệ hoặc hết hạn, xem mục 5.

Bước 4 (thay thế): Chạy bằng Docker

Dùng khi bạn muốn chạy RetainPDF như một trang web trên máy hoặc máy chủ của mình. Cài Docker và Git (mục 2), kiểm tra:

docker --version
docker compose version

Rồi tải mã và khởi động:

git clone https://github.com/wxyhgk/retain-pdf.git
cd retain-pdf/ops/deployment/docker/delivery
docker compose up -d

Sau khi khởi động xong, mở http://127.0.0.1:40001 trong trình duyệt.

Thấy gì là đúng: trang RetainPDF hiện ra. Nếu ô khóa để trống, bạn nhập khóa OCR và khóa mô hình ở hộp thoại cấu hình API như Bước 3.

Lưu ý: mặc định dịch vụ chỉ lắng nghe ở 127.0.0.1, tức chỉ máy bạn truy cập được. Tài liệu của dự án dặn chỉ đổi sang cho phép truy cập từ ngoài khi đã có lớp bảo vệ đăng nhập riêng (ví dụ Basic Auth ở NGINX). Không tự mở ra Internet khi chưa có.

4. Dùng lần đầu

Thử với một file PDF ngắn, vài trang:

1. Mở RetainPDF và đảm bảo khóa OCR, khóa mô hình đã nhập đúng (Bước 3).
2. Thêm file PDF vào ứng dụng (phần nhập file của thư viện). Tài liệu chính thức không mô tả từng nút, nên tên nút có thể khác đôi chút giữa các phiên bản.
3. Bắt đầu dịch. Ứng dụng chạy theo từng giai đoạn: nhận dạng chữ, dịch, dàn trang lại. Bạn thấy tiến độ trên màn hình.
4. Khi xong, mở bản dịch. Bạn tải được PDF đã dịch, bản Markdown hoặc gói ZIP.

Thấy gì là đúng: PDF bản dịch giữ nguyên vị trí hình, bảng và công thức; chữ trong các khung đã được thay bằng bản dịch. Dùng chế độ đọc song song để so bản gốc với bản dịch.

Vài tính năng thêm theo README:

Bạn muốn	Làm ở đâu
Đối chiếu nguyên bản và bản dịch	Trình đọc song song (hiển thị hai bản cạnh nhau)
Đọc dạng Markdown, giữ công thức và hình	Trình đọc Markdown
Hỏi đáp về nội dung tài liệu, có trích dẫn số trang	Trợ lý AI trong trình đọc (dùng mô hình AI bạn đã cấu hình)
Quản lý nhiều file, đánh dấu yêu thích	Thư viện

Giới hạn cỡ file: bộ Docker của dự án gợi ý tối đa khoảng 200 MB và 300 trang mỗi file; giao diện hiển thị đúng giới hạn đang áp dụng.

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
macOS báo ứng dụng "đã hỏng"	macOS gắn cờ kiểm dịch cho ứng dụng tải từ Internet	Kéo ứng dụng vào Applications rồi chạy lệnh sudo xattr -r -d com.apple.quarantine /Applications/RetainPDF.app ở Bước 2
Kiểm tra khóa báo lỗi, hoặc dịch dừng ngay từ đầu	Khóa OCR hoặc khóa mô hình sai, hết hạn, hoặc tài khoản hết số dư	Kiểm tra lại khóa ở trang của dịch vụ; dùng nút kiểm tra ("检测") bên cạnh ô khóa; nạp thêm tiền nếu dịch vụ yêu cầu
Báo "翻译接口检测失败" (kiểm tra giao diện dịch thất bại)	Sai địa chỉ API, sai khóa, hoặc mạng bị chặn	Kiểm tra địa chỉ API đúng theo nhà cung cấp, kiểm tra kết nối mạng tới dịch vụ đó
Tác vụ dịch thất bại ở giữa chừng, thử lại vẫn lỗi	Có những lỗi đã được người dùng báo trên GitHub (ví dụ issue #132 về giai đoạn dịch hay thất bại, #134 về việc một số nội dung PDF không được dịch)	Thử file ngắn hơn, đổi nhà cung cấp hoặc mô hình, cập nhật bản mới nhất, hoặc xem và báo lỗi tại https://github.com/wxyhgk/retain-pdf/issues
File bị từ chối vì quá lớn hoặc quá nhiều trang	Vượt giới hạn dung lượng hoặc số trang của bản cài đặt	Cắt nhỏ file PDF; giao diện hiển thị giới hạn đang áp dụng
Docker: docker compose up -d báo không kéo được ảnh	Máy không truy cập được Docker Hub	Kiểm tra mạng; dự án ghi rõ cần truy cập được Docker Hub, MinerU và API mô hình
Docker: không mở được http://127.0.0.1:40001	Container chưa khởi động xong hoặc cổng đang bị chiếm	Chờ vài chục giây; xem trạng thái bằng docker compose ps; tắt chương trình đang dùng cổng 40001 hoặc dùng biến WEB_PORT (ví dụ WEB_PORT=40002 docker compose up -d)

6. Gỡ cài đặt / cập nhật

Cập nhật

• Bản desktop: tải bản mới từ https://github.com/wxyhgk/retain-pdf/releases/latest và cài đè lên.
• Docker: vào thư mục retain-pdf/ops/deployment/docker/delivery và chạy:

docker compose pull
docker compose up -d

Gỡ cài đặt

• Windows: vào danh sách ứng dụng đã cài trong Settings, tìm RetainPDF và gỡ.
• macOS: kéo RetainPDF từ thư mục Applications vào Thùng rác.
• Linux: tìm tên gói bằng lệnh sau, rồi gỡ gói đó bằng sudo apt remove <tên gói>.

dpkg -l | grep -i retain

• Docker: trong thư mục delivery, chạy lệnh sau để dừng và gỡ container:

docker compose down

Nếu muốn xóa luôn dữ liệu đã lưu trong Docker (các tác vụ và kết quả dịch), thêm cờ -v:

docker compose down -v

Các file PDF đã dịch mà bạn tải về máy không bị xóa khi gỡ ứng dụng.

7. Câu hỏi hay gặp

RetainPDF có mất tiền không? Phần mềm miễn phí, mã nguồn mở (MIT). Nhưng việc dịch dùng dịch vụ OCR và mô hình AI bên ngoài, các dịch vụ này có thể tính phí theo mức dùng. Hãy xem trang giá của từng dịch vụ.

Có cần mạng không? Có. Cần mạng để gọi dịch vụ OCR và mô hình AI; bản Docker còn cần tải ảnh từ Docker Hub.

File của tôi có bị gửi đi đâu không? Theo thiết kế của dự án, file PDF được gửi tới nhà cung cấp OCR bạn chọn (PaddleOCR hoặc MinerU) và phần chữ được gửi tới nhà cung cấp mô hình AI để dịch. Nếu tài liệu nhạy cảm, hãy đọc chính sách dữ liệu của các dịch vụ đó trước.

Dịch sang tiếng Việt được không? Mặc định bản dịch là tiếng Trung giản thể (theo mã nguồn). Tài liệu chính thức không nói có tùy chọn ngôn ngữ đích khác hay không. Hãy thử với file nhỏ và xem giao diện, hoặc hỏi tại https://github.com/wxyhgk/retain-pdf/issues

Máy yếu có chạy được không? Việc nặng (OCR và dịch) do dịch vụ bên ngoài xử lý, dự án nói nó chủ yếu dùng CPU, RAM và mạng chứ không cần card đồ họa. Gợi ý cho bản Docker là 4 nhân CPU và 8 GB RAM trở lên.