byteforce

CPN 한국어 자습서 · 러닝패스 2 / 4 — Building with the Claude API

API로 Claude에 접근하기

API 요청의 전체 흐름

Accessing the API · Working with the API

챗봇 앱에서 사용자가 메시지를 보내면 응답이 나타나기까지, 뒤에서는 무슨 일이 일어날까요? 이 장에서는 Anthropic API 요청의 전체 생명주기를 다섯 단계로 따라가고, Claude 내부에서 텍스트가 만들어지는 과정도 직접 눌러 가며 들여다봅니다.

전체 내레이션영상 나레이션 한국어 번역 (전체)›

Stephen Grider · Anthropic 기술 스태프

이 모듈에서는 Claude에 접근해 텍스트를 생성하는 방법을 살펴봅니다. 작동 방식을 이해할 수 있도록, Anthropic API에 보내는 요청의 전체 생명주기를 따라가 보겠습니다. Claude 내부에서 무슨 일이 벌어지는지도 잠깐 들여다봅니다.

시작을 위해, 평범하고 표준적인 챗봇 앱을 떠올려 봅시다. 웹 앱을 만들면서 브라우저에 채팅 창을 보여 주고 싶다고 가정하겠습니다. 사용자가 메시지를 입력하고 전송을 누르면, 응답이 그냥 마법처럼 나타나기를 기대합니다. 앞서 말했듯, 이 텍스트가 생성되어 화면에 표시되기까지 뒤에서 무슨 일이 일어나는지 살펴보려 합니다. 이를 다섯 단계로 나누겠습니다. 다이어그램 위쪽에 정리해 두었고, 한 단계씩 따라가 봅니다.

사용자가 텍스트를 입력하고 전송을 누르면, 그 텍스트는 개발자인 여러분이 구현한 서버로 보내집니다. 이 단계를 짚는 이유는 한 가지를 분명히 하기 위해서입니다. Anthropic API를 웹이나 모바일 앱에서 직접 호출하면 안 됩니다. API에 요청할 때는 반드시 비밀 API 키를 포함해야 하는데, 이 키를 비밀로 지키는 가장 좋은 방법은 클라이언트 앱에 절대 넣지 않고, 여러분이 구현한 서버를 통해서만 요청하는 것입니다.

2단계로 갑니다. 서버가 클라이언트로부터 요청을 받으면, 서버는 Anthropic API로 직접 요청을 보냅니다. 보통은 Anthropic이 공개한 SDK 중 하나를 통해 요청합니다. Python, TypeScript, JavaScript, Go, Ruby용 공식 SDK가 있습니다. 원하지 않으면 SDK를 쓰지 않아도 됩니다. 일반 HTTP 요청을 보내도 됩니다. 이 요청에는 몇 가지 데이터를 함께 전달해야 합니다. 특히 API 키, 실행할 모델 이름, 사용자가 입력한 텍스트가 담긴 messages 리스트, 그리고 Claude가 생성할 텍스트의 길이를 제한하는 max tokens 값이 필요합니다.

다음은 Anthropic API입니다. 실제로 텍스트가 생성되는 곳입니다. 여기서 언어 모델 내부의 텍스트 생성 과정을 조금 자세히 들여다봅니다. 이 과정은 복잡하므로 단순화한 고수준 개요로 설명하겠습니다. 텍스트 생성 과정을 네 단계로 나눠 보겠습니다.

첫 단계에서는 사용자 입력을 더 작은 문자열로 쪼갭니다. 이 텍스트 조각 하나하나를 토큰이라고 부릅니다. 토큰은 단어 전체일 수도, 단어의 일부일 수도, 심지어 공백이나 기호일 수도 있습니다. 설명을 단순하게 하기 위해, 단어 하나가 토큰 하나를 이룬다고 가정하겠습니다. 그다음 각 토큰은 임베딩으로 변환됩니다. 임베딩은 긴 숫자 리스트로, 어떤 단어를 숫자로 정의한 것이라고 생각하면 됩니다. 문자 언어의 흥미로운 점은, 한 단어가 여러 의미를 가질 수 있고 문장 속 위치와 주변 단어들이 있어야 비로소 그 의미가 하나로 좁혀진다는 것입니다. 예를 들어 “quantum”은 정의가 여럿인 단어라, 이 단어만 봐서는 주변 단어를 보기 전까지 무슨 뜻인지 정확히 알 수 없습니다. 마찬가지로 각 임베딩은 그 단어의 모든 가능한 의미를 담고 있다고 볼 수 있습니다. 각 임베딩을 하나의 정확한 정의로 좁히기 위해 컨텍스트화라는 과정을 거칩니다.

