프롬프트 관리

프롬프트 관리 (Prompt Management)

실험을 실행하거나 특정 모델(예: gpt-5.6-terra에서 gpt-5.6-luna 파인튜닝으로)을 애플리케이션에서 바꾸지 않고 프롬프트 관리 도구(예: Langfuse)에서 변경할 수 있어요.

다음 통합들을 지원해요: Neo LiteLLM GitOps(.prompt 파일), Langfuse, Humanloop, Generic Prompt Management API.

출처: 문서

본문

실험을 실행하거나 특정 모델(예: gpt-5.6-terra에서 gpt-5.6-luna 파인튜닝으로)을 애플리케이션에서 바꾸지 않고 프롬프트 관리 도구(예: Langfuse)에서 변경할 수 있어요.

지원 통합	링크
Neo LiteLLM GitOps (.prompt 파일)	Get Started
Langfuse	Get Started
Humanloop	Get Started
Generic Prompt Management API	Get Started

config.yaml로 프롬프트 온보딩하기

config.yaml 파일에서 직접 프롬프트를 온보딩하고 초기화할 수 있어요. 이를 통해:

• 프록시 시작 시 프롬프트 로드
• 프록시 설정 옆에 코드로 프롬프트 관리
• 지원되는 모든 프롬프트 통합(dotprompt, Langfuse, BitBucket, GitLab, custom) 사용

기본 구조

config.yaml에 prompts 필드를 추가하세요:

    model_list:
      - model_name: gpt-5.6-terra
        litellm_params:
          model: openai/gpt-5.6-terra
          api_key: os.environ/OPENAI_API_KEY

    prompts:
      - prompt_id: "my_prompt_id"
        litellm_params:
          prompt_id: "my_prompt_id"
          prompt_integration: "dotprompt"  # or langfuse, bitbucket, gitlab, generic_prompt_management, custom
          # integration-specific parameters below

prompt_integration 이해하기

prompt_integration 필드는 프롬프트가 어디서 어떻게 로드되는지 결정해요:

• dotprompt : 로컬 .prompt 파일 또는 인라인 콘텐츠에서 로드
• langfuse : Langfuse 프롬프트 관리에서 프롬프트 가져오기
• bitbucket : BitBucket 저장소 .prompt 파일에서 로드 (팀 기반 접근 제어)
• gitlab : GitLab 저장소 .prompt 파일에서 로드 (팀 기반 접근 제어)
• generic_prompt_management : 간단한 API 엔드포인트로 어떤 프롬프트 관리 시스템이든 통합 (PR 불필요)
• custom : 자체 커스텀 프롬프트 관리 구현 사용

각 통합은 자체 구성 파라미터와 접근 제어 메커니즘을 가져요.

지원 통합

• DotPrompt (파일 기반)
• Langfuse
• BitBucket
• GitLab
• Generic Prompt Management

옵션 1: 프롬프트 디렉터리 사용

    prompts:
      - prompt_id: "hello"
        litellm_params:
          prompt_id: "hello"
          prompt_integration: "dotprompt"
          prompt_directory: "./prompts"  # Directory containing .prompt files

    litellm_settings:
      global_prompt_directory: "./prompts"  # Global setting for all dotprompt integrations

옵션 2: 인라인 프롬프트 데이터 사용

    prompts:
      - prompt_id: "my_inline_prompt"
        litellm_params:
          prompt_id: "my_inline_prompt"
          prompt_integration: "dotprompt"
          prompt_data:
            my_inline_prompt:
              content: "Hello {{name}}! How can I help you with {{topic}}?"
              metadata:
                model: "gpt-5.6-terra"
                temperature: 0.7
                max_tokens: 150

옵션 3: 단일 프롬프트에 dotprompt_content 사용

    prompts:
      - prompt_id: "simple_prompt"
        litellm_params:
          prompt_id: "simple_prompt"
          prompt_integration: "dotprompt"
          dotprompt_content: |
            ---
            model: gpt-5.6-terra
            temperature: 0.7
            ---
            System: You are a helpful assistant.

            User: {{user_message}}

