Biên tập PII trong PDF bằng Connect

Tổng quan nhanh

Công thức này loại bỏ thông tin định danh cá nhân (PII) được phát hiện khỏi lớp văn bản của tài liệu bằng các công cụ biên tập do NextPDF Connect cung cấp. Các công cụ này thuộc bậc Enterprise. ToolRegistry khởi tạo redact_pdf, zone_redact_pdf và deidentify_pdf bằng cách dò tìm các lớp quyền riêng tư Enterprise (RedactionEngine + PiiDetector) với class_exists(). Registry này chỉ đăng ký từng công cụ ở bậc enterprise khi các lớp đó có thể được tự động nạp. Trên một bản cài đặt chỉ có mã nguồn mở, các công cụ này không hiện diện: lệnh gọi sẽ thất bại với lỗi công cụ không xác định thay vì suy giảm chức năng một cách âm thầm. Cả ba công cụ đều khai báo destructiveHint: true. Thao tác chỉnh sửa này viết lại nội dung trang và không thể đảo ngược từ tài liệu đã chỉnh sửa.

Trang này mô tả hành vi của công cụ trên bề mặt Connect. Một quy trình biên tập không chứng nhận rằng tài liệu không còn dữ liệu cá nhân sau lệnh gọi. Việc phát hiện chỉ chạy trên lớp văn bản có thể trích xuất, và bản triển khai vẫn chịu trách nhiệm xác minh kết quả.

Cài đặt

composer require nextpdf/server

Các công cụ biên tập chỉ được đăng ký khi bạn cài đặt mô-đun quyền riêng tư Enterprise cùng với máy chủ. Mô-đun này được phân phối trong nextpdf/premium. Hãy xác nhận rằng công cụ có mặt trên bản triển khai đang chạy trước khi bạn dựa vào nó:

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

Nếu redact_pdf bị thiếu trong kết quả tools/list, các lớp quyền riêng tư Enterprise đã không được phân giải trên bản cài đặt này. Xem /connect/tool-catalog/ để tìm hiểu cách registry tính toán tập công cụ theo từng bậc ở thời điểm khởi động.

Tổng quan khái niệm

Ba công cụ bao quát ba chiến lược biên tập. Tất cả đều thuộc bậc Enterprise, và tất cả đều có gợi ý mang tính phá hủy:

redact_pdf — phát hiện và loại bỏ dữ liệu cá nhân khỏi nội dung văn bản thuần của tài liệu bằng một bộ phát hiện tích hợp sẵn, rồi trả về nội dung đã chỉnh sửa và một báo cáo có cấu trúc.
zone_redact_pdf — áp dụng biên tập theo vùng dựa trên tọa độ cho nội dung văn bản thuần. Hãy dùng công cụ này khi bạn biết vùng theo vị trí thay vì theo mẫu.
deidentify_pdf — áp dụng một chiến lược xóa định danh có hệ thống (biên tập hoặc loại bỏ) trên các thực thể được phát hiện.

Việc loại bỏ nội dung khỏi luồng nội dung trang sẽ chỉnh sửa luồng đó theo cách phá hủy: các byte bị ảnh hưởng bị viết lại và không thể khôi phục từ tài liệu đã chỉnh sửa (ISO 32000-2 §14.11). Theo thiết kế, báo cáo ghi lại số ký tự và vị trí của mỗi lần loại bỏ, không bao giờ ghi lại chính văn bản đã bị loại bỏ.

Bề mặt API

Gói Enterprise định nghĩa từng công cụ và cũng cung cấp chính xác schema yêu cầu và phản hồi của công cụ đó. Trang này mô tả hợp đồng gọi lệnh Connect, không phải một danh sách tham số cố định. Các tên công cụ được xác minh với registry đang chạy là redact_pdf, zone_redact_pdf và deidentify_pdf, tất cả thuộc danh mục document với destructiveHint: true. Danh mục chính thức là /connect/tool-catalog/. Công thức này không nêu lại số lượng công cụ, vì giá trị đó là một thuộc tính ở thời gian chạy của bản triển khai.

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

