버전 및 호환성(Versions & Compatibility)
버전 및 호환성(Versions & Compatibility)
Langfuse의 서버, SDK, API 버전이 Langfuse Cloud와 셀프 호스팅 배포 전반에서 어떻게 관련되는지에 대한 참조입니다. 이 문서는 호환성 규칙, GA 버전, 기능 가용성 매트릭스, 그리고 자주 묻는 질문을 다룹니다. 2026년 11월 16일(2026-11-16)에 레거시 API와 수집 경로가 제거됩니다.
출처: 문서
본문
Langfuse v4가 GA(generally available) 상태입니다. 셀프 호스팅 배포는 v3 to v4 마이그레이션 가이드 로 업그레이드하고, 2026년 3월부터 프리뷰로 롤아웃 중인 Langfuse Cloud는 v4를 유일한 경험으로 전환하며, 이 시점에 남은 레거시 API와 수집 경로도 제거됩니다.
호환성 규칙: 각 Langfuse 서버 메이저 버전은 각 언어의 현재 및 이전 SDK 메이저 버전을 지원하는 것을 목표로 합니다. 새 SDK 버전은 최근 서버 버전을 필요로 합니다. 일부 기능은 오래된 서버에서 사용할 수 없기 때문입니다. 기능 가용성 매트릭스 를 참고하세요.
우리는 이 규칙을 지키기 위해 매우 노력합니다. v4는 이전 SDK와의 역호환성을 깨뜨립니다. 자세한 내용은 Langfuse v4 페이지 를 참고하세요.
| 배포 | 버전 관리 방식 |
|---|---|
| Langfuse Cloud | 항상 최신 Langfuse 버전 실행. 서버 버전은 관리됩니다. 내 SDK 버전과 호출하는 API 엔드포인트만 중요하며, 이 페이지의 셀프 호스팅 서버 최소 요구사항은 적용되지 않습니다. 파괴적 제거는 게시된 날짜에 발생합니다. |
| Self-hosted (OSS & Enterprise) | 서버 업그레이드 시점을 직접 선택. 새 기능은 셀프 호스팅 릴리스에 나오기 전에 Langfuse Cloud에서 먼저 검증되므로 Cloud가 최신 셀프 호스팅 버전보다 앞서 실행될 수 있습니다. SDK 메이저는 셀프 호스팅 호환성 매트릭스 의 최소 서버 버전을 요구합니다. 파괴적 제거는 서버 메이저 릴리스에서만 발생합니다. |
Langfuse 버전
모든 Langfuse 구성 요소(서버, SDK, API)는 다음 수명주기 단계를 거칩니다:
| 단계 | 의미 |
|---|---|
| Preview | 프로덕션 준비가 된 새 기능이지만 인터페이스나 API 설계는 여전히 변경될 수 있음 |
| GA | 권장되며 완전히 지원됨 |
| Deprecated | 여전히 작동하지만 대체됨. 아래 매트릭스에 제거가 명시됨. 대체품으로 마이그레이션. |
| End of life | 지원되지 않음, 보안 패치 없음 |
GA 버전
| 구성 요소 | GA 버전 | 패키지 / 저장소 | 비고 |
|---|---|---|---|
| Server | v4 | langfuse/langfuse | Observations-first 데이터 모델; v3는 계속 보안 패치를 받음 |
| Python SDK | v4 | langfuse |
v3부터 OpenTelemetry 기반. Python 3.9+ 필요 |
| JS/TS SDK | v5 | @langfuse/* |
v4부터 OpenTelemetry 기반. Node.js 20+ 필요 |
| Other languages | n/a | OpenTelemetry | Langfuse OTel 엔드포인트로의 모든 OTel SDK |
기능 가용성 매트릭스
Langfuse Cloud는 2026년 11월 16일(2026-11-16) v4 컷오버까지 v3와 v4를 나란히 실행합니다. v3 컬럼은 deprecated입니다. 아래에서 Deprecated로 표시된 모든 것은 컷오버까지 계속 작동한 뒤 제거됩니다.
셀프 호스팅한다면 셀프 호스팅 호환성 매트릭스 를 대신 사용하세요. 각 서버 버전과 SDK별 최소 서버 버전을 다룹니다.
Python · 업그레이드 가이드
| 기능 | Langfuse Cloud v3 (2026-11-16부터 Deprecated) | Langfuse Cloud v4 (GA) |
|---|---|---|
| Python SDK v4 | Full | Full |
| Python SDK v3 | Full | Deprecated |
| Python SDK v2 | Full | Deprecated |
| Python SDK v1 | Unsupported | Unsupported |
JS/TS · 업그레이드 가이드
| 기능 | Langfuse Cloud v3 | Langfuse Cloud v4 (GA) |
|---|---|---|
| JS/TS SDK v5 | Full | Full |
| JS/TS SDK v4 | Full | Deprecated |
| JS/TS SDK v3 / v2 | Full | Deprecated |
| JS/TS SDK v1 | Unsupported | Unsupported |
Third-party instrumentation · OpenTelemetry docs
| 기능 | 엔드포인트 | v3 | v4 |
|---|---|---|---|
| OpenTelemetry | /api/public/otel/v1/traces |
Full | Full |
| Direct scores ingestion | /api/public/scores |
Full | Full |
| SDK scores ingestion | score-create via /api/public/ingestion |
Full | Full |
| Legacy trace and observation events | /api/public/ingestion |
Full | Deprecated |
Read APIs · Public API docs
| 기능 | 엔드포인트 | v3 | v4 |
|---|---|---|---|
| Observations API v2 & Metrics API v2 | /api/public/v2/... |
Full | Full |
| Scores API v3 | /api/public/v3/scores |
Full | Full |
| Deprecated read APIs | traces, observations, sessions, scores, metrics, dataset runs |
Full | Deprecated |
Integrations & exports · Export docs
| 기능 | v3 소스 | v4 소스 |
|---|---|---|
| Blob storage export | Traces & observations | Enriched observations |
| PostHog integration | Traces & observations | Enriched observations |
| Mixpanel integration | Traces & observations | Enriched observations |
| Legacy export source (traces and observations) | Full | Deprecated |
Evaluations · LLM-as-a-judge docs
| 기능 | v3 | v4 |
|---|---|---|
| Observation-level evaluators | Full | Full |
| Trace-level evaluators | Full | Deprecated |
Deprecated. Python SDK v4 로 업그레이드하세요.
Python SDK — 제한 사항
| 기능 | Langfuse Cloud v3 | Langfuse Cloud v4 |
|---|---|---|
| Tracing (OpenTelemetry) | 지원됨 | 지원됨 (데이터 최대 15분 지연; 실시간은 Python SDK v4 ≥ 4.7.0) |
| Datasets & experiments | Datasets만 (실험은 Python SDK v4 필요) | Datasets만 (실험은 Python SDK v4 필요) |
Public API & querying (api.*) |
지원됨 | 2026년 11월 16일(2026-11-16) v4 컷오버까지 지원. 이후 deprecated read API는 sunset |
Deprecated. SDK 업그레이드 경로 로 업그레이드하세요.
| 기능 | v3 | v4 |
|---|---|---|
| Tracing (legacy batch ingestion) | 지원됨 | 2026년 11월 16일(2026-11-16)에 제거됨. 이후 trace 수집이 중단됨 |
| Score ingestion | 지원됨 | 지원됨 |
| Datasets & experiments | Datasets만 | Datasets만 |
Public API & querying (api.*) |
지원됨 | 2026년 11월 16일까지 지원. 이후 deprecated read API sunset |
JS/TS SDK — 제한 사항
Deprecated. JS/TS SDK v5 로 업그레이드하세요.
| 기능 | v3 | v4 |
|---|---|---|
| Tracing (OpenTelemetry) | 지원됨 | 지원됨 (데이터 최대 15분 지연; 실시간은 JS/TS SDK v5 ≥ 5.4.0) |
| Datasets & experiments | Datasets만 (실험은 JS/TS SDK v5 필요) | Datasets만 (실험은 JS/TS SDK v5 필요) |
Public API & querying (api.*) |
지원됨 | 2026년 11월 16일까지 지원. 이후 deprecated read API 제거 |
Deprecated. SDK 업그레이드 경로 로 업그레이드하세요.
| 기능 | v3 | v4 |
|---|---|---|
| Tracing (legacy batch ingestion) | 지원됨 | 2026년 11월 16일(2026-11-16)에 제거됨. 이후 trace 수집이 중단됨 |
| Score ingestion | 지원됨 | 지원됨 |
| Datasets & experiments | Datasets만 | Datasets만 |
Public API & querying (api.*) |
지원됨 | 2026년 11월 16일까지 지원. 이후 deprecated read API sunset |
OpenTelemetry
GA. 모든 OpenTelemetry SDK는 OSS 3.22.0 부터 사용 가능한 OTLP 엔드포인트로 내보낼 수 있습니다. Langfuse v4에서는 span exporter에 x-langfuse-ingestion-version: 4 헤더를 보내면 데이터를 실시간으로 볼 수 있습니다. 헤더가 없으면 데이터가 최대 15분 지연될 수 있습니다. (Langfuse SDK Python ≥ 4.7.0 / JS ≥ 5.4.0은 자동으로 실시간 자격이 됩니다. 셀프 호스팅 배포는 LANGFUSE_MIGRATION_V4_NATIVE_OTEL_BEHAVIOUR=direct를 설정해 헤더 없이도 모든 OTLP 수집을 실시간으로 만들 수 있습니다.) OpenTelemetry 설정 가이드 를 참고하세요.
Deprecated. legacy 배치 수집 API를 통한 trace, span, generation 이벤트는 v4 데이터 모델에서 지원되지 않습니다. Langfuse Cloud에서는 2026년 11월 16일(2026-11-16)까지 작동하고, 셀프 호스팅 Langfuse v4의 events_only 모드에서는 거부됩니다. 이전 POST /api/public/traces, /spans, /generations, /events 엔드포인트도 마찬가지입니다. OpenTelemetry 수집으로 마이그레이션 하세요.
Observations/Metrics API v2
GA. Langfuse v4 필요. Observations API v2 및 Metrics API v2 문서를 참고하세요.
- Via SDK: 이들은 Python SDK v4(
api.observations,api.metrics)와 JS/TS SDK v5(api.observations,api.metrics)의 기본 리소스입니다. OSS v3에서는 기본값이 실패하므로api.legacy.observations_v1/api.legacy.metrics_v1(Python) 또는api.legacy.observationsV1/api.legacy.metricsV1(JS/TS)을 사용하세요. - Via REST:
GET /api/public/v2/observations?fromStartTime={datetime}&toStartTime={datetime}그리고GET /api/public/v2/metrics?query={json}. - 데이터 신선도: 이전 SDK(Python < 4.7.0, JS < 5.4.0)나
x-langfuse-ingestion-version: 4헤더가 없는 OTel exporter의 데이터는 이 API에 최대 10분 지연으로 나타날 수 있습니다. 실시간 데이터에는 Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0으로 업그레이드(또는 헤더 설정)하세요.
Deprecated read APIs
Deprecated. Langfuse v4와 Langfuse Cloud 2026년 11월 16일(2026-11-16)에 제거됩니다. 마이그레이션 가이드 는 매개변수 표와 before/after 예시가 있는 엔드포인트별 표준 매핑입니다. deprecated 엔드포인트 자체도 문서화합니다.
Deprecated GET 엔드포인트 |
대체 |
|---|---|
/api/public/observations, /api/public/observations/{id} |
Observations API v2 |
/api/public/traces, /api/public/traces/{id} |
Observations API v2, traceId로 필터링 |
/api/public/sessions, /api/public/sessions/{id} |
Observations API v2, sessionId로 필터링 |
/api/public/scores, /api/public/v2/scores (+ /{id}) |
Scores API v3 |
/api/public/metrics, /api/public/metrics/daily |
Metrics API v2 |
/api/public/datasets/{name}/runs (+ /{runName}) |
Experiments API |
/api/public/dataset-run-items |
Experiment Items API |
Deprecated. observation-level evaluators로 마이그레이션 하세요. Trace-level evaluators는 v4 데이터 모델에서 지원되지 않습니다. Langfuse Cloud에서는 2026년 11월 16일(2026-11-16)까지 계속 실행됩니다. 셀프 호스팅 Langfuse v4의 events_only 모드에서는 더 이상 결과를 만들지 않습니다.
Deprecated. legacy "traces and observations" 소스에 구축된 내보내기는 enriched observations 소스(v4 데이터 모델)로 대체됩니다. Langfuse Cloud에서 2026-05-20 이후 생성된 프로젝트는 legacy 소스를 선택할 수 없고, 2026-06-22 이후 새 legacy 내보내기 통합을 만들 수 없으며, 남은 legacy 내보내기는 2026년 11월 16일(2026-11-16)에 자동으로 enriched 소스로 전환됩니다.
자주 묻는 질문(Frequently asked questions)
Langfuse Cloud에서 어떤 버전을 신경 써야 하나요?
내 SDK 버전과 호출하는 API 엔드포인트만 신경 쓰면 됩니다. Langfuse Cloud는 항상 최신 서버 버전을 실행하므로 셀프 호스팅 서버 최소 요구사항은 내게 적용되지 않습니다. SDK를 GA 메이저 버전(Python v4, JS/TS v5)으로 유지하고, 2026년 11월 16일(2026-11-16) v4 컷오버 전에 deprecated 엔드포인트에서 벗어나세요.
Langfuse v3를 셀프 호스팅하고 Python SDK v4 / JS SDK v5로 업그레이드했는데 뭐가 작동하나요?
Tracing, 프롬프트 관리, 데이터셋, 점수는 완전히 작동합니다(서버 ≥ 3.63.0). 기본 api.observations와 api.metrics 리소스는 Langfuse v4가 필요한 v2 엔드포인트를 호출하므로, 서버를 v4로 업그레이드할 때까지 api.legacy.* 리소스를 사용하세요. 셀프 호스팅 호환성 매트릭스 에 서버 버전별 전체 그림이 있습니다.
데이터가 UI에 나타나는 데 몇 분 걸리는 이유가 뭐죠?
v4 데이터 모델에서 Python SDK < 4.7.0, JS SDK < 5.4.0, 또는 x-langfuse-ingestion-version: 4 헤더가 없는 OTel exporter의 데이터는 최대 15분까지 지연될 수 있습니다. 실시간 데이터에는 Python SDK ≥ 4.7.0 / JS SDK ≥ 5.4.0으로 업그레이드(또는 헤더 설정)하세요.
Langfuse Cloud에서 이전 SDK는 언제 중단되나요?
Python SDK v2와 JS/TS SDK v3(및 그 이전)는 2026년 11월 16일(2026-11-16)에 Langfuse Cloud에서 제거되는 legacy 배치 수집 API로 trace를 보냅니다. 지금 GA SDK 메이저로 업그레이드하세요. SDK 업그레이드 경로 를 참고하세요.
셀프 호스팅 서버를 업그레이드하면 SDK가 깨지나요?
각 서버 메이저는 각 언어의 현재 및 이전 SDK 메이저를 지원합니다. v3 → v4 업그레이드는 Python SDK v3+/v4와 JS SDK v4/v5를 계속 작동하게 합니다(이전 SDK는 실시간 가시성을 잃음. Python v2 / JS v3 trace 수집은 v4에서 지원되지 않음). 업그레이드 전에 셀프 호스팅 호환성 매트릭스 를 확인하세요.