프롬프트 관리 시작하기

프롬프트 관리 시작하기 (Get Started with Prompt Management)

이 가이드는 Langfuse로 프롬프트를 만들고 사용하는 과정을 안내해요. 프롬프트 관리가 무엇이고 왜 중요한지 이해하고 싶다면 먼저 프롬프트 관리 개요를 확인해 보세요. Langfuse에서 프롬프트가 어떻게 구조화되고 백그라운드에서 어떻게 작동하는지 자세히 알아보려면 핵심 개념 (Core Concepts)을 참고하세요.

출처: 문서

본문

에이전트 설치

Langfuse Agent Skill을 설치하면 코딩 에이전트가 모든 Langfuse 기능에 접근할 수 있어요.

코딩 에이전트에게 요청Cursor 플러그인수동 설치

코딩 에이전트에게 GitHub 저장소를 가리키며 스킬을 설치하고 프롬프트를 마이그레이션하라고 지시하세요.

Agent instruction

Install the Langfuse Agent Skill from github.com/langfuse/skills
and use it to migrate the prompts in this codebase to Langfuse.

Langfuse는 스킬을 자동으로 포함하는 Cursor Plugin을 제공해요.

Install Plugin in Cursor

그런 다음 에이전트에게 요청하세요:

Agent instruction

Migrate the prompts in this codebase to Langfuse.

npm을 통한 설치(skills CLI):

npx skills add langfuse/skills --skill "langfuse"

특정 에이전트를 직접 지정하려면:

npx skills add langfuse/skills --skill "langfuse" --agent "<agent-id>"

수동으로 스킬 복제하기

• 안정적인 위치에 저장소를 클론하세요

git clone https://github.com/langfuse/skills.git /path/to/langfuse-skills

• 에이전트의 skills 디렉토리가 존재하는지 확인하세요

mkdir -p /path/to/<agent-skill-root>/skills

• 스킬 폴더를 심링크하세요

ln -s /path/to/langfuse-skills/skills/langfuse /path/to/<agent-skill-root>/skills/langfuse

그런 다음 에이전트에게 요청하세요:

Agent instruction

Migrate the prompts in this codebase to Langfuse.

수동 설치

이 가이드는 Langfuse 프롬프트 관리를 수동으로 시작하는 데 도움을 줘요.

API 키 얻기

• Langfuse 계정 만들기 또는 Langfuse 셀프 호스트.
• 프로젝트 설정에서 새 API 자격 증명을 만들어요.

프롬프트 만들기

Langfuse UIPython SDKJS/TS SDKAPIMigrate from existing code

Langfuse UI를 사용해 새 프롬프트를 만들거나 기존 프롬프트를 업데이트해요. 프롬프트 유형을 선택해야 하며, 이후에는 바꿀 수 없어요.

pip install langfuse

SDK가 어떤 프로젝트에 프롬프트를 만들지 알도록 Langfuse 자격 증명을 환경 변수로 추가해요.

.env

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://cloud.langfuse.com" # 🇪🇺 EU region
# Other Langfuse data regions include 🇺🇸 US: https://us.cloud.langfuse.com, 🇯🇵 Japan: https://jp.cloud.langfuse.com and ⚕️ HIPAA: https://hipaa.cloud.langfuse.com

Python SDK를 사용해 새 프롬프트를 만들거나 기존 프롬프트를 업데이트해요.

# Create a text prompt
langfuse.create_prompt(
    name="movie-critic",
    type="text",
    prompt="As a {{criticlevel}} movie critic, do you like {{movie}}?",
    labels=["production"]  # optionally, directly promote to production
)

# Create a chat prompt
langfuse.create_prompt(
    name="movie-critic-chat",
    type="chat",
    prompt=[
      { "role": "system", "content": "You are an {{criticlevel}} movie critic" },
      { "role": "user", "content": "Do you like {{movie}}?" },
    ],
    labels=["production"]  # optionally, directly promote to production
)

이미 같은 이름의 프롬프트가 있다면 새 버전으로 추가돼요.

npm i @langfuse/client

SDK가 어떤 프로젝트에 프롬프트를 만들지 알도록 Langfuse 자격 증명을 환경 변수로 추가해요.

.env

