Tạo tệp PDF đầu tiên của bạn với NextPDF Connect

Tổng quan nhanh

Công thức này chỉ ra lộ trình ngắn nhất để đi từ một phiên trống đến một tệp PDF đã kết xuất bằng NextPDF Connect. Bạn tạo một tài liệu A4 một trang, thêm tiêu đề và phụ đề, rồi trả về tệp ở dạng base64. Ba công cụ Core đảm nhận việc này: create_pdf, add_text và output_pdf. Bạn không cần phông chữ, hình ảnh hay gói có bản quyền.

Một transport Connect gửi mỗi lệnh gọi công cụ dưới dạng yêu cầu và trả về kết quả của công cụ dưới dạng phản hồi. Lớp transport độc lập với kết quả do công cụ báo cáo (PSR-18 §p2).

Cài đặt

Cài đặt NextPDF Server và liên kết với một transport:

composer require nextpdf/server

Chạy máy chủ với transport mà host của bạn yêu cầu: Model Context Protocol qua stdio, REST hoặc gRPC. Xem Khả dụng của transport bên dưới. Các công cụ trong công thức này là công cụ Core. Chúng đi kèm với máy chủ, nên bạn không cần gói Pro hay Enterprise.

Tổng quan khái niệm

Một phiên Connect là kho tài liệu phía máy chủ được định danh bằng một document_id. create_pdf mở một phiên và trả về id. Mỗi lệnh gọi công cụ sau đó đều dùng id này. Tài liệu bắt đầu bằng một trang trống. Page tree là cấu trúc mà trình đọc dùng để truy cập từng trang (ISO 32000-2 §7.7.3). output_pdf kết xuất phiên thành một tệp PDF. Theo mặc định, sau đó công cụ này hủy phiên để giải phóng bộ nhớ.

Khi bạn gọi add_text mà không chỉ định rõ x hoặc y, văn bản sẽ tự xếp vị trí. Nó bắt đầu tại con trỏ hiện tại, và con trỏ tiến lên sau mỗi lệnh gọi.

Bề mặt API

Tool registry phân giải các công cụ này khi máy chủ khởi động. Các tên hiển thị ở đây là tên giao thức của registry. Danh mục chính thức là tool catalog hợp nhất. Các công cụ khả dụng tùy thuộc vào gói đã cài đặt, nhưng ba công cụ này luôn có trong Core.

Công cụ	Vai trò	Mức rủi ro
create_pdf	Mở một phiên tài liệu	An toàn
add_text	Ghi văn bản vào tài liệu	Thận trọng
output_pdf	Kết xuất và trả về PDF	Cần phê duyệt (chế độ tệp) / Xem xét (base64)

Mẫu mã — bắt đầu nhanh

Host thực hiện ba lệnh gọi công cụ theo thứ tự:

1. Gọi create_pdf với page_size: "A4", orientation: "portrait", cùng tiêu đề và tác giả của tài liệu. Máy chủ trả về một document_id.
2. Gọi add_text với document_id đó, văn bản tiêu đề, một font_size lớn, width: 0 (toàn bộ chiều rộng nội dung), và alignment: "center".
3. Gọi output_pdf với document_id. Khi không có file_path, máy chủ trả về PDF dưới dạng base64 và hủy phiên.

Đây là một đối tượng đối số create_pdf tối thiểu:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

Phản hồi bao gồm document_id, số lượng trang và hình học trang. Hãy xem id như một giá trị mờ và đừng suy diễn ý nghĩa từ nó.

Mẫu mã — sản xuất

Bên gọi trong môi trường sản xuất kiểm tra từng phản hồi trước khi thực hiện lệnh gọi tiếp theo. Bên gọi không bao giờ tái sử dụng một document_id sau khi output_pdf đã hủy phiên.

1. create_pdf — xác nhận phản hồi chứa một document_id. Nếu máy chủ trả về lỗi giới hạn phiên, hãy giải phóng các phiên không dùng và thử lại.
2. add_text (tiêu đề) — xác nhận phản hồi trả về một position.
3. add_text (phụ đề) — dùng một font_size nhỏ hơn; con trỏ tiếp tục bên dưới tiêu đề.
4. output_pdf — đọc trường base64 và giải mã thành byte. Cờ destroyed xác nhận phiên không còn tồn tại.

