프로덕션 환경에서의 Claude Files API: 문서 워크플로우를 위한 5가지 패턴

• Files API를 통해 요청 간에 40KB의 인라인 블롭(inline blobs)을 재사용 가능한 파일 ID(file IDs)로 교체했습니다.

• 인용 근거 제시(Citation grounding)를 통해 200회의 테스트 실행 결과 환각(hallucination) 인용이 거의 0에 가깝게 줄었습니다.

• 90KB 계약서에 대한 캐시 재사용(Cache reuse)으로 후속 질문당 11초를 절약했습니다.

• 정리 크론(Cleanup cron) 작업이 7일 후 고아 파일(orphaned files)을 삭제하여 스토리지 사용량을 일정하게 유지합니다.

저는 문서 파이프라인을 인라인 텍스트 블롭에서 Claude Files API로 전환했으며, 후속 질문에 대한 지연 시간(latency)이 14초에서 3초로 단축되었습니다. 더 큰 성과는 인용 근거 제시(citation grounding)였습니다. Claude가 계약 조항을 의역하다가 약간 틀리는 대신, 이제는 참조와 함께 정확한 문장을 인용합니다. 제가 프로덕션에서 실행 중인 5가지 패턴과 각 패턴을 유지하게 만든 수치들을 소개합니다.

패턴 1: 한 번 업로드하고 ID로 참조하기

Files API를 사용하기 전에는 문서 텍스트를 메시지 배열(messages array)에 직접 집어넣었습니다. 40KB 크기의 PDF는 매 요청마다 40KB의 인라인 콘텐츠가 되었습니다. 만약 사용자가 동일한 문서에 대해 5개의 후속 질문을 던지면, 저는 그 40KB를 5번이나 보냈습니다. 이는 낭비이며, 디버깅을 매우 힘들게 만드는 방식으로 프롬프트(prompt)를 부풀립니다.

Files API는 간단한 교체로 이 문제를 해결합니다. 파일을 한 번 업로드하여 파일 ID를 받은 다음, 콘텐츠 블록(content block)에서 해당 ID를 참조합니다. 업로드 호출은 files 엔드포인트로 보내는 멀티파트 POST(multipart POST) 방식이며, 응답으로 Anthropic 측에 저장되는 file_abc123과 같은 ID를 받게 됩니다.

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

실질적인 차이는 로그에서 나타납니다. 요청당 38KB를 보내던 흐름이 이제는 30자 길이의 ID만 보냅니다. 사용자가 하나의 문서에 대해 8개의 질문을 하는 세션의 경우, 더 이상 네트워크를 통해 전송할 필요가 없는 304KB의 중복 페이로드(payload)를 줄일 수 있습니다.

제가 초기에 겪었던 문제 중 하나는 파일 ID (file IDs)가 단일 대화가 아닌 조직 (organization) 단위로 범위가 지정된다는 점이었습니다. 즉, 한 번의 요청으로 문서를 업로드한 뒤 한 시간 뒤의 별도 요청에서 이를 참조할 수 있습니다. 이는 어떤 ID가 어떤 사용자에게 속하는지 반드시 추적해야 함을 의미하며, 그렇지 않으면 세션 간에 문서 접근 권한이 유출될 수 있습니다. 저는 이 매핑 정보를 파일 ID, 사용자 ID, 업로드 타임스탬프(timestamp), 그리고 TTL (Time To Live)을 포함하는 아주 작은 SQLite 테이블에 저장합니다. 이 테이블은 이 글의 다른 모든 내용의 중추 역할을 합니다.

만약 이를 더 큰 에이전트 (agent)에 연결한다면, 파일 ID 방식은 도구 루프 (tool loops)와 잘 맞물려 작동합니다. 문서를 다시 직렬화 (re-serializing)할 필요 없이 도구 호출 (tool calls) 간에 ID를 전달할 수 있기 때문입니다. 더 광범위한 요청 스캐폴딩 (request scaffolding)을 위해서는 이들이 어떻게 결합되는지 다루는 Claude Blueprint를 참고하는 편입니다.

패턴 2: 실제로 인용하는 인용 근거 제시 (Citation Grounding)

전체 마이그레이션을 정당화해 준 기능은 바로 인용 (citations)이었습니다. 문서를 첨부하고 문서 블록 (document block)에서 인용을 활성화하면, Claude는 자신이 사용한 정확한 텍스트 구간 (span)을 가리키는 구조화된 참조 (structured references)를 반환합니다. 계약서에 실제로 '서면 통지 시 30일 이내에 취소할 수 있다'라고 되어 있음에도 불구하고, '계약서에 언제든 취소할 수 있다고 되어 있다'라고 말하는 일은 더 이상 발생하지 않습니다.

