데이터셋(Datasets)

데이터셋(Datasets)

데이터셋은 입력과 expected output의 모음으로, 애플리케이션을 테스트하는 데 사용합니다. 이 문서는 데이터셋 생성, 데이터셋 아이템 업로드/생성, 멀티모달 아이템, 폴더, 버전 관리, 스키마 강제, 그리고 프로덕션 데이터에서 아이템을 만드는 방법을 다룹니다. UI 기반·SDK 기반·OpenTelemetry 실험이 모두 Langfuse 데이터셋을 사용할 수 있습니다.

출처: 문서

본문

데이터셋은 입력과 expected output의 모음이며 애플리케이션을 테스트하는 데 사용됩니다. UI 기반, SDK 기반, OpenTelemetry 실험이 모두 Langfuse 데이터셋을 사용할 수 있습니다.

왜 데이터셋을 사용하나요?

  • 실제 프로덕션 traces로 애플리케이션의 테스트 케이스 생성
  • 팀과 협업해 데이터셋 아이템 생성·수집
  • 테스트 데이터의 단일 소스 오브 트루스(single source of truth) 유지

데이터셋 범위를 정하고 현실적인 입력을 고르고 실제로 평가할 수 있는 expected output을 쓰는 방법에 대한 지침은 Langfuse Academy의 데이터셋 설계 를 읽어 보세요.

시작하기(Get Started)

데이터셋 만들기

데이터셋은 프로젝트 내에서 고유한 이름을 가집니다.

Python:

langfuse.create_dataset(
    name="<dataset_name>",
    # optional description
    description="My first dataset",
    # optional metadata
    metadata={
        "author": "Alice",
        "date": "2022-01-01",
        "type": "benchmark"
    }
)

JS/TS:

import { LangfuseClient } from "@langfuse/client"

const langfuse = new LangfuseClient()

await langfuse.api.datasets.create({
  name: "<dataset_name>",
  // optional description
  description: "My first dataset",
  // optional metadata
  metadata: {
    author: "Alice",
    date: "2022-01-01",
    type: "benchmark",
  },
});
  • Your Project > Datasets로 이동
  • + New dataset을 클릭해 새 데이터셋 생성

데이터셋 아이템 업로드 또는 생성

데이터셋 아이템은 input과 선택적으로 expected output을 제공해 추가할 수 있습니다. 원하면 Langfuse UI의 CSV 업로더로 데이터셋 아이템을 가져올 수 있습니다.

Python:

langfuse.create_dataset_item(
    dataset_name="<dataset_name>",
    # any python object or value, optional
    input={
        "text": "hello world"
    },
    # any python object or value, optional
    expected_output={
        "text": "hello world"
    },
    # metadata, optional
    metadata={
        "model": "llama3",
    }
)

데이터셋 아이템 input, expected_output, metadata에 미디어를 추가할 수도 있습니다:

from langfuse.media import LangfuseMedia

langfuse.create_dataset_item(
    dataset_name="visual-qa",
    input={
        "question": "What is shown in this image?",
        "image": LangfuseMedia(
            file_path="./example.jpg",
            content_type="image/jpeg",
        ),
    },
    expected_output={"label": "invoice"},
)

JS/TS:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

await langfuse.dataset.createItem({
  datasetName: "<dataset_name>",
  // any JS object or value
  input: {
    text: "hello world",
  },
  // any JS object or value, optional
  expectedOutput: {
    text: "hello world",
  },
  // metadata, optional
  metadata: {
    model: "llama3",
  },
});

데이터셋 아이템 input, expectedOutput, metadata에 미디어를 추가할 수도 있습니다:

import { LangfuseClient, LangfuseMedia } from "@langfuse/client";
import fs from "node:fs";

const langfuse = new LangfuseClient();

await langfuse.dataset.createItem({
  datasetName: "visual-qa",
  input: {
    question: "What is shown in this image?",
    image: new LangfuseMedia({
      source: "bytes",
      contentBytes: fs.readFileSync("./example.jpg"),
      contentType: "image/jpeg",
    }),
  },
  expectedOutput: { label: "invoice" },
});

