Claude API로 PDF 문서 다루기: 직접 첨부와 Files API, 인용 기능까지

대화창에서 PDF를 분석하는 법을 다뤘다면, 이번에는 API로 PDF를 다루는 방법입니다. 계약서 수백 건에서 조항을 뽑거나, 사내 매뉴얼 Q&A 봇을 만들 때 필요한 기능입니다.

PDF를 보내는 두 가지 방법

1. base64로 직접 첨부

import base64
import anthropic

client = anthropic.Anthropic()

with open("report.pdf", "rb") as f:
    pdf = base64.standard_b64encode(f.read()).decode("utf-8")

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=2048,
    messages=[{
        "role": "user",
        "content": [
            {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": pdf}},
            {"type": "text", "text": "이 보고서의 결론과 근거 수치를 표로 정리해 줘."},
        ],
    }],
)

문서 블록을 질문보다 앞에 둡니다. 긴 문서일수록 이 순서가 효과적입니다.

2. Files API로 한 번 올리고 여러 번 쓰기

같은 PDF로 여러 번 질문한다면 매번 base64로 보내는 대신 Files API에 올려 두고 file_id로 참조합니다. 업로드 방법과 SDK 사용법은 SDK 버전에 따라 다를 수 있으니 공식 Files API 문서를 확인하세요. 참조할 때는 문서 블록의 source를 {"type": "file", "file_id": "..."} 형태로 지정합니다.

인용 기능으로 근거 받기

문서 기반 Q&A에서 가장 중요한 것은 답의 근거입니다. 문서 블록에 인용 기능을 켜면, 클로드가 답변의 각 부분이 문서의 어디에서 왔는지(PDF는 페이지 위치) 함께 돌려줍니다.

{"type": "document",
 "source": {"type": "file", "file_id": file_id},
 "citations": {"enabled": True}}

응답의 텍스트 블록에 인용 정보가 붙어 오므로, 화면에 "3페이지 참고"처럼 출처를 보여 줄 수 있습니다. 사용자가 원문을 직접 확인할 수 있게 되어 환각 위험을 크게 줄입니다.

페이지와 비용 관리

PDF는 텍스트와 페이지 이미지가 함께 처리되어 같은 분량의 텍스트보다 토큰을 더 쓸 수 있습니다. 실제 문서 몇 개로 usage를 측정해 비용을 추정하세요.

주의할 점

• 개인정보·기밀 문서: 회사 정책과 데이터 처리 조건을 먼저 확인합니다.
• 스캔본 숫자: 중요한 금액·날짜는 샘플 검증 단계를 둡니다.
• 파일 관리: Files API에 올린 파일은 필요 없어지면 삭제해 관리합니다.

만들어 보며 느낀 점

PDF Q&A를 만들 때 인용 기능을 켜기 전과 후의 차이가 컸습니다. 답이 맞는지 확인하려면 원문을 처음부터 뒤져야 했는데, 인용 위치가 오니 해당 페이지만 열어 보면 됩니다. 사용자에게도 "AI가 이렇게 말했다"가 아니라 "문서 몇 쪽에 이렇게 쓰여 있다"를 보여 줄 수 있어 신뢰가 달라집니다.

기억할 것 세 가지

1. 한 번 쓰는 문서는 base64 첨부, 반복해서 쓰는 문서는 Files API로 올려 참조하세요.
2. 문서 Q&A에는 인용 기능을 켜서 답의 근거 위치를 함께 받습니다.
3. 필요한 페이지만 보내고, 캐싱·배치·구조화 출력으로 비용과 형식을 관리합니다.

더 알아보기

• PDF 지원 (Anthropic 공식 문서)
• Citations (Anthropic 공식 문서)