점수 데이터 모델
점수 데이터 모델 (Scores Data Model)
이 문서는 Langfuse에서 score 관련 객체의 데이터 모델을 설명해요. score가 무엇이고 언제 쓰는지에 대한 개요는 Scores overview를, dataset·experiment run·함수 정의는 Experiments data model을 참고하세요.
출처: 문서
본문
자세한 레퍼런스로는 다음을 참고하세요:
- Python SDK 레퍼런스
- JS/TS SDK 레퍼런스
- API 레퍼런스
점수 (Scores)
Scores는 평가 결과를 저장하는 데이터 객체예요. trace, observation, session, 또는 dataset run에 평가 점수를 부여하는 데 사용돼요. 점수는 주석(annotation)으로 수동 추가하거나, SDK/API로 프로그래밍 방식으로, 또는 LLM-as-a-Judge 평가기로 자동으로 추가할 수 있어요.
Scores는 다음과 같은 속성을 가져요:
- 각 Score는 정확히 하나의 Trace, Observation, Session, 또는 DatasetRun을 참조해요.
- Scores는 numeric, categorical, boolean, 또는 text 중 하나예요 (Score Types 참고).
- Scores는 선택적으로 ScoreConfig에 연결해 특정 스키마를 준수하도록 할 수 있어요.
Score 객체 (Score object)
| Attribute | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Score의 고유 식별자. SDK가 자동 생성해요. 선택적으로 score를 업데이트하기 위한 멱등성 키로도 쓸 수 있어요. |
| name | string | Yes | Score의 이름. 예: user_feedback, hallucination_eval |
| value | number | No | Score의 숫자 값. numeric과 boolean score에서 항상 정의돼요. categorical score에선 선택 사항, text score에선 사용되지 않아요. |
| stringValue | string | No | Score의 문자열 값. categorical, boolean(문자열 동등), text 데이터 타입에 사용돼요. configId가 제공되면 config를 기준으로 categorical score에 자동 설정돼요. |
| dataType | string | No | configId가 제공되면 config의 데이터 타입을 기준으로 자동 설정돼요. 그 외에는 NUMERIC, CATEGORICAL, BOOLEAN, TEXT로 직접 정의할 수 있어요. |
| source | string | Yes | Score의 출처를 기준으로 자동 설정돼요. API, EVAL, 또는 ANNOTATION 중 하나예요. |
| comment | string | No | 평가 주석. 사용자 피드백, 평가 추론 출력, 내부 메모에 흔히 사용돼요. |
| traceId | string | No | Score가 관련된 trace의 id. |
| observationId | string | No | Score가 관련된 observation(예: LLM 호출)의 id. |
| sessionId | string | No | Score가 관련된 session의 id. |
| datasetRunId | string | No | Score가 관련된 dataset run의 id. |
| configId | string | No | Score가 특정 스키마를 따르도록 보장하는 score config id. Langfuse UI 또는 API에서 정의할 수 있어요. |
일반적인 사용 사례 (Common Use Cases)
| Level | Description |
|---|---|
| Trace | 단일 상호작용의 평가에 사용 (가장 흔함). |
| Observation | trace 레벨 아래의 단일 observation 평가에 사용. |
| Session | 여러 상호작용에 걸친 출력의 종합 평가에 사용. |
| Dataset Run | Dataset Run의 성능 점수에 사용. |
점수 설정 (Score Config)
Score config는 점수가 특정 스키마를 따르도록 보장하는 데 사용돼요. Score config를 사용하면 팀 전체에서 점수 스키마를 표준화하고, 향후 분석을 위해 점수가 일관되고 비교 가능하도록 보장할 수 있어요.
ScoreConfig는 Langfuse UI 또는 API에서 정의할 수 있어요. 설정(config)은 불변(immutable)이며 아카이브할 수 있지만(언제든 복원 가능) 변경할 수는 없어요.
Score config는 다음을 포함해요:
- Score 이름
- 데이터 타입: NUMERIC, CATEGORICAL, BOOLEAN, TEXT
- Score 값 범위에 대한 제약 (numeric은 Min/Max, categorical은 커스텀 카테고리, text는 1-500자)
ScoreConfig 객체 (ScoreConfig object)
| Attribute | Type | Required | Description |
|---|---|---|---|
| id | string | Yes | Score config의 고유 식별자. |
| name | string | Yes | Score config의 이름. 예: user_feedback, hallucination_eval |
| dataType | string | Yes | NUMERIC, CATEGORICAL, BOOLEAN, TEXT 중 하나. |
| isArchived | boolean | No | Score config가 아카이브되었는지 여부. 기본값은 false. |
| minValue | number | No | 숫자 score의 최소값을 설정. 설정하지 않으면 최소값 기본값은 -∞. |
| maxValue | number | No | 숫자 score의 최대값을 설정. 설정하지 않으면 최대값 기본값은 +∞. |
| categories | list | No | 범주형 score의 카테고리 정의. label·value 쌍의 객체 목록. |
| description | string | No | Score 설정에 대한 추가 설명. |