Mirascope 구조화 출력 — 타입 안전한 응답

Mirascope 구조화 출력

기본적으로 LLM은 자유 형식 텍스트를 출력해요. Mirascope는 format 파라미터로 정의된 타입에 맞는 구조화 데이터로 응답을 제한하고, response.parse()로 결과를 얻어요.

기본 사용

from mirascope import llm

@llm.call("openai/gpt-4o-mini", format=dict[str, str])
def recommend_books(genres: list[str]):
    return f"Recommend a book for each of the following genres: {', '.join(genres)}"

recommendations = recommend_books(["scifi", "fantasy", "romantasy"]).parse()
print(recommendations)

지원 타입은 str, int, float, bool, list, dict, Enum, Literal, 그리고 Pydantic BaseModel 클래스예요.

Pydantic 모델

복잡한 구조는 Pydantic BaseModel을 정의해요.

from pydantic import BaseModel
from mirascope import llm

class Book(BaseModel):
    title: str
    author: str

@llm.call("openai/gpt-4o-mini", format=Book)
def recommend_book(genre: str):
    return f"Recommend a {genre} book."

book = recommend_book("fantasy").parse()
print(f"{book.title} by {book.author}")

list[Book], dict[str, Book] 같은 제네릭 컬렉션도 BaseModel과 함께 동작해요.

파싱 오류 처리

LLM이 유효하지 않은 데이터를 반환하면 parse()가 llm.ParseError를 던져요.

try:
    book = response.parse()
except llm.ParseError as e:
    print(f"Invalid response: {e}")

response.validate()는 검증 실패 시 자동 재시도를 해요. (parsed_value, response) 튜플을 반환하고, max_retries로 재시도 횟수를 조절할 수 있어요(기본값 1).

book, response = response.validate(max_retries=3)

포맷팅 모드

여러 전략으로 구조화 출력을 추출할 수 있는데, 기본값은 프로바이더가 strict를 지원하면 strict, 아니면 tool 모드예요. llm.format()으로 강제할 수 있어요.

from mirascope import llm

@llm.call("openai/gpt-5-mini", format=llm.format(Book, mode="strict"))
def recommend_book(genre: str):
    return f"Recommend a {genre} book."

더 알아보기

• Structured Output
• Streaming
• Reliability