실험 데이터 모델(Experiments Data Model)

이 페이지는 Langfuse의 실험 관련 객체에 대한 데이터 모델을 설명합니다. 이 문서는 Datasets, DatasetItems, DatasetRuns(Experiment Runs) 같은 객체의 속성과 관계, 그리고 task/evaluator 함수 정의를 다룹니다. 객체들이 어떻게 함께 동작하는지에 대한 개요는 Concepts 페이지를 참고하세요.

출처: 문서

본문

이 페이지는 Langfuse의 실험 관련 객체에 대한 데이터 모델을 설명합니다. 이 객체들이 어떻게 함께 동작하는지에 대한 개요는 Concepts 페이지를 참고하세요. score와 score config 객체는 Scores data model 을 참고하세요.

상세 참조는 다음을 참고하세요:

실험은 어떻게 생성되나요?

다음 경로 중 하나로 Langfuse에서 실험 실행을 만듭니다:

경로	사용 시점
Experiments via SDK	Python 또는 JS/TS Experiment runner
Experiments via UI	데이터셋 페이지에서 프롬프트/모델 실험
Experiments via OpenTelemetry	직접 OTEL 수집: 다른 언어, 커스텀 OTLP 파이프라인, 실험 trace 재수집

생성된 실험 실행, 아이템, 점수를 읽으려면 Experiments API 를 사용하세요. 새 실험 실행을 생성하는 공개 REST 엔드포인트는 없습니다. 기존 POST /api/public/dataset-run-items 경로는 deprecated입니다.

객체(Objects)

Datasets

Datasets는 Dataset run 동안 사용할 수 있는 입력과 (선택적으로) expected output의 모음입니다. Dataset는 DatasetItem의 모음입니다.

Dataset 객체

속성	타입	필수	설명
`id`	string	예	데이터셋의 고유 식별자
`name`	string	예	데이터셋 이름
`description`	string	아니요	데이터셋 설명
`metadata`	object	아니요	데이터셋의 추가 메타데이터
`remoteExperimentUrl`	string	아니요	실험 트리거용 웹훅 엔드포인트
`remoteExperimentPayload`	object	아니요	실험 트리거용 페이로드

DatasetItem 객체

속성	타입	필수	설명
`id`	string	예	데이터셋 아이템의 고유 식별자. 데이터셋 아이템은 id 기준으로 upsert됩니다. id는 (프로젝트 수준에서) 고유해야 하며 데이터셋 간에 재사용할 수 없습니다.
`datasetId`	string	예	이 아이템이 속한 데이터셋의 ID
`input`	object	아니요	데이터셋 아이템의 입력 데이터
`expectedOutput`	object	아니요	데이터셋 아이템의 expected output 데이터
`metadata`	object	아니요	데이터셋 아이템의 추가 메타데이터
`mediaReferences`	object[]	아니요	`input`, `expectedOutput`, `metadata`에서 확인된(resolved) 미디어 참조. 해결된 데이터셋 미디어를 포함하는 SDK 데이터셋 조회와 API 응답에 포함됩니다.
`sourceTraceId`	string	아니요	이 데이터셋 아이템을 연결할 소스 trace의 ID
`sourceObservationId`	string	아니요	이 데이터셋 아이템을 연결할 소스 observation의 ID
`status`	DatasetStatus	아니요	데이터셋 아이템 상태. 새로 생성된 아이템의 기본값은 ACTIVE. 가능한 값: `ACTIVE`, `ARCHIVED`

DatasetItemMediaReference 객체

데이터셋 아이템 미디어 참조는 input, expectedOutput, metadata에 저장된 미디어 토큰을 서명된 미디어 다운로드 URL로 가리킵니다.

속성	타입	필수	설명
`field`	string	예	참조를 포함하는 데이터셋 아이템 속성의 필드 enum. `input`, `expected_output`(`expectedOutput`용), 또는 `metadata` 중 하나.
`referenceString`	string	예	데이터셋 아이템에 저장된 원래 Langfuse 미디어 참조 문자열
`jsonPath`	string	예	필드 안에서 참조를 담고 있는 문자열의 JSONPath. 예: `$['image']`
`media`	object	예(nullable)	해결된 미디어 메타데이터. 참조된 미디어가 존재하지 않거나 성공적으로 업로드되지 않았다면 `null`

중첩된 media 객체는 mediaId, contentType, contentLength, url, urlExpiry를 포함합니다. url은 서명된 다운로드 URL이며 만료일 전에 사용해야 합니다. 서명된 URL을 새로 고치려면 데이터셋을 다시 조회하세요.

DatasetRun (Experiment Run)