저는 이를 문서 블록별로 활성화합니다:

content = [{
    "type": "document",
...

그러면 응답에 인용된 텍스트와 위치가 포함된 인용 객체 (citation objects)가 포함됩니다. 저는 UI에서 이를 각주 (footnotes)로 렌더링하며, 각 각주는 소스 구간 (source span)으로 다시 연결됩니다. 신뢰도의 차이는 밤과 낮만큼이나 큽니다. 사용자들이 직접 클릭해서 확인할 수 있기 때문에, "이 내용이 정말 문서에 있나요?"라고 묻는 이메일을 저에게 보내는 일이 사라졌습니다.

인용을 활성화하기 전과 후, 12개의 계약서를 대상으로 200개의 질문 테스트 세트를 실행했습니다. 근거 제시 (grounding)가 없을 때는 34개의 답변에 원문에 그대로 나타나지 않는 인용구가 포함되어 있었습니다. 인용을 활성화하자 이 수치는 2개로 줄어들었으며, 두 사례 모두 모델이 내용을 조작한 것이 아니라 두 개의 조항을 가로질러 요약한 경우였습니다. 이는 제가 가장 중요하게 생각했던 실패 모드 (failure mode)가 94% 감소했음을 의미합니다.

문제는 인용 (citations) 기능이 Claude가 인덱싱할 수 있는 실제 텍스트로 문서가 구조화되어 있을 때만 제대로 작동한다는 점입니다. 텍스트 레이어가 없는 스캔된 이미지 PDF는 유용한 정보를 전혀 제공하지 못합니다. 저는 인용할 실제 텍스트가 존재하도록 이러한 파일들을 먼저 OCR (광학 문자 인식) 단계를 거쳐 처리합니다. 디지털로 생성된 (born-digital) PDF나 일반 텍스트의 경우에는 별도의 설정 없이도 바로 작동합니다.

한 가지 더 세부적인 사항은, 각 참조가 인용된 구간 (cited span)을 포함하기 때문에 인용이 출력 토큰 (output tokens)을 추가한다는 점입니다. 인용이 많은 긴 문서의 경우, 출력 토큰 수가 약 20% 정도 증가했습니다. 실제로 검증 가능한 답변을 얻기 위한 합리적인 대가이므로, 저는 이에 놀라기보다는 미리 예산을 책정해 둡니다.

패턴 3: 혼란 없는 다중 파일 컨텍스트 (Multi-File Context)

실제 문서 작업은 단 하나의 파일만 다루는 경우가 드뭅니다. 사용자가 계약서, 수정안, 그리고 이메일 스레드를 업로드한 뒤 "수정안이 원본의 해지 조건을 변경하나요?"라고 질문하는 식입니다. 이전 방식 (Inline)에서는 모델이 준수해주길 바라며 구분자 헤더 (delimiter headers)를 붙여 텍스트를 이어 붙여야 했는데, 이는 악몽과 같았습니다.

파일 ID (file IDs)를 사용하면, 하나의 메시지에 여러 개의 문서 블록을 단순히 첨부하기만 하면 됩니다. 각 블록은 고유한 정체성을 유지하며, 인용은 정확한 소스 파일로 다시 연결됩니다. 따라서 Claude는 "원본에는 30일이라고 되어 있지만 (파일 A), 수정안에서는 이를 60일로 연장합니다 (파일 B)."라고 말할 수 있습니다. 이러한 파일 간 추론 (cross-file reasoning)이야말로 사람들이 비용을 지불하는 바로 그 기능입니다.

content = [
    {"type": "document", "source": {"type": "file", "file_id": original.id}, "citations": {"enabled": True}},
...

실무에서는 각 요청당 파일 수를 8개로 제한합니다. 그 이상의 경우에는 먼저 검색 (retrieval) 단계를 거쳐 관련 파일을 선별한 다음, 해당 파일들만 첨부하는 것이 더 효율적입니다. 40개의 문서가 포함된 사건 기록의 경우, 매번 40개를 모두 보내는 것은 느리고 비용이 많이 듭니다. 저는 저렴한 임베딩 검색 (embedding search)을 실행하여 상위 6개를 찾고, 그것들을 첨부한 뒤, 인용 기능을 통해 모델이 올바른 파일을 사용했는지 확인합니다.

숫자가 중요합니다. 두 개의 긴 계약서와 이메일 스레드가 포함된 3개 파일 요청은 약 90KB의 기반 문서 콘텐츠를 포함합니다. 이를 파일 ID (file IDs)로 전송하면 Claude가 세 파일 모두에 대한 전체 액세스 권한을 유지하면서도 요청 페이로드 (request payload)를 매우 작게 유지할 수 있습니다. 아래의 캐시 패턴 (cache pattern)과 결합하면, 동일한 데이터 세트에 대한 후속 질문의 지연 시간 (latency)은 첫 번째 요청의 아주 일부분으로 줄어듭니다.

여러 단계에 걸쳐 많은 문서를 다루는 에이전트 (agents)를 구축하고 있다면, 도구 (tools) 간의 파일 ID 전달 (file-ID handoff)이 핵심 열쇠입니다. 저는 Claude Agent SDK in Production에서 오케스트레이션 (orchestration) 측면을 심도 있게 다루었으며, 이는 여기서 설명하는 파일 패턴들과 잘 결합됩니다.

패턴 4: 요청 간 캐시 재사용 (Cache Reuse Across Requests)

이 부분에서 지연 시간 단축 효과가 복리로 나타납니다. Anthropic의 프롬프트 캐싱 (prompt caching)을 사용하면 프롬프트의 일부를 캐시 가능 (cacheable)하도록 표시할 수 있으며, 해당 접두사 (prefix)를 공유하는 후속 요청은 이를 다시 처리하는 대신 캐시에서 읽어옵니다. 캐시된 부분이 대규모 문서일 경우, 절감 효과는 극적입니다.

긴 문서를 첨부하고 캐시 제어 마커 (cache control marker)를 추가하면, 첫 번째 요청에서 Claude가 전체 내용을 처리합니다. 캐시 유효 기간 내에 동일한 문서에 대해 이루어지는 모든 후속 질문에서 문서 토큰 (document tokens)은 캐시로부터 가져옵니다. 제가 측정한 90KB 계약서의 첫 번째 요청 시간은 14초였습니다. 캐시를 사용하는 두 번째 질문은 3초 만에 응답되었습니다. 이 11초의 차이는 동작이 느릿느릿하게 느껴지는 도구와 즉각적으로 느껴지는 도구 사이의 차이입니다.

content = [{
    "type": "document",
...

캐시에는 수명이 있으므로, 사용자가 동일한 문서에 대해 빠르게 질문을 던지는 활성 세션 (active sessions)에서 가장 효과적입니다. 10분간의 대화 동안 하나의 정책 문서를 검토하는 지원 에이전트 (support agent)의 경우, 첫 번째 질문 이후의 모든 질문은 저렴하고 빠릅니다. 저는 문서 블록을 content 배열의 앞부분에 두고 질문을 마지막에 배치하는데, 이는 캐시가 공유된 접두사 (shared prefix)를 읽기 때문입니다.

알아둘 만한 시퀀싱(sequencing) 세부 사항이 있습니다. 캐시는 정확한 접두사(exact prefix)를 기준으로 일치 여부를 판단합니다. 만약 요청 사이에 문서 블록의 순서를 변경하면, 캐시 미스(cache miss)가 발생하여 다시 전체 비용을 지불해야 합니다. 그래서 저는 요청을 생성하기 전에 첨부된 파일들을 결정론적(deterministically, 파일 ID 기준)으로 정렬합니다. 이 코드 한 줄 덕분에 정렬이 우연에 맡겨졌을 때의 50%였던 캐시 히트율(cache hit rate)을 80% 이상으로 유지할 수 있었습니다.

다중 사용자 시스템의 경우, 캐시는 사용자가 아닌 콘텐츠를 기준으로 키(key)가 지정된다는 점을 기억하세요. 동일한 공개 문서에 대해 질문하는 두 사용자는 캐시 히트를 공유할 수 있으며, 이는 조용한 보너스와 같습니다. 개인 문서의 경우, 파일 ID는 업로드할 때마다 달라지므로 캐시를 통한 사용자 간 정보 유출은 발생하지 않습니다. 제 스스로의 편집증이 제기한 첫 번째 의문이었기에, 배포 전에 이 부분을 확인했습니다.

패턴 5: 스토리지가 부패하지 않도록 정리하기

업로드된 파일은 삭제하기 전까지 유지됩니다. 이는 재사용 측면에서는 훌륭하지만, 이를 무시한다면 최악의 상황이 될 수 있습니다. 고아 파일(orphaned files)이 쌓이게 되고 무엇이 어디에 저장되어 있는지 파악할 수 없게 되기 때문입니다. 첫 달에 저는 1,400개의 파일을 업로드하고 단 하나도 삭제하지 않았습니다. 이는 문제가 되기 위해 기다리고 있는 난장판과 같습니다.

저는 세 가지 작업을 수행하는 야간 크론(cron) 작업을 실행합니다. 첫째, SQLite 매핑 테이블을 읽어 TTL(Time To Live)이 지난 모든 파일 ID를 찾습니다(기본값은 7일로 설정했습니다). 둘째, 각 파일에 대해 삭제 엔드포인트(delete endpoint)를 호출합니다. 셋째, 로컬 상태와 Anthropic의 상태가 동기화되도록 해당 행을 삭제합니다.

expired = db.query("SELECT file_id FROM files WHERE uploaded < datetime('now', '-7 days')")
for row in expired:
...

또한 매주 조정(reconcile) 작업을 수행합니다. API로부터 모든 파일 목록을 가져와 제 테이블과 비교합니다. API는 알고 있지만 제 테이블에는 없는 파일은 고아 파일이며, 대개 ID가 기록되지 않은 채 중단된 업로드로 인해 발생합니다. 이 파일들도 삭제합니다. 조정 작업을 추가한 후, 제 파일 수는 계속 늘어나는 더미가 아니라 약 90개에서 120개의 활성 파일 수준으로 안정화되었습니다.

7일이라는 기본 설정값은 실제 사용 사례를 관찰하며 도출되었습니다. 대부분의 사용자는 하루 이내에 문서 작업을 마치지만, 일부는 주 중간에 후속 작업을 위해 다시 돌아옵니다. 7일은 파일을 쌓아두지 않으면서도 이러한 롱테일 (long tail) 사용자를 커버할 수 있는 기간입니다. 사용자가 다시 방문할 가능성이 있는 유료 케이스와 연결된 문서의 경우, TTL (Time To Live)을 30일로 늘리고 정리 작업에서 제외되도록 플래그 (flag)를 지정합니다. 이 플래그는 동일한 테이블 내의 하나의 불리언 (boolean) 컬럼에 저장됩니다.

제가 내재화하는 데 너무 오랜 시간이 걸렸던 교훈은 다음과 같습니다: 업로드된 파일을 다른 상태 저장 리소스 (stateful resource)와 동일하게 취급하십시오. 파일에는 라이프사이클 (lifecycle)이 있습니다. 당신이 라이프사이클을 관리하지 못하면, 라이프사이클이 당신을 지배하게 됩니다. 저는 전체 문서 스택을 Shopify에 게시하고 Buffer를 통해 공지 포스트를 예약하지만, 제가 가장 자랑스럽게 생각하는 부분은 정리 작업이 자동화되어 있어 매주 스토리지 사용량이 일정하게 유지된다는 점입니다.

핵심 요약 (Bottom Line)

Files API는 다음과 같은 다섯 가지 구체적인 방식으로 제가 문서 워크플로우를 구축하는 방식을 변화시켰습니다: 한 번 업로드하고 ID로 참조하기, 실제 인용을 통해 모든 답변의 근거를 제시하기 (grounding), 교차 문서 추론을 위해 여러 파일 첨부하기, 즉각적인 후속 작업을 위해 긴 문서 캐싱하기, 그리고 스토리지가 부패하지 않도록 정리 자동화하기. 이들의 결합된 효과로 인해 후속 작업 지연 시간 (latency)은 14초에서 3초로 줄어들었고, 허위 인용 (fabricated quotes)은 94% 감소했으며, 파일 수는 계속 상승하는 대신 안정적으로 유지되었습니다.

이 패턴들은 각각 단독으로는 어렵지 않습니다. 가치는 이 다섯 가지를 함께 실행할 때 발생하는데, 왜냐하면 서로를 강화하기 때문입니다. 파일 ID가 캐싱을 가능하게 하고, 캐싱은 다중 파일 요청을 경제적으로 만들며, 정리는 이 모든 과정을 지속 가능하게 유지합니다. 만약 인라인 텍스트 블롭 (inline text blobs) 방식으로 시작하고 있다면, 먼저 업로드 패턴을 마이그레이션하고, 그다음 인용을 계층화하고, 그다음 캐싱을 적용한 뒤, 마지막으로 정리를 도입하십시오.

전체 요청 스캐폴딩 (scaffolding)과 이러한 요소들이 더 큰 에이전트 루프 (agent loop) 내에서 어떻게 배치되는지 알고 싶다면, Claude Blueprint에서 설정 과정을 처음부터 끝까지 살펴볼 수 있습니다. 먼저 작은 버전을 구축하고, 자체적인 지연 시간을 측정하며, 문서 양이 늘어남에 따라 패턴을 추가해 나가십시오.

이 기사에는 제휴 링크가 포함되어 있습니다. 이 링크를 통해 가입하시면 귀하에게 추가 비용 부담 없이 저에게 소정의 수수료가 지급될 수 있습니다. (광고)