LANGFUSE_SECRET_KEY = "sk-lf-..."
LANGFUSE_PUBLIC_KEY = "pk-lf-..."
LANGFUSE_BASE_URL = "https://cloud.langfuse.com" # 🇪🇺 EU region
# Other Langfuse data regions include 🇺🇸 US: https://us.cloud.langfuse.com, 🇯🇵 Japan: https://jp.cloud.langfuse.com and ⚕️ HIPAA: https://hipaa.cloud.langfuse.com

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

const langfuse = new LangfuseClient();

JS/TS SDK를 사용해 새 프롬프트를 만들거나 기존 프롬프트를 업데이트해요.

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

// Create a chat prompt
await langfuse.prompt.create({
  name: "movie-critic-chat",
  type: "chat",
  prompt: [
    { role: "system", content: "You are an {{criticlevel}} movie critic" },
    { role: "user", content: "Do you like {{movie}}?" },
  ],
  labels: ["production"] // optionally, directly promote to production
});

이미 같은 이름의 프롬프트가 있다면 새 버전으로 추가돼요.

Public API를 사용해 새 프롬프트를 만들거나 기존 프롬프트를 업데이트해요.

curl -X POST "https://cloud.langfuse.com/api/public/v2/prompts" \
  -u "your-public-key:your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "chat",
    "name": "movie-critic",
    "prompt": [
      { "role": "system", "content": "You are an {{criticlevel}} movie critic" },
      { "role": "user", "content": "Do you like {{movie}}?" }
    ]
  }'

API Reference

기존 코드에서 마이그레이션

기존 코드베이스에 프롬프트가 있다면 프로그래밍 방식으로 Langfuse에 마이그레이션할 수 있어요.

Langfuse Skill 사용

• Langfuse Skill 설치:

# Cursor plugin
/add-plugin langfuse

# skills CLI
npx skills add langfuse/skills --skill "langfuse"

# Manual: clone and symlink
git clone https://github.com/langfuse/skills.git /path/to/langfuse-skills
ln -s /path/to/langfuse-skills/skills/langfuse ~/.skills/langfuse

• 에이전트에게 프롬프트 마이그레이션을 요청:

Migrate the hardcoded prompts in this codebase to Langfuse prompt management.

API 사용

기존 프롬프트를 읽어 Public API로 Langfuse에 만드는 스크립트를 작성할 수 있어요. 대량 마이그레이션이나 CI/CD 통합에 이상적이에요.

API Reference

주의할 점:

• Langfuse는 변수, 프롬프트 참조, 메시지 플레이스홀더에 특정 구문을 사용해요. Langfuse의 동적 렌더링 기능을 사용하려면 프롬프트를 올바른 형식으로 업데이트하세요.

코드에서 프롬프트 사용하기

런타임에 Langfuse에서 프롬프트를 가져올 수 있어요. 프로덕션용으로 의도적으로 선택된 버전을 가져오려면 production 라벨을 사용할 것을 권장해요. (버전/라벨) 제어에 대해 더 알아보려면 여기를 참고하세요.

Python SDKJS/TS SDKAPIOpenAI SDK (Python)OpenAI SDK (JS/TS)Langchain (Python)Langchain (JS)Vercel AI SDK

from langfuse import get_client

# Initialize Langfuse client
langfuse = get_client()

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

텍스트 프롬프트

# By default, the production version is fetched.
prompt = langfuse.get_prompt("movie-critic")

# Insert variables into prompt template
compiled_prompt = prompt.compile(criticlevel="expert", movie="Dune 2")
# -> "As an expert movie critic, do you like Dune 2?"

채팅 프롬프트

# By default, the production version of a chat prompt is fetched.
chat_prompt = langfuse.get_prompt("movie-critic-chat", type="chat") # type arg infers the prompt type (default is 'text')

# Insert variables into chat prompt template
compiled_chat_prompt = chat_prompt.compile(criticlevel="expert", movie="Dune 2")
# -> [{"role": "system", "content": "You are an expert movie critic"}, {"role": "user", "content": "Do you like Dune 2?"}]

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

// Initialize the Langfuse client
const langfuse = new LangfuseClient();

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

텍스트 프롬프트

// By default, the production version of a text prompt is fetched.
const prompt = await langfuse.prompt.get("movie-critic");

// Insert variables into prompt template
const compiledPrompt = prompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});
// -> "As an expert movie critic, do you like Dune 2?"

채팅 프롬프트

// By default, the production version of a chat prompt is fetched.
const chatPrompt = await langfuse.prompt.get("movie-critic-chat", {
  type: "chat",
}); // type option infers the prompt type (default is 'text')

