Stop sequences, stop reasons, 그리고 구조 강제

네 가지 stop reason

모든 응답은 stop_reason을 포함, 왜 생성이 멈췄는지 알려줌. 프로덕션에서 볼 네 가지: end_turn(자연스럽게 완료), max_tokens(예산 소진), stop_sequence(custom stop 문자열 발화), tool_use(모델이 도구 호출하고 싶음 — 따로 처리). stop_reason='max_tokens' 응답은 truncated; end_turn과 다르게 다뤄야 해.

구조화 출력용 stop sequences

stop_sequences=["", "END"] 넘기면 그 문자열 중 아무거나 나오는 즉시 API halt. 프롬프트 디자인이랑 결합하면 구조화된 fragment 추출의 가벼운 방법. 무거운 구조는 tool use나 schema-prompted JSON 써, stop sequences X.

Tool use 없이 JSON 출력

순수 JSON 출력 위해 가장 신뢰할 패턴: 시스템 프롬프트에 정확한 JSON 스키마 알려주기, assistant 턴을 {로 prefill, defensive하게 parse. Assistant 메시지 prefill이 모델을 원하는 모양으로 bias — tool 오버헤드 없이.

원칙: response 길이가 아니라 stop_reason으로 분기. Truncated와 complete가 똑같이 보여; reason만이 어느 쪽인지 알려줘.

Code

stop_reason 분기·python

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    messages=[{"role": "user", "content": "Write 30 sentences about JSON."}],
)

match response.stop_reason:
    case "end_turn":
        save(response.content[0].text)
    case "max_tokens":
        # truncated — 예산 올리거나 요청을 chunk
        retry_with_higher_budget(response)
    case "stop_sequence":
        partial = response.content[0].text
        log.info("stopped on user-defined sequence")
    case "tool_use":
        dispatch_tool_calls(response)

Prefill로 JSON 강제·python

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=512,
    system='Respond with a single JSON object matching {"intent": str, "confidence": float}. No prose.',
    messages=[
        {"role": "user", "content": "User said: 'cancel my subscription'"},
        {"role": "assistant", "content": "{"},  # prefill — 모델이 여기서부터 이어서 생성
    ],
    stop_sequences=["}\n"],
)
import json
payload = json.loads("{" + response.content[0].text)  # prefill 다시 더해
print(payload)

Stop sequences, stop reasons, 그리고 구조 강제

네 가지 stop reason

구조화 출력용 stop sequences

Tool use 없이 JSON 출력

Code

External links

Exercise

Progress

댓글 0