프롬프트 구성

프롬프트 구성 (Prompt Config)

Langfuse의 프롬프트 구성(config)은 각 프롬프트에 붙는 선택적인 임의의 JSON 객체로, LLM 호출을 실행하는 코드가 사용할 수 있어요. 일반적인 사용 사례는 다음과 같아요:

출처: 문서

본문

• 모델 파라미터 저장(model, temperature, max_tokens)
• 구조화된 출력 스키마 저장(response_format)
• 함수/도구 정의 저장(tools, tool_choice)

구성이 프롬프트와 함께 버전화되기 때문에 모든 파라미터를 한 곳에서 관리할 수 있어요. 이렇게 하면 애플리케이션 코드를 건드리지 않고 모델을 바꾸거나, 스키마를 업데이트하거나, 동작을 조정하기 쉬워요.

구성 설정하기

구성은 Langfuse 프롬프트 UI와 SDK 양쪽에서 설정할 수 있어요.

UIPython SDKJS/TS SDK

프롬프트의 구성을 추가하거나 편집하려면:

• Langfuse UI에서 Prompt Management로 이동
• 프롬프트 선택 또는 생성
• 프롬프트 편집기에서 Config 필드(JSON 편집기) 찾기
• 구성을 유효한 JSON 객체로 입력
• 프롬프트 저장 — 이제 구성이 이 프롬프트 버전과 함께 버전화됨

프롬프트를 만들거나 업데이트할 때 config 파라미터를 전달하세요:

from langfuse import get_client

langfuse = get_client()

# example config with a model and temperature
config = {
    "model": "gpt-4o",
    "temperature": 0
}

langfuse.create_prompt(
  name="invoice-extractor",
  type="chat",
  prompt=[
    {
      "role": "system",
      "content": "Extract structured data from invoices."
      }
  ],
  config=config
)

프롬프트를 만들거나 업데이트할 때 config 파라미터를 전달하세요:

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

const langfuse = new LangfuseClient();

// example config with a model and temperature
const config = {
  model: "gpt-4o",
  temperature: 0
}

await langfuse.prompt.create({
  name: "invoice-extractor",
  type: "chat",
  prompt: [
    { role: "system", content: "Extract structured data from invoices." }
  ],
  config: config
});

Playground에서 구성과 함께 프롬프트를 직접 테스트할 수 있어요.

구성 사용하기

아래 예시는 프롬프트 구성에서 AI 모델과 temperature를 가져와요.

프롬프트를 가져온 후 config 속성으로 구성에 접근하고 그 값을 LLM 호출에 전달하세요.

Python SDKJS/TS SDK

이 예시는 트레이싱을 위해 Langfuse OpenAI 통합을 사용하지만, 이는 선택 사항이에요. LLM을 호출하는 어떤 방법이든 사용할 수 있어요(예: OpenAI SDK 직접 사용, 다른 공급자 등).

from langfuse import get_client

# Initialize Langfuse OpenAI client for this example.
from langfuse.openai import OpenAI
client = OpenAI()

langfuse = get_client()

# Fetch prompt
prompt = langfuse.get_prompt("invoice-extractor")

# Access config values
cfg = prompt.config
model = cfg.get("model")
temperature = cfg.get("temperature")

# Use in your LLM call
client.chat.completions.create(
  model=model,
  temperature=temperature,
  messages=prompt.prompt
)

이 예시는 트레이싱을 위해 Langfuse OpenAI 통합을 사용하지만, 이는 선택 사항이에요. LLM을 호출하는 어떤 방법이든 사용할 수 있고(예: OpenAI SDK 직접 사용, 다른 공급자 등) 여전히 구성을 사용할 수 있어요.

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

// Initialize OpenAI client for this example.
import OpenAI from "openai";
import { observeOpenAI } from "@langfuse/openai";
const client = observeOpenAI(new OpenAI());

const langfuse = new LangfuseClient();

// Fetch prompt
const prompt = await langfuse.prompt.get("invoice-extractor");

