dspy.Example
dspy.Example
dspy.Example(base=None, **kwargs)
명명된 필드를 가진, DSPy 예시·트레이닝 데이터용 유연한 데이터 컨테이너예요.
Example은 대략 HuggingFace 데이터셋이나 pandas DataFrame의 **한 행(row)**이라 보면 돼요. 딕셔너리나 점 접근 레코드처럼 동작해서, example["question"] 또는 example.question으로 필드를 읽을 수 있어요.
DSPy에서 Example 객체의 리스트가 바로 우리의 trainset, devset, testset이에요. 대부분의 예시는 키워드 인자나 기존 레코드에서 만들고, 그다음 with_inputs(...)로 어떤 필드를 모듈에 넣을지 표시해요. 나머지 필드는 레이블(label)이나 메타데이터예요.
평가 코드·커스텀 옵티마이저·트레이닝 루프를 쓸 때는, 모듈에 넣을 필드에는 example.inputs()를, 모듈 출력과 비교할 필드에는 example.labels()를 사용해요.
예시를 볼게요.
키워드 인자로 만들기:
>>> import dspy
>>> example = dspy.Example(
... question="What is the capital of France?",
... answer="Paris",
... ).with_inputs("question")
>>> example.question
'What is the capital of France?'
>>> example.answer
'Paris'
>>> example.inputs().toDict()
{'question': 'What is the capital of France?'}
기존 레코드에서 만들기:
>>> record = {"question": "What is 2+2?", "answer": "4"}
>>> example = dspy.Example(**record).with_inputs("question")
>>> example["question"]
'What is 2+2?'
>>> example.labels().answer
'4'
입력 필드 표시하기:
>>> example = dspy.Example(
... question="What is the weather?",
... answer="It's sunny",
... ).with_inputs("question")
>>> example.inputs().question
'What is the weather?'
>>> example.labels().answer
"It's sunny"
trainset에서 사용하기:
>>> trainset = [
... dspy.Example(question="What is 2+2?", answer="4").with_inputs("question"),
... dspy.Example(question="What is 3+3?", answer="6").with_inputs("question"),
... ]
>>> trainset[0].inputs().toDict()
{'question': 'What is 2+2?'}
메트릭에서 사용하기:
>>> def exact_match_metric(example, pred, trace=None):
... return example.answer.lower() == pred.answer.lower()
>>> gold = dspy.Example(question="What is 1+1?", answer="2").with_inputs("question")
>>> pred = dspy.Prediction(answer="2")
>>> exact_match_metric(gold, pred)
True
딕셔너리처럼 사용하기:
>>> example = dspy.Example(name="Alice", age=30).with_inputs("name")
>>> "name" in example
True
>>> example.get("city", "Unknown")
'Unknown'
생성자는 필드에서 또는 기존 레코드에서 Example을 만들어요. 일반적인 경우엔 dspy.Example(question="...", answer="...")처럼 필드를 키워드 인자로 넘겨요. 이미 딕셔너리나 다른 Example이 있고 그 필드를 복사한 뒤 몇 개 값을 더하거나 덮으려면 base를 써요.
| 이름 | 타입 | 설명 | 기본값 |
|---|---|---|---|
base |
필드를 복사해 올 딕셔너리 또는 Example. **kwargs를 적용하기 전에 씀. None이면 필드 없이 시작 |
None |
|
**kwargs |
예시에 저장할 필드 이름·값. base와 **kwargs 양쪽에 같은 필드가 있으면 **kwargs 값이 우선 |
{} |
소스: dspy/primitives/example.py
메서드:
copy(**kwargs)
선택적으로 필드를 덮은 **얕은 복사(shallow copy)**를 돌려줘요.
>>> import dspy
>>> ex = dspy.Example(question="Why?", answer="Because.")
>>> ex.copy(answer="No reason.")
Example({'question': 'Why?', 'answer': 'No reason.'}) (input_keys=None)
get(key, default=None)
key의 값을 돌려주고, 필드가 없으면 default를 돌려줘요. key는 필수.
>>> ex = dspy.Example(name="Alice")
>>> ex.get("name")
'Alice'
>>> ex.get("city", "Unknown")
'Unknown'
inputs()
입력 필드만 담은 새 Example을 돌려줘요. 먼저 with_inputs를 호출해야 해요. 그러지 않으면 ValueError가 나요.
>>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
>>> ex.inputs()
Example({'question': 'Why?'}) (input_keys={'question'})
items(include_dspy=False)
dict.items()처럼 (field_name, value) 쌍을 돌려줘요. include_dspy=True면 dspy_ 접두사 내부 필드도 포함돼요.
keys(include_dspy=False)
dict.keys()처럼 필드 이름을 돌려줘요. 기본으론 dspy_ 내부 필드는 제외해요.
labels()
레이블(비입력) 필드만 담은 새 Example을 돌려줘요. 레이블은 입력이 아닌 전부이므로 먼저 with_inputs를 호출해야 해요.
>>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
>>> ex.labels()
Example({'answer': 'Because.'}) (input_keys=None)
toDict()
중첩 객체를 재귀적으로 직렬화해 평범한 딕셔너리로 변환해요. 중첩 Example·Pydantic 모델·리스트·dict가 JSON 친화적으로 변환돼요.
>>> dspy.Example(question="Why?", answer="Because.").toDict()
{'question': 'Why?', 'answer': 'Because.'}
values(include_dspy=False)
dict.values()처럼 필드 값들을 돌려줘요. 기본으론 dspy_ 내부 필드는 제외해요.
with_inputs(*keys)
어떤 필드가 입력인지 표시하고 새 Example을 돌려줘요. 여기 나열되지 않은 필드는 레이블(기대 출력)로 취급돼요. DSPy 옵티마이저·평가자는 이 구분을 써서 example.inputs()를 프로그램에 넘기고 출력을 example.labels()와 비교해요.
>>> ex = dspy.Example(question="Why?", answer="Because.").with_inputs("question")
>>> ex.inputs().keys()
['question']
>>> ex.labels().keys()
['answer']
without(*keys)
지정된 필드를 제거한 복사본을 돌려줘요.
>>> ex = dspy.Example(question="Why?", answer="Because.", source="web")
>>> ex.without("source")
Example({'question': 'Why?', 'answer': 'Because.'}) (input_keys=None)
참고: dspy.Evaluate는 Example 목록에서 프로그램을 평가하고, Metrics는 Example을 예측과 비교하는 메트릭 함수를 작성해요.
출처: 공식문서