ทำเครื่องหมายอาร์ติแฟกต์บนหน้าผ่าน Connect

ภาพรวมโดยสรุป

สูตรนี้ห่อหุ้มองค์ประกอบประกอบหน้า ซึ่งรวมถึงส่วนหัวและส่วนท้ายแบบต่อเนื่อง หมายเลขหน้า ลายน้ำ และพื้นหลัง ไว้ในเนื้อหาที่ทำเครื่องหมายเป็นอาร์ติแฟกต์ผ่านทรานสปอร์ตของ Connect องค์ประกอบประกอบหน้ายังคงปรากฏบนหน้า แต่จะไม่อยู่ในโครงสร้างทรีและลำดับการอ่านของเทคโนโลยีสิ่งอำนวยความสะดวก เครื่องมืออาร์ติแฟกต์อยู่ใน ระดับ Enterprise: NextPDF ค้นพบเครื่องมือนี้ด้วยการตรวจสอบ class_exists() และจะลงทะเบียนเครื่องมือนี้ก็ต่อเมื่อมีการติดตั้ง nextpdf/premium ไว้ควบคู่กับเซิร์ฟเวอร์ ชนิดย่อยใช้ enum ที่กำหนดชนิดไว้ (Pagination, Layout, Page, Background)

เมื่อต้องการตรวจสอบเอาต์พุต ให้ใช้เครื่องมือตรวจสอบมาตรฐานระดับ Enterprise ซึ่งรายงานผลเทียบกับ PDF/UA-2 ผลลัพธ์ที่ผ่านเป็นเพียงผลการตรวจสอบของเครื่องมือ ไม่ใช่การรับรองความสอดคล้องตามมาตรฐานจากหน่วยงานอิสระ

การติดตั้ง

composer require nextpdf/server

ยืนยันว่ามีเครื่องมืออาร์ติแฟกต์ระดับ Enterprise อยู่โดยเรียก tools/list ดู /connect/tool-catalog/

ภาพรวมเชิงแนวคิด

เนื้อหาที่ไม่ใช่ส่วนหนึ่งของโครงสร้างเชิงตรรกะจะถูกทำเครื่องหมายเป็นอาร์ติแฟกต์และถูกแยกออกจากลำดับการอ่าน (PDF/UA-2 §8.3) อาร์ติแฟกต์ประกอบด้วยเนื้อหาประเภทประกอบหน้า การจัดวาง หน้า หรือพื้นหลัง และแยกออกจากเนื้อหาจริง (PDF/UA-2 §8.3) เนื้อหาจริงจะสะท้อนอยู่ในโครงสร้างทรี แต่อาร์ติแฟกต์จะไม่สะท้อนอยู่ในโครงสร้างนั้น (PDF/UA-2 §8.2.4)

เครื่องมือจะเปิดลำดับเนื้อหาที่ทำเครื่องหมาย (marked-content) ของอาร์ติแฟกต์ตามชนิดย่อยที่ร้องขอ การวาดใดๆที่สั่งก่อนการปิดที่จับคู่กันจะถูกห่อหุ้มอยู่ภายในลำดับนั้น

พื้นผิว API

ตรวจสอบชื่อเครื่องมือเทียบกับรีจิสทรีที่กำลังทำงานอยู่ด้วย tools/list แคตตาล็อกอ้างอิงคือ /connect/tool-catalog/ สูตรนี้จะไม่กล่าวซ้ำถึงจำนวนเครื่องมือ

ตัวอย่างโค้ด — เริ่มใช้งานอย่างรวดเร็ว

เปิดอาร์ติแฟกต์แบบ Background วาดลายน้ำ แล้วปิด:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Background" }
  }
}

ตัวอย่างโค้ด — สำหรับการใช้งานจริง

จับคู่การเปิดทุกครั้งกับการปิด และตรวจสอบว่าหน้านั้นไม่มีเนื้อหากำพร้า (orphan content):

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "emit_artifact",
    "arguments": { "document_id": "<id>", "subtype": "Page", "attached": "Bottom" }
  }
}

หลังจากวาดข้อความส่วนท้ายแล้ว ให้ปิดด้วยเครื่องมือสิ้นสุดอาร์ติแฟกต์ (end-artifact) และเรียกใช้การตรวจสอบมาตรฐานเทียบกับ PDF/UA-2 โครงสร้างทรีต้องมีเฉพาะเนื้อหาส่วนเนื้อความเท่านั้น ส่วนลายน้ำและส่วนท้ายต้องถูกแยกออกจากโครงสร้างนั้น

กรณีขอบและข้อควรระวัง

