UI 기반 Experiments

UI 기반 Experiments (Prompt Experiments)

Langfuse UI에서 Experiments via UI(프롬프트 실험, Prompt Experiments라고도 해요)를 실행해 Prompt Management의 서로 다른 프롬프트 버전이나 언어 모델을 테스트하고 결과를 나란히 비교할 수 있어요. 선택적으로 LLM-as-a-Judge 평가기나 code evaluator를 사용해 기대 출력을 기준으로 응답을 자동 점수화하고, 집계 레벨에서 결과를 분석할 수도 있어요.

출처: 문서

본문

프롬프트 실험(Prompt Experiments)이란? Langfuse UI에서 서로 다른 프롬프트 버전이나 언어 모델을 테스트하고 결과를 나란히 비교할 수 있는 방법이에요.

왜 프롬프트 실험을 쓰나요? (Why use Prompt Experiments?)

서로 다른 프롬프트 버전이나 모델을 빠르게 테스트해요.
데이터셋을 사용해 프롬프트 테스트를 구조화해 서로 다른 프롬프트 버전과 모델을 테스트해요.
프롬프트 실험을 통해 프롬프트를 빠르게 반복해요.
선택적으로 데이터셋의 기대 출력을 기준으로 LLM-as-a-Judge 또는 code evaluator로 응답을 점수화해요.
프롬프트를 변경할 때 테스트를 실행해 회귀를 방지해요.

실험을 구성할 때 데이터셋 버전을 선택하면 과거 데이터셋 상태에 대해 실행할 수 있어요. 버전을 선택하지 않으면 최신 버전을 사용해요. Versioned datasets에서의 실험 실행을 참고하세요.

전제 조건 (Prerequisites)

사용 가능한 프롬프트 만들기 (Create a usable prompt)

테스트하고 평가하려는 프롬프트를 만드세요. 프롬프트는 어떻게 만들까요?

프롬프트가 사용 가능하려면: 프롬프트에 실험에 사용될 데이터셋의 항목 키와 일치하는 변수(variables)가 있어야 해요. 아래 예시를 참고하세요.

예시: 프롬프트 변수 & 데이터셋 항목 키 매핑 (Prompt Variables & Dataset Item Keys Mapping)

프롬프트:

{{ documentation }}

Question: {{question}}

데이터셋 항목:

{
  "documentation": "Langfuse is an AI Engineering Platform",
  "question": "What is Langfuse?"
}

이 예시에서:

프롬프트 변수 {{documentation}}은 JSON 키 "documentation"에 매핑돼요.
프롬프트 변수 {{question}}은 JSON 키 "question"에 매핑돼요.
실험이 성공적으로 실행되려면 두 키 모두 데이터셋 항목의 input JSON에 존재해야 해요.

예시: 채팅 메시지 플레이스홀더 매핑 (Chat Message Placeholder Mapping)

변수 외에도 채팅 메시지 프롬프트의 플레이스홀더를 데이터셋 항목 키에 매핑할 수 있어요. 데이터셋 항목에 사용할 채팅 메시지 기록이 포함된 경우 유용해요. 채팅 프롬프트에 이름이 있는 플레이스홀더가 포함되어야 해요. 플레이스홀더 안의 변수는 해석되지 않아요.

채팅 프롬프트:

message_history라는 이름의 플레이스홀더

데이터셋 항목:

{
  "message_history": [
    {
      "role": "user",
      "content": "What is Langfuse?"
    },
    {
      "role": "assistant",
      "content": "Langfuse is a tool for tracking and analyzing the performance of language models."
    }
  ],
  "question": "What is Langfuse?"
}

이 예시에서:

채팅 프롬프트 플레이스홀더 message_history은 JSON 키 "message_history"에 매핑돼요.
프롬프트 변수 {{question}}은 플레이스홀더 메시지에 있지 않은 변수의 JSON 키 "question"에 매핑돼요.
실험이 성공적으로 실행되려면 두 키 모두 데이터셋 항목의 input JSON에 존재해야 해요.

사용 가능한 데이터셋 만들기 (Create a usable dataset)

프롬프트 실험에 사용할 입력과 기대 출력이 있는 데이터셋을 만드세요. 데이터셋은 어떻게 만들까요?

