pdfx CLI: ทำงานในเครื่องก่อน ใช้คลาวด์เมื่อจำเป็น
pdfx ประมวลผล PDF บนเครื่องเป็นค่าเริ่มต้น และเข้าสู่โหมดคลาวด์เมื่อระบุ API base พร้อมคีย์ เพื่อเรียกปลายทาง REST ของ PDF123 ทั้งแบบโฮสต์และที่โฮสต์เอง
PDF123 คือชื่อผลิตภัณฑ์ ส่วน pdfx คือ CLI ขนาดสั้นที่คุยกับการดำเนินการชุดเดียวกัน เส้นทางเริ่มต้นคือทำงานในเครื่อง อ่านไฟล์ รัน op ผ่าน pdf-core แล้วเขียนผลลัพธ์ โดยไม่ต้องมีบัญชี ไม่ต้องใช้คีย์ API และไม่มีการอัปโหลด
ทำงานในเครื่องก่อน หมายความว่าไฟล์ไม่เคยออกไปไหน
คำสั่งทั่วไปหน้าตาแบบ pdfx merge a.pdf b.pdf -o merged.pdf หรือ pdfx compress input.pdf การประมวลผลจะรันในที่ที่ไบนารีรันอยู่ เหมาะกับงาน CI บน runner ส่วนตัว สคริปต์ข้างชุดใบแจ้งหนี้ และทุกกรณีที่อัปโหลดไปบุคคลที่สามเป็นคำตอบที่ผิด
โหมดในเครื่องไม่ใช่ wrapper บาง ๆ ที่แอบส่งไบต์ไปที่อื่น CLI ใช้ operation registry ชุดเดียวกับเซิร์ฟเวอร์ (pdf_core::ops::run) ถ้าต้องการเส้นทางเครือข่ายต้องเลือกใช้เองด้วย --cloud
subcommand ในตัวครอบคลุม op ที่ใช้บ่อย ทั้ง merge, split, compress, rotate, extract, OCR, convert, protect, unlock, watermark และงานที่เกี่ยวข้อง ผลลัพธ์ในโหมดในเครื่องเขียนลงไฟล์เป็นค่าเริ่มต้นผ่าน -o / --output ส่วน - เขียนออก stdout
--cloud คือแคตตาล็อกเดียวกันผ่าน HTTP
เมื่อต้องการใช้ hosted API (หรือ pdfx-server ที่คุณรันเอง) ให้ใส่ --cloud พร้อม --api-base และ --api-key (หรือตั้ง PDFX_API_KEY) โหมดคลาวด์ต้องมี curl เบื้องหลัง และล้มเหลวถ้าไม่ได้ตั้งคีย์ ตัวอย่างจากสกิลที่เผยแพร่:
pdfx --cloud --api-base "$PDFX_API_BASE" --api-key "$PDFX_API_KEY" \
merge a.pdf b.pdf -o merged.pdf
--api-base มีค่าเริ่มต้นเป็น https://pdf123.xyz ซึ่งคือ API แบบโฮสต์ หากใช้สแตก Docker Compose บนเครื่อง ให้ชี้ไปที่ http://127.0.0.1:8080 แทน CLI กลายเป็นไคลเอนต์ของพื้นผิว REST ใน Developers โดยชื่อ op ตรงกับเครื่องมือในพอร์ทัลและ OpenAPI (/v1/openapi.json)
โหมดคลาวด์ไม่ได้เปลี่ยนว่า op หมายถึงอะไร Compress ยังเป็นการบีบอัดสตรีมด้วย qpdf OCR ยังคืนข้อความ Markdown จากเส้นทาง Rust ไม่ใช่เลเยอร์ PDF ที่ค้นหาได้ และ flag CLI ที่ตกค้างซึ่งแมปกับพารามิเตอร์ OCR ยุค Java ที่ถูกละเว้น (เช่น languages) ก็ไม่เปลี่ยนสัญญานั้น
ทำไมต้องมีสองโหมด
โหมดในเครื่องตอบโจทย์ความเชื่อใจแบบออฟไลน์และต้นทุนไปกลับที่เป็นศูนย์ ส่วนโหมดคลาวด์ตอบโจทย์การแชร์ข้อจำกัดอัตรา การรัน op บนเครื่องที่มีแค่ CLI กับ curl และทีมที่ออกคีย์ API แล้ว เอเจนต์ยังเรียก base เดียวกันผ่าน MCP ที่ /mcp หรือสกิลที่ dist/skills/pdf-toolbox/SKILL.md และดัชนีอย่าง /llms.txt ช่วยให้เอเจนต์เขียนโค้ดหาเอนด์พอยต์เจอ แต่ไม่ใช่สัญญาณจัดอันดับของ Google
สำหรับการลองใหม่ที่ปลอดภัยของ POST ที่เปลี่ยนสถานะ ให้ส่ง Idempotency-Key (ดู Idempotency-Key: การลองใหม่ที่ปลอดภัยสำหรับงาน PDF) เส้นทางคลาวด์ของ CLI ยังเป็นการเรียก HTTP หนึ่งครั้งต่อครั้ง จึงควรใส่เฮดเดอร์นี้เมื่อตัวห่อลองใหม่
เลือกโหมดในทางปฏิบัติ
ใช้โหมดในเครื่องเมื่อไฟล์ต้องอยู่บน runner เมื่อมีไบนารี pdfx กับไดเพนเดนซีเนทีฟบนเครื่องนั้นแล้ว และเมื่อเวลาแฝงขึ้นกับ op มากกว่าการอัปโหลด ใช้โหมดคลาวด์เมื่อไดเพนเดนซีหนักอยู่แค่บนเซิร์ฟเวอร์ เมื่อต้องการข้อจำกัดอัตราและการวัดปริมาณแบบเดียวกับไคลเอนต์ API รายอื่น หรือเมื่อเอเจนต์มีคีย์ API สำหรับ https://pdf123.xyz หรือ base ที่โฮสต์เองแล้ว
อย่าปนความคาดหวัง เพราะ OCR ในโหมดในเครื่องก็ยังทำตามสัญญา Markdown ของ misc/ocr-pdf และ compress บนคลาวด์ก็ยังบีบอัดสตรีมด้วย qpdf ไม่ใช่ตัดฟอนต์ การสลับโหมดเปลี่ยนตำแหน่งที่ op รัน ไม่เปลี่ยนความหมายของแคตตาล็อก
pdfx ไม่ใช่อะไร
pdfx ไม่ใช่ GUI เดสก์ท็อป และไม่ใช่ไลบรารี OCR ที่ฝังในแอปอื่น มันคือไคลเอนต์บรรทัดคำสั่งสำหรับงาน PDF ที่ทำในเครื่องเป็นค่าเริ่มต้น และใช้ HTTP เมื่อสั่ง งานครั้งเดียวบนเบราว์เซอร์ยังอยู่ที่พอร์ทัล (Compress OCR และเครื่องมืออื่นในแคตตาล็อก) ส่วนงานอัตโนมัติที่ถนัดไบนารีก็ใช้ pdfx ต่อได้
การเปรียบเทียบ op เดียวกันผ่านเบราว์เซอร์ curl MCP และ CLI สรุปไว้ใน ปฏิบัติการเดียวกัน สี่ไคลเอนต์ เริ่มที่ Developers สำหรับคีย์และ OpenAPI หรือ Self-host ถ้า API base ควรเป็นสแตก Docker Compose ของคุณเอง