ชนิดย่อยที่ไม่รู้จัก (ตัวอย่างเช่น "Header") จะถูกปฏิเสธ ส่งค่าใดค่าหนึ่งจาก Pagination, Layout, Page, Background เข้ามา
การปิดโดยไม่มีการเปิด จะล้มเหลวพร้อมข้อความแจ้งว่าระดับความลึกเป็นศูนย์ (depth-zero) จับคู่การเปิดและการปิดเสมอ
การวาดก่อนมีบริบทอาร์ติแฟกต์หรือบริบทโครงสร้างใดๆ จะทำให้เกิดเนื้อหากำพร้าและทำให้กฎโครงสร้างล้มเหลว เปิดบริบทโครงสร้างหรือบริบทอาร์ติแฟกต์ก่อน
ไม่มีเครื่องมือ หากไม่มี nextpdf/premium เครื่องมืออาร์ติแฟกต์ระดับ Enterprise จะไม่ถูกลงทะเบียน และการเรียกจะล้มเหลวพร้อมข้อผิดพลาดว่าไม่รู้จักเครื่องมือ

ประสิทธิภาพ

งบประมาณใน frontmatter เป็นเพดานที่เอกสารกำหนดไว้ การห่อหุ้มอาร์ติแฟกต์ไม่ได้เพิ่มเฟสแยกต่างหากที่วัดผลได้

หมายเหตุด้านความปลอดภัย

ไม่มีข้อกำหนดเพิ่มเติมนอกเหนือจากคำแนะนำทั่วไปเกี่ยวกับทรานสปอร์ตของ Connect

ความสอดคล้องตามมาตรฐาน

การแมป PDF/UA-2

ชนิดย่อย	กรณีการใช้งาน
`Pagination`	headers/footers แบบต่อเนื่อง หมายเลขหน้า องค์ประกอบประกอบของการนำทาง
`Layout`	เส้นคั่น ตัวคั่น เส้นขอบตกแต่ง
`Page`	องค์ประกอบช่วยที่ผูกกับหน้า (เครื่องหมายตัด การลงทะเบียนสี)
`Background`	ลายน้ำ การเติมสีพื้นหลัง การแสดงตราสินค้า

การอ้างอิงข้ามจากแท็กไปยัง ISO 32000-2 §14.9

ข้อกล่าวอ้าง	ข้อกำหนด	reference_id (รหัสอ้างอิง)
เนื้อหาที่ไม่ใช่เชิงโครงสร้างถูกทำเครื่องหมายเป็นอาร์ติแฟกต์ และถูกแยกออกจากลำดับการอ่าน	PDF/UA-2 §8.3
ชนิดย่อยของอาร์ติแฟกต์: pagination/layout/page/background	PDF/UA-2 §8.3
เนื้อหาจริงอยู่ในโครงสร้างทรี ส่วนอาร์ติแฟกต์ไม่อยู่	PDF/UA-2 §8.2.4

การแมป WCAG 2.2

การแยกองค์ประกอบประกอบเชิงตกแต่งออกจากลำดับการอ่านสนับสนุน Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships) ในระดับเนื้อหา

ผลการตรวจสอบมาตรฐานที่ผ่านเป็นผลการตรวจสอบ ไม่ใช่การรับรองความสอดคล้องตามมาตรฐาน ผู้ตรวจสอบอิสระเป็นผู้ตัดสินประเด็นนั้น

บริบทเชิงพาณิชย์

เครื่องมืออาร์ติแฟกต์เป็นระดับ Enterprise และจะลงทะเบียนก็ต่อเมื่อมีการติดตั้ง nextpdf/premium ไว้ควบคู่กับเซิร์ฟเวอร์

รายละเอียดเฉพาะของ Connect

ความพร้อมใช้งานของทรานสปอร์ต (MCP / REST / gRPC)

คุณเรียกใช้เครื่องมือเหล่านี้ได้ด้วยวิธีเดียวกันผ่าน MCP tools/call, ปลายทาง REST tool และบริการ gRPC ทั้งสามแบบใช้ตัวประมวลผลเครื่องมือร่วมกัน

ระดับความเสี่ยง HITL

การส่งออกอาร์ติแฟกต์และการวาดเนื้อหาอยู่ในระดับ caution ส่วนการตรวจสอบมาตรฐานเป็นการอ่านอย่างเดียว ไม่มีรายการใดเป็น approval_required โดยค่าเริ่มต้น ดู /connect/hitl-risk-tiers/

JSON envelope ของเกตยืนยัน

เครื่องมือเหล่านี้จะไม่ทริกเกอร์เกต เว้นแต่การลบล้างค่าโดยผู้ปฏิบัติงานจะยกระดับรายการใดรายการหนึ่งให้เป็น approval_required สัญญาของ envelope และโทเค็นแบบใช้ครั้งเดียวอยู่ใน /connect/hitl-risk-tiers/

ดูเพิ่มเติม

/cookbook/connect/aria-tagged-pdf/ — การแมปบทบาท landmark
/cookbook/connect/figure-caption/ — การจัดกลุ่มรูปภาพที่เข้าถึงได้
/connect/tool-catalog/ — การคำนวณชุดเครื่องมือต่อระดับ
/connect/hitl-risk-tiers/ — โมเดลความเสี่ยงและเกต