JS/TS v3 → v4

JS/TS v3 → v4

JS/TS SDK v3을 사용 중이라면 최신 메이저인 v5로 직접 업그레이드할 것을 권장해요. JS/TS v4 → v5 마이그레이션 가이드를 참고하세요. 아래의 v3 → v4 변경 사항이 여전히 적용되므로 먼저 완료한 뒤 v4 → v5 가이드를 따르세요.

출처: 문서

본문

애플리케이션을 v3에서 v4로 업그레이드하려면 아래 각 섹션을 따르세요.

업그레이드 중 질문이나 문제가 생기면 GitHub에 이슈를 올려 주세요.

초기화

Langfuse 기본 URL 환경 변수는 이제 LANGFUSE_BASE_URL이며 더 이상 LANGFUSE_BASEURL이 아니에요. 하위 호환을 위해 후자는 v4에서 여전히 동작하지만 향후 버전에서는 동작하지 않아요.

트레이싱

v4 SDK 트레이싱은 OpenTelemetry 기반의 주요 재작성으로 몇 가지 호환성 파괴 변경을 도입해요.

• OTEL 기반 아키텍처: SDK가 이제 OpenTelemetry 위에 구축돼요. LangfuseSpanProcessor를 OpenTelemetry NodeSDK에 등록해 OpenTelemetry 설정이 필요해요.
• 새 트레이싱 함수: langfuse.trace(), langfuse.span(), langfuse.generation() 메서드가 @langfuse/tracing 패키지의 startObservation, startActiveObservation 등으로 대체됐어요.
• 관심사 분리:
  • @langfuse/tracing과 @langfuse/otel 패키지는 트레이싱용.
  • @langfuse/client 패키지와 LangfuseClient 클래스는 이제 스코어링, 프롬프트 관리, 데이터셋 같은 비-트레이싱 기능 전용.

각각에 대한 자세한 내용은 SDK v4 문서를 참고하세요.

프롬프트 관리

• Import: Langfuse 클라이언트의 import는 이제:

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

• 사용법: Langfuse 클라이언트의 사용법은 이제:

const langfuse = new LangfuseClient();

const prompt = await langfuse.prompt.get("my-prompt");

const compiledPrompt = prompt.compile({ topic: "developers" });

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: compiledPrompt }],
});

• version은 이제 위치 인자가 아니라 langfuse.prompt.get() 옵션 객체의 선택적 속성이에요.

const prompt = await langfuse.prompt.get("my-prompt", { version: "1.0" });

OpenAI 통합

• Import: OpenAI 통합의 import는 이제:

import { observeOpenAI } from "@langfuse/openai";

• 이제 LANGFUSE_TRACING_ENVIRONMENT와 LANGFUSE_TRACING_RELEASE 환경 변수로 environment와 release를 설정할 수 있어요.

Vercel AI SDK

v3와 매우 유사하게 동작하지만, langfuse-vercel의 LangfuseExporter를 @langfuse/otel의 일반 LangfuseSpanProcessor로 대체해요.

AI SDK와의 사용 예시는 여기를 참고하세요.

LLM에 제공된 도구 정의는 이제 metadata.tools에 매핑되고 더 이상 input.tools에 있지 않아요. generation에 대해 평가를 실행하는 경우 관련돼요.

Langchain 통합

• Import: Langchain 통합의 import는 이제:

import { CallbackHandler } from "@langfuse/langchain";

• 이제 LANGFUSE_TRACING_ENVIRONMENT와 LANGFUSE_TRACING_RELEASE 환경 변수로 environment와 release를 설정할 수 있어요.

• langfuseClient.getTraceUrl 메서드는 이제 비동기이며 promise를 반환해요.

const traceUrl = await langfuseClient.getTraceUrl(traceId);

스코어링

• Import: Langfuse 클라이언트의 import는 이제:

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

• 사용법: Langfuse 클라이언트의 사용법은 이제:

const langfuse = new LangfuseClient();

await langfuse.score.create({
  traceId: "trace_id_here",
  name: "accuracy",
  value: 0.9,
});

새 스코어링 방법은 커스텀 점수 문서를 참고하세요.

데이터셋

새 데이터셋 메서드는 데이터셋 문서를 참고하세요.

더 알아보기 (Learn more)

• 출처 문서: JS/TS v3 → v4