컨텍스트화에서는 각 임베딩이 주변 임베딩에 따라 조정됩니다. 이 과정은 이웃 단어들을 고려했을 때 가장 잘 맞는 의미를 부각시킵니다. 마지막 단계는 생성으로, 실제로 텍스트가 쓰이는 곳입니다. 이 시점이면 각 임베딩은 이웃으로부터 엄청난 양의 정보를 흡수한 상태입니다. 최종 처리된 임베딩은 출력 레이어로 전달되어, 가능한 다음 단어마다 확률을 만들어 냅니다. 모델은 확률이 가장 높은 단어를 자동으로 고르지 않습니다. 대신 확률과 무작위성을 섞어 단어를 고르는데, 이렇게 하면 더 자연스럽고 다양한 응답이 만들어집니다. 선택된 단어는 임베딩 리스트 끝에 더해지고, 전체 과정이 처음부터 다시 반복됩니다.

각 출력 토큰을 생성한 뒤, 모델은 잠시 멈춰 텍스트 생성을 끝낼지 스스로 몇 가지를 점검합니다. 먼저 지금까지 생성한 토큰 수를 세어, 입력 요청에 함께 들어온 max tokens 값보다 큰지 확인합니다. 이 max tokens 값은 모델이 생성할 토큰의 총수를 제한합니다. 또한 모델이 생성할 수 있는 특별한 end-of-sequence 토큰이 있습니다. 이것은 일반적인 단어가 아니라, 모델이 스스로 자연스러운 끝에 도달했으니 멈춰야 한다고 알리는 특별한 신호입니다.

생성이 끝나면 API는 서버로 응답을 보냅니다. 응답에는 생성된 텍스트가 담긴 message와 함께 usage, stop reason이 들어 있습니다. usage는 모델에 넣은 토큰 수와 생성된 토큰 수를 센 값입니다. stop reason은 모델이 왜 생성을 멈췄는지 — 자연스러운 end-of-sequence 토큰에 도달했는지, 아니면 할당된 토큰 수를 초과했는지 — 정확히 알려 줍니다. 서버가 이 응답을 받으면, 생성된 텍스트를 웹이나 모바일 앱으로 보내 화면에 표시합니다. 이것이 전체 흐름입니다.

이 영상에서는 많은 주제를 다뤘습니다. 지금 당장 이걸 외울 필요는 없습니다. 목표는 API로 Claude에 접근할 때 쓰는 공통 용어에 익숙해지기 시작하는 것입니다.

이 장에서 배우는 것What you'll learn

약 5분
1

챗봇 요청의 5단계 흐름 (서버 → API → 처리 → 응답)

2

왜 API 키를 서버에 두어야 하는지

3

API 요청에 꼭 필요한 필드 (API Key·Model·Messages·Max Tokens)

4

Claude 내부 처리 4단계 (토큰화 → 임베딩 → 컨텍스트화 → 생성)

5

응답 구조와 생성이 멈추는 조건

먼저, 이 장에 나오는 용어
토큰 (token)
텍스트를 잘게 나눈 조각입니다. 단어 전체나 일부, 공백·기호일 수 있습니다.
임베딩 (embedding)
토큰을 의미를 담아 표현한 긴 숫자 리스트입니다.
컨텍스트화 (contextualization)
주변 단어를 참고해 각 단어의 의미를 문맥에 맞게 좁히는 과정입니다.
max tokens
모델이 생성할 토큰 수의 상한입니다. 이 한도에 닿으면 생성을 멈춥니다.
end-of-sequence 토큰 (EOS)
모델이 생성을 자연스럽게 끝낼 때 내보내는 특별한 신호입니다.
stop reason
응답에 담기는, 모델이 생성을 멈춘 이유입니다.

5단계 요청 흐름

The five-step request flow

사용자가 메시지를 보내면 응답이 ‘마법처럼’ 나타나는 것 같지만, 그 뒤에는 다섯 단계의 흐름이 있습니다. 먼저 챗봇이 어떻게 동작하는지 직접 확인해 보세요.

