프롬프트 버전 관리
프롬프트 버전 관리 (Version Prompts)
프롬프트의 서로 다른 버전을 만들고 관리하는 방법을 배워볼게요. 프롬프트 버전 관리를 통해 프롬프트의 여러 버전을 최적화하고 테스트할 수 있어요. 프롬프트를 GitHub나 CSV, 코드의 메모리에 두는 곳은 많지만, Confident AI에 두어야만 평가 기능을 온전히 활용할 수 있어요.
출처: 문서
본문
개요
프롬프트 버전 관리를 통해 프롬프트의 여러 버전을 최적화하고 테스트할 수 있어요. Confident AI에서 프롬프트를 관리하면:
- 비기술적 팀원도 포함해 프롬프트가 저장되고 편집되는 곳을 중앙화·협업할 수 있어요
- 어떤 버전(또는 프롬프트 버전들의 어떤 조합)이 가장 잘 수행했는지 정확히 짚어낼 수 있어요
- 모델 설정, 아웃풋 타입, 툴을 프롬프트와 함께 배치해 단일 단위로 버전화할 수 있어요(선택)
프롬프트를 둘 곳은 정말 많아요 — GitHub, CSV 파일, 코드의 메모리, Google Sheets, Notion, 심지어 책상 서랍 아래 숨겨진 일기장까지요. 하지만 Confident AI에 프롬프트를 두어야만 Confident AI의 평가 기능을 완전히 활용할 수 있어요.
프롬프트는 Confident AI의 하이퍼파라미터 유형 중 하나예요. 다른 것에는 모델, 임베더(embedder), top-K, max tokens 같은 것들이 있어요. Confident AI에 있는 프롬프트로 평가를 실행하면 어떤 버전이 가장 잘 수행하는지 알려주고, 나중에는 자동으로 최적화해줘요.
프롬프트 vs 프롬프트 + 모델 구성: Confident AI를 순수하게 프롬프트 버전 관리에만 쓸 수 있어요 — 프롬프트를 가져와 코드에서 설정한 어떤 모델이든 함께 사용하면 돼요. 반대로 프롬프트와 모델 구성을 단일 버전 단위로 함께 관리하고 싶다면, 프롬프트 버전에 모델 설정, 아웃풋 타입, 툴을 붙일 수 있어요.
프롬프트 유형 (Types of Prompts)
만들 수 있는 프롬프트는 두 가지가 있어요:
- (싱글) 텍스트 프롬프트 (Text Prompt): 단순한 완료를 위한 직관적인 일회성 프롬프트가 필요할 때 사용해요.
- 프롬프트 메시지 목록 (Prompt Message List): OpenAI messages 형식으로 특정 역할(system, user, assistant)을 가진 여러 메시지를 정의해야 할 때 사용해요. 컨텍스트를 설정하는 system 메시지로 시작할 수 있는 few-shot 프롬프팅에 이상적이에요.
프롬프트가 "message"나 "list" 언급 없이 언급된다면 싱글 프롬프트를 말하는 것으로 간주하세요.
프롬프트 버전 관리 이해하기 (Understanding Prompt Versioning)
Confident AI에서 각 프롬프트는 고유한 alias로 식별돼요. 이 alias는 고유 식별자 역할을 하며 단일하고 특정한 프롬프트를 가리켜요. 다른 alias는 완전히 별개의 프롬프트를 가리켜요.
프롬프트에 대한 모든 변경은 **커밋(commit)**으로 추적돼요. 이를 통해 모든 프롬프트 수정의 완전한 기록과 추적 가능성이 보장돼요. 커밋을 안정 릴리스로 표시할 준비가 되면 **버전(version)**으로 승격할 수 있어요.
예시
MyPrompt라는 alias를 가진 프롬프트가 있다고 해볼게요. 모든 편집이 새 커밋을 만듭니다. 특정 커밋을 버전으로 승격할 수 있어요.flowchart TD MyPrompt["Alias: MyPrompt"] MyPrompt --> C1["Commit 1"] MyPrompt --> C2["Commit 2"] MyPrompt --> C3["Commit 3 → Version 00.00.01"] MyPrompt --> C4["Commit 4"] MyPrompt --> C5["Commit 5 → Version 00.00.02"]
- 커밋 (Commit): 프롬프트에 대한 모든 변경이 새 커밋을 만들어요. 커밋은 자동으로 추적되며 모든 수정의 완전한 기록을 제공해요.
- 버전 (Version): 안정 릴리스를 나타내는 승격된 커밋이에요. 버전 번호는 Confident AI가
00.00.0X형식(예:00.00.01,00.00.02)으로 제어해요. - 라벨 (Label): 라벨(
staging이나production같은)은 커밋이 아닌 버전에만 지정할 수 있어요. 이를 통해 안정적이고 버전화된 프롬프트만 다른 환경에 배포되도록 보장해요.
새 프롬프트 커밋하기 (Commit a New Prompt)
Project > Prompt Studio에서 두 단계로 프롬프트를 만들 수 있어요:
- 텍스트 또는 메시지 프롬프트 만들기
- 프롬프트 에디터에서 변경 사항을 편집하고 커밋
프롬프트는 텍스트와 메시지 프롬프트를 동시에 될 수 없어요.
Messages
Create Prompt Messages
Text
Create Prompt Text
편집을 마친 후 커밋하지 않는 것을 잊지 마세요. 모든 커밋이 추적되고, 나중에 어떤 커밋이든 버전으로 승격할 수 있어요. 코드에서도 커밋을 만들 수 있어요.
새 버전은 가장 최근 버전화된 커밋 이후에 만들어진 커밋에만 만들 수 있어요. 기존 버전 이전에 만들어진 커밋은 버전으로 승격할 수 없어요.
모델 설정, 아웃풋 타입, 툴을 포함한 더 고급 푸시 옵션은 프롬프트 관리 자동화를 참고하세요.
템플릿 옵션 (Templating Options)
동적 변수 (Dynamic variables)
나중에 LLM 애플리케이션에서 동적으로 보간할 수 있는 변수를 포함할 수 있어요. 다섯 가지 보간 유형이 있어요:
| Type | Syntax | Example |
|---|---|---|
FSTRING |
{variable} |
Hello, {name}! |
MUSTACHE |
{{variable}} |
Hello, {{name}}! |
MUSTACHE_WITH_SPACE |
{{ variable }} |
Hello, {{ name }}! |
DOLLAR_BRACKETS |
${variable} |
Hello, ${name}! |
JINJA |
{% ... %} |
{% if admin %}Hello!{% endif %} |
변수 이름에는 공백이 있으면 안 돼요:
# ✅ Correct usage:
"Hi, my name is {name}."
"The temperature is {temperature} degrees."
"User input: {user_input}"
# ❌ Incorrect usage:
"Hi, my name is {variable name}." # Spaces in variable name
조건부 로직 (Conditional logic)
JINJA 보간을 사용할 때 조건부 로직을 추가할 수 있어요. JINJA는 jinja templates를 지원하며, 조건부 if/else 블록 같은 더 복잡한 로직을 렌더링할 수 있게 해줘요:
{% if is_admin %}
Welcome back, mighty admin {{ name }}!
{% else %}
Hello {{ name }}, you have regular access.
{% endif %}
for 루프도 지원해요:
Shopping List:
{% for item in items %}
- {{ item }}
{% endfor %}
Jinja로 보간된 프롬프트는 Python 사용자에게만 제공돼요.
이미지 포함 (Including images)
텍스트 영역에 무언가를 끌어다 놓기만 해도 이미지를 포함할 수 있어요.
Prompt with images
모델 구성 (Model Configs)
프롬프트를 만들고 편집하는 것 외에도, 프롬프트와 연관된 모델 설정, 아웃풋 타입, 툴을 구성할 수 있어요. 이 구성들은 각 커밋에 포함되어 다음을 할 수 있게 해줘요:
- 프롬프트 변경뿐 아니라 모델 구성 변경도 추적
- 코드에서 프롬프트를 가져올 때 코드에서 직접 사용
- AI 앱에 실험을 실행할 때 같은 프롬프트에 대한 모델의 영향을 비교(그 반대도 가능)
Confident AI에 프롬프트의 모델 구성을 두는 것은 해롭지 않지만, 꼭 써야 한다는 뜻은 아니에요 — 코드에서든 플랫폼의 Arena나 실험 실행에서든요. 모델 구성이 헷갈린다면 빼도 괜찮아요.
모델 설정 (Model settings)
각 프롬프트에 대해 모델 프로바이더, 모델 이름, 모델 파라미터를 구성할 수 있어요. 이 설정들은 각 커밋과 함께 추적되어, 코드에서 프롬프트를 가져올 때 실행에 필요한 정확한 모델 구성을 함께 얻게 돼요.
Configure Model Settings
| 필드 | 설명 | 예시 |
|---|---|---|
| Provider | LLM 프로바이더 (예: OpenAI, Anthropic, Azure) | openai |
| Model | 특정 모델 이름 | gpt-4.1 |
| Parameters | temperature, max tokens 같은 모델별 파라미터 | {"temperature": 0.7, "max_tokens": 1024} |
예시
커스텀 temperature와 max tokens를 가진 OpenAI GPT-4.1 구성의 경우:
- Provider:
openai- Model:
gpt-4.1- Parameters:
{ "temperature": 0.7, "max_tokens": 1024 }
아웃풋 타입 (Output type)
아웃풋 타입을 선택해 프롬프트의 예상 아웃풋 형식을 지정할 수 있어요. 이 구성은 각 커밋과 함께 추적돼요:
- Text Output: 표준 텍스트 응답 (기본값)
- JSON Output: 구조화된 JSON 응답
- Schema Output: 정의된 스키마를 따르는 구조화된 응답
Configure Output Type
Schema Output을 사용하면 LLM 응답이 따라야 할 커스텀 스키마를 정의할 수 있어요. 구조적이고 예측 가능한 아웃풋을 보장할 때 유용해요.
스키마를 구성하려면:
- 아웃풋 타입 드롭다운에서 Schema Output을 클릭
- Schema Name 입력 (필수)
- Schema Fields를 속성 이름과 타입(String, Number, Boolean 등)과 함께 추가
- Save Schema 클릭
Configure Schema Output
스키마는 Pydantic BaseModel 클래스로 미리 보여져, 구조화된 아웃풋이 어떻게 생길지 쉽게 시각화할 수 있어요.
툴 붙이기 (Attach tools)
함수 호출(function calling) 기능을 위해 프롬프트에 툴을 붙일 수 있어요. 이를 통해 LLM이 웹 검색, API, 커스텀 함수 같은 외부 툴을 호출할 수 있어요. 툴 구성은 각 커밋과 함께 추적돼요.
툴을 붙이려면:
- 프롬프트 에디터에서 Tools 버튼 클릭
- 사용 가능한 툴 검색
- 이 프롬프트 버전에서 활성화할 툴 선택
Attach Tools
프롬프트 라벨 지정 (Assign Prompt Labels)
라벨은 버전에만 지정할 수 있고 커밋에는 지정할 수 없어요. 이를 통해 안정적이고 버전화된 프롬프트만 다른 환경에 배포되도록 보장해요. Version History 페이지에서 라벨을 지정할 수 있어, 특정 환경에 새 버전을 "배포"하기 위해 코드를 바꿀 필요가 없어요.
라벨을 지정하려면 먼저 커밋을 버전으로 승격한 다음, 그 버전에 원하는 라벨(예: staging, production)을 지정해요.
충분한 권한이 있는 사용자만 프롬프트 라벨을 수정할 수 있어요.
다음 섹션에서 더 깊이 다루겠지만, 이것이 Python에서 라벨로 프롬프트를 가져오는 방법이에요:
from deepeval.prompt import Prompt prompt = Prompt(alias="YOUR-PROMPT-ALIAS") prompt.pull(label="staging")
다음 단계
이제 플랫폼에서 프롬프트를 버전화하는 방법을 알았으니, 평가에서 활용해볼게요.
실험 (Experiments)
프롬프트 버전을 통계적으로 엄밀하게 나란히 비교해요.
싱글턴 평가 (Single-Turn Evals)
코드를 쓰지 않고 프롬프트에서 평가를 실행해요.
프롬프트 가져오기 (Pull Prompts)
프롬프트 버전을 코드로 가져와 LLM 앱에서 사용해요.
프롬프트 관리 자동화
Confident API를 통해 프롬프트를 프로그래밍 방식으로 푸시하고 관리해요.