데이터셋 업로드는 input과 expected output을 업로드하기 위한 것입니다. 이미 생성된 출력이 있다면 Experiments SDK 를 사용하세요.

Observations 테이블에서 여러 observations를 선택한 뒤 Actions → Add to dataset을 클릭하세요. 새 데이터셋을 만들거나 기존 데이터셋에 추가할 수 있으며, observation 데이터가 데이터셋 아이템에 어떻게 매핑되는지 제어하는 유연한 필드 매핑 옵션이 있습니다. 자세한 내용은 Batch add observations to datasets 를 참고하세요.

멀티모달 데이터셋 아이템

데이터셋 아이템 input, expectedOutput, metadata 필드는 이미지, 오디오, 비디오, 문서 등 미디어 첨부를 포함할 수 있습니다. Langfuse UI에서 아이템을 만들거나 편집할 때 미디어를 추가하거나, Python/JS/TS SDK로 LangfuseMedia를 사용해 업로드할 수 있습니다.

멀티모달 데이터셋은 Python SDK >= 4.10.0과 JS/TS SDK @langfuse/client >= 5.6.0의 SDK 기반 실험에서 지원됩니다. UI 기반 실험은 아직 미디어 첨부가 있는 데이터셋 아이템을 지원하지 않습니다.

UI에서 데이터셋 아이템을 열고 첨부 버튼, 드래그 앤 드롭, 또는 input, expectedOutput, metadata 편집기에 파일 붙여넣기를 사용하세요.

SDK에서는 데이터셋 아이템을 만들기 전에 미디어를 LangfuseMedia로 감쌉니다. SDK가 미디어를 업로드하고 데이터셋 아이템에 참조를 저장하며, Langfuse UI가 첨부 미리보기를 렌더링합니다.

Python:

from langfuse import get_client
from langfuse.media import LangfuseMedia

langfuse = get_client()

langfuse.create_dataset_item(
    dataset_name="visual-qa",
    input={
        "question": "What is shown in this image?",
        "image": LangfuseMedia(
            file_path="./example.jpg",
            content_type="image/jpeg",
        ),
    },
    expected_output={"label": "invoice"},
)

dataset = langfuse.get_dataset("visual-qa")

JS/TS:

import { LangfuseClient, LangfuseMedia } from "@langfuse/client";
import fs from "node:fs";

const langfuse = new LangfuseClient();

await langfuse.dataset.createItem({
  datasetName: "visual-qa",
  input: {
    question: "What is shown in this image?",
    image: new LangfuseMedia({
      source: "bytes",
      contentBytes: fs.readFileSync("./example.jpg"),
      contentType: "image/jpeg",
    }),
  },
  expectedOutput: { label: "invoice" },
});

const dataset = await langfuse.dataset.get("visual-qa");

실험에서 멀티모달 아이템을 사용하는 방법은 Experiments via SDK 를 참고하세요.

CSV 가져오기는 텍스트와 구조화된 JSON 데이터셋 아이템을 위한 것입니다. 멀티모달 데이터셋 아이템에는 UI 아이템 편집기나 SDK를 사용하세요.

데이터셋 폴더(Dataset Folders)

데이터셋은 비슷한 사용 사례를 제공하는 데이터셋을 그룹화하는 가상 폴더로 구성할 수 있습니다. 폴더를 만들려면 데이터셋 이름에 슬래시(/)를 추가하세요. UI는 /로 끝나는 모든 세그먼트를 자동으로 폴더로 표시합니다.

폴더 안에서 데이터셋 생성·조회

데이터셋 이름에 슬래시(/)를 추가해 Langfuse UI나 SDK로 폴더 안의 데이터셋을 만들고 조회할 수 있습니다.

Python:

dataset_name = "evaluation/qa-dataset"

# When creating a dataset, use the full dataset name
langfuse.create_dataset(
    name=dataset_name,
)