프롬프트 디렉터리에 .prompt 파일을 만드세요:

    # prompts/hello.prompt
    ---
    model: gpt-5.6-terra
    temperature: 0.7
    ---
    System: You are a helpful assistant.

    User: {{user_message}}

    prompts:
      - prompt_id: "my_langfuse_prompt"
        litellm_params:
          prompt_id: "my_langfuse_prompt"
          prompt_integration: "langfuse"
          langfuse_public_key: "os.environ/LANGFUSE_PUBLIC_KEY"
          langfuse_secret_key: "os.environ/LANGFUSE_SECRET_KEY"
          langfuse_host: "https://cloud.langfuse.com"  # optional

    litellm_settings:
      langfuse_public_key: "os.environ/LANGFUSE_PUBLIC_KEY"  # Global setting
      langfuse_secret_key: "os.environ/LANGFUSE_SECRET_KEY"  # Global setting

    prompts:
      - prompt_id: "my_bitbucket_prompt"
        litellm_params:
          prompt_id: "my_bitbucket_prompt"
          prompt_integration: "bitbucket"
          bitbucket_workspace: "your-workspace"
          bitbucket_repository: "your-repo"
          bitbucket_access_token: "os.environ/BITBUCKET_ACCESS_TOKEN"
          bitbucket_branch: "main"  # optional, defaults to main

    litellm_settings:
      global_bitbucket_config:
        workspace: "your-workspace"
        repository: "your-repo"
        access_token: "os.environ/BITBUCKET_ACCESS_TOKEN"
        branch: "main"

BitBucket 저장소에는 .prompt 파일이 있어야 해요:

    # prompts/my_bitbucket_prompt.prompt
    ---
    model: gpt-5.6-terra
    temperature: 0.7
    ---
    System: You are a helpful assistant.

    User: {{user_message}}

    prompts:
      - prompt_id: "my_gitlab_prompt"
        litellm_params:
          prompt_id: "my_gitlab_prompt"
          prompt_integration: "gitlab"
          gitlab_project: "group/sub/repo"
          gitlab_access_token: "os.environ/GITLAB_ACCESS_TOKEN"
          gitlab_branch: "main"  # optional
          gitlab_prompts_path: "prompts"  # optional, defaults to root

    litellm_settings:
      global_gitlab_config:
        project: "group/sub/repo"
        access_token: "os.environ/GITLAB_ACCESS_TOKEN"
        branch: "main"

GitLab 저장소에는 .prompt 파일이 있어야 해요:

    # prompts/my_gitlab_prompt.prompt
    ---
    model: gpt-5.6-terra
    temperature: 0.7
    ---
    System: You are a helpful assistant.

    User: {{user_message}}

    prompts:
      - prompt_id: "simple_prompt"
        litellm_params:
          prompt_integration: "generic_prompt_management"
          provider_specific_query_params:
            project_name: litellm
            slug: hello-world-prompt-2bac
          api_base: http://localhost:8080
          api_key: os.environ/GENERIC_PROMPT_API_KEY
          ignore_prompt_manager_model: true  # optional
          ignore_prompt_manager_optional_params: true  # optional

구현해야 할 것:

다음을 반환하는 /beta/litellm_prompt_management의 GET 엔드포인트:

    {
      "prompt_id": "simple_prompt",
      "prompt_template": [
        {
          "role": "system",
          "content": "You are a helpful assistant."
        },
        {
          "role": "user",
          "content": "Help me with {task}"
        }
      ],
      "prompt_template_model": "gpt-5.6-terra",
      "prompt_template_optional_params": {
        "temperature": 0.7,
        "max_tokens": 500
      }
    }

장점:

• PR 불필요 - 어떤 프롬프트 관리 시스템이든 통합
• 프롬프트 저장·버전 관리에 대한 완전한 제어
• {variable} 문법으로 변수 치환 지원
• 필터링·접근 제어를 위한 커스텀 쿼리 파라미터

더 알아보기: Generic Prompt Management API 문서

전체 예제 (Complete Example)

