delta

• delta는 LLM 스트리밍 API에서 이전 청크 이후 새로 생성된 텍스트 조각(증분 변경량)
• SSE (Server-Sent Events) 방식으로 전달되는 각 이벤트 청크 안의 변경 내용 객체
• 수학의 Δ(델타) = “변화량”에서 유래한 “전체 중 이번에 추가된 부분” 의미

해당 개념이 필요한 이유

• LLM이 전체 응답을 생성 후 한 번에 반환하면 사용자가 수 초~수십 초 대기해야 함
• delta를 이용한 스트리밍으로 첫 글자부터 실시간 표시 → UX 대폭 개선
• 긴 응답이나 Tool Use에서 HTTP 타임아웃 방지

AS-IS (스트리밍 없음)

sequenceDiagram
    autonumber
    Client->>LLM API: POST /messages (stream: false)
    Note over LLM API: 전체 응답 생성 중...<br/>(5~30초 대기)
    LLM API-->>Client: 완성된 전체 응답 반환
    Note over Client: 사용자는 결과를<br/>한 번에 받음

TO-BE (delta 스트리밍)

sequenceDiagram
    autonumber
    Client->>LLM API: POST /messages (stream: true)
    LLM API-->>Client: delta: "안"
    LLM API-->>Client: delta: "녕"
    LLM API-->>Client: delta: "하세요"
    LLM API-->>Client: message_stop
    Note over Client: 글자가 생성될 때마다<br/>실시간 표시

Anthropic API의 delta 이벤트 구조

delta가 전달되는 전체 이벤트 흐름:

event: message_start          ← 1. 메시지 초기화
event: content_block_start    ← 2. 콘텐츠 블록 시작
event: content_block_delta    ← 3. delta 반복 전달 (핵심!)
event: content_block_delta
event: content_block_delta
event: content_block_stop     ← 4. 블록 종료
event: message_delta          ← 5. 메시지 레벨 변경 (stop_reason 등)
event: message_stop           ← 6. 스트림 종료

실제 delta 청크 예시:

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",
    "text": "안녕하세요"
  }
}

delta의 3가지 타입 (Anthropic 기준)

delta 타입	설명	포함 필드
text_delta	일반 텍스트 응답 조각	text
input_json_delta	Tool Use 파라미터 (partial JSON)	partial_json
thinking_delta	Extended Thinking 내용	thinking

# Python SDK에서 delta 타입별 처리
with client.messages.stream(...) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)
            elif event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)

OpenAI vs Anthropic delta 구조 비교

두 API 모두 delta 개념을 사용하지만 구조가 다름:

OpenAI (chat.completion.chunk):

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion.chunk",
  "choices": [{
    "index": 0,
    "delta": {
      "role": "assistant",   // 첫 청크에만 포함
      "content": "안녕"      // 텍스트 조각
    },
    "finish_reason": null
  }]
}

Anthropic (content_block_delta):

{
  "type": "content_block_delta",
  "index": 0,
  "delta": {
    "type": "text_delta",    // delta 타입 명시
    "text": "안녕"           // 텍스트 조각
  }
}

비교 항목	OpenAI	Anthropic
delta 위치	choices[0].delta.content	delta.text
delta 타입 구분	없음 (content/tool_calls)	type 필드로 명시
이벤트 래핑	단순 JSON chunk	SSE event + data
Tool Use delta	delta.tool_calls	input_json_delta

delta 누적으로 전체 텍스트 조합하기

delta는 조각이므로, 전체 응답을 얻으려면 직접 누적해야 함:

full_text = ""
with client.messages.stream(...) as stream:
    for text in stream.text_stream:
        full_text += text          # delta 누적
        print(text, end="", flush=True)  # 실시간 출력
 
print(f"\n최종 전체 응답: {full_text}")

참고 문서

• Anthropic Streaming Messages
• OpenAI Streaming Guide