dspy.experimental.ReAnchor

이 페이지는 DSPy의 실험적 기능인 ReAnchor를 다뤄요. 결정 타입(Noul, Score, Choice)을 쓰는 프로그램에서 임계값이나 구간 같은 숫자 설정을 사람이 손으로 조정하는 대신, 메트릭에 맞춰 자동으로 맞추는 보정기(calibrator)예요. 이름 그대로 "닻을 다시 내린다(Re-Anchor)"는 뜻처럼, 값이 어디에 놓이는 게 좋을지를 데이터로 다시 정해 주죠.

출처: 문서

본문

!!! warning "Experimental API" ReAnchor는 실험적이며 경고 없이 바뀔 수 있어요.

ReAnchor는 프로그램 안의 숫자 결정 설정을 여러분의 메트릭에 맞춰요. 이 설정은 각 예측기(predictor)의 fields에 있는 threshold, cuts, weights 항목들이에요. 자세한 내용은 Decision types and System One models에 설명되어 있어요. ReAnchor는 어떤 지시문, 설명, 데모도 바꾸지 않아요.

ReAnchor에 메트릭, 프로그램, 훈련 예시(training examples)를 주면 돼요. 프로그램은 단일 dspy.Predict이거나 결정 출력이 있는 예측기들을 담은 어떤 모듈이든 가능해요. 결정 출력은 Noul, Score, Choice 출력이거나 네이티브 bool 또는 Literal 출력이에요. RLM은 결정 출력을 지원하지 않으므로, ReAnchor도 RLM 프로그램을 지원하지 않아요.

import dspy
from dspy.experimental import ReAnchor, TypeSafe


class Match(dspy.Signature):
    """Decide whether two product listings describe the same item."""

    pair: str = dspy.InputField(desc="Two listings.")
    match: bool = dspy.OutputField(desc="Are they the same item?")


def metric(example, prediction, trace=None):
    return float(prediction.match == example.match)


dspy.configure(lm=TypeSafe("jev-latest"))
optimizer = ReAnchor(metric)
tuned = optimizer.compile(dspy.Predict(Match), trainset=trainset, valset=valset)
print(optimizer.report)

ReAnchor가 맞추는 것

ReAnchor는 각 출력의 숫자 설정을 프로그램 전체 메트릭에 대고 탐색해요. 새 설정은 훈련 점수를 개선하고 폴드 검증(fold check)을 통과해야 해요.

호환되는 모든 출력에 대해 ReAnchor는 원래 구성과 점수를 저장하고, 확률 기반 실행을 활성화하며, 숫자 설정을 맞춰요. 그다음 맞춘 동작을 폴드 검증으로 원래 동작과 비교해요. 거부되면 정확히 원래 구성을 복원해요. 원래 없던 항목을 제거하는 것도 포함해서요. 어댑터가 각 호출에 사용되는 백엔드를 처리하며, 보정은 그 백엔드를 검사하지 않아요.

각 출력을 맞추기 전에, ReAnchor는 프로그램을 실행하고 매 호출에서 그 출력의 확률을 기록해요. 이웃한 두 P(True) 값 사이의 어느 임계값이든 같은 결정을 내리므로, ReAnchor는 그 사이의 각 간격 중간점(midpoint)을 시도해요. 예를 들어 모델이 P(True)로 0.98과 1.0만 반환하면, ReAnchor는 0.5와 0.99를 시도해요.

Boolean 출력의 경우, ReAnchor는 관찰된 P(True) 값들 사이의 각 중간점을 시도해요.
Score 출력의 경우, 수준은 평균 수준 인덱스에 달려 있어요. ReAnchor는 관찰된 평균 인덱스 사이의 중간점에서 각 cut을 시도하고, cuts의 순서를 유지해요. cuts는 .level을 선택하며 .value를 바꾸지 않아요.
Choice 출력의 경우, ReAnchor는 한 번에 하나의 옵션 배수를 이동해요. 그 옵션의 선택이 어떤 호출에서 뒤집히는 지점 사이에 있는 배수들을 시도해요.

현재 설정은 다른 설정이 엄격히 더 좋은 점수를 내고 폴드 검증을 통과할 때까지 유지돼요. 검증은 훈련 예시를 최대 다섯 부분으로 나눠요. 각 부분에 대해 ReAnchor는 나머지 부분으로 설정을 고르고, 그 선택을 배제된 부분(held-out part)에서 채점해요. 새 설정은 결합된 배제 점수가 현재 설정보다 좋을 때만 유지돼요. 이 검증은 데이터셋의 작은 일부에만 국한된 이득은 억제하지만, 여러 폴드에서 반복되면 받아들일 수 있어요. 점수가 같은 개선 후보들 중 ReAnchor는 가장 넓은 간격을 선호해요. 그쪽이 양쪽에 가장 많은 여지를 남기기 때문이에요. 각 탐색 단계는 최대 40개의 간격 중간점을 시도하며, 관찰된 값들을 통해 고르게 분포된 설정으로 큰 목록을 얇게 만들어요. Boolean 출력의 경우 P(True)=0이 관찰되면 임계값 0도 시도해요. 그 경계가 그 답들을 True로 분류하는 유일한 방법이기 때문이에요. 두 관찰 확률이 인접한 부동소수점이면 임계값으로 위쪽 값을 시도해요. p >= threshold가 중간점 없이 둘을 분리하기 때문이에요.