다른 통합을 사용하는 여러 프롬프트를 보여주는 전체 예제:

    model_list:
      - model_name: gpt-5.6-terra
        litellm_params:
          model: openai/gpt-5.6-terra
          api_key: os.environ/OPENAI_API_KEY

    prompts:
      # File-based dotprompt
      - prompt_id: "coding_assistant"
        litellm_params:
          prompt_id: "coding_assistant"
          prompt_integration: "dotprompt"
          prompt_directory: "./prompts"

      # Inline dotprompt
      - prompt_id: "simple_chat"
        litellm_params:
          prompt_id: "simple_chat"
          prompt_integration: "dotprompt"
          prompt_data:
            simple_chat:
              content: "You are a {{personality}} assistant. User: {{message}}"
              metadata:
                model: "gpt-5.6-terra"
                temperature: 0.8

      # Langfuse prompt
      - prompt_id: "langfuse_chat"
        litellm_params:
          prompt_id: "langfuse_chat"
          prompt_integration: "langfuse"
          langfuse_public_key: "os.environ/LANGFUSE_PUBLIC_KEY"
          langfuse_secret_key: "os.environ/LANGFUSE_SECRET_KEY"

    litellm_settings:
      global_prompt_directory: "./prompts"

동작 방식 (How It Works)

1. 시작 시 : 프록시가 시작하면 config.yaml에서 prompts 필드를 읽어요
2. 초기화 : 각 프롬프트가 prompt_integration 유형에 따라 초기화돼요
3. 인메모리 저장 : 프롬프트가 IN_MEMORY_PROMPT_REGISTRY에 저장돼요
4. 접근 : 요청의 prompt_id로 /v1/chat/completions 또는 /v1/responses에서 이 프롬프트를 사용해요

config 로드 프롬프트 사용하기

config.yaml로 프롬프트를 로드한 뒤 API 요청에서 사용해요:

    curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ***" \
    -d '{
        "model": "gpt-5.6-terra",
        "prompt_id": "coding_assistant",
        "prompt_variables": {
            "language": "python",
            "task": "create a web scraper"
        }
    }'

같은 prompt_id를 Responses API에서도 쓸 수 있어요:

    curl -L -X POST 'http://0.0.0.0:4000/v1/responses' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ***" \
    -d '{
        "model": "gpt-5.6-terra",
        "prompt_id": "coding_assistant",
        "prompt_variables": {
            "language": "python",
            "task": "create a web scraper"
        },
        "input": []
    }'

Prompt 스키마 레퍼런스

prompts 목록의 각 프롬프트는 다음을 요구해요:

• prompt_id (string, required): 프롬프트의 고유 식별자
• litellm_params (object, required): 프롬프트 설정
  • prompt_id (string, required): 최상위 prompt_id와 일치해야 함
  • prompt_integration (string, required): dotprompt, langfuse, bitbucket, gitlab, custom 중 하나
  • 통합별 추가 파라미터 (위 탭 참고)
• prompt_info (object, optional): 프롬프트에 대한 메타데이터
  • prompt_type (string): config 로드 프롬프트의 경우 기본 "config"

참고 (Notes)

• config 로드 프롬프트는 prompt_type: "config"를 가지며 API로 업데이트할 수 없어요
• config 프롬프트를 업데이트하려면 config.yaml을 수정하고 프록시를 재시작하세요
• API로 업데이트할 수 있는 동적 프롬프트는 /prompts 엔드포인트를 대신 사용하세요
• 모든 지원 통합이 config 로드 프롬프트에서 동작해요

빠른 시작 (Quick Start)

• SDK
• PROXY

    import os
    import litellm

    os.environ["LANGFUSE_PUBLIC_KEY"] = "public_key" # [OPTIONAL] set here or in `.completion`
    os.environ["LANGFUSE_SECRET_KEY"] = "secret_key" # [OPTIONAL] set here or in `.completion`

    litellm.set_verbose = True # see raw request to provider

    resp = litellm.completion(
        model="langfuse/gpt-5.6-luna",
        prompt_id="test-chat-prompt",
        prompt_variables={"user_message": "this is used"}, # [OPTIONAL]
        messages=[{"role": "user", "content": "<IGNORED>"}],
    )

