Guidance 시작하기

Guidance 시작하기

Guidance는 마이크로소프트 리서치에서 시작한 제약 생성(constrained generation) 라이브러리예요. LLM이 내뱉을 토큰에 "하드한 구조 제약"을 걸어서, JSON이 깨질 일이 없게 해요. 일반 프롬프트나 파인튜닝과 비교해 지연과 비용을 줄이면서 고품질 출력을 얻는 게 목표예요. 코드와 생성을 자연스럽게 섞는 방식이라, 조건문·반복문·도구 호출을 평소 파이썬처럼 쓸 수 있어요.

설치와 기본 흐름

먼저 설치해요. 백엔드별 선택 의존성은 pip install guidance[transformers]처럼 지정할 수 있어요.

pip install guidance

기본 사용법은 이렇게 생겼어요. system(), user(), assistant() 컨텍스트 매니저 안에 텍스트와 생성 호출을 +=로 이어 나가요.

from guidance import system, user, assistant, gen
from guidance.models import Transformers

phi_lm = Transformers("microsoft/Phi-4-mini-instruct")

# Model 객체는 불변이라 이건 복사본이에요
lm = phi_lm

with system():
    lm += "You are a helpful assistant"

with user():
    lm += "Hello. What is your name?"

with assistant():
    lm += gen(max_tokens=20)

print(lm)

출처: https://github.com/guidance-ai/guidance/blob/main/README.md

출력이 <|system|>...<|end|> 같은 태그를 포함한 문법 형식으로 나와요. gen()이 실제 생성을 담당하고, 이름(lm_response)을 붙이면 결과를 lm['lm_response']처럼 꺼낼 수 있어요.

제약 생성(gen)과 정규식

gen(name=..., regex=...)에 정규식을 주면 그 패턴을 벗어나지 않는 생성만 허용돼요. 예를 들어 나이를 숫자로만 받고 싶다면:

lm = phi_lm

with system():
    lm += "You are a teenager"

with user():
    lm += "How old are you?"

with assistant():
    lm += gen("lm_age", regex=r"\d+", temperature=0.8)

print(f"The language model is {lm['lm_age']} years old")

정규식 대신 완전한 문맥 자유 문법(CFG)도 지원해요. gen(regex=...)로 문법 문자열을 직접 검증할 수도 있어요.

from guidance import gen
from guidance.models import Mock

grammar = "expr=" + gen(regex=r"\d+([+*]\d+)*", name="expr")

assert grammar.match("expr=12+7*3") is not None
assert grammar.match("expr=12+*3") is None

선택(select)

고정된 몇 가지 중 하나를 고르게 할 땐 select를 써요. 모델이 다음 토큰으로 이 중 하나만 선택할 수 있어, 객관식이나 라벨링에 적합해요.

from guidance import select

lm = phi_lm

with system():
    lm += "You are a geography expert"

with user():
    lm += """What is the capital of Sweden? Answer with the correct letter.

    A) Helsinki
    B) Reykjavík
    C) Stockholm
    D) Oslo
    """

with assistant():
    lm += select(["A", "B", "C", "D"], name="model_selection")

print(f"The model selected {lm['model_selection']}")

재사용 가능한 문법 함수

@guidance 데코레이터로 재사용 가능한 함수를 만들 수 있어요. 이 함수는 문법 조각을 반환해서 다른 문법과 합성돼요.

import guidance
from guidance.models import Model

ASCII_OFFSET = ord("a")

@guidance
def zero_shot_multiple_choice(language_model: Model, question: str, choices: list[str]):
    with user():
        language_model += question + "\n"
        for i, choice in enumerate(choices):
            language_model += f"{chr(i + ASCII_OFFSET)} : {choice}\n"
    with assistant():
        language_model += select(
            [chr(i + ASCII_OFFSET) for i in range(len(choices))], name="string_choice"
        )
    return language_model

더 알아보기