강의 계획 레슨 250개 중 138번째 · 구조화된 출력과 함수/도구 호출
구조화된 출력과 함수/도구 호출

제약된 / 스키마로 강제되는 출력

지난 레슨들에서 모델 JSON을 손으로 검증했어요. 현대의 실무는 한 단계 더 일찍 가요: 모델이 애초에 잘못된 JSON을 내지 못하게 막아요. 이것이 제약된 디코딩(구조화된 출력이라고도 해요)이에요. API에 스키마를 건네면, 디코더는 출력을 그 스키마에 맞게 지키는 토큰만 뽑을 수 있어요. 모델은 말 그대로 빠진 필드나 타입이 틀린 값을 만들 수 없어요.

OpenAI식 API에서는 JSON Schema와 strict: true가 있는 response_format을 넘겨요(보여 주기만 해요 -> 여기서는 어떤 모델도 부르지 않아요):

resp = client.chat.completions.create(
    model="...",
    messages=[...],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "person",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
                "required": ["name", "age"],
            },
        },
    },
)

이 강좌의 나머지는 Anthropic을 부르는데, 보장된 JSON 응답을 위한 output_config와 스키마에 완벽한 도구 입력을 위한 strict 도구 사용으로 같은 보장을 줘요:

resp = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[...],
    output_config={"format": {
        "type": "json_schema",
        "schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "age": {"type": "integer"}},
            "required": ["name", "age"],
        },
    }},
)

어느 쪽이든 제공자가 제약을 해요. 하지만 제약된 디코딩도 내 업무 규칙(나이가 그럴듯한가? 통화가 지원하는 것인가?)은 확인할 수 없고, 모든 모델이나 게이트웨이가 그것을 지원하는 것도 아니에요. 그러니 어쨌든 내 쪽에서 검증해요. 지금 만드는 게 그 검증기예요.

Python 쪽에서 그 모양을 선언하고 검증하는 사실상의 표준은 Pydantic이에요. 모델 클래스를 쓰면 라이브러리가 해석하고, 강제 변환하고, 검증해 줘요:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

record = Person.model_validate_json(text)   # raises if it does not fit

Pydantic은 이 브라우저 속 샌드박스에서 쓸 수 없으니, 표준 라이브러리로 같은 생각을 손수 만들어요. 그게 바로 이 라이브러리들이 속에서 하는 일이고, 규칙을 얼버무릴 수 없게 해 줘요. validate_against_schema(obj, schema)를 써요.

schema는 dict예요. 각 값은 타입 이름 문자열("int", "float", "str", "bool", "list", "dict")이거나 {"type": "int", "default": 0} 같은 작은 명세 dict예요. 함수는 결과 dict {"ok": bool, "value": dict, "errors": list}를 돌려줘요:

  • obj가 dict가 아니면, 뿌리 오류 하나와 빈 value로 ok=False를 돌려줘요.
  • 각 필드에 대해: 빠졌고 명세에 "default"가 있으면 기본값을 채워요(강제 변환/기본값 단계). 기본값 없이 빠졌으면 오류를 기록해요.
  • 있으면 타입을 확인해요. 어긋나면 필드 이름을 댄 오류를 기록해요.
  • float가 필요하면 평범한 int를 float로 강제 변환해요(손실 없고 안전해요). 하지만 그 밖의 것은 강제 변환하지 마세요.
  • 오류가 하나라도 있으면 모은 errors와 빈 value로 ok=False를, 아니면 검증된 value로 ok=True를 돌려줘요.

bool이 int인 함정. Python에서 bool은 int의 하위 클래스라서 isinstance(True, int)는 True이고 JSON true는 Python True로 디코딩돼요. 순진한 타입 확인은 "age": true가 int 필드를 유유히 지나가게 할 거예요. int나 float가 필요한 곳에서는 bool을 명시적으로 거부하세요:

if expected is int and isinstance(value, bool):
    errors.append(field + ": expected int, got bool")

잘 만들어진 서로 다른 두 페이로드가 둘 다 통과하고, 빠진 필드와 틀린 타입이 각각 errors에 들어가고, 기본값이 채워지고, int가 float로 강제 변환되고, 숫자가 필요한 곳에서 슬쩍 들어온 bool이 거부되도록 만드세요.

내 차례

{"ok", "value", "errors"}를 돌려주는 validate_against_schema(obj, schema)를 쓰세요. schema는 각 필드를 타입 이름 문자열("int"/"float"/"str"/"bool"/"list"/"dict")이나 명세 dict {"type": ..., "default": ...}에 대응시켜요. dict가 아닌 obj는 거부하고, (기본값 없이) 빠지거나 타입이 틀린 필드마다 오류를 기록하고, 기본값이 주어지면 채우고, 평범한 int는 float로 강제 변환하고, int나 float가 필요한 곳의 bool은 거부하세요(bool이 int인 함정). 오류가 없을 때만 검증된 value와 함께 ok=True를 돌려주세요.

이 레슨에서 문제를 발견했나요? 알려 주세요 · 이 레슨에 대해 묻기

이 연습은 곧 열려요

앞의 레슨을 마치면 이 레슨이 열려요. 강좌 전체가 무료이고 계정도 필요 없으며, 이 레슨은 지금 바로 읽을 수 있어요.