Dataset run은 데이터셋을 내 LLM 애플리케이션으로 실행하고 선택적으로 결과에 평가 방법을 적용하는 데 사용됩니다. 이를 보통 Experiment run이라고 합니다.

DatasetRun 객체

속성	타입	필수	설명
`id`	string	예	데이터셋 run의 고유 식별자
`name`	string	예	데이터셋 run 이름
`description`	string	아니요	데이터셋 run 설명
`metadata`	object	아니요	데이터셋 run의 추가 메타데이터
`datasetId`	string	예	이 run이 속한 데이터셋의 ID

실험 메타데이터와 설명은 개별 아이템이 아닌 전체 run을 설명합니다. Python과 JS/TS Experiment runner는 실험 메타데이터를 자식 observations에 전파하지만, description은 실험 아이템 루트 observations에 직접 설정하고 자식에는 전파하지 않습니다. 각 필드를 이 필드를 담고 있는 observations 전반에서 일관되게 유지하세요. 직접 수집의 경우 OpenTelemetry 실험 속성 가이드 를 따르세요.

DatasetRunItem 객체

속성	타입	필수	설명
`id`	string	예	데이터셋 run 아이템의 고유 식별자
`datasetRunId`	string	예	이 아이템이 속한 데이터셋 run의 ID
`datasetItemId`	string	예	이 run에 연결할 데이터셋 아이템의 ID
`traceId`	string	예	이 run에 연결할 trace의 ID
`observationId`	string	아니요	이 run에 연결할 observation의 ID

Langfuse는 현재 실험에 반복(repetition)이 없다고 가정합니다. 각 데이터셋 아이템은 실험당 한 번 나타납니다. 따라서 읽기는 실험 내에서 데이터셋 아이템당 최대 하나의 실험 아이템을 표시합니다. 반복 지원은 #5855 에서 추적됩니다.

대부분의 경우 DatasetRunItem이 TraceID를 직접 참조하도록 권장합니다. ObservationID 참조는 이전 SDK 버전과의 역호환성을 위해 존재합니다.

엔드투엔드 데이터 관계

실험은 몇 가지 Langfuse 객체를 결합할 수 있습니다:

DatasetRuns(또는 Experiment runs)는 내 LLM 애플리케이션으로 Dataset의 전체 또는 선택된 DatasetItem을 반복하며 생성됩니다.
LLM 애플리케이션에 Input으로 전달된 각 DatasetItem에 대해 DatasetRunItem와 Trace가 생성됩니다.
선택적으로 Trace에 Score를 추가해 DatasetRun 중 LLM 애플리케이션 출력을 평가할 수 있습니다.

이 객체들이 개념적으로 어떻게 함께 동작하는지는 Concepts 페이지 를 참고하세요. traces와 observations에 대한 자세한 내용은 observability core concepts 페이지 를 참고하세요. score와 score config 객체에 대한 자세한 내용은 Scores data model 을 참고하세요.

함수 정의(Function Definitions)

SDK로 실험을 실행할 때 task와 evaluator 함수를 정의합니다. 이는 실험 runner가 각 데이터셋 아이템에 대해 호출하는 사용자 정의 함수입니다. 실험이 개념적으로 어떻게 동작하는지는 Concepts 페이지 를 참고하세요.

Task

task는 실험 run 동안 데이터셋 아이템을 받아 출력을 반환하는 함수입니다.

함수 시그니처와 매개변수는 SDK 참조를 확인하세요:

Evaluator

evaluator는 단일 데이터셋 아이템에 대한 task의 출력에 점수를 매기는 함수입니다. Evaluator는 input, output, expected output, metadata를 받아 Langfuse에서 Score가 되는 Evaluation 객체를 반환합니다.

함수 시그니처와 매개변수는 SDK 참조를 확인하세요:

Run Evaluator

run evaluator는 전체 실험 결과를 평가하고 집계 메트릭을 계산하는 함수입니다. Langfuse 데이터셋에서 실행하면 결과 점수가 데이터셋 run에 연결됩니다.

함수 시그니처와 매개변수는 SDK 참조를 확인하세요:

task와 evaluator의 자세한 사용 예시는 Experiments via SDK 를 참고하세요. SDK 없이 실험 trace를 수집하려면 Experiments via OpenTelemetry 를 참고하세요.

로컬 데이터셋(Local Datasets)

Langfuse v4와 현재 SDK에서 로컬 데이터에 대한 실험 은 호스팅된 데이터셋 없이 Experiments 아래에 나타납니다. 각 task 실행은 디버깅용 trace도 만듭니다. Compare experiments 를 참고하세요.

더 알아보기 (Learn more)

출처 문서: 실험 데이터 모델(Experiments Data Model)