평가 데이터 내보내기

W&B Weave에서 평가를 실행하는 팀은 Weave UI 외부에서 평가 결과가 필요한 경우가 많습니다. 일반적인 사용 사례는 다음과 같습니다:

맞춤형 분석 및 시각화를 위해 스프레드시트나 노트북으로 메트릭을 가져옵니다.
배포를 제어하기 위해 CI/CD 파이프라인에 평가 결과를 공급합니다.
W&B 시트가 없는 이해관계자와 Looker와 같은 BI 도구나 내부 대시보드를 통해 결과를 공유합니다.
프로젝트 전반의 점수를 집계하는 자동화된 보고 파이프라인을 구축합니다.

v2 Evaluation REST API는 평가 run, 예측, 점수, Scorer와 같은 집중된 평가 개념을 제공합니다. 그 결과는 범용 Calls API에 비해 유형 지정 Scorer statistics 및 resolved dataset inputs가 포함된 더 풍부하고 구조화된 출력을 제공합니다.

API endpoints used

이 페이지의 스니펫은 v2 Evaluation REST API의 다음 엔드포인트를 사용합니다:

GET /v2/{entity}/{project}/evaluation_runs: 프로젝트의 evaluation run을 목록으로 표시하며, evaluation reference, model reference 또는 run ID로 선택 필터링할 수 있습니다.
GET /v2/{entity}/{project}/evaluation_runs/{evaluation_run_id}: 단일 evaluation run을 조회하여 해당 모델, evaluation reference, status, timestamps 및 summary를 가져옵니다.
POST /v2/{entity}/{project}/eval_results/query: 하나 이상의 evaluations에 대한 그룹화된 evaluation result 행을 조회합니다. model output, 점수 및 선택적으로 해결된 dataset row 입력이 포함된 행별 trial을 반환합니다. 요청 시 aggregated scorer statistics도 반환합니다.
GET /v2/{entity}/{project}/predictions/{prediction_id}: 입력, 출력 및 model reference가 포함된 개별 prediction을 조회합니다.

인증은 HTTP Basic을 사용하며, 사용자 이름은 api, 비밀번호는 W&B API 키입니다.

사전 요구 사항

이 페이지의 예시는 Python을 사용하지만, Evaluation REST API는 언어에 구애받지 않습니다. TypeScript나 다른 HTTP 클라이언트에서 동일한 엔드포인트를 호출할 수 있습니다. 시작하기 전에 다음을 준비하세요:

Python 3.7 이상.
requests 라이브러리. pip install requests로 설치하세요.
WANDB_API_KEY 환경 변수로 설정된 API 키. CoreWeave Forge UI에서 키를 가져오세요.

인증 설정

다음 스니펫은 이 페이지 전반에 걸쳐 사용되는 라이브러리를 임포트하고 base URL, authentication 튜플, 대상 entity와 프로젝트를 설정합니다. 이후의 모든 예시는 이 변수를 재사용합니다.

import json
import os

import requests

TRACE_BASE = "https://trace.wandb.ai"
AUTH = ("api", os.environ["WANDB_API_KEY"])

entity = "my-team"
project = "my-project"

인증이 설정되면 다음 섹션에 설명된 엔드포인트를 호출할 수 있습니다.

evaluation run 목록

evaluation run의 목록은 보통 export 워크플로에서 가장 먼저 필요한 것입니다. 이 목록은 다른 endpoint에서 요구하는 evaluation_run_id 값을 제공하기 때문입니다. 프로젝트에서 최근 evaluation run을 가져오고 각 run의 ID와 status 같은 세부 정보를 나열하세요.

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/evaluation_runs",
    auth=AUTH,
)
runs = [json.loads(line) for line in resp.text.strip().splitlines()]

for run in runs:
    print(run["evaluation_run_id"], run.get("status"))

단일 evaluation run 조회

evaluation_run_id를 가지고 있으면 해당 run의 전체 record를 가져올 수 있습니다. 특정 evaluation run의 상세 정보를 조회하며, 여기에는 모델, evaluation 레퍼런스, status, timestamps가 포함됩니다. 가져오려는 evaluation run의 ID로 [EVALUATION_RUN_ID]를 교체하세요.

eval_run_id = "[EVALUATION_RUN_ID]"

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/evaluation_runs/{eval_run_id}",
    auth=AUTH,
)
eval_run = resp.json()
print(eval_run["evaluation_run_id"], eval_run.get("status"), eval_run.get("model"))

