pdfx CLI: Local trước, Cloud khi cần

PDF123 là tên sản phẩm. pdfx là CLI ngắn gọn nói chuyện với đúng những thao tác đó. Đường mặc định là cục bộ: đọc tệp, chạy thao tác qua pdf-core, ghi kết quả. Không tài khoản, không API key, không tải lên.

Local trước nghĩa là tệp không rời khỏi máy

Một lệnh điển hình trông như pdfx merge a.pdf b.pdf -o merged.pdf hoặc pdfx compress input.pdf. Quá trình xử lý chạy ngay nơi binary chạy. Điều này hợp với tác vụ CI trên runner riêng, script đặt cạnh một lô hóa đơn, và mọi trường hợp mà tải lên bên thứ ba là câu trả lời sai.

Chế độ local không phải một lớp bọc mỏng lén gửi byte đi nơi khác. CLI dùng chung sổ đăng ký thao tác với server (pdf_core::ops::run). Nếu muốn đi đường mạng, bạn chủ động bật --cloud.

Các subcommand có sẵn bao phủ những thao tác phổ biến: merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark và các việc liên quan. Kết quả local mặc định ghi ra tệp qua -o / --output; - ghi ra stdout.

--cloud là chính danh mục đó qua HTTP

Khi cần API hosted (hoặc pdfx-server của riêng bạn), truyền --cloud kèm --api-base và --api-key (hoặc PDFX_API_KEY). Chế độ cloud cần curl ở bên dưới và sẽ thất bại nếu chưa đặt API key. Ví dụ từ skill đã công bố:

pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
  merge a.pdf b.pdf -o merged.pdf

--api-base mặc định là https://pdf123.xyz, tức API hosted. Với một stack Docker Compose cục bộ, hãy trỏ nó tới http://127.0.0.1:8080. CLI trở thành client của bề mặt REST được ghi tại Nhà phát triển; tên thao tác khớp với các công cụ trên portal và OpenAPI (/v1/openapi.json).

Chế độ cloud không đổi ý nghĩa của thao tác. Compress vẫn là nén luồng bằng qpdf; OCR vẫn trả văn bản Markdown từ đường Rust, không phải một lớp PDF tìm kiếm được. Những cờ CLI còn sót lại ánh xạ tới tham số OCR thời Java đã bị bỏ qua (ví dụ trường languages) không làm thay đổi hợp đồng đó.

Vì sao tồn tại hai chế độ

Local đáp ứng nhu cầu tin cậy khi offline và chi phí không phải đi vòng. Cloud đáp ứng hạn mức chia sẻ, chạy thao tác trên một máy chỉ có CLI và curl, và những nhóm đã cấp API key. Agent cũng có thể gọi cùng base qua MCP tại /mcp hoặc skill tại dist/skills/pdf-toolbox/SKILL.md. Các chỉ mục khám phá như /llms.txt giúp agent lập trình tìm điểm cuối; chúng không phải tín hiệu xếp hạng Google.

Để thử lại an toàn các POST có thay đổi dữ liệu trên API, hãy gửi Idempotency-Key (xem Idempotency-Key: thử lại an toàn cho tác vụ PDF). Đường cloud của CLI vẫn là một yêu cầu HTTP cho mỗi lần gọi; hãy dùng tiêu đề đó khi lớp bọc của bạn thử lại.

Chọn chế độ trong thực tế

Dùng local khi tệp buộc phải ở lại runner, khi bạn đã có binary pdfx và các phụ thuộc native trên máy đó, và khi độ trễ chủ yếu đến từ thao tác chứ không phải tải lên. Dùng cloud khi các phụ thuộc nặng chỉ nằm trên server, khi bạn muốn cùng hạn mức và cách đo như những client API khác, hoặc khi agent đã giữ API key cho https://pdf123.xyz hay base self-host của bạn.

Đừng trộn lẫn kỳ vọng: OCR local vẫn theo hợp đồng đầu ra Markdown của misc/ocr-pdf; compress trên cloud vẫn là luồng qpdf, không phải cắt bớt font. Việc đổi chế độ thay đổi nơi thao tác chạy, không đổi ngữ nghĩa của danh mục.

pdfx không phải là gì

pdfx không phải một desktop GUI và cũng không phải thư viện OCR nhúng để liên kết vào ứng dụng khác. Nó là client dòng lệnh cho các thao tác PDF: mặc định cục bộ, dùng HTTP khi bạn yêu cầu. Việc dùng một lần trên trình duyệt vẫn nằm trên portal (Compress, OCR và phần còn lại của danh mục). Tự động hóa ưa binary có thể ở lại với pdfx.

So sánh cùng thao tác qua trình duyệt, curl, MCP và CLI được phác ở Cùng thao tác, bốn client. Bắt đầu từ Nhà phát triển để lấy key và OpenAPI, hoặc Self-host nếu API base nên là stack Docker Compose của bạn.