Connect를 통한 태그된 PDF 튜토리얼

적합성 경계 (먼저 읽어 주십시오). NextPDF는 PDF/UA-2가 기대하는 태그된 구조, 대체 텍스트, 메타데이터를 내보냅니다. 이는 출력이 PDF/UA-2(ISO 14289-2)에 적합하도록 의도된 상태가 되게 합니다. 그렇다고 해서 문서 자체가 “적합한” 상태가 되는 것은 아닙니다. 독립적인 검사기(엄격한 PDF/UA-2 모드의 veraPDF)가 적합성을 결정합니다. 따라서 아래의 모든 “PASS”, “적합”, “준수” 진술은 “문서가 적합하도록 의도되었으며, 결과는 veraPDF가 결정한다”는 뜻으로 읽으십시오.

한눈에 보기

이 튜토리얼에서는 Connect 전송으로 태그된 PDF를 작성합니다. 태그 모드를 활성화하고 제목을 설정한 뒤, 시맨틱하게 구조화된 HTML을 추가한 다음, 표준 검사 도구와 veraPDF로 결과를 검증합니다. 여기에서 사용하는 태그 모드와 콘텐츠 도구는 core입니다. 표준 검사 검증 도구는 Pro/Enterprise 계층입니다. 해당 도구는 nextpdf/premium이 서버와 함께 설치된 경우에만 class_exists()를 통해 등록됩니다.

설치

composer require nextpdf/server

개념 개요

논리 구조와 자연어 명세는 함께 작용해 콘텐츠를 읽기 순서대로 탐색할 수 있게 합니다(ISO 32000-2 §14.7). 텍스트가 아닌 콘텐츠의 대체 설명은 /Alt 항목에 보관됩니다(ISO 32000-2 §14.8). 콘텐츠는 구조 트리에 반영되어야 하며, 적합성은 검사기가 결정합니다(PDF/UA-2 §8.2.4). 시맨틱 HTML을 잘 구성하면 파이프라인이 그에 맞는 구조를 대신 생성합니다. 이 튜토리얼은 구조를 직접 손으로 구축하는 방식이 아니라 이 방식에 의존합니다.

API 표면

도구 이름은 tools/list를 통해 실행 중인 레지스트리와 대조해 검증합니다. 기준 카탈로그는 /connect/tool-catalog/에 있습니다. 이 튜토리얼에서는 도구 개수를 다시 명시하지 않습니다.

코드 예제 — 빠른 시작

가장 짧은 경로는 다음과 같습니다. 언어와 함께 태그 모드를 활성화하고, 제목을 설정한 다음 콘텐츠를 추가합니다.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

첫 번째 콘텐츠 호출 전에 태그 모드를 활성화하십시오. 작성기는 첫 페이지를 내보낼 때 모드를 고정하므로, 나중에 켜더라도 이미 내보낸 콘텐츠로 돌아가 태그를 지정하지 않습니다. 문서 제목은 PDF/UA-2에서 필수이며, 태그 모드는 뷰어 제목 환경 설정을 지정합니다.

코드 예제 — 프로덕션

시맨틱 HTML을 추가합니다. 파이프라인은 제목, 목록, 표(<th scope> 포함), 링크, 그림(alt 포함)을 올바른 구조 유형에 매핑합니다:

그런 다음 PDF/UA-2를 기준으로 표준 검사를 실행하고, 출력에 대해 veraPDF --flavour ua2를 실행합니다. 검사 결과와 veraPDF 판정은 평가 결과입니다. 이 결과를 통해 문서가 적합하도록 의도되었는지 확인할 수 있습니다. 적합성은 NextPDF가 아니라 veraPDF가 결정합니다.

예외 사례 및 주의 사항