Phát hiện và loại bỏ nội dung qua Model Context Protocol (MCP) (tools/call). Các đối số bên dưới minh họa dạng lệnh gọi. Schema đối số chính thức là schema mà tools/list trả về trên bản triển khai của bạn:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "redact_pdf",
    "arguments": {
      "source": "/var/lib/nextpdf/in/employee-directory.pdf"
    }
  }
}

Một lệnh gọi thành công sẽ trả về một báo cáo. Với mỗi lần loại bỏ, một mục ghi lại trang, một nhãn danh mục, số ký tự ban đầu và một khung bao, chứ không phải văn bản đã bị loại bỏ.

Mẫu mã — môi trường sản xuất

Hãy coi lệnh gọi biên tập là một thao tác phá hủy, và kiểm tra báo cáo trước khi bạn phát hành tài liệu. Khi đi qua một transport mạng, hãy xử lý lỗi transport và lỗi ở cấp công cụ như hai trường hợp riêng biệt:

curl -sS -X POST https://connect.example.com/v1/tools/redact_pdf \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/legal-discovery-batch.pdf"}' \
  -o /tmp/redaction-report.json -w '%{http_code}' > /tmp/redaction-status

status="$(cat /tmp/redaction-status)"
if [ "$status" != "200" ]; then
  # 4xx/5xx is a normal HTTP outcome the caller inspects, not a transport
  # failure. A connection error (curl non-zero exit) is the separate case.
  echo "redact_pdf returned HTTP $status; inspect the body, do not release the document" >&2
  exit 1
fi

Chỉ phát hành tài liệu đã chỉnh sửa sau khi một người hoặc một biện pháp kiểm soát ở bước sau đã xem lại báo cáo. Việc chặn phát hành cho đến sau khâu xem lại đó đặt kiểm soát ngay tại điểm mà thao tác chỉnh sửa tự động tạo ra rủi ro dữ liệu còn sót (IEC 31010:2019).

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

PDF quét không có lớp văn bản. Việc phát hiện chạy trên lớp văn bản có thể trích xuất. Một trang chỉ có ảnh sẽ không tạo ra lần loại bỏ nào, và đây không phải là lỗi. Nếu nội dung đã được raster hóa, hãy chạy nhận dạng ký tự quang học (OCR) trên tài liệu trước khi biên tập.
Nguồn được mã hóa. Hãy cung cấp mật khẩu tài liệu thông qua schema đối số của công cụ. Nếu thiếu mật khẩu, lệnh gọi sẽ thất bại thay vì chỉ xử lý một phần của tài liệu.
Không có công cụ. Trên một bản cài đặt chỉ có mã nguồn mở, các lớp quyền riêng tư Enterprise không được phân giải và redact_pdf không được đăng ký, nên lệnh gọi thất bại với lỗi công cụ không xác định. Đây là ranh giới có chủ đích, không phải hành vi suy giảm.
Các phát hiện chồng lấn. Khi hơn một bộ phát hiện khớp cùng một vùng, công cụ loại bỏ vùng đó một lần và khử trùng lặp trong báo cáo.

Hiệu năng

Ngân sách hiệu năng trong front-matter là một mức trần ở cấp tài liệu, không phải một cam kết ở cấp dịch vụ. Các tài liệu lớn được xử lý theo từng trang. Hãy lên kế hoạch chạy lại lệnh gọi trên một tập con trong phạm vi trang thay vì nâng timeout toàn cục.

Ghi chú bảo mật

Lưu trú dữ liệu & biện pháp giảm thiểu PII

Máy chủ Connect xử lý văn bản tài liệu ngay trong tiến trình. Báo cáo cố tình bỏ qua văn bản đã bị loại bỏ và chỉ báo cáo số lượng cùng vị trí, nên báo cáo không đưa trở lại dữ liệu cá nhân mà nó mô tả. Việc lưu trú dữ liệu ở cấp triển khai đối với đầu vào và đầu ra đã chỉnh sửa là trách nhiệm của bên tích hợp, không phải một thuộc tính của công cụ.

Telemetry an toàn & làm sạch log

