멀티모달과 첨부 파일
멀티모달과 첨부 파일 (Multi-Modality and Attachments)
Langfuse는 텍스트, 이미지, 오디오, 기타 첨부 파일을 포함한 멀티모달 trace를 지원해요. 기본적으로 base64 인코딩된 data URI는 Langfuse SDK가 자동으로 처리해요. 멀티모달 LLM에서 흔히 쓰는 페이로드에서 추출되어 Langfuse의 객체 저장소에 업로드되고 trace에 연결돼요.
출처: 문서
본문
Langfuse는 텍스트, 이미지, 오디오, 기타 첨부 파일을 포함한 멀티모달 trace를 지원해요.
기본적으로 base64 인코딩 data URI는 Langfuse SDK가 자동 처리해요. 멀티모달 LLM에서 흔히 쓰는 페이로드에서 추출되어 Langfuse의 객체 저장소에 업로드되고 trace에 연결돼요.
이것은 다음 경우에도 동작해요:
- 외부 URL로 미디어 파일을 참조할 때.
LangfuseMedia클래스로 SDK에서 미디어 파일 처리를 커스터마이즈할 때.- Langfuse API를 통해 직접 통합할 때.
시작하는 방법과 내부 동작은 아래에서 알아볼 수 있어요.
가용성 (Availability)
Langfuse Cloud
Langfuse Cloud의 멀티모달 첨부는 현재 무료예요. 향후 대규모 멀티모달 trace와 관련된 추가 저장·컴퓨트 비용을 반영하는 새 과금 메트릭을 도입할 수 있는 옵션을 보유하고 있어요.
셀프호스팅
멀티모달 첨부는 현재 사용 가능해요. Langfuse 환경 변수(LANGFUSE_S3_MEDIA_UPLOAD_*)로 자체 객체 저장소 버킷을 구성해야 해요. 상세는 셀프호스팅 문서를 참고하세요. S3 호환 API는 주요 클라우드 프로바이더 전반에서 지원되며 minio로 셀프호스팅할 수 있어요. 구성된 저장소 버킷은 SDK를 통한 직접 업로드와 브라우저에서 직접 미디어 자산 가져오기를 지원하려면 공개적으로 해석 가능한 호스트네임을 가져야 해요.
지원되는 미디어 형식 (Supported media formats)
Langfuse는 다양한 미디어 유형을 지원해요:
- 이미지(Images): .png, .jpg, .webp, .gif
- 오디오(Audio): .mp3, .wav, .ogg
- 비디오(Video): .mp4, .webm, .mov
- 텍스트·코드(Text & code): .txt, .md, .html, .csv
- 문서(Documents): .pdf, .docx, .xlsx, .pptx
- 데이터·아카이브(Data & archives): .json, .xml, .zip
추가 파일 유형이 필요하면 멀티모달 지원에 대한 피드백을 모으는 GitHub Discussion에서 알려주세요.
시작하기 (Get Started)
Base64 data URI 인코딩 미디어
멀티모달 trace를 만들 때 SDK가 data URI 미디어를 자동 처리하므로 별도 설정이 필요 없어요.
미디어 참조 해석하기 (Resolving media references)
추후 데이터셋 구축이나 다운스트림 처리를 위해 미디어 참조를 다시 base64 data URI로 해석할 수 있어요.
Python
from langfuse import get_client
langfuse = get_client()
# Example object with media references
obj = {
"image": "@@@langfuseMedia:type=image/jpeg|id=some-uuid|source=bytes@@@",
"nested": {
"pdf": "@@@langfuseMedia:type=application/pdf|id=some-other-uuid|source=bytes@@@",
},
}
# Resolve media references to base64 data URIs
resolved_trace = langfuse.resolve_media_references(
obj=obj,
resolve_with="base64_data_uri"
)
# Result:
# {
# "image": "[IMAGE]...",
# "nested": {
# "pdf": "data:application/pdf;base64,JVBERi0xLjcK..."
# }
# }
TypeScript
import { LangfuseClient } from "@langfuse/client";
const langfuse = new LangfuseClient()
// Example object with media references
const obj = {
image: "@@@langfuseMedia:type=image/jpeg|id=some-uuid|source=bytes@@@",
nested: {
pdf: "@@@langfuseMedia:type=application/pdf|id=some-other-uuid|source=bytes@@@",
},
};
// Resolve media references to base64 data URIs
const resolvedTrace = await langfuse.resolveMediaReferences({
obj: obj,
resolveWith: "base64DataUri",
});
// Result:
// {
// image: "[IMAGE]...",
// nested: {
// pdf: "data:application/pdf;base64,JVBERi0xLjcK..."
// }
// }