콘텐츠 이후에 태그 모드를 활성화한 경우. 모드를 켜기 전에 추가한 콘텐츠에는 태그가 지정되지 않으며, 검사에서 태그된 콘텐츠 실패를 보고합니다. 문서를 생성한 직후 모드를 활성화하십시오.
alt 없는 정보성 이미지. 검사에서 그림 대체 텍스트 실패를 보고합니다. 대체 텍스트를 제공하거나 장식용 이미지를 아티팩트로 표시하십시오(/cookbook/connect/page-artifacts/).
제목 수준 건너뜀. 수준을 건너뛰면(예: H1 다음에 H3) 제목 순서 실패입니다. 한 번에 최대 한 수준씩만 내려가십시오.
scope 없는 <th>. 연결된 데이터 셀이 없는 헤더 셀은 표 구조 실패입니다. 모든 <th>에 scope="col" 또는 scope="row" 중 하나를 지정하십시오.
제목 누락. 제목이 없는 문서는 메타데이터 실패입니다. 태그 모드를 활성화한 후 제목을 설정하십시오.

성능

프런트매터의 예산은 문서화된 상한입니다. 태그 지정은 일반 레이아웃 패스의 일부입니다.

보안 참고 사항

일반적인 Connect 전송 지침 외에 여기에서 추가로 적용되는 사항은 없습니다. 외부로 전달되는 로그 수준에서 문서 콘텐츠나 HTML 본문을 기록하지 마십시오.

적합성

PDF/UA-2 매핑

시맨틱 HTML은 PDF/UA-2 표준 구조 유형(H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside)에 매핑됩니다. 매핑은 자동으로 이루어집니다. 이 계약에서 사용자가 맡은 부분은 시맨틱 HTML을 작성하는 것입니다.

태그 → ISO 32000-2 §14.9 상호 참조

주장	조항	reference_id
논리 구조 + 언어 → 읽기 순서대로 탐색 가능	ISO 32000-2 §14.7
`/Alt`에 보관된 대체 설명	ISO 32000-2 §14.8
구조 트리 내 콘텐츠. 적합성은 검사기가 결정함	PDF/UA-2 §8.2.4

WCAG 2.2 매핑

이 구조는 콘텐츠 수준에서 WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1, 2.4.6을 지원합니다. 콘텐츠 작성자인 사용자는 WCAG 수준의 작성 결정에 대한 책임을 계속 집니다.

NextPDF는 PDF/UA-2에 적합하도록 의도된 출력을 생성합니다. 적합성을 단언하지는 않습니다. 적합성 판정은 veraPDF(또는 다른 검사기)가 내립니다. 검사 통과 또는 veraPDF 실행은 출력이 적합하도록 의도되었다는 증거이며, NextPDF에 의한 인증은 아닙니다.

상업적 맥락

태그 모드와 콘텐츠 도구는 core입니다. 표준 검사 검증 도구는 Pro/Enterprise 계층이며, nextpdf/premium이 서버와 함께 설치된 경우에만 등록됩니다.

Connect 세부 사항

전송 가용성(MCP / REST / gRPC)

이 튜토리얼의 모든 도구는 MCP tools/call, REST 도구 엔드포인트, gRPC 서비스에서 동일한 방식으로 호출됩니다. 모두 공유 도구 실행기를 통해 실행됩니다.

HITL 위험 계층

태그 모드 활성화와 콘텐츠 도구 사용은 주의 수준입니다. 표준 검사는 읽기 전용입니다. 파일 쓰기 출력 경로에는 승인이 필요하지만, base64 모드에는 필요하지 않습니다. /connect/hitl-risk-tiers/를 참조하십시오.

확인 게이트 JSON 엔벨로프

파일 쓰기 출력 경로가 게이팅되면 게이트는 챌린지 엔벨로프와 일회용 토큰을 반환합니다. 토큰은 도구 이름, nonce, 300 초의 수명(TTL)에 바인딩됩니다. 진행하려면 arguments._confirmation_token과 함께 도구를 다시 호출하십시오. /connect/hitl-risk-tiers/를 참조하십시오.

함께 보기

/cookbook/connect/conformance-mode/ — 태그 모드 이면의 모드 판별기입니다.
/cookbook/connect/aria-tagged-pdf/ — 랜드마크 역할 매핑입니다.
/cookbook/connect/page-artifacts/ — 구조 트리에서 장식용 콘텐츠를 제외하는 방법입니다.
/connect/tool-catalog/ — 계층별 도구 집합 계산 방식입니다.