챗봇 예시 · [전송]을 눌러 보세요

이 응답이 나오기까지 거치는 다섯 단계는 다음과 같습니다.

1서버로 요청
2Anthropic API로 요청
3모델 처리
4서버로 응답
5클라이언트로 응답
왜 서버가 필요한가
  • API에 요청할 때는 반드시 비밀 API 키가 필요합니다.
  • 이 키를 클라이언트(웹 · 모바일 앱) 코드에 넣으면, 누구나 키를 추출해 무단으로 요청할 수 있습니다.
  • 그래서 앱은 여러분의 서버로 보내고, 서버가 안전하게 보관한 키로 Anthropic API에 요청합니다. Claude API를 클라이언트에서 직접 호출하면 안 됩니다.

API 요청에 담기는 것

Making a request

서버가 Anthropic API에 요청할 때는 다음 필드를 함께 보냅니다.

필드역할
API KeyAnthropic에 보내는 요청을 인증합니다.
Model사용할 모델의 이름입니다. (예: claude-sonnet-4-6)
Messages사용자가 입력한 텍스트가 담긴 메시지 리스트입니다.
Max TokensClaude가 생성할 토큰 수의 상한입니다.
SDK

Anthropic은 Python · TypeScript · JavaScript · Go · Ruby용 공식 SDK를 제공합니다. SDK 없이 일반 HTTP 요청을 보내도 됩니다.

요청 보내기 · Python SDK
from anthropic import Anthropic

client = Anthropic()   # ANTHROPIC_API_KEY 환경 변수에서 키를 읽습니다

response = client.messages.create(
    model="claude-sonnet-4-6",     # 실행할 모델
    max_tokens=1024,                # 생성할 토큰 수 상한
    messages=[                      # 사용자 입력이 담긴 메시지 리스트
        {"role": "user", "content": "양자 컴퓨팅이 뭐야?"}
    ],
)

print(response.content[0].text)     # 생성된 텍스트 (Message)
print(response.usage)               # 입력/출력 토큰 수 (Usage)
print(response.stop_reason)         # 멈춘 이유 (Stop Reason)

Claude 내부에서 일어나는 일

Inside the model

요청을 받은 Anthropic API는 텍스트를 네 단계로 생성합니다. 실제 과정은 복잡하므로 단순화한 개요로 봅니다. 아래에서 단계를 눌러 가며 “What is quantum computing?”이 어떻게 처리되는지 따라가 보세요.

텍스트 생성 과정 · 단계를 눌러 따라가기

입력: What is quantum computing?

Whatisquantumcomputing?

생성이 멈추는 시점

When generation stops

모델은 토큰을 하나씩 생성하면서, 매번 멈출지 점검합니다. 멈추는 조건은 세 가지입니다.

생성을 멈추는 시점

생성된 출력 토큰

Quantummechanicsisaformofcomputing.EOS

각 토큰을 생성한 뒤, 모델은 멈출지 점검합니다

max tokens 도달?요청의 상한에 닿으면 멈춥니다.
stop sequence?미리 정해 둔 문구를 만나면 멈춥니다.
EOS 토큰?자연스러운 끝 신호를 내보내며 멈춥니다.

응답 구조

The API response

생성이 끝나면 API는 서버로 응답을 보냅니다. 응답에는 다음이 담깁니다.

필드내용
Message생성된 텍스트가 담깁니다.
Usage입력 토큰 수와 출력(생성) 토큰 수입니다.
Stop Reason모델이 생성을 멈춘 이유입니다. (max tokens 초과, 자연스러운 끝 등)
정리

서버는 이 응답에서 생성된 텍스트(Message)를 꺼내 앱으로 보내 화면에 표시합니다. Usage로 토큰 사용량을, Stop Reason으로 멈춘 이유를 확인할 수 있습니다.

스스로 점검

Check yourself

정답을 먼저 떠올려 본 뒤 골라 보세요. 맞히면 설명이 나옵니다.

Q1Anthropic API를 웹 · 모바일 앱에서 직접 호출하면 안 되는 이유는?

Q2요청의 max tokens 값이 하는 일은?

Q3응답의 stop reason이 알려 주는 것은?