Tệp được trả về nội tuyến (chế độ base64), nên không có tác dụng phụ trên hệ thống tệp và không có cổng phê duyệt của con người. Xem Mức rủi ro HITL.

Trường hợp biên & điểm cần lưu ý

• Phiên đã hủy. Sau khi output_pdf chạy với destroy: true mặc định, document_id không còn hợp lệ. Bất kỳ lệnh gọi nào sau đó dùng nó đều trả về lỗi không-biết-tài-liệu. Thay vào đó, hãy tạo một phiên mới.
• Kích thước trang không xác định. Máy chủ từ chối một page_size mà nó không nhận ra và trả về lỗi rõ ràng. Hãy dùng một kích thước có trong tài liệu (A3, A4, A5, A6, Letter, Legal, Tabloid).
• Văn bản rỗng. Một text rỗng tạo ra một mục có chiều rộng bằng không, chứ không phải lỗi. Hãy kiểm tra dữ liệu đầu vào của bạn trước khi gọi.
• Giới hạn phiên. Kho lưu trữ trong bộ nhớ giới hạn số phiên chạy đồng thời. Hãy giải phóng phiên kịp thời bằng output_pdf.

Hiệu năng

Một trang đơn chỉ có văn bản sẽ kết xuất gọn trong ngân sách trang, và kết quả thường là 1–3 KB. Công thức này dùng hồ sơ khả tái tạo kết xuất-kép structural. PDF mang một /ID trong trailer cùng các dấu thời gian thay đổi giữa các lần chạy, nên phép so sánh cấu trúc (đã chuẩn hóa) mới là phép so sánh chính xác.

Lưu ý bảo mật

Đường dẫn base64 không có tác dụng phụ trên hệ thống tệp. Đường dẫn xuất-tệp thì có tác dụng phụ, và tác dụng đó được kiểm soát qua cổng. Xem phần HITL. Hãy xem base64 được trả về là nội dung tài liệu, chứ không phải một kênh đáng tin cậy. Nó chính là các byte mà các công cụ đã tạo ra.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Một transport gửi một yêu cầu và nhận một phản hồi độc lập với kết quả.	PSR-18	§p2
Các trang được truy cập thông qua page tree của tài liệu.	ISO 32000-2	§7.7.3

Công thức này mô tả cách máy chủ tạo ra kết quả. Nó không khẳng định sự tuân thủ hồ sơ.

Bối cảnh thương mại

Không áp dụng — cả ba công cụ đều thuộc Core.

Khả dụng của transport

Transport	Khả dụng	Ghi chú
MCP (stdio)	Có	Các lệnh gọi công cụ ánh xạ tới MCP tools/call.
REST	Có	Mỗi công cụ là một thao tác REST; kết quả là phần thân phản hồi.
gRPC	Có	Mỗi công cụ là một lệnh gọi đơn (unary).

Kết quả của công cụ giống nhau trên mọi transport; chỉ khác cách đóng khung. Một kết quả không-thành-công vẫn là phản hồi bình thường, chứ không phải lỗi transport (PSR-18 §p2).

Mức rủi ro HITL

Máy chủ đặt mỗi lệnh gọi công cụ lên thang rủi ro có-con-người-tham-gia (HITL): An toàn (0) → Thận trọng (1) → Xem xét (2) → Cần phê duyệt (3). create_pdf là An toàn, và add_text là Thận trọng. output_pdf là Cần phê duyệt, nhưng ở chế độ base64 (không có file_path) nó hạ xuống Xem xét và chạy mà không cần con người xác nhận. Ghi vào một tệp sẽ giữ nó ở mức Cần phê duyệt. Xem output-approval và tài liệu tham khảo về mức rủi ro HITL.

Phong bì JSON của cổng xác nhận

Công thức này luôn ở chế độ base64, nên cổng xác nhận trả về phong bì cho phép:

{ "allowed": true }

Phong bì thử thách (allowed: false, kèm một chuỗi challenge và một token dùng một lần) được mô tả trong output-approval.

Xem thêm

• Tài liệu nhiều trang
• Nhúng hình ảnh
• Danh mục công cụ
• Các mức rủi ro HITL