예측 및 점수 조회

run의 기본 데이터가 필요한 경우(예: 스프레드시트 내보내기 또는 행 수준 분석), eval_results/query 엔드포인트를 사용하여 evaluation run의 행별 결과를 조회하세요. 각 행에는 resolved dataset inputs, 모델 출력 및 개별 Scorer 결과가 포함됩니다. include_rows, include_raw_data_rows, resolve_row_refs를 설정하여 전체 행별 detail을 가져오세요. 조회하려는 evaluation run의 ID로 [EVALUATION_RUN_ID]를 교체하세요.

eval_run_id = "[EVALUATION_RUN_ID]"

resp = requests.post(
    f"{TRACE_BASE}/v2/{entity}/{project}/eval_results/query",
    json={
        "evaluation_run_ids": [eval_run_id],
        "include_rows": True,
        "include_raw_data_rows": True,
        "resolve_row_refs": True,
    },
    auth=AUTH,
)
results = resp.json()

for row in results["rows"]:
    inputs = row.get("raw_data_row")
    for ev in row.get("evaluations", []):
        for trial in ev.get("trials", []):
            output = trial.get("model_output")
            scores = trial.get("scores", {})
            print("Input:", inputs)
            print("Output:", output)
            print("Scores:", scores)

집계된 점수 조회

고수준 메트릭만 필요한 경우(예: 대시보드 또는 CI/CD 게이팅), 행별 데이터 대신 요약 통계를 요청하세요. 동일한 eval_results/query 엔드포인트는 행별 데이터 대신 집계된 Scorer 통계도 반환할 수 있습니다. include_summary를 설정하여 이진 Scorer의 통과율이나 연속 Scorer의 평균과 같은 요약 수준 메트릭을 가져오세요.

resp = requests.post(
    f"{TRACE_BASE}/v2/{entity}/{project}/eval_results/query",
    json={
        "evaluation_run_ids": [eval_run_id],
        "include_summary": True,
        "include_rows": False,
    },
    auth=AUTH,
)
results = resp.json()

for ev in results["summary"]["evaluations"]:
    for stat in ev["scorer_stats"]:
        print(stat["scorer_key"], stat.get("value_type"), stat.get("pass_rate") or stat.get("numeric_mean"))

단일 prediction 조회

단일 행을 격리하여 검사하려면, 예를 들어 예상치 못한 score를 조사할 때, ID로 직접 prediction을 가져올 수 있습니다. 개별 prediction의 전체 세부 정보를 가져오며, 여기에는 inputs, 출력 및 model 레퍼런스가 포함됩니다. 검색하려는 prediction의 ID로 [PREDICTION_ID]를 교체하세요.

prediction_id = "[PREDICTION_ID]"

resp = requests.get(
    f"{TRACE_BASE}/v2/{entity}/{project}/predictions/{prediction_id}",
    auth=AUTH,
)
prediction = resp.json()
print(prediction)

Row digests

각 엔드포인트가 반환하는 원시 데이터 외에도, eval_results/query의 응답에는 run 간에 행을 서로 연관 짓는 데 도움이 되는 추가 식별자가 포함됩니다. eval_results/query 엔드포인트의 각 결과 행에는 row_digest가 포함됩니다. 이는 평가 데이터셋의 특정 입력을 위치가 아닌 내용을 기준으로 고유하게 식별하는 콘텐츠 해시입니다. Row digest는 다음과 같은 경우에 유용합니다.

평가 간 비교: 동일한 데이터셋으로 서로 다른 두 모델을 실행하면 digest가 같은 행은 동일한 입력을 나타냅니다. row_digest를 기준으로 조인하면 정확히 같은 작업에서 각 모델의 성능을 비교할 수 있습니다.
중복 제거: 동일한 작업이 여러 평가 스위트에 포함된 경우 digest로 이를 파악할 수 있습니다.
재현성: digest는 콘텐츠 주소 기반이므로 누군가 데이터셋 행을 수정하면(지시문 텍스트, 루브릭 또는 기타 필드 변경) 새 digest가 부여됩니다. 이를 통해 두 evaluation run이 동일한 입력을 사용했는지, 아니면 서로 다른 버전을 사용했는지 확인할 수 있습니다.

​API endpoints used

​사전 요구 사항

​인증 설정

​evaluation run 목록

​단일 evaluation run 조회

​예측 및 점수 조회

​집계된 점수 조회

​단일 prediction 조회

​Row digests