데이터셋이 사용 가능하려면: [1] 데이터셋 항목이 JSON 객체를 input으로 가지고, [2] 그 객체에 사용할 프롬프트의 변수와 일치하는 JSON 키가 있어야 해요. 아래 예시를 참고하세요.

예시: 프롬프트 변수 & 데이터셋 항목 키 매핑 (앞의 예시와 동일)

LLM 연결 구성하기 (Configure LLM connection)

각 데이터셋 항목에 대해 프롬프트가 실행되므로 프로젝트 설정에 LLM 연결을 구성해야 해요. LLM 연결은 어떻게 구성하나요?

선택: 평가기 설정하기 (Optional: Set up evaluators)

의미론적 기준을 평가하는 LLM-as-a-Judge 평가기나 결정적 검사를 위한 code evaluator를 설정할 수 있어요. experiments를 대상으로 하고 사용하려는 데이터셋으로 필터링하세요.

UI를 통한 Experiment (Prompt Experiment) 실행 (Trigger an Experiment via UI)

데이터셋으로 이동 (Navigate to the dataset)

Experiments는 현재 데이터셋의 상세 페이지에서 시작해요.

Your Project > Datasets로 이동하세요.
Experiment를 시작할 데이터셋을 클릭하세요.

New Experiment Button

설정 페이지 열기 (Open the setup page)

Start Experiment를 클릭해 설정 페이지를 여세요.
Prompt Experiment 아래의 Create를 클릭하세요.

Experiment 구성하기 (Configure the Experiment)

Experiment 이름을 설정하세요.
사용할 프롬프트를 선택하세요.
- 동적 콘텐츠가 하나뿐이라면 정적 시스템 프롬프트에 동적 사용자 메시지(예: 전체 사용자 메시지를 변수로)가 있는 채팅 프롬프트를 권장해요. 이렇게 하면 동적 콘텐츠를 사용자 메시지로 매핑할 수 있어요.
- 동적 콘텐츠가 여러 개라면 각 동적 콘텐츠에 대해 프롬프트에 변수를 만드는 것을 권장해요. 이렇게 하면 동적 콘텐츠를 해당 변수에 매핑할 수 있어요.
사용할 LLM 연결을 설정하거나 선택하세요.
사용할 데이터셋을 선택하세요.
선택적으로 구조화된 출력(structured output) 구성 — 토글을 켜서 JSON 스키마 응답 형식을 강제하세요.
- 프로젝트의 기존 스키마를 선택하거나 새로 만들 수 있어요.
- 스키마는 Playground에서 만들고 저장해 여기서 재사용할 수 있어요.
- 스키마 선택기 옆의 눈 아이콘으로 스키마를 보고/편집할 수 있어요.
선택적으로 사용할 평가기를 선택하세요.
Create를 클릭해 Experiment를 실행하세요.

구조화된 출력은 LLM 응답이 특정 JSON 스키마를 따르도록 보장해요. 평가나 다운스트림 처리를 위해 일관되고 파싱 가능한 출력이 필요할 때 유용해요. Playground에서 정의한 것과 같은 스키마가 실험에서도 사용 가능해요.

이렇게 하면 Experiment가 실행되고 Experiments 페이지로 리디렉션돼요. 프롬프트 복잡도와 데이터셋 크기에 따라 run은 몇 초에서 몇 분이 걸릴 수 있어요.

실행 비교하기 (Compare runs)

각 Experiment run 후 Experiments 테이블에서 집계된 점수를 확인하고 결과를 나란히 비교할 수 있어요. 베이스라인을 선택하고, 회귀를 검사하고, 개별 출력을 검토하려면 Compare experiments를 참고하세요.

프롬프트 전용 실행 대신 전체 애플리케이션·에이전트 로직(커스텀 런타임 설정 포함)을 평가해야 한다면 Experiments via SDK를 사용하세요. 웹훅으로 UI에서 SDK 기반 평가 실행을 트리거할 수도 있어요.
다른 언어나 커스텀 파이프라인에서 OpenTelemetry로 trace를 내보낸다면 Experiments via OpenTelemetry를 사용하세요.

GitHub Discussions

더 알아보기 (Learn more)

출처 문서: UI 기반 Experiments (Prompt Experiments)

UI 기반 Experiments