Guard 객체: LLM 호출을 감싸는 검증 창구

Guardrails를 쓸 때 가장 먼저 만나는 게 바로 Guard 객체예요. 이 객체가 LLM 호출을 감싸고, 검증을 조율하며, 호출 이력을 챙겨주는 핵심 창구 역할을 하죠. 문자열 기반 LLM 앱이라면 별다른 설정 없이도 바로 쓸 수 있고, 구조화된 출력이 필요하면 pydantic 객체를 함께 받아 다룰 수 있어요. Guardrails AI 엔진 전체를 이 객체를 통해 돌리게 돼요.

출처: The Guard - Guardrails AI 공식 문서

동작 원리

Guard는 LLM 호출을 감싸고(wrap), 설정한 기준대로 검증을 조율하며(orchestrate), 모든 호출 이력을 기록(call history)하는 역할을 맡아요. 구조 다이어그램은 공식 문서의 아키텍처 그림을 참고하면 전체 흐름이 한눈에 보여요.

두 가지 주요 흐름

Call

guard를 초기화한 뒤에는 LLM SDK를 직접 호출하듯 모델 이름과 messages를 넘겨 사용할 수 있어요. Guardrails가 LLM을 호출하고 나서 설정해 둔 가드에 맞춰 출력을 검증하고, 결과를 GuardResponse 객체로 돌려주죠. 이 객체에는 raw LLM 출력, 검증된 출력, 검증 성공 여부가 담겨요.

from guardrails import Guard
import os

# Set your openai API key here
# os.environ["OPENAI_API_KEY"] = [YOUR API KEY]

guard = Guard()

res = guard(
    model="gpt-3.5-turbo",
    messages=[{
        "role": "user",
        "content": "How do I make a cake?"
    }]
)

print(res.raw_llm_output)
print(res.validated_output)
print(res.validation_passed)

parse

LLM을 직접 호출하고 싶다면 Guard.parse를 써서 RAIL 스펙을 출력에 사후 처리(post process)로 적용할 수 있어요. num_reasks 인자를 지정하면 Guardrails가 LLM을 다시 질문(re-ask)하도록 만들 수도 있고, 0으로 두면 순수한 post-processor로만 동작하게 되죠. 반환 필드는 __call__과 동일해요.

Post-processor로 Guard.parse를 호출하는 예시예요.

import openai
from guardrails import Guard

guard = Guard()

output = openai.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{
        "role": "user",
        "content": "How do I make a cake?"
    }]
).choices[0].message.content

res = guard.parse(
    llm_output=output
)

print(res.validated_output) # Validated output

reask를 함께 쓰는 Guard.parse 호출은 이렇게 해요. num_reasks를 1로 줬고, guard.history.last.reasks로 재질문 목록을 확인할 수 있어요.

import openai
from guardrails import Guard

guard = Guard()

output = openai.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[{
        "role": "user",
        "content": "How do I make a cake?"
    }]
).choices[0].message.content

res = guard.parse(
    llm_output=output,
    model="gpt-3.5-turbo",
    num_reasks=1
)

print(res.validated_output) # Validated output
print(guard.history.last.reasks) # A list of reasks

오류 처리와 재시도

Guardrails는 LLM 호출 중 발생할 수 있는 여러 유형의 오류를 미리 감안해서 설계됐어요. 검증이 실패할 때는 문제를 파악하기 쉽도록 도움이 되는 오류를 내보내도록 되어 있고요. 오류 처리와 재시도에 대한 자세한 내용은 공식 문서의 error remediation 항목에서 더 다룰 수 있어요.

더 알아보기

Validators: 검증의 기본 단위가 되는 기준과 실패 시 조치를 다뤄요.
시작하기 (앱에 Guardrails 임베딩): 설치부터 첫 guard 구성까지 이어지는 흐름을 봐요.