> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 점수화 개요
> Weave Scorer로 AI 출력을 평가하고 평가 메트릭을 반환하세요
Weave에서 Scorer는 AI 출력을 평가하고 평가 메트릭을 반환합니다. Scorer는 AI의 출력을 받아 분석한 뒤 결과를 딕셔너리로 반환합니다. 필요하면 입력 데이터를 레퍼런스로 사용할 수 있고, 평가에 대한 설명이나 추론 같은 추가 정보도 출력할 수 있습니다.
이 가이드는 AI 시스템 출력의 품질을 측정하려는 개발자를 대상으로 합니다. Scorer가 Weave 평가에서 어떤 역할을 하는지, Scorer를 직접 구축하는 방법, 개별 Call에 Scorer를 적용하는 방법, 결과 점수를 분석하는 방법을 설명합니다.
평가 시 Scorer를 `weave.Evaluation` 객체에 전달하세요. Weave는 두 가지 유형의 Scorer를 지원합니다.
1. **함수 기반 Scorer:** `@weave.op`로 데코레이트된 Python 함수입니다.
2. **클래스 기반 Scorer:** 더 복잡한 평가를 위해 `weave.Scorer`를 상속하는 Python 클래스입니다.
Scorer는 반드시 딕셔너리를 반환해야 합니다. 여러 메트릭이나 중첩된 메트릭을 반환할 수 있으며, LLM 평가자가 자신의 추론에 대해 작성한 텍스트처럼 숫자가 아닌 값도 반환할 수 있습니다.
Scorer는 평가 시 `weave.Evaluation` 객체에 전달하는 특수한 Op입니다.
나만의 Scorer 만들기
맞춤형 Scorer를 사용하면 기본 제공 Scorer로는 다룰 수 없는, 사용 사례에 특화된 평가 기준을 직접 정의할 수 있습니다. 다음 섹션에서는 Scorer를 정의하는 두 가지 방법을 설명합니다. 함수로 정의하는 방법과, 더 복잡한 로직이 필요할 때 클래스로 정의하는 방법입니다.
**바로 사용할 수 있는 Scorer**
이 가이드에서는 맞춤형 Scorer를 만드는 방법을 설명하지만, Weave는 바로 사용할 수 있는 [사전 정의된 Scorer](/ko/products/wandb/weave/guides/evaluation/builtin_scorers)와 [로컬 SLM Scorer](/ko/products/wandb/weave/guides/evaluation/weave_local_scorers)도 제공합니다. 예를 들면 다음과 같습니다.
* [할루시네이션 감지](/ko/products/wandb/weave/guides/evaluation/builtin_scorers#hallucinationfreescorer)
* [요약 품질](/ko/products/wandb/weave/guides/evaluation/builtin_scorers#summarizationscorer)
* [임베딩 유사도](/ko/products/wandb/weave/guides/evaluation/builtin_scorers#embeddingsimilarityscorer)
* [유해성 감지(로컬)](/ko/products/wandb/weave/guides/evaluation/weave_local_scorers#weavetoxicityscorerv1)
* [컨텍스트 관련성 점수화(로컬)](/ko/products/wandb/weave/guides/evaluation/weave_local_scorers#weavecontextrelevancescorerv1)
함수 기반 Scorer
함수 기반 Scorer는 `@weave.op` 데코레이터가 적용되어 딕셔너리를 반환하는 함수입니다. 다음과 같은 간단한 평가에 적합합니다.
```python lines theme={"system"}
import weave
@weave.op
def evaluate_uppercase(text: str) -> dict:
return {"text_is_uppercase": text.isupper()}
my_eval = weave.Evaluation(
dataset=[{"text": "HELLO WORLD"}],
scorers=[evaluate_uppercase]
)
```
평가를 실행하면 `evaluate_uppercase`가 텍스트가 모두 대문자인지 확인합니다.
함수 기반 Scorer는 `weave.op`로 래핑된 함수로, `modelOutput`과 선택 항목인 `datasetRow`가 포함된 객체를 인수로 받습니다. 다음 예시와 같은 간단한 평가에 적합합니다.
```typescript lines theme={"system"}
import * as weave from 'weave'
const evaluateUppercase = weave.op(
({modelOutput}) => modelOutput.toUpperCase() === modelOutput,
{name: 'textIsUppercase'}
);
const myEval = new weave.Evaluation({
dataset: [{text: 'HELLO WORLD'}],
scorers: [evaluateUppercase],
})
```
클래스 기반 Scorer
Scorer 메타데이터를 추가로 추적하거나, LLM 평가자에 여러 프롬프트를 사용해 보거나, 여러 번의 함수 호출이 필요한 고급 평가에는 `Scorer` 클래스를 사용하세요.
**요구 사항:**
1. `weave.Scorer`를 상속하세요.
2. `@weave.op`로 데코레이트된 `score` 메서드를 정의하세요.
3. `score` 메서드는 딕셔너리를 반환해야 합니다.
예시:
```python lines {7} theme={"system"}
import weave
from openai import OpenAI
from weave import Scorer
llm_client = OpenAI()
class SummarizationScorer(Scorer):
model_id: str = "gpt-4o"
system_prompt: str = "Evaluate whether the summary is good."
@weave.op
def some_complicated_preprocessing(self, text: str) -> str:
processed_text = "Original text: \n" + text + "\n"
return processed_text
@weave.op
def call_llm(self, summary: str, processed_text: str) -> dict:
res = llm_client.chat.completions.create(
messages=[
{"role": "system", "content": self.system_prompt},
{"role": "user", "content": (
f"Analyze how good the summary is compared to the original text."
f"Summary: {summary}\n{processed_text}"
)}])
return {"summary_quality": res}
@weave.op
def score(self, output: str, text: str) -> dict:
"""요약 품질을 채점합니다.
Args:
output: AI 시스템이 생성한 요약
text: 요약할 원본 텍스트
"""
processed_text = self.some_complicated_preprocessing(text)
eval_result = self.call_llm(summary=output, processed_text=processed_text)
return {"summary_quality": eval_result}
evaluation = weave.Evaluation(
dataset=[{"text": "The quick brown fox jumps over the lazy dog."}],
scorers=[summarization_scorer])
```
이 클래스는 요약을 원본 텍스트와 비교하여 요약 품질을 평가합니다.
```plaintext theme={"system"}
이 기능은 아직 TypeScript에서 사용할 수 없습니다.
```
Scorer 작동 방식
이 섹션에서는 Scorer가 평가에서 데이터를 전달받는 방식, 데이터셋 열을 Scorer 인수에 매핑하는 방법, 점수화 프롬프트에서 op 변수를 참조하는 방법, 그리고 Weave가 행별 점수를 집계해 최종 결과를 도출하는 방식을 설명합니다.
Scorer 키워드 인수
Scorer는 AI 시스템의 출력과 데이터셋 행의 입력 데이터 모두에 액세스할 수 있습니다.
* **입력:** Scorer에서 데이터셋 행의 데이터(예: `label` 또는 `target` 열)를 사용하려면, Scorer 정의에 `label` 또는 `target` 키워드 인수를 추가하여 Scorer가 해당 데이터를 사용할 수 있게 하세요.
예를 들어 데이터셋의 `label` 열을 사용하려면 Scorer 함수(또는 `score` 클래스 메서드)의 매개변수 목록을 다음과 같이 작성합니다.
```python lines theme={"system"}
@weave.op
def my_custom_scorer(output: str, label: int) -> dict:
...
```
Weave `Evaluation`은 실행 시 AI 시스템의 출력을 `output` 매개변수에 전달합니다. 또한 `Evaluation`은 그 밖의 Scorer 인수 이름을 데이터셋 열과 자동으로 대응시키려고 시도합니다. Scorer 인수나 데이터셋 열을 수정하기 어렵다면 열 매핑을 사용할 수 있습니다. 자세한 내용은 다음 섹션을 참조하세요.
* **출력:** AI 시스템의 출력에 액세스하려면 Scorer 함수의 시그니처에 `output` 매개변수를 포함하세요.
`column_map`으로 열 이름 매핑하기
`score` 메서드의 인수 이름이 데이터셋의 열 이름과 일치하지 않을 때가 있습니다. 이럴 때는 `column_map`을 사용하면 됩니다.
클래스 기반 Scorer를 사용한다면 Scorer 클래스를 초기화할 때 `Scorer`의 `column_map` 속성에 딕셔너리를 전달하세요. 이 딕셔너리는 `score` 메서드의 인수 이름을 데이터셋의 열 이름에 `{scorer_keyword_argument: dataset_column_name}` 순서로 매핑합니다.
예시:
```python lines theme={"system"}
import weave
from weave import Scorer
# 요약할 뉴스 아티클 데이터셋
dataset = [
{"news_article": "The news today was great...", "date": "2030-04-20", "source": "Bright Sky Network"},
...
]
# Scorer 클래스
class SummarizationScorer(Scorer):
@weave.op
def score(self, output, text) -> dict:
"""
output: LLM 요약 시스템이 출력한 요약
text: 요약할 텍스트
"""
... # 요약 품질 평가
# `text` 인수를 `news_article` 데이터 열에 매핑하는 Scorer 생성
scorer = SummarizationScorer(column_map={"text" : "news_article"})
```
이제 `score` 메서드의 `text` 인수는 `news_article` 데이터셋 열의 데이터를 받습니다.
**참고:**
* `Scorer`를 서브클래싱하고 `score` 메서드를 오버로드하여 열을 명시적으로 매핑하는 방법도 같은 효과를 냅니다.
```python lines theme={"system"}
import weave
from weave import Scorer
class MySummarizationScorer(SummarizationScorer):
@weave.op
def score(self, output: str, news_article: str) -> dict: # 유형 힌트 추가
# score 메서드를 오버로드하고 열을 수동으로 매핑
return super().score(output=output, text=news_article)
```
Scorer는 AI 시스템의 출력과 데이터셋 행의 내용 모두에 액세스할 수 있습니다.
Scorer 정의에 `datasetRow` 키워드 인수를 추가하면 데이터셋 행의 관련 열에 액세스할 수 있습니다.
```typescript twoslash lines theme={"system"}
// @noErrors
const myScorer = weave.op(
({modelOutput, datasetRow}) => {
return modelOutput * 2 === datasetRow.expectedOutputTimesTwo;
},
{name: 'myScorer'}
);
```
`columnMapping`으로 열 이름 매핑하기
TypeScript에서는 이 기능이 개별 Scorer가 아닌 `Evaluation` 객체에 있습니다.
`datasetRow` 키가 의미상으로는 비슷하지만 Scorer의 명명 규칙과 정확히 일치하지 않을 때가 있습니다. 이럴 때는 `Evaluation`의 `columnMapping` 옵션으로 열을 매핑할 수 있습니다.
매핑은 항상 Scorer 기준으로, `{scorer_key: dataset_column_name}` 형식을 따릅니다.
예시:
```typescript twoslash lines theme={"system"}
// @noErrors
const myScorer = weave.op(
({modelOutput, datasetRow}) => {
return modelOutput * 2 === datasetRow.expectedOutputTimesTwo;
},
{name: 'myScorer'}
);
const myEval = new weave.Evaluation({
dataset: [{expected: 2}],
scorers: [myScorer],
columnMapping: {expectedOutputTimesTwo: 'expected'}
});
```
점수화 프롬프트에서 Op의 변수에 액세스하기
LLM-as-a-judge Scorer의 점수화 프롬프트에서는 Op의 변수를 참조할 수 있습니다. Scorer가 실행되면 Weave가 이 값을 자동으로 추출합니다.
예를 들어 다음과 같은 함수가 있다고 해 보겠습니다.
```python theme={"system"}
@weave.op
def summarize_article(article: str, max_length: int) -> str:
# 여기에 요약 로직을 작성하세요
return summary
```
다음 변수를 사용할 수 있습니다.
| 변수 | 설명 |
| - | - |
| `{article}` | 입력 인수 `article`의 값 |
| `{max_length}` | 입력 인수 `max_length`의 값 |
| `{inputs}` | 모든 입력 인수를 담은 JSON 딕셔너리 |
| `{output}` | op가 반환한 결과 |
점수화 프롬프트 예시:
```text theme={"system"}
이 요약의 품질을 평가하세요.
원본 기사: {article}
요약: {output}
요청된 최대 길이: {max_length}
다음 기준에 따라 요약을 1~10점으로 평가하세요.
- 정확도: 기사 내용을 정확하게 반영하나요?
- 완전성: 핵심 내용을 빠짐없이 다루나요?
- 간결성: 적절한 길이로 간결하게 작성되었나요?
평점과 그 근거가 되는 추론을 포함한 JSON 객체를 반환하세요.
```
Scorer의 최종 요약
평가 중에 Weave는 데이터셋의 각 행에 대해 Scorer를 계산합니다. 평가의 최종 점수를 산출하기 위해 Weave는 출력의 반환 유형에 따라 `auto_summarize`를 실행합니다.
`Scorer` 클래스의 `summarize` 메서드를 재정의하면 최종 점수를 계산하는 방식을 직접 정의할 수 있습니다. `summarize` 함수의 요건은 다음과 같습니다.
* 단일 매개변수 `score_rows`를 받습니다. 이 매개변수는 딕셔너리 목록이며, 각 딕셔너리에는 데이터셋의 한 행에 대해 `score` 메서드가 반환한 점수가 담겨 있습니다.
* 요약된 점수를 담은 딕셔너리를 반환합니다.
**활용 사례**
데이터셋의 최종 점수 값을 결정하기 전에 모든 행을 먼저 채점해야 할 때 유용합니다.
```python lines theme={"system"}
class MyBinaryScorer(Scorer):
"""
전체 출력이 target과 일치하면 True, 그렇지 않으면 False를 반환합니다
"""
@weave.op
def score(self, output, target):
return {"match": output == target}
def summarize(self, score_rows: list) -> dict:
full_match = all(row["match"] for row in score_rows)
return {"full_match": full_match}
```
> 이 예제에서 기본 `auto_summarize`를 사용하면 True의 개수와 비율이 반환됩니다.
자세한 내용은 [CorrectnessLLMJudge](/ko/products/wandb/weave/tutorial-rag#optional-defining-a-scorer-class) 구현을 참조하세요.
평가 중에 Weave는 데이터셋의 각 행에 대해 Scorer를 계산합니다. 최종 점수를 산출하기 위해 Weave는 출력 유형에 따라 결과를 집계하는 내부 `summarizeResults` 함수를 사용합니다.
Weave는 맞춤형 요약을 지원하지 않습니다.
Call에 Scorer 적용하기
Scorer는 `weave.Evaluation`의 일부로 실행할 수 있을 뿐 아니라, 개별 Call에 직접 적용할 수도 있습니다. 이 방법은 프로덕션 트래픽에 점수를 매기거나 특정 Op 호출에 평가 메트릭을 첨부하려는 경우에 유용합니다.
Weave Op에 Scorer를 적용하려면 `.call()` 메서드를 사용하세요. 이 메서드를 사용하면 오퍼레이션의 결과와 추적 정보에 모두 액세스할 수 있으므로, Scorer 결과를 Weave 데이터베이스의 특정 Call과 연결할 수 있습니다.
`.call()` 메서드 사용에 대한 자세한 내용은 [Op 호출하기](/ko/products/wandb/weave/guides/tracking/tracing#getting-a-handle-to-the-call-object-during-execution) 가이드를 참조하세요.
다음은 기본 예시입니다.
```python lines theme={"system"}
# 결과와 Call 객체를 모두 조회
result, call = generate_text.call("Say hello")
# Scorer 적용
score = await call.apply_scorer(MyScorer())
```
동일한 Call에 여러 Scorer를 적용할 수도 있습니다.
```python lines theme={"system"}
# 여러 Scorer를 병렬로 적용
await asyncio.gather(
call.apply_scorer(quality_scorer),
call.apply_scorer(toxicity_scorer)
)
```
**참고:**
* Weave는 Scorer 결과를 데이터베이스에 자동으로 저장합니다.
* Scorer는 기본 오퍼레이션이 완료된 후 비동기적으로 실행됩니다.
* Scorer 결과는 UI에서 확인하거나 API로 쿼리할 수 있습니다.
프로덕션 모범 사례와 전체 예제 등 Scorer를 가드레일이나 모니터로 사용하는 방법에 대한 자세한 내용은 [가드레일 및 모니터 가이드](/ko/products/wandb/weave/guides/evaluation/monitors)를 참조하세요.
```plaintext theme={"system"}
This feature is not available in TypeScript yet.
```
`preprocess_model_input` 매개변수를 사용하면 평가 중에 데이터셋 예시가 모델에 전달되기 전에 해당 예시를 수정할 수 있습니다.
`preprocess_model_input` 함수는 Weave가 입력을 모델의 예측 함수에 전달하기 전에만 입력을 변환합니다.
Scorer 함수는 항상 전처리가 적용되지 않은 원본 데이터셋 예시를 받습니다.
사용 방법과 예시는 [평가 전에 `preprocess_model_input`으로 데이터셋 행 서식 지정하기](/ko/products/wandb/weave/guides/core-types/evaluations#using-preprocess_model_input-to-format-dataset-rows-before-evaluating)를 참조하세요.
점수 분석
Scorer가 실행된 후에는 모델 동작을 파악하거나 버전을 비교하기 위해 Scorer가 생성한 점수를 살펴봐야 하는 경우가 많습니다. 다음 섹션에서는 API와 Weights & Biases UI를 사용하여 단일 Call, 여러 Call, 그리고 특정 Scorer가 점수를 매긴 모든 Call의 점수를 분석하는 방법을 설명합니다.
단일 Call의 점수 분석하기
단일 Call API
단일 Call을 조회하려면 `get_call` 메서드를 사용하세요.
```python lines theme={"system"}
client = weave.init("my-project")
# 단일 Call 조회
call = client.get_call("call-uuid-here")
# 점수가 담긴 Call의 피드백 조회
feedback = list(call.feedback)
```
단일 Call UI
Call details 패널의 **Scores** 탭에는 개별 Call의 점수가 표시됩니다.
여러 Call의 점수 분석하기
여러 Call API
여러 Call을 조회하려면 `get_calls` 메서드를 사용하세요.
```python lines theme={"system"}
client = weave.init("my-project")
# 여러 Call 조회 - 원하는 필터를 자유롭게 사용하고 feedback을 포함하세요
calls = client.get_calls(..., include_feedback=True)
# Call을 순회하며 점수가 담긴 feedback에 액세스하세요
for call in calls:
feedback = list(call.feedback)
```
여러 Call UI
트레이스 table의 **Scores** 열에는 여러 Call의 점수가 표시됩니다.
특정 Scorer로 평가된 모든 Call 분석하기
Scorer별 모든 Call API
특정 Scorer로 평가한 모든 Call을 조회하려면 `get_calls` 메서드를 사용하세요.
```python lines theme={"system"}
client = weave.init("my-project")
# Scorer의 버전에 관계없이 점수가 매겨진 모든 Call을 조회하려면 Scorer 이름(일반적으로 클래스 이름)을 사용하세요
calls = client.get_calls(scored_by=["MyScorer"], include_feedback=True)
# Scorer의 특정 버전으로 점수가 매겨진 모든 Call을 조회하려면 전체 ref를 사용하세요
# Ref는 Scorer 객체에서 가져오거나 UI를 통해 획득할 수 있습니다.
calls = client.get_calls(scored_by=[myScorer.ref.uri()], include_feedback=True)
# Call을 순회하며 점수가 담긴 feedback에 액세스하세요
for call in calls:
feedback = list(call.feedback)
```
UI에서 Scorer별 모든 Call 보기
마지막으로, 특정 Scorer가 점수를 매긴 모든 Call을 확인하려면 UI에서 **Scorers** 탭으로 이동한 다음 **Programmatic Scorer** 탭을 선택하세요. 원하는 Scorer를 클릭하면 Scorer 세부 정보 페이지가 열립니다.
그런 다음 **Scores** 아래의 **View Traces** 버튼을 클릭하면 해당 Scorer가 점수를 매긴 모든 Call을 볼 수 있습니다.
기본적으로 현재 선택한 Scorer 버전으로 필터링됩니다. 버전 필터를 제거하면 Scorer의 모든 버전이 점수를 매긴 Call을 모두 볼 수 있습니다.