# When fetching a dataset in a folder, use the full dataset name
langfuse.get_dataset(
    name=dataset_name
)

이렇게 하면 evaluation이라는 폴더에 qa-dataset이라는 데이터셋이 만들어지고 조회됩니다. 전체 데이터셋 이름은 evaluation/qa-dataset으로 유지됩니다.

JS/TS:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

const datasetName = "evaluation/qa-dataset";
const encodedName = encodeURIComponent(datasetName); // "evaluation%2Fqa-dataset"

// When creating a dataset, use the full dataset name
await langfuse.dataset.create(datasetName);

// When fetching a dataset in a folder, use the encoded name
await langfuse.dataset.get(encodedName);

이렇게 하면 evaluation이라는 폴더에 qa-dataset이라는 데이터셋이 만들어지고 조회됩니다. 전체 데이터셋 이름은 evaluation/qa-dataset으로 유지됩니다.

UI에서 데이터셋을 만들고 이름 필드에 슬래시(/)를 사용해 폴더로 구성하세요. 폴더로 이동하고 폴더 이름을 클릭한 뒤 목록에서 데이터셋 이름을 클릭해 조회하세요.

URL 인코딩: API나 JS/TS SDK에서 슬래시가 있는 데이터셋 이름을 경로 매개변수로 사용할 때는 URL 인코딩을 사용하세요. 예: TypeScript의 encodeURIComponent(name).

버전 관리(Versioning)

Langfuse UI에서 데이터셋 버전에 접근하려면 Datasets > 특정 데이터셋으로 이동 > Items 탭 선택으로 이동하세요. 이 페이지에서 버전 보기를 토글할 수 있습니다.

데이터셋 아이템의 모든 add, update, delete, archive는 새 데이터셋 버전을 만듭니다. 버전은 타임스탬프로 시간 경과에 따른 변경을 추적합니다.

GET API는 기본적으로 조회 시점의 최신 버전을 반환합니다. version 매개변수로 특정 버전 타임스탬프의 데이터셋을 조회할 수 있습니다.

버전 관리는 데이터셋 아이템에만 적용되며 데이터셋 스키마에는 적용되지 않습니다. 데이터셋 스키마 변경은 새 버전을 만들지 않습니다.

특정 버전에서 데이터셋 조회

버전 타임스탬프를 제공해 특정 시점에 존재했던 데이터셋을 조회할 수 있습니다. 이는 그 타임스탬프에 존재했던 아이템만 반환합니다.

Python:

from langfuse import get_client
from datetime import datetime, timezone

langfuse = get_client()

# Capture dataset state as of 2025-12-15 at 06:30:00 UTC
version_timestamp = datetime(2025, 12, 15, 6, 30, 0, tzinfo=timezone.utc)

# Fetch dataset at version timestamp
dataset_at_version = langfuse.get_dataset(
    name="my-dataset",
    version=version_timestamp
)

# Fetch latest version
dataset_latest = langfuse.get_dataset(name="my-dataset")

