구조화된 출력
지정한 JSON 스키마에 맞춰 답변을 생성합니다.
JSON 스키마를 지정하면 모델이 해당 스키마를 따르는 JSON으로 답변합니다. 텍스트에서 정보를 추출하거나 양식을 채우는 등 코드에서 답변을 파싱해야 할 때 사용합니다.
스키마 지정
OpenAI SDK는 Pydantic 모델이나 Zod 객체로 스키마를 생성하고 답변 파싱까지 처리합니다.
from pydantic import BaseModel
class Person(BaseModel):
name: str
age: int
completion = client.chat.completions.parse(
model="raon-1-mini-preview",
messages=[{"role": "user", "content": "Make up a person who lives in Seoul."}],
response_format=Person,
)
print(completion.choices[0].message.parsed)| API | 스키마 지정 위치 |
|---|---|
| Chat Completions | response_format: {"type": "json_schema", "json_schema": {...}} |
| Responses | text.format: {"type": "json_schema", "name": ..., "schema": {...}} |
| Messages | output_config: {"format": {"type": "json_schema", "schema": {...}}} |
구조화된 출력을 사용해도 모델은 먼저 추론합니다. 추론 내용은 별도 필드로 반환되며, 스키마는 답변에만 적용됩니다.
JSON 모드
Chat Completions에서 response_format: {"type": "json_object"}를 지정하면 스키마 없이 유효한 JSON 객체로 답변합니다. 필요한 키는 프롬프트에 명시하세요.
권장 사항
- 필드 이름은 의미가 명확하게 짓고, 이름만으로 의미가 모호하면
description을 추가하세요. 모델은 이 정보를 바탕으로 필드 값을 생성합니다. - 추론과 JSON 답변을 모두 생성할 수 있도록 출력 한도를 충분히 지정하세요. Chat Completions는
max_tokens또는max_completion_tokens, Messages는max_tokens, Responses는max_output_tokens를 사용합니다. - 출력 한도에 도달해 답변이 중간에 끊겼는지 확인하세요. Chat Completions는
finish_reason: "length", Messages는stop_reason: "max_tokens", Responses는status: "incomplete"와incomplete_details로 확인할 수 있습니다. 답변을 사용하기 전에 JSON을 파싱하고 스키마에 맞는지 검증하세요.