// Insert variables into chat prompt template
const compiledChatPrompt = chatPrompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});
// -> [{"role": "system", "content": "You are an expert movie critic"}, {"role": "user", "content": "Do you like Dune 2?"}]

Public API를 사용해 런타임에 프롬프트를 가져와요. 기본적으로 production 라벨이 있는 프롬프트가 반환돼요.

curl "https://cloud.langfuse.com/api/public/v2/prompts/movie-critic?label=production" \
  -u "your-public-key:your-secret-key"

라벨 대신 특정 버전을 가져오려면:

curl "https://cloud.langfuse.com/api/public/v2/prompts/movie-critic?version=1" \
  -u "your-public-key:your-secret-key"

API Reference

pip install langfuse openai

import openai
from langfuse import get_client

# Initialize Langfuse client
langfuse = get_client()

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

텍스트 프롬프트

# By default, the production version of a text prompt is fetched.
prompt = langfuse.get_prompt("movie-critic")

# Compile the prompt with variables
compiled_prompt = prompt.compile(criticlevel="expert", movie="Dune 2")

# Use with OpenAI - prompt is a string
completion = openai.chat.completions.create(
  model="gpt-4o",
  messages=[{"role": "user", "content": compiled_prompt}]
)

채팅 프롬프트

# By default, the production version of a chat prompt is fetched.
chat_prompt = langfuse.get_prompt("movie-critic-chat", type="chat")

# Compile the prompt with variables - returns a list of message dicts
compiled_chat_prompt = chat_prompt.compile(criticlevel="expert", movie="Dune 2")

# Use with OpenAI - prompt is a list of messages
completion = openai.chat.completions.create(
  model="gpt-4o",
  messages=compiled_chat_prompt
)

예시 노트북

Example Cookbook

npm install @langfuse/openai openai

import { observeOpenAI } from "@langfuse/openai";
import { LangfuseClient } from "@langfuse/client";
import OpenAI from "openai";

// Initialize Langfuse client
const langfuse = new LangfuseClient();

// Wrap OpenAI client
const openai = observeOpenAI(new OpenAI());

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

텍스트 프롬프트

// By default, the production version of a text prompt is fetched.
const prompt = await langfuse.prompt.get("movie-critic", {
  type: "text",
});

// Compile the prompt with variables
const compiledPrompt = prompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});

// Use with OpenAI - prompt is a string
const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: compiledPrompt }],
});

채팅 프롬프트

// By default, the production version of a chat prompt is fetched.
const chatPrompt = await langfuse.prompt.get("movie-critic-chat", {
  type: "chat",
});

// Compile the prompt with variables - returns an array of messages
const compiledChatPrompt = chatPrompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});

// Use with OpenAI - prompt is an array of messages
const completion = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: compiledChatPrompt,
});

from langfuse import Langfuse
from langchain_core.prompts import ChatPromptTemplate

# Initialize Langfuse client
langfuse = Langfuse()

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

이 예시들은 변수를 포함해요. Langfuse와 Langchain은 프롬프트 템플릿의 입력 변수를 다르게 처리하므로({} 대신 {{}}), prompt.get_langchain_prompt() 메서드를 제공해 Langfuse 프롬프트를 Langchain의 PromptTemplate에서 사용할 수 있는 문자열로 변환해요. 일부 변수를 미리 컴파일하고 나머지를 Langchain의 PromptTemplate으로 처리하려면 prompt.get_langchain_prompt(**kwargs)에 선택적 키워드 인자를 전달할 수 있어요.

텍스트 프롬프트

# By default, the production version of a text prompt is fetched.
langfuse_prompt = langfuse.get_prompt("movie-critic")

# Example using ChatPromptTemplate
langchain_prompt = ChatPromptTemplate.from_template(langfuse_prompt.get_langchain_prompt())

# Example using ChatPromptTemplate with pre-compiled variables.
langchain_prompt = ChatPromptTemplate.from_template(langfuse_prompt.get_langchain_prompt(strictness='tough'))

채팅 프롬프트

# By default, the production version of a chat prompt is fetched.
langfuse_prompt = langfuse.get_prompt("movie-critic-chat", type="chat")

# Create a Langchain ChatPromptTemplate from the Langfuse prompt chat messages
langchain_prompt = ChatPromptTemplate.from_messages(langfuse_prompt.get_langchain_prompt())

