프롬프트 관리 핵심 개념

프롬프트 관리 핵심 개념 (Core Concepts)

이 페이지는 프롬프트 관리의 개념과 모범 사례를 다뤄요. 아직 안 읽어봤다면, 애플리케이션 관찰성에서 프롬프트 관리가 왜 중요한지 알려주는 개요 페이지를 먼저 확인해 보세요.

출처: 문서

본문

시작할 준비가 됐다면 Get Started 가이드를 확인해 첫 프롬프트를 만들어 보세요.

프롬프트 객체 (The Prompt Object)

Langfuse는 프롬프트를 LLM에 대한 지침(단일 문자열 또는 메시지 배열일 수 있음)과, 선택적으로 동작에 영향을 주는 추가 구성의 조합으로 간주해요.

프롬프트 객체에는 버전, 변형(variant), 배포를 관리하기 위한 몇 가지 속성도 있어요. 이 페이지는 프롬프트를 생산적으로 사용하는 가장 중요한 원리를 안내할 거예요.

모든 프롬프트 객체 필드와 메서드에 대한 자세한 정보는 SDK 레퍼런스 문서를 참고하세요.

채팅 vs 텍스트 프롬프트

Langfuse는 두 가지 프롬프트 유형을 지원해요. type 필드가 형식을 결정하며 생성 후에는 변경할 수 없어요.

텍스트 프롬프트(Text prompts) 는 단일 문자열로, 간단한 사용 사례나 시스템 메시지만 필요한 경우에 적합해요.

채팅 프롬프트(Chat prompts) 는 특정 역할(system, user, assistant)을 가진 메시지 배열로, 완전한 대화 구조를 관리하거나 예시 교환을 포함하거나 채팅 기록을 처리하고 싶을 때 유용해요.

텍스트 프롬프트 예시:

{
  "name": "movie-critic",
  "type": "text",
  "prompt": "As a movie critic, do you like Dune 2?",
  "version": 1
}

채팅 프롬프트 예시:

{
  "name": "movie-critic-chat",
  "type": "chat",
  "prompt": [
    {
      "role": "system",
      "content": "You are a movie critic."
    },
    {
      "role": "user",
      "content": "Do you like Dune 2?"
    }
  ],
  "version": 1
}

채팅 프롬프트를 언제 사용하나요? 대부분의 애플리케이션은 텍스트 프롬프트로 시작해요. 여러 메시지, 역할 기반 구조, 채팅 기록을 관리해야 하는 더 복잡한 로직을 만들 때 채팅 프롬프트로 전환하는 것이 합리적이에요. 이렇게 하면 프롬프트 관리 시스템에서 완전한 대화 구조를 관리할 수 있어요.

프롬프트의 동적 렌더링

런타임에 동적으로 채울 수 있는 변수를 프롬프트에 추가할 수 있어요. 사용할 수 있는 변수 유형은 여러 가지인데, 아래에서 설명할게요.

프롬프트는 런타임에 동적 콘텐츠를 삽입하는 세 가지 방법을 지원해요:

| 유형 | 사용 사례 | | Variables | 메시지에 동적 텍스트 삽입 | | Prompt References | 다른 프롬프트에 걸쳐 프롬프트 재사용, 공통 지침 중복 방지 | | Message Placeholders | 메시지 배열 삽입 (예: 채팅 기록) |

프롬프트 캐싱

Langfuse 프롬프트 관리는 두 가지 주요 이유로 캐시된 프롬프트를 사용해요:

• 애플리케이션에 지연을 추가하지 않음
• 가용성 위험을 제거

즉, 프롬프트를 업데이트한 직후의 첫 몇 개 트레이스는 여전히 이전 버전을 사용할 수 있어요. 즉각적인 업데이트가 중요한 사용 사례라면 캐싱을 비활성화하거나 TTL(time-to-live)을 더 짧게 구성할 수 있어요.

캐싱이 어떻게 동작하고 어떻게 구성하는지 자세히 알아보려면 캐싱 문서를 참고하세요.

버전 관리와 라벨

프로덕션에서 프롬프트를 관리하려면 버전과 라벨이 어떻게 함께 동작하는지 이해하는 것이 필수적이에요. 두 개념은 서로 다르지만 보완적인 목적을 가져요.

버전(Versions) 은 모든 프롬프트 변경의 불변 이력을 제공해요. 업데이트할 때마다 새 버전(1, 2, 3...)이 생성돼요.

라벨(Labels) 은 특정 버전을 가리키는 포인터예요. 코드는 보통 라벨을 참조하죠. 일반적인 라벨은 다음과 같아요:

• production - 기본 라벨, 프로덕션 애플리케이션이 사용
• latest - 항상 최신 버전을 가리킴
• 커스텀 라벨 - 스테이징, 테스트, 테넌트 또는 A/B 테스트용 라벨 만들기

버전 관리와 라벨에 대해 더 알아보세요.

배포 워크플로우

다음은 프롬프트 변경을 배포하는 일반적인 워크플로우예요:

• 생성 및 테스트: 새 프롬프트 버전 생성 (자동으로 latest 라벨을 받음)
• 검증: 개발 환경 또는 플레이그라운드를 사용해 새 버전 테스트
• 배포: production 라벨이 새 버전을 가리키도록 업데이트
• 모니터링: 프로덕션 애플리케이션이 다음 조회 시 새 버전을 자동으로 가져옴
• 필요시 롤백: production 라벨을 이전 버전으로 다시 지정하기만 하면 됨

코드가 라벨을 참조하므로 이 모든 과정이 코드 변경 없이 일어나요.

더 알아보기 (Learn more)

• 출처 문서: 프롬프트 관리 핵심 개념 (Core Concepts)