// Access config values
const cfg = prompt.config;
const model = cfg.model;
const temperature = cfg.temperature;

// Use in your LLM call
client.chat.completions.create({
  model,
  temperature,
  messages: prompt.prompt
});

예시 사용 사례

구조화된 출력 (Structured Outputs)

LLM이 특정 JSON 형식으로 데이터를 반환해야 할 때, 그 스키마를 프롬프트 구성에 저장하세요. 이렇게 하면 스키마가 프롬프트와 함께 버전화되고 코드 변경 없이 업데이트할 수 있어요.

모범 사례: response_format을 type: "json_schema"와 strict: true로 사용해 스키마를 강제하세요. 이렇게 하면 모델의 출력이 예상한 구조와 정확히 일치해요. Pydantic 모델을 사용한다면 type_to_response_format_param으로 변환하세요 — OpenAI Structured Outputs 가이드 참고.

from langfuse import get_client
from langfuse.openai import OpenAI

langfuse = get_client()
client = OpenAI()

# Fetch prompt with config containing response_format
prompt = langfuse.get_prompt("invoice-extractor")
system_message = prompt.compile()

# Extract parameters from config
cfg = prompt.config

# Example config:
# {
#   "response_format": {
#     "type": "json_schema",
#     "json_schema": {
#       "name": "invoice_schema",
#       "schema": {
#         "type": "object",
#         "properties": {
#           "invoice_number": { "type": "string" },
#           "total": { "type": "number" }
#         },
#         "required": ["invoice_number", "total"],
#         "additionalProperties": false
#       },
#       "strict": true
#     }
#   }
# }

response_format = cfg.get("response_format")

res = client.chat.completions.create(
  model="gpt-4o",
  messages=[
    {"role": "system", "content": system_message},
    {"role": "user", "content": "Extract invoice number and total from: ..."},
  ],
  response_format=response_format,
  langfuse_prompt=prompt,  # Links this generation to the prompt version in Langfuse
)

# Response is guaranteed to match your schema
content = res.choices[0].message.content

함수 호출 (Function Calling)

에이전트와 도구 사용 애플리케이션의 경우 프롬프트 구성에 함수 정의를 저장하세요. 이렇게 하면 사용 가능한 도구를 프롬프트와 함께 버전화하고 업데이트할 수 있어요.

모범 사례: tools(JSON Schema 파라미터가 있는 함수 정의)와 tool_choice를 구성에 저장하세요. 이렇게 하면 함수 시그니처가 버전화되고 코드 배포 없이 도구를 추가·수정·제거할 수 있어요.

from langfuse import get_client
from langfuse.openai import OpenAI

langfuse = get_client()
client = OpenAI()

# Fetch prompt with config containing tools
prompt = langfuse.get_prompt("weather-agent")
system_message = prompt.compile()

# Extract parameters from config
cfg = prompt.config

# Example config:
# {
#   "tools": [
#     {
#       "type": "function",
#       "function": {
#         "name": "get_current_weather",
#         "description": "Get the current weather in a given location",
#         "parameters": {
#           "type": "object",
#           "properties": {
#             "location": { "type": "string", "description": "City and country" },
#             "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
#           },
#           "required": ["location"],
#           "additionalProperties": false
#         }
#       }
#     }
#   ],
#   "tool_choice": { "type": "auto" }
# }

tools = cfg.get("tools", [])
tool_choice = cfg.get("tool_choice")

res = client.chat.completions.create(
  model="gpt-4o",
  messages=[
    {"role": "system", "content": system_message},
    {"role": "user", "content": "What's the weather in Berlin?"},
  ],
  tools=tools,
  tool_choice=tool_choice,
  langfuse_prompt=prompt,  # Links this generation to the prompt version in Langfuse
)

완전한 엔드투엔드 예시는 OpenAI Functions cookbook과 Structured Outputs 문서를 참고하세요.

더 알아보기 (Learn more)

• 출처 문서: 프롬프트 구성 (Prompt Config)