예시 노트북

Example Cookbook

import { LangfuseClient } from "@langfuse/client";
import { ChatPromptTemplate } from "@langchain/core/prompts";

const langfuse = new LangfuseClient();

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

이 예시들은 변수를 포함해요. Langfuse와 Langchain은 프롬프트 템플릿의 입력 변수를 다르게 처리하므로({} 대신 {{}}), prompt.get_langchain_prompt() 메서드를 제공해 Langfuse 프롬프트를 Langchain의 PromptTemplate에서 사용할 수 있는 문자열로 변환해요. 일부 변수를 미리 컴파일하고 나머지를 Langchain의 PromptTemplate으로 처리하려면 prompt.get_langchain_prompt(**kwargs)에 선택적 키워드 인자를 전달할 수 있어요.

텍스트 프롬프트

// Get current `production` version
const langfusePrompt = await langfuse.prompt.get("movie-critic");

// Example using ChatPromptTemplate
const promptTemplate = PromptTemplate.fromTemplate(
  langfusePrompt.getLangchainPrompt()
);

채팅 프롬프트

// Get current `production` version of a chat prompt
const langfusePrompt = await langfuse.prompt.get(
  "movie-critic-chat",
  { type: "chat" }
);

// Example using ChatPromptTemplate
const promptTemplate = ChatPromptTemplate.fromMessages(
  langfusePrompt.getLangchainPrompt().map((msg) => [msg.role, msg.content])
);

예시 노트북

Example Cookbook.

Vercel AI SDK와 함께 Langfuse 프롬프트 관리를 사용하세요.

npm install @langfuse/client ai

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { LangfuseClient } from "@langfuse/client";

// Initialize Langfuse client
const langfuse = new LangfuseClient();

다음은 텍스트 유형 프롬프트와 채팅 유형 프롬프트에 대한 코드 예시예요. 프롬프트 유형에 대해 더 알아보려면 여기를 참고하세요.

텍스트 프롬프트

// By default, the production version of a text prompt is fetched.
const prompt = await langfuse.prompt.get("movie-critic", {
  type: "text",
});

// Compile the prompt with variables
const compiledPrompt = prompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});

// Use with Vercel AI SDK
const result = await generateText({
  model: openai("gpt-4o"),
  prompt: compiledPrompt,
  experimental_telemetry: {
    isEnabled: true,
  },
});

채팅 프롬프트

// By default, the production version of a chat prompt is fetched.
const chatPrompt = await langfuse.prompt.get("movie-critic-chat", {
  type: "chat",
});

// Compile the prompt with variables - returns an array of messages
const compiledChatPrompt = chatPrompt.compile({
  criticlevel: "expert",
  movie: "Dune 2",
});

// Use with Vercel AI SDK
const result = await generateText({
  model: openai("gpt-4o"),
  messages: compiledChatPrompt,
  experimental_telemetry: {
    isEnabled: true,
  },
});

최신 버전이 안 보이나요? 캐싱 동작 때문일 수 있어요. 자세한 내용은 프롬프트 캐싱을 참고하세요.

프롬프트 관리는 애플리케이션의 크리티컬 경로에 있지 않아요. SDK가 클라이언트 측에서 프롬프트를 캐시하므로 첫 조회 이후에는 추가 지연 없이 메모리에서 제공돼요. Langfuse가 다운되더라도 애플리케이션은 캐시된 프롬프트를 계속 사용해요.

빈 캐시로 새 인스턴스가 시작될 때도 100% 가용성이 필요하다면 보장된 가용성을 참고하세요.

예상과 다른 결과가 나왔나요?

• 내 프롬프트의 최신 버전이 안 보여요. 왜죠?
• 다른 것도 궁금하면 물어보세요

다음 단계

이제 첫 프롬프트를 사용했으니, Langfuse 프롬프트 관리를 최대한 활용하기 위해 다음을 권장해요:

• 프롬프트를 트레이스에 연결해 프롬프트 버전별 성능 분석
• 데이터셋에서 프롬프트 버전을 테스트하기 위해 experiments로 프롬프트 개선
• 환경 전반의 배포를 관리하기 위해 버전 관리와 라벨 사용

특정한 것을 찾고 있다면 Features 아래에서 특정 주제에 대한 가이드를 살펴보세요.

더 알아보기 (Learn more)

• 출처 문서: 프롬프트 관리 시작하기 (Get Started with Prompt Management)