JS/TS:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Capture the timestamp (use item's createdAt)
const versionTimestamp = new Date("2025-12-15T06:30:00Z").toISOString();

// Fetch dataset at version timestamp
const datasetAtVersion = await langfuse.dataset.get("my-dataset", {
  version: versionTimestamp
});

// Fetch latest version
const datasetLatest = await langfuse.dataset.get("my-dataset");

모든 데이터셋 버전을 보려면 Datasets → 데이터셋 선택 → Items 탭 → Version view 토글로 이동하세요.

버전 데이터셋에서 실험 실행

버전 데이터셋에서 직접 실험을 실행할 수 있습니다. 이는 다른 데이터셋 버전에 대한 모델 성능을 비교하거나 특정 시점의 정확한 데이터셋 상태로 실험 결과를 재현하는 데 유용합니다.

Python:

from datetime import datetime, timezone
from langfuse import Langfuse

langfuse = Langfuse()

version_timestamp = datetime(2025, 12, 15, 6, 30, 0, tzinfo=timezone.utc)

# Fetch versioned dataset
versioned_dataset = langfuse.get_dataset("qa-dataset", version=version_timestamp)

# Run experiment on the versioned dataset
def my_llm_application(*, item, **kwargs):
    # Your LLM application logic here
    # For this example, we'll just return the expected output
    return item.expected_output

result = versioned_dataset.run_experiment(
    name="Baseline Experiment v1",
    description="Running on dataset v1",
    task=my_llm_application
)

JS/TS:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Capture the version timestamp
const versionTimestamp = new Date("2025-12-15T06:30:00Z").toISOString();

// Fetch versioned dataset
const versionedDataset = await langfuse.dataset.get("qa-dataset", {
  version: versionTimestamp
});
// Run experiment on the versioned dataset
const result = await versionedDataset.runExperiment({
  name: "Baseline Experiment v1",
  description: "Running on dataset v1",
  task: async (item) => {
    // Your LLM application logic here
    // For this example, we'll just return the expected output
    return item.expectedOutput;
  }
});

UI에서 실험을 실행할 때 특정 데이터셋 버전을 선택할 수 있습니다:

  • Experiments → Run Experiment로 이동
  • Dataset Selection 단계에서 데이터셋 선택
  • Dataset Version 드롭다운에서 버전 선택
  • 드롭다운은 사용 가능한 버전 타임스탬프를 보여줍니다
  • 실험은 그 특정 시점의 데이터셋 상태에 대해 실행됩니다
  • 버전을 선택하지 않으면 최신 버전에 대해 실행됩니다

이 접근법은 재현성을 보장합니다:

  • 아이템이 업데이트되거나 삭제된 후에도 과거 데이터셋 버전에서 실험 재실행
  • 데이터셋 변경 전후의 모델 성능 비교
  • 실험 일관성 유지와 이전 실행의 정확한 결과 재현
  • 같은 baseline 데이터셋 버전에 대해 개선 사항 테스트

스키마 강제(Schema Enforcement)

선택적으로 데이터셋에 JSON Schema 검증을 추가해 모든 데이터셋 아이템이 정의된 구조를 따르도록 할 수 있습니다. 이는 데이터 품질 유지, 오류 조기 발견, 팀 전반 일관성 보장에 도움을 줍니다.

데이터셋을 만들거나 업데이트할 때 input 및/또는 expectedOutput 필드에 JSON 스키마를 정의할 수 있습니다. 설정되면 모든 데이터셋 아이템이 이 스키마에 대해 자동으로 검증됩니다. 유효한 아이템은 수락되고, 유효하지 않은 아이템은 검증 문제를 보여주는 상세 오류 메시지와 함께 거부됩니다.

Python:

langfuse.create_dataset(
    name="qa-conversations",
    input_schema={
        "type": "object",
        "properties": {
            "messages": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "role": {"type": "string", "enum": ["user", "assistant", "system"]},
                        "content": {"type": "string"}
                    },
                    "required": ["role", "content"]
                }
            }
        },
        "required": ["messages"]
    },
    expected_output_schema={
        "type": "object",
        "properties": {"response": {"type": "string"}},
        "required": ["response"]
    }
)

JS/TS:

await langfuse.createDataset({
  name: "qa-conversations",
  inputSchema: {
    type: "object",
    properties: {
      messages: {
        type: "array",
        items: {
          type: "object",
          properties: {
            role: { type: "string", enum: ["user", "assistant", "system"] },
            content: { type: "string" }
          },
          required: ["role", "content"]
        }
      }
    },
    required: ["messages"]
  },
  expectedOutputSchema: {
    type: "object",
    properties: { response: { type: "string" } },
    required: ["response"]
  }
});

Datasets → New Dataset으로 이동하거나 기존 데이터셋을 편집 → Schema Validation 섹션 확장 → JSON 스키마 추가 → Save 클릭.

합성 데이터셋 만들기

