PDF는 한 번 읽을지 여러 번 쓸지로 경로를 골라

일회성 분석은 document 블록이 간단해

PDF를 document 콘텐츠 블록으로 보내면 Claude가 텍스트와 표·그림 같은 시각 요소를 함께 읽어. 계약서나 논문, 설명서 한 권을 한 번 분석하는 작업에는 별도 전처리 없이 가장 마찰이 적은 길이야.

반복해서 쓸 문서는 Files API로

같은 PDF를 여러 턴 참조한다면 한 번 업로드해 file_id를 받고 다음 호출부터 ID로 불러와. 전송량과 지연을 줄이는 대신 업로드 상태와 오래된 파일 정리 책임이 생겨. 자산의 수명 주기를 함께 설계해야 해.

스캔 문서는 OCR 예비 경로를 둬

문자로 만들어진 PDF는 기본 읽기가 잘 되지만 오래된 스캔 문서는 텍스트 추출이 실패할 수 있어. Tesseract나 관리형 OCR로 먼저 처리하거나, 배치 자체가 중요하면 페이지를 이미지 블록으로 보내. 입력 문서의 성격을 검사해 경로를 바꾸는 게 안전해.

원칙: 한 번 읽기는 기본 PDF, 반복 자산은 Files API, 종이 스캔은 OCR 예비 경로로 나눠.

Code

네이티브 PDF document 블록·python

import base64, pathlib

pdf_b64 = base64.standard_b64encode(pathlib.Path("contract.pdf").read_bytes()).decode()

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_b64,
                    },
                },
                {"type": "text", "text": "List all parties named in the agreement."},
            ],
        }
    ],
)

반복 읽기에 Files API·python

uploaded = client.beta.files.upload(
    file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"),
)

# 후속 턴은 file_id로만 참조
for question in ["List the parties.", "Find termination clauses.", "Total fees over 24 months?"]:
    r = client.beta.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        messages=[{
            "role": "user",
            "content": [
                {"type": "document", "source": {"type": "file", "file_id": uploaded.id}},
                {"type": "text", "text": question},
            ],
        }],
        betas=["files-api-2025-04-14"],
    )
    print(question, "->", r.content[0].text[:120])

일회성 분석은 document 블록이 간단해

반복해서 쓸 문서는 Files API로

스캔 문서는 OCR 예비 경로를 둬

Code

External links

Exercise

Progress

댓글 0