요청과 캐시

숫자 설정은 요청의 일부가 아니에요. 반복되는 동일 요청은 캐시된 답을 재사용해요. 합성(composed) 프로그램에서 상류 결정을 바꾸면 하류 입력이나 어떤 예측기가 실행되는지가 바뀌어 새 요청과 추가 백엔드 호출이 생길 수 있어요. 네이티브 출력 승격(native-output promotion)도 요청을 바꿔요.

compile은 기본적으로 캐싱을 요구해서 동일한 백엔드 호출이 반복되지 않게 해요. 고정된 요청 수를 보장하지는 않아요. 이 검사 없이 실행하려면 require_cache=False를 전달해요. 캐시 검사는 정적으로 바인딩되거나 전역으로 구성된 클라이언트를 검사해요. forward() 안에서 클라이언트를 선택하는 프로그램이라면 검사를 비활성화하고 해당 클라이언트에서 캐싱을 직접 관리하세요.

생성형 LM에서의 네이티브 출력

생성형 LM은 네이티브 bool 또는 Literal 출력에 단일 값으로 답해요. 확률을 보고하지 않으므로 ReAnchor는 맞출 것이 없어요. 출력이 예측기의 fields에 항목을 가지면, Predict는 LM에 확률을 대신 요청해요. 그러면 Predict가 임계값이나 가중치를 적용해 값을 고르고, 출력은 여전히 bool이나 Literal 멤버를 반환해요.

확률이 있는 첫 번째 패스는 요청이 바뀌므로 새 요청을 보내요. 맞춘 동작이 거부되면 원래 구성을 복원하며, 구성되지 않은 네이티브 필드를 직접 생성으로 되돌려요.

dspy.configure(lm=dspy.LM("your-provider/your-model"))  # Use your model's identifier.
tuned = ReAnchor(metric).compile(dspy.Predict(Match), trainset=trainset)

Jev 같은 System One 모델은 항상 확률을 반환해요. 확률 실행을 활성화해도 요청은 바뀌지 않고, 필드를 복원하면 직접 생성이 아니라 원래 디코딩 설정을 복원해요.

오류

ReAnchor는 프로그램이나 메트릭의 첫 번째 오류에서 멈춰요. 생성형 LM에서는 잘못된 형태의 답도 오류로 계산돼요. 예를 들어 Score 답이 어느 수준의 확률이라도 빠뜨리면 Predict가 오류를 일으켜요. JSON 스키마를 안정적으로 따르는 모델을 쓰고, 백엔드 부하에 맞는 클라이언트 timeout을 설정하세요.

결과

compile은 프로그램의 복사본을 반환하며 원래 프로그램은 바꾸지 않아요. compile 후 report는 다음을 담아요:

train_score_before와 train_score — 보정 전후의 훈련 예시 평균 메트릭 점수.
val_score_before와 val_score — valset을 넘기면 같은 점수. ReAnchor는 valset에는 절대 설정을 맞추지 않아요.
fitted — 출력당 한 행으로, 맞춘 값 또는 ReAnchor가 건너뛴 이유. 각 맞춘 행은 호출 수와 시도한 설정이 담긴 observed 항목을 가져요. threshold와 cut 보고서는 관찰된 값도 요약해요. fold_check 항목은 폴드 검증을 통과하거나 실패한 더 좋은 훈련 점수를 가진 탐색 단계 수를 세요. 필드별 train_score_original은 확률 활성화 전 점수, train_score_at_start는 확률 기반 기준선, train_score는 유지된 동작을 설명해요. 거부된 구성은 맞춘 value 대신 skipped 이유를 가져요.

메트릭은 숫자나 score가 있는 dspy.Prediction을 반환할 수 있어요.

log_dir를 설정하면 ReAnchor가 그 폴더에 report.json을 써요.

맞춘 설정은 각 예측기의 fields 일부이므로, 조정된 프로그램은 다른 Predict 프로그램처럼 저장/불러오기가 돼요.

::: dspy.experimental.ReAnchor options: members: [init, compile]

dspy.experimental.ReAnchor