종종 애플리케이션을 테스트하기 위한 합성 예시를 만들어 데이터셋을 부트스트랩하고 싶을 때가 있습니다. LLM은 공통 질문/작업을 프롬프팅해 이를 아주 잘 생성합니다.

시작하려면 합성 데이터셋 생성 예시가 있는 이 쿡북을 확인하세요: Notebook: Synthetic Datasets

프로덕션 데이터에서 아이템 만들기

일반적인 워크플로우는 애플리케이션이 예상대로 수행되지 않은 프로덕션 traces를 선택하는 것입니다. 그런 다음 전문가가 expected output을 추가해 같은 데이터에서 애플리케이션의 새 버전을 테스트하게 합니다.

Python:

langfuse.create_dataset_item(
    dataset_name="<dataset_name>",
    input={ "text": "hello world" },
    expected_output={ "text": "hello world" },
    # link to a trace
    source_trace_id="<trace_id>",
    # optional: link to a specific observation
    source_observation_id="<observation_id>"
)

JS/TS:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

await langfuse.dataset.createItem({
  datasetName: "<dataset_name>",
  input: { text: "hello world" },
  expectedOutput: { text: "hello world" },
  // link to a trace
  sourceTraceId: "<trace_id>",
  // optional: link to a specific observation
  sourceObservationId: "<observation_id>",
});

UI에서 프로덕션 trace의 모든 observation 에 + Add to dataset을 사용하세요.

배치로 observations를 데이터셋에 추가

observations 테이블에서 여러 observations를 데이터셋에 배치 추가할 수 있습니다. 프로덕션 데이터에서 테스트 데이터셋을 빠르게 구축하는 데 유용합니다.

필드 매핑 시스템은 observation 데이터가 데이터셋 아이템으로 어떻게 변환되는지 제어하게 해줍니다. 전체 필드를 있는 그대로 사용하거나(예: 전체 observation input을 데이터셋 아이템 input으로 매핑), JSON path 표현식으로 특정 값을 추출하거나, 여러 필드에서 커스텀 객체를 만들 수 있습니다.

  • Observations 테이블로 이동
  • 필터로 관련 observations 찾기
  • 체크박스로 observations 선택
  • Actions → Add to dataset 클릭
  • 새 데이터셋 만들기 또는 기존 데이터셋 선택
  • observation 데이터가 데이터셋 아이템 필드로 어떻게 매핑되는지 제어하는 필드 매핑 구성
  • 매핑 미리보기 후 확인

배치 작업은 부분 성공을 지원하며 백그라운드에서 실행됩니다. 일부 observations가 데이터셋 스키마 검증에 실패하면 유효한 아이템은 여전히 추가되고 오류는 검토용으로 기록됩니다. Settings → Batch Actions에서 진행 상황을 모니터링할 수 있습니다.

데이터셋 아이템 편집/아카이브

데이터셋 아이템을 편집하거나 아카이브할 수 있습니다. 아카이브하면 향후 실험 실행에서 제거됩니다.

업데이트할 아이템의 id를 제공해 upsert할 수 있습니다.

Python:

langfuse.create_dataset_item(
    dataset_name="<dataset_name>",
    id="<item_id>",
    # example: update status to "ARCHIVED"
    status="ARCHIVED"
)

JS/TS:

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

await langfuse.dataset.createItem({
  datasetName: "<dataset_name>",
  id: "<item_id>",
  // example: update status to "ARCHIVED"
  status: "ARCHIVED",
});

UI에서는 아이템 id를 클릭해 편집할 수 있습니다. 아이템을 아카이브하거나 삭제하려면 아이템 옆의 점을 클릭하고 Archive 또는 Delete를 선택하세요.

데이터셋 run(Dataset runs)

데이터셋을 만들면 이를 바탕으로 애플리케이션을 테스트하고 평가할 수 있습니다.

Experiments 데이터 모델 에 대해 자세히 알아보세요.

더 알아보기 (Learn more)