프롬프트 로깅

프롬프트 로깅 (Log Prompts)

프로덕션에서 버전 추적을 위해 LLM 스팬에 프롬프트를 기록하는 방법을 다루는 페이지예요. Confident AI에서 관리하는 프롬프트를 사용할 때, 각 LLM 호출에 사용된 정확한 프롬프트 버전을 기록할 수 있어요. 모든 트레이스가 이를 만든 프롬프트 버전에 연결되므로, 추측이 아니라 실제 트래픽에서 버전을 비교할 수 있답니다.

출처: 문서

본문

개요 (Overview)

Confident AI에서 관리하는 프롬프트를 사용한다면 각 LLM 호출에 사용된 정확한 프롬프트 버전을 기록할 수 있어요. 프롬프트 로깅은 다음 두 단계로 동작해요:

Confident AI에서 프롬프트를 가져온다
LLM 스팬에 사용된 프롬프트 버전을 기록한다

그게 전부예요! 덕분에 프로덕션에서 어떤 프롬프트가 돌아가고 있는지, 시간이 지나며 어떤 프롬프트가 가장 좋은 성능을 내는지 모니터링할 수 있어요 — 모든 트레이스(그리고 그 위의 모든 온라인 평가 결과)가 그것을 만든 프롬프트 버전으로 연결되기 때문에, 실제 트래픽에서 버전을 비교할 수 있거든요.

Prompt Observability & Performance

아직 Confident AI에서 프롬프트 관리가 어떻게 동작하는지 모른다면 여기에서 배워보세요.

프롬프트를 가져오는 것과 어떤 버전을 사용했는지 기록하는 것은 별개의 두 단계예요. 프롬프트는 여전히 DeepEval의 프롬프트 관리 API(prompt management APIs)로 가져와요. confident-trace는 트레이싱 쪽을 담당하죠.

프롬프트 로깅하기 (Log a Prompt)

프롬프트 로깅은 LLM 스팬에서만 의미가 있어요. 모델 호출을 감싸는 스팬에 type="llm"이 설정되어 있는지 확인하세요.

프롬프트 가져오기와 보간하기 (Pull and interpolate your prompt)

Confident AI에서 프롬프트 버전을 가져오고 변수를 보간(interpolate)해요.

Python

from deepeval.prompt import Prompt

prompt = Prompt(alias="YOUR-PROMPT-ALIAS")
prompt.pull()
interpolated_prompt = prompt.interpolate(name="Joe")

TypeScript

import { Prompt } from "deepeval";

const prompt = new Prompt({ alias: "YOUR-PROMPT-ALIAS" });
await prompt.pull();
const interpolatedPrompt = prompt.interpolate({ name: "Joe" });

변수가 없더라도 프롬프트 템플릿의 사용 가능한 복사본을 만들려면 interpolate()를 반드시 호출해야 해요.

프롬프트를 사용하고 스팬에 기록하기 (Use the prompt and record it on the span)

LLM 스팬 안에서 보간된 프롬프트를 생성에 사용하고, 스팬에 프롬프트의 alias와 버전을 기록해서 어떤 프롬프트가 각 호출을 만들었는지 보고 필터링할 수 있게 해요.

confident-trace에는 아직 전용 프롬프트 귀속(attribution) 헬퍼가 없어서 (DeepEval 시대의 update_llm_span(prompt=...)에 해당하는 직접적인 기능이 없음) 스팬이 Prompts 페이지의 버전화된 프롬프트에 연결되지는 않아요. 그 기능이 나오기 전까지 권장하는 방법은 아래처럼 가져온 alias와 버전을 스팬 metadata로 기록하는 것이에요. 이렇게 하면 트레이스 뷰의 모든 LLM 스팬에서 참조를 볼 수 있고, 프롬프트 버전으로 트레이스를 필터링할 수도 있어요.

Python

from confident_trace import span, update_span
from deepeval.prompt import Prompt
from openai import OpenAI

client = OpenAI()

@span(type="llm", model="gpt-4o", provider="openai")
def generate_response(user_input: str) -> str:
    prompt = Prompt(alias="YOUR-PROMPT-ALIAS")
    prompt.pull(version="00.00.01")
    interpolated_prompt = prompt.interpolate(name="Joe")

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=interpolated_prompt,
    )
    update_span(
        metadata={"prompt_alias": "YOUR-PROMPT-ALIAS", "prompt_version": "00.00.01"}
    )
    return response.choices[0].message.content

TypeScript

import { span, updateSpan } from "confident-trace";
import { Prompt } from "deepeval";
import OpenAI from "openai";

const openai = new OpenAI();

const generateResponse = span(
  { name: "generate_response", type: "llm", model: "gpt-4o", provider: "openai" },
  async (userInput: string) => {
    const prompt = new Prompt({ alias: "YOUR-PROMPT-ALIAS" });
    await prompt.pull({ version: "00.00.01" });
    const interpolatedPrompt = prompt.interpolate({ name: "Joe" });

    const response = await openai.chat.completions.create({
      model: "gpt-4o",
      messages: interpolatedPrompt as any[],
    });
    updateSpan({
      metadata: { promptAlias: "YOUR-PROMPT-ALIAS", promptVersion: "00.00.01" },
    });
    return response.choices[0].message.content;
  },
);

보간된 텍스트가 아니라 가져온 alias와 버전을 기록하세요. 핵심은 프롬프트 템플릿을 식별해서 같은 버전으로 만든 호출을 비교하는 것이기 때문이에요 — 보간된 메시지는 이미 스팬의 입력으로 캡처되어 있어요.

기록이 끝나면 프롬프트 alias와 버전이 트레이스 뷰의 스팬 메타데이터에 나타나서, 각 LLM 호출에 정확히 어떤 프롬프트가 사용됐는지 쉽게 볼 수 있고 프롬프트 버전 간 온라인 평가 결과를 비교할 수 있어요.

OpenAI 같은 프로바이더 통합(provider integration)을 사용 중이라면 모델 호출이 이미 LLM 스팬이에요 — 여기에 두 번째 llm 스팬을 감싸지 마세요. 대신 둘러싼 agent나 커스텀 스팬에서 update_span()을 호출하거나, update_trace()를 통해 트레이스 레벨 metadata로 프롬프트 참조를 설정하세요.

다음 단계 (Next Steps)

프롬프트를 기록했다면 비용 추적을 설정하거나 트레이스가 캡처하는 데이터를 다듬어요.

Track LLM Costs

LLM 스팬의 토큰 사용량과 비용을 — 수동으로 또는 자동으로 — 추적해요.

Set Input/Output

더 나은 시각화와 평가를 위해 트레이스와 스팬의 기본 입력·출력을 재정의해요.

더 알아보기

Configure Span Types — 스팬을 LLM·리트리버·툴·에이전트로 분류하고 타입별 필드를 설정해요.
Online Evaluations — 트레이스·스팬·스레드를 실시간으로 평가해요.