CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API
Claude의 기능
Citations
PDF에서 답을 얻어도, 사용자는 Claude가 기억으로 말하는지 실제 출처가 있는지 알 수 없습니다. Citations를 켜면 Claude가 외부 문서의 특정 부분을 직접 인용합니다 — document 블록에 title과 citations:{enabled:true}만 추가하면 됩니다. 응답의 일부 text 블록에 citation location(어느 문서·어느 페이지)이 붙어, 인용 팝업 UI로 출처를 확인할 수 있습니다. PDF뿐 아니라 평문 텍스트도 됩니다.
Stephen Grider · Anthropic 기술 스태프
앞에서 다룬 PDF의 맨 아래 페이지로 내려가면, "지구의 대기와 바다는 화산 활동과 가스 방출(outgassing)로 형성됐다"는 문장이 보입니다. 간단한 실습으로, Claude에게 "지구의 대기와 바다는 어떻게 형성됐어?"라고 물어봅니다. 첫 문장에서 "화산 활동과 가스 방출로 형성됐다"는 아주 적절한 답이 나옵니다.
그런데 사용자 입장에서 이 답을 받는다고 상상해 보세요. 생성된 텍스트만 보면, 사용자는 Claude가 그냥 기억에서 말하는 것이라 생각할 수 있고, 우리가 사실은 어떤 출처를 인용하고 있다는 걸 알지 못합니다. 그래서 정보가 어디서 왔는지 알려 주는 방법이 있으면 좋습니다. 다행히 Claude에는 Citations라는 기능이 있습니다.
켜는 법은 간단합니다. 메시지에 넣는 첫 블록에서, source 필드 바로 다음에 title을 earth.pdf로 추가하고, citations 필드에 enabled: true 딕셔너리를 넣습니다. 다시 요청을 보내면 응답이 이전보다 훨씬 복잡해집니다. content가 여러 text 블록의 리스트인데, 그중 일부 블록에 citations 리스트가 있고 그 안에 citation page location이 들어 있습니다.
citation page location은 Claude가 어떤 사실을 어디서 가져왔는지 정확히 알려 주는 구조입니다. 우리 경우엔 cited_text, document_index, document_title, start_page, end_page를 받습니다. cited_text는 출처 문서(earth.pdf)에서 Claude의 진술을 뒷받침하는 실제 텍스트입니다. document_index와 document_title은 어느 문서인지, start_page와 end_page는 그 문서 어디(몇 페이지)에서 나왔는지 알려 줍니다.
이 인용을 주는 진짜 의도는, Claude의 답으로 인용 팝업 UI를 만들 수 있게 하려는 것입니다. 마커 위에 마우스를 올리면 잘 정리된 팝업이 떠서, 이 문장이 earth.pdf의 4~5페이지에 있는 특정 텍스트에 근거한다는 것을 보여 줍니다. 사용자는 그 출처를 직접 찾아가 Claude가 정보를 올바르게 해석했는지 확인할 수 있습니다.
Citations는 PDF에만 쓰는 게 아닙니다. 평문 텍스트에도 됩니다. 예를 들어 PDF에서 본문을 복사해 article_text 변수에 넣어 두고, 블록의 type을 text, media_type을 text/plain, data를 article_text로 바꿉니다. title은 "Earth Article"쯤으로 두고 citations enabled true는 그대로 둡니다. 다시 실행하면 citation page location 대신 citation char location이 나옵니다 — 큰 텍스트 블록 안에서의 위치를 알려 줍니다. 사용자가 Claude의 응답이 어떻게 만들어졌는지 확인하는 게 중요할 때면 언제든 Citations를 쓰길 권합니다.
이 장에서 배우는 것What you'll learn
약 5분Citations = 응답을 출처 문서의 특정 부분으로 되짚기
켜는 법: document 블록에 title + citations:{enabled:true}
응답의 text 블록에 citation location이 붙음
PDF → citation_page_location (start_page·end_page)
평문 → citation_char_location (텍스트 내 위치)
인용 팝업 UI로 사용자가 출처를 직접 확인
title과 함께 추가합니다.cited_text·document_index·document_title·start_page·end_page.earth.pdf 맨 아래엔 "지구의 대기와 바다는 화산 활동과 가스 방출로 형성됐다"는 문장이 있습니다. Claude에게 물으면 맞는 답이 나오지만 — 사용자는 그게 기억인지 인용인지 알 수 없습니다.
# 그냥 물어보면 — 맞는 답은 오지만 출처는 안 보임 add_user_message(messages, [ {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": file_bytes}}, {"type": "text", "text": "지구의 대기와 바다는 어떻게 형성됐어?"}, ]) chat(messages)
source 다음에 title과 citations:{enabled:true}를 더하면 끝입니다. 응답이 복잡해지면서, 일부 text 블록에 citation page location이 붙습니다 — cited_text·document_index·document_title·start_page·end_page.
# Citations 켜기 — source 다음에 title + citations 추가 add_user_message(messages, [ {"type": "document", "source": {"type": "base64", "media_type": "application/pdf", "data": file_bytes}, "title": "earth.pdf", "citations": {"enabled": True}}, {"type": "text", "text": "지구의 대기와 바다는 어떻게 형성됐어?"}, ]) chat(messages)
# 응답 content = text 블록들의 리스트. # 일부 블록에 citations 가 붙어 옴. [ TextBlock(text="지구의 대기와 바다는 화산 활동과 가스 방출(outgassing)로 형성되었습니다.", citations=[{ "type": "citation_page_location", "cited_text": "Earth's atmosphere and oceans were formed by volcanic activity and outgassing.", "document_index": 0, "document_title": "earth.pdf", "start_page_number": 4, "end_page_number": 5, }]), ... ]
이 위치 정보로 인용 팝업 UI를 만듭니다. 답변 문장 옆 마커에 호버하면, 그 진술이 earth.pdf의 4~5페이지 어느 텍스트에 근거하는지 카드가 뜹니다. 직접 만져 보세요.
아래 답변의 1·2 마커 위에 마우스를 올리거나 누르면, 그 문장이 어느 문서·몇 페이지에서 왔는지 카드가 뜹니다.
cited_text ▸ Earth's atmosphere and oceans were formed by volcanic activity and outgassing.
document_index 0start_page 4end_page 5 초기 지구의 표면은 이 과정을 통해 점차 지금의 모습을 갖추었습니다.인용 · citation_page_locationp.4earth.pdfcited_text ▸ The planet's early surface was shaped over geological time.
document_index 0start_page 4end_page 4각 마커는 응답 속 citation location 객체 하나에 대응합니다. 사용자는 카드로 출처를 확인하고, 실제 문서로 찾아가 Claude의 해석이 맞는지 검증할 수 있습니다.
사용자는 출처를 직접 확인하고 실제 문서로 찾아가, Claude가 정보를 올바르게 해석했는지 검증할 수 있습니다.
Citations는 PDF 전용이 아닙니다. source의 type을 text, media_type을 text/plain, data를 본문 문자열로 바꾸면 평문도 인용합니다 — 이때 응답은 citation_char_location(텍스트 내 위치)을 줍니다.
# 평문 텍스트 인용 — type 을 text 로 바꾸면 됨 add_user_message(messages, [ {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": article_text}, "title": "Earth Article", "citations": {"enabled": True}}, {"type": "text", "text": "지구의 대기와 바다는 어떻게 형성됐어?"}, ]) # → 응답은 citation_char_location (텍스트 내 위치)
title + citations:{enabled:true}.citation_page_location(cited_text·start_page·end_page), 평문 → citation_char_location.Q1document 블록에서 인용을 켜려면 무엇을 추가하나요?
source 다음에 title과 citations:{enabled:true}를 더하면 인용이 켜집니다.
Q2PDF 인용 응답에 들어 있는 위치 정보는?
PDF는 page location, 평문 텍스트는 char location을 줍니다. cited_text는 실제 인용된 원문입니다.
Q3평문 텍스트로 인용할 때 응답이 주는 위치는?
평문은 페이지가 없으니, 큰 텍스트 블록 안에서의 문자 위치(char location)를 줍니다.
인용으로 답의 출처까지 추적할 수 있게 됐습니다. 다음 장부터는 속도와 비용을 잡는 프롬프트 캐싱 3부작이 시작됩니다 — 먼저 캐싱이 무엇이고 왜 빨라지는지부터. → 프롬프트 캐싱
전 코스는 계속 무료입니다. 등록하면 이 코스의 남은 76개 레슨을 끝까지 읽을 수 있습니다.
이미 등록하셨다면 그때 쓰신 이메일을 넣어 주세요.