Optimizers API Reference

Optimizers API Reference (옵티마이저 API 문서)

Ragas는 지표 프롬프트를 자동 최적화해서 더 나은 결과를 얻을 수 있게 해주는 옵티마이저를 제공해요. 이 페이지에서는 사용 가능한 옵티마이저 클래스와 그 설정을 다룬답니다.

출처: 문서

본문

개요

옵티마이저는 정답 점수(ground truth)가 붙은 주석 데이터셋을 사용해 지표 프롬프트를 다듬어 정확도를 높여요. 주로 세 가지 방식으로 개선해요.

지시문 최적화 (Instruction optimization): 더 나은 프롬프트 문구 찾기
데모 최적화 (Demonstration optimization): 효과적인 few-shot 예시 선택
탐색 전략 (Search strategies): 프롬프트 공간을 효율적으로 탐색

코어 클래스

Optimizer(metric: Optional[MetricWithLLM] = None, llm: Optional[BaseRagasLLM] = None)

GeneticOptimizer

프롬프트 지시문을 위한 단순한 진화 기반 옵티마이저예요.

파라미터

Parameter	Type	Default	Description
`max_steps`	`int`	50	Maximum evolution steps
`population_size`	`int`	10	Population size per generation
`mutation_rate`	`float`	0.2	Probability of mutation

사용법

from ragas.optimizers import GeneticOptimizer
from ragas.config import InstructionConfig

optimizer = GeneticOptimizer(
    max_steps=50,
    population_size=10,
)

config = InstructionConfig(llm=llm, optimizer=optimizer)
metric.optimize_prompts(dataset, config)

동작 방식

프롬프트 변형의 모집단(population)을 생성해요
각각을 주석 데이터셋으로 평가해요
성능이 좋은 후보를 선택해요
교차(crossover)와 돌연변이(mutation)로 다음 세대를 만들어요
max_steps만큼 반복해요

장점: 단순하고, 데이터가 적어도 동작해요 단점: 수렴이 느리고, 지시문만 최적화해요

DSPyOptimizer

DSPy의 MIPROv2 알고리즘을 사용하는 고급 옵티마이저예요.

파라미터

Parameter	Type	Default	Description
`num_candidates`	`int`	10	Number of prompt variants to try
`max_bootstrapped_demos`	`int`	5	Max auto-generated examples
`max_labeled_demos`	`int`	5	Max human-annotated examples
`init_temperature`	`float`	1.0	Exploration temperature (0.0-2.0)

사용법

from ragas.optimizers import DSPyOptimizer
from ragas.config import InstructionConfig

optimizer = DSPyOptimizer(
    num_candidates=10,
    max_bootstrapped_demos=5,
    max_labeled_demos=5,
)

config = InstructionConfig(llm=llm, optimizer=optimizer)
metric.optimize_prompts(dataset, config)

동작 방식

후보 프롬프트 지시문을 생성해요
데이터에서 few-shot 데모를 부트스트랩해요
인간이 주석한 최고의 예시를 골라요
데이터셋에서 모든 조합을 평가해요
가장 좋은 설정을 돌려줘요

DSPy 개념에 대해 더 알아보려면 아래를 참고해요.

Signatures - DSPy가 입출력 사양을 정의하는 방식
Optimizers - 프롬프트와 LM 가중치를 개선하는 알고리즘
Modules - LLM 프로그램을 위한 구성 블록

장점: 더 나은 결과, 지시문 + 데모를 함께 최적화해요 단점: DSPy 설치가 필요하고, LLM 호출이 더 많아요

설치

DSPy는 선택적 의존성(optional dependency)이에요.

# Using uv (recommended)
uv add "ragas[dspy]"

# Using pip
pip install "ragas[dspy]"

비용 추정

최적화 1회당 대략적인 LLM 호출 수예요.

Total calls ≈ num_candidates × 30 + max_bootstrapped_demos × 7

예시:

기본 설정 (10, 5, 5): 약 335회 호출
예산 설정 (5, 2, 3): 약 164회 호출
공격적 설정 (20, 10, 10): 약 670회 호출

Optimizer 기본 클래스

optimize(dataset: SingleMetricAnnotation, loss: Loss, config: Dict[Any, Any], run_config: Optional[RunConfig] = None, batch_size: Optional[int] = None, callbacks: Optional[Callbacks] = None, with_debugging_logs=False, raise_exceptions: bool = True) -> Dict[str, str]

설정

두 옵티마이저 모두 InstructionConfig와 함께 사용해요.

from ragas.config import InstructionConfig

config = InstructionConfig(
    llm=llm,                      # LLM for optimization
    optimizer=optimizer_instance, # Optimizer to use
)

# Use with metric
metric.optimize_prompts(dataset, config)

데이터셋 형식

옵티마이저는 정답 점수가 붙은 주석 데이터셋을 필요로 해요.

from ragas.dataset_schema import (
    PromptAnnotation,
    SampleAnnotation,
    SingleMetricAnnotation
)

# Create annotated sample
prompt_annotation = PromptAnnotation(
    prompt_input={"user_input": "...", "response": "..."},
    prompt_output={"score": 0.9},
    edited_output=None,  # Optional: corrected output
)

sample = SampleAnnotation(
    metric_input={"user_input": "...", "response": "..."},
    metric_output=0.9,  # Ground truth score
    prompts={"metric_prompt": prompt_annotation},
    is_accepted=True,  # Include in optimization
)

# Create dataset
dataset = SingleMetricAnnotation(
    name="metric_name",
    samples=[sample, ...]  # 20-50+ samples recommended
)

손실 함수 (Loss Functions)

옵티마이저는 손실 함수로 프롬프트 품질을 평가해요.

from ragas.losses import MSELoss, HuberLoss

# Mean Squared Error (default)
loss = MSELoss()

# Huber Loss (robust to outliers)
loss = HuberLoss(delta=1.0)

# Use with config
config = InstructionConfig(llm=llm, optimizer=optimizer, loss=loss)

비교

Feature	GeneticOptimizer	DSPyOptimizer
Installation	Built-in	Requires `ragas[dspy]`
Optimization Target	Instructions only	Instructions + Demos
Min Dataset Size	10+ samples	20+ samples
Typical LLM Calls	100-500	200-700
Accuracy Improvement	+5-8%	+8-12%
Best For	Quick optimization	Production metrics

같이 보기 (See Also)

DSPy Optimizer Guide - 자세한 사용법
Metric Customization - 지표 만들기
Prompt API Reference - 프롬프트 이해하기

추가 자료

DSPy 문서:

DSPy Official Documentation - DSPy 완전 가이드
MIPROv2 API Reference - MIPROv2 상세 문서
DSPy Optimizers Overview - 모든 DSPy 옵티마이저 가이드
DSPy GitHub Repository - 소스 코드와 예시

연구 논문:

Optimizing Instructions and Demonstrations for Multi-Stage Language Model Programs - MIPROv2 논문

더 알아보기 (Learn more)

API References