Không ghi log đường dẫn tài liệu nguồn hoặc nội dung báo cáo tại mức log sẽ được gửi ra bên ngoài. Chỉ ghi log tên công cụ, request id và kết quả pass/fail.

Mô hình mối đe dọa

Một thao tác biên tập chỉ che văn bản về mặt hình ảnh nhưng không loại bỏ nó sẽ khiến dữ liệu vẫn có thể trích xuất được. Các công cụ này viết lại luồng nội dung bị ảnh hưởng thay vì phủ một hình chữ nhật lên trên; việc khôi phục các byte đã bị loại bỏ từ tài liệu đã chỉnh sửa là không thể (ISO 32000-2 §14.11). Rủi ro còn sót vẫn tồn tại khi bộ phát hiện bỏ lỡ nội dung: một mẫu nằm ngoài các quy tắc của nó, hoặc văn bản chỉ hiện diện dưới dạng ảnh đã raster hóa. Quy trình giảm thiểu rủi ro đó bằng khâu xem lại báo cáo bắt buộc, chứ không phải bằng một tuyên bố về tính đầy đủ.

Hành vi ở chế độ FIPS

Biên tập không thực hiện thao tác mã hóa nào và không bị ảnh hưởng bởi chính sách chế độ Federal Information Processing Standards (FIPS) trên máy chủ.

Tuân thủ

Tuyên bố	Điều khoản	reference_id
Việc loại bỏ nội dung sẽ viết lại luồng nội dung bị ảnh hưởng	ISO 32000-2 §14.11
Biên tập đánh dấu rồi loại bỏ; việc loại bỏ là một thao tác chỉnh sửa nội dung	ISO 32000-2 §14.11
Kiểm soát được đặt tại điểm mà thao tác chỉnh sửa tự động tạo ra rủi ro	IEC 31010:2019

Việc hỗ trợ các công cụ biên tập không chứng nhận rằng một tài liệu đã xử lý không còn dữ liệu cá nhân. Chỉ một cuộc xem xét độc lập mới đưa ra kết luận đó.

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

Các công cụ biên tập thuộc bậc Enterprise. Chúng chỉ được đăng ký khi nextpdf/premium được cài đặt cùng với máy chủ. Xem liên kết chuyển đổi trong front-matter.

Chi tiết riêng của Connect

Tính khả dụng của transport (MCP / REST / gRPC)

Bạn gọi các công cụ theo cùng một cách qua mọi transport vận hành bộ thực thi công cụ dùng chung: MCP tools/call, endpoint công cụ REST và dịch vụ gRPC. Schema đối số độc lập với transport. Đây là schema được trả về bởi tools/list (MCP) hoặc bộ mô tả dịch vụ (gRPC).

Bậc rủi ro HITL

Cả ba công cụ đều khai báo destructiveHint: true. Khi một người vận hành nâng một công cụ lên mức rủi ro approval_required thông qua một ghi đè cấu hình, lệnh gọi sẽ bị ConfirmationGate chặn. Việc ghi đè chỉ có thể nâng rủi ro, không bao giờ hạ thấp nó. Xem /connect/hitl-risk-tiers/.

Lớp bọc JSON của cổng xác nhận

Khi công cụ bị chặn và được gọi mà không có token hợp lệ, cổng sẽ trả về một lớp bọc challenge có dạng như sau:

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

Bên gọi gọi lại cùng công cụ đó với arguments._confirmation_token được đặt thành token đã cấp. Token ràng buộc với tên công cụ, một nonce và một TTL 300 giây — chứ không phải các đối số — và chỉ dùng được một lần.

Xem thêm

/connect/tool-catalog/ — cách registry tính toán tập công cụ theo từng bậc.
/connect/hitl-risk-tiers/ — mô hình rủi ro bốn cấp và cổng kiểm soát.
/cookbook/connect/extract-text-content/ — xem trước văn bản có thể trích xuất trước khi biên tập.
/cookbook/connect/digital-signature/ — ký tài liệu đã chỉnh sửa để bảo toàn chuỗi giám sát.