1. config.yaml 설정하기

    model_list:
      - model_name: my-langfuse-model
        litellm_params:
          model: langfuse/openai-model
          prompt_id: "<langfuse_prompt_id>"
          api_key: os.environ/OPENAI_API_KEY
      - model_name: openai-model
        litellm_params:
          model: openai/gpt-5.6-luna
          api_key: os.environ/OPENAI_API_KEY

2. 프록시 시작하기

    litellm --config config.yaml --detailed_debug

3. 테스트하기!

• CURL
• OpenAI Python SDK

    curl -L -X POST 'http://0.0.0.0:4000/v1/chat/completions' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ***" \
    -d '{
        "model": "my-langfuse-model",
        "messages": [
            {
                "role": "user",
                "content": "THIS WILL BE IGNORED"
            }
        ],
        "prompt_variables": {
            "key": "this is used"
        }
    }'

    import openai
    client = openai.OpenAI(
        api_key="anything",
        base_url="http://0.0.0.0:4000"
    )

    # request sent to model set on litellm proxy, `litellm --model`
    response = client.chat.completions.create(
        model="gpt-5.6-luna",
        messages = [
            {
                "role": "user",
                "content": "this is a test request, write a short poem"
            }
        ],
        extra_body={
            "prompt_variables": { # [OPTIONAL]
                "key": "this is used"
            }
        }
    )

    print(response)

기대 로그:

    POST Request Sent from LiteLLM:
    curl -X POST \
    https://api.openai.com/v1/ \
    -d '{'model': 'gpt-5.6-luna', 'messages': <YOUR LANGFUSE PROMPT TEMPLATE>}'

모델 설정 방법 (How to set model)

LiteLLM에 모델 설정

langfuse/<litellm_model_name>을 할 수 있어요.

• SDK
• PROXY

    litellm.completion(
        model="langfuse/gpt-5.6-luna", # or `langfuse/anthropic/claude-sonnet-5`
        # ...
    )

    model_list:
      - model_name: gpt-5.6-luna
        litellm_params:
          model: langfuse/gpt-5.6-luna # OR langfuse/anthropic/claude-sonnet-5
          prompt_id: <langfuse_prompt_id>
          api_key: os.environ/OPENAI_API_KEY

Langfuse에 모델 설정

Langfuse 설정에 모델이 지정되어 있으면 그것이 사용돼요.

    model_list:
      - model_name: gpt-5.6-luna
        litellm_params:
          model: azure/chatgpt-v-2
          api_key: os.environ/AZURE_API_KEY
          api_base: os.environ/AZURE_API_BASE

'prompt_variables'란 무엇인가요?

• prompt_variables: 프롬프트의 일부를 바꾸는 데 사용될 변수 사전.

'prompt_id'란 무엇인가요?

• prompt_id: 요청에 사용될 프롬프트의 ID.

포맷된 프롬프트는 어떻게 생길까요?

/chat/completions messages

클라이언트가 보낸 messages 필드는 무시돼요.

Langfuse 프롬프트가 messages 필드를 대체해요.

프롬프트의 일부를 바꾸려면 prompt_variables 필드를 사용하세요. 프롬프트 변수가 어떻게 쓰이는지 보기

Langfuse 프롬프트가 문자열이면 user 메시지로 보내져요 (모든 공급자가 system 메시지를 지원하지 않으므로).

Langfuse 프롬프트가 목록이면 그대로 보내져요 (Langfuse 채팅 프롬프트는 OpenAI 호환).

아키텍처 개요 (Architectural Overview)

API 레퍼런스

SDK의 litellm.completion 함수와 config.yaml의 litellm_params에 전달할 수 있는 파라미터예요:

    prompt_id: str # required
    prompt_variables: Optional[dict] # optional
    prompt_version: Optional[int] # optional
    langfuse_public_key: Optional[str] # optional
    langfuse_secret: Optional[str] # optional
    langfuse_secret_key: Optional[str] # optional
    langfuse_host: Optional[str] # optional

더 알아보기 (Learn more)

• Neo LiteLLM GitOps 프롬프트 관리
• LiteLLM AI Gateway 프롬프트 관리
• Generic Prompt Management API