프롬프트 버전 관리

프롬프트 버전 관리 (Prompt Version Control)

Langfuse에서 프롬프트의 버전 관리와 배포는 버전(versions)과 라벨(labels)로 관리돼요.

출처: 문서

본문

구현

버전 & 라벨

각 프롬프트 버전에는 자동으로 버전 ID가 할당돼요. 또한 당신만의 버전 관리 체계를 따르도록 라벨을 지정할 수 있어요.

라벨은 프롬프트를 환경(staging, production), 테넌트(tenant-1, tenant-2), 또는 실험(prod-a, prod-b)에 할당하는 데 사용할 수 있어요.

Langfuse UIPython SDKJS/TS SDK

Langfuse UI를 사용해 프롬프트에 라벨을 할당하세요.

Python SDK를 사용해 새 프롬프트 버전을 만들 때 라벨을 할당하세요.

langfuse.create_prompt(
    name="movie-critic",
    type="text",
    prompt="As a {{criticlevel}} movie critic, do you like {{movie}}?",
    labels=["production"],  # add the label "production" to the prompt version
)

또는 Python SDK를 사용해 기존 프롬프트 버전의 라벨을 업데이트할 수도 있어요:

langfuse = Langfuse()
langfuse.update_prompt(
    name="movie-critic",
    version=1,
    new_labels=["john", "doe"], # assign these labels to the prompt version
)

JS/TS SDK를 사용해 새 프롬프트 버전을 만들 때 라벨을 할당하세요.

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

const langfuse = new LangfuseClient();

await langfuse.prompt.create({
  name: "movie-critic",
  type: "text",
  prompt: "As a {{criticlevel}} critic, do you like {{movie}}?",
  labels: ["production"], // add the label "production" to the prompt version
});

또는 JS/TS SDK를 사용해 기존 프롬프트 버전의 라벨을 업데이트할 수도 있어요:

await langfuse.prompt.update({
  name: "movie-critic",
  version: 1,
  newLabels: ["john", "doe"],
});

라벨 또는 버전으로 가져오기

애플리케이션에서 사용할 프롬프트를 가져올 때 특정 버전 또는 라벨로 가져올 수 있어요. 라벨 또는 버전으로 프롬프트를 가져오는 코드 예시는 다음과 같아요.

프롬프트 버전을 "배포"하려면 그 프롬프트 버전에 production 라벨 또는 생성한 환경 라벨을 할당해야 해요.

프롬프트 가져오기에 대한 참고 사항:

  • latest 라벨은 가장 최근에 생성된 버전을 가리켜요.
  • 라벨을 지정하지 않고 프롬프트를 사용하면 Langfuse가 production 라벨이 있는 버전을 제공해요.

Python SDKJS/TS SDK

from langfuse import get_client

# Initialize Langfuse client
langfuse = get_client()

# Get specific version
prompt = langfuse.get_prompt("movie-critic", version=1)

# Get specific label
prompt = langfuse.get_prompt("movie-critic", label="staging")

# Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
prompt = langfuse.get_prompt("movie-critic", label="latest")

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

const langfuse = new LangfuseClient();

// Get specific version of a prompt (here version 1)
const prompt = await langfuse.prompt.get("movie-critic", {
  version: 1,
});

// Get specific label
const prompt = await langfuse.prompt.get("movie-critic", {
  label: "staging",
});

// Get latest prompt version. The 'latest' label is automatically maintained by Langfuse.
const prompt = await langfuse.prompt.get("movie-critic", {
  label: "latest",
});

운영 워크플로우

롤백 (Rollbacks)

프롬프트에 production 라벨이 있으면 SDK에서 기본적으로 그 버전을 제공해요. Langfuse UI에서 production 라벨을 이전 버전으로 설정하면 이전 버전으로 빠르게 롤백할 수 있어요.

프롬프트 차이 (Prompt Diffs)

프롬프트 버전 차이 뷰는 시간에 따라 프롬프트에 만든 변경 사항을 보여줘요. 프롬프트가 어떻게 진화했는지, 어떤 변경이 있었는지 이해해 이슈를 디버깅하거나 변경의 영향을 파악하는 데 도움이 돼요.

보호된 프롬프트 라벨

이 기능은 어디서 사용할 수 있나요?

  • Hobby — 사용 불가
  • Core — 사용 불가
  • Pro — Teams 애드온 필요
  • Enterprise — 사용 가능
  • Self Hosted — Enterprise Edition

보호된 프롬프트 라벨은 프로젝트 관리자와 소유자(RBAC 문서)가 라벨이 수정되거나 삭제되는 것을 방지할 수 있게 해줘요. 프롬프트 배포에 대한 더 나은 제어를 보장하죠.

production 같은 라벨이 보호로 표시되면:

  • viewer와 member 역할은 프롬프트에서 라벨을 수정하거나 삭제할 수 없어요. 프로덕션 프롬프트 버전을 변경하는 것을 방지하고, 프롬프트 삭제도 차단해요.
  • admin과 owner 역할은 여전히 라벨을 수정하거나 삭제할 수 있어요. 즉 프로덕션 프롬프트 버전을 변경할 수 있죠.

관리자와 소유자는 프로젝트 설정에서 라벨의 보호 상태를 업데이트할 수 있어요.

관련 자료

더 알아보기 (Learn more)