多模态时代,一次 LLM 调用的 input/output 里可能塞着一张图、一段音频、一个 PDF——动辄几 MB 的二进制。如果把这些原样写进第 8 课的 ClickHouse 宽表, input/output 列会瞬间膨胀,查询变慢、存储浪费。Langfuse 的解法干净利落:大块二进制根本不进 ClickHouse, 而是单独存进 S3 媒体桶,事件里只留一个小小的引用串。这一课,就讲这套「把笨重的 blob 挡在热路径之外」的媒体存储设计。
@@@langfuseMedia:…@@@);
真正厚重的书(媒体二进制)摆在书库的架子上(S3 媒体桶)。两个人上传同一本书,图书馆不会摆两本——靠书的「指纹」(sha256 哈希)认出是同一本,只存一份。
你需要看书时,凭索书号去把书取出来。卡片轻、检索快;书库便宜、容量大——各得其所。
核心思想一句话:把 blob 从事件里拆出去。媒体二进制存进 S3 媒体桶;事件的 input/output 里,原本那张图的位置被替换成一个引用串
@@@langfuseMedia:…@@@。于是 ClickHouse 存的是几十字节的索书号,而不是几 MB 的图片。
@@@langfuseMedia:…@@@ 引用串,本体存入 S3 媒体桶(按 sha256 去重),blob_storage_file_log 记录每个 blob 归属哪个 entity。源码:packages/shared/src/utils/mediaReferences.ts:6(MEDIA_REFERENCE_PATTERN)。MEDIA_REFERENCE_PATTERN;值为示例):图片/音频不直接塞进 observation,而是替换成一个 @@@langfuseMedia:…@@@ 引用 token,真正的字节按 {{projectId}}/{{mediaId}} 存到 S3。于是宽表的行保持小而可聚合,UI 要看时再按指针去 S3 取——「队列轻、本体重」在媒体场景的延续。// 事件里媒体被替换成这种小引用串,ClickHouse 只存它(几十字节) export const MEDIA_REFERENCE_PATTERN = /@@@langfuseMedia:.+?@@@/g; // 例:@@@langfuseMedia:type=image/png|id=abc123|source=base64@@@ // blob_storage_file_log:所有 blob 的台账(又是第 8 课的 ReplacingMergeTree 宽表) CREATE TABLE blob_storage_file_log ( project_id String, entity_type String, entity_id String, event_id String, bucket_name String, bucket_path String, -- 这个 blob 在哪 event_ts DateTime64(3), is_deleted UInt8, ) ENGINE = ReplacingMergeTree(event_ts, is_deleted) ORDER BY (project_id, entity_type, entity_id, event_id);
为什么非得这么分?因为遥测数据和媒体 blob 的「体质」根本不同,硬放在一起会两头受罪——一个被撑大、一个被低效访问。对比一下就一目了然:
| 维度 | 遥测数据(trace/observation) | 媒体 blob(图/音/文件) |
|---|---|---|
| 大小 | 小,几 KB 的结构化 JSON/文本 | 大,动辄几 MB 的二进制 |
| 访问方式 | 高频查询、过滤、聚合 | 几乎只按 id 整取,不查内部 |
| 该放哪 | ClickHouse 宽表(第 8 课)——为分析而生 | S3 对象存储——为大文件而生、便宜 |
| 事件里留什么 | — | 只留 @@@langfuseMedia:…@@@ 引用串 |
媒体怎么进到 S3?关键是SDK 直接传给 S3,本体不经过 Langfuse 的应用服务器。流程是:SDK 先把媒体的指纹(sha256 哈希)、
类型、大小报给 POST /api/public/media;服务端据此决定——这媒体之前传过吗?
prisma.media(按 projectId+sha256 唯一);已传过则回 uploadUrl: null 跳过,否则回 presigned URL 让 SDK 直传 S3。本体不过应用层。源码:web/src/features/media/server/mediaService.ts:66-122。计算媒体的 sha256、contentType、contentLength,POST /api/public/media(先不传本体)。
按 (projectId, sha256Hash) 查 prisma.media;已成功上传过同类型 → 返回 uploadUrl: null,秒过。
新媒体则算出 mediaId、bucketPath,返回一个有时效的 S3 直传地址。
SDK 凭 URL 把本体直接 PUT 进 S3 媒体桶,不经 Langfuse 应用服务器——省带宽、不堵 API。
媒体与 trace/observation 关联;blob_storage_file_log 记下这个 blob 归属哪个 entity,供生命周期管理与导出。
内容寻址去重在真实场景里收益惊人。设想你做了个「图片问答」应用,每条对话都带同一张企业 logo 当水印,或者一个 few-shot 提示里固定塞着同几张示例图——
一天下来可能有上万条 trace 引用同一张图。靠 sha256 指纹,这张图在 S3 里只存一份,后续每次「上传」都会在第 2 步被识破、uploadUrl: null 秒过,
既省存储、又省带宽、还省了 SDK 反复上传的时间。这就是把「同一性」交给内容哈希、而非文件名或时间戳来判断的妙处——相同的字节,永远只有一份,无论它被多少条 trace、多少个项目内的对话引用。
取用时反过来:GET /api/public/media/[mediaId] 返回一个有时效的下载地址,UI 或你的程序凭它去 S3 取回本体。
这个「有时效」也顺带管住了访问控制:下载链接由服务端在鉴权之后才签发、且很快过期,媒体既不会被公开裸奔在互联网上、也不会绕过项目边界(第 10 课)被别的租户读到。
整个生命周期里,几 MB 的二进制只在 SDK 和 S3 之间流动,Langfuse 的应用层和 ClickHouse 全程只碰那个轻飘飘的引用串——这正是把笨重负载挡在热路径之外的关键。
input 列里躺着几 MB base64,宽表体积暴涨;连「查最近 100 条 trace」这种压根不碰图的查询,也要扫过这些大字段,全表跟着变慢——一颗老鼠屎坏一锅汤。
ClickHouse 只存几十字节引用,宽表始终精瘦、扫描飞快;图片躺在便宜的对象存储里,要用才按 id 取。各自待在最适合的地方,互不拖累,这也是第 7 课「双存储分工」在媒体场景的延续。
@@@langfuseMedia@@@ 引用串牵线;再用 sha256 内容寻址天然去重、
用 presigned URL 让本体绕开应用层直传。这套组合拳背后是一条朴素的工程智慧:让每种数据待在最适合它的存储里——这也为第三部分「摄取链路」画上句点。
@@@langfuseMedia:…@@@(MEDIA_REFERENCE_PATTERN)。(projectId, sha256) 唯一;已传过则回 uploadUrl: null 跳过——同一文件只占一份存储。blob_storage_file_log(第 8 课同款 ReplacingMergeTree 宽表)记录每个 blob 归属哪个 entity,供生命周期管理与导出。核心智慧:让每种数据待在最适合它的存储里。In the multimodal era, an LLM call's input/output may carry an image, an audio clip, a PDF — binaries of several MB. Write those verbatim into Lesson 8's ClickHouse wide tables and the input/output columns balloon instantly, queries slow, storage is wasted. Langfuse's answer is clean: large binaries never enter ClickHouse at all; they're stored separately in an S3 media bucket, and the event keeps only a tiny reference string. This lesson covers that media-storage design — keeping bulky blobs off the hot path.
@@@langfuseMedia:…@@@); the heavy books themselves (the media binaries) sit on the stacks
(the S3 media bucket). Two people upload the same book and the library doesn't shelve two copies — it recognizes them as one by the book's
"fingerprint" (the sha256 hash), storing just one. When you want to read, you fetch the book by its call number. Cards are light and searchable; stacks
are cheap and roomy — each in its right place.
The core idea in one line: pull the blob out of the event. Media binaries go to the S3 media bucket; in the event's input/output, where
that image used to sit, a reference string @@@langfuseMedia:…@@@ takes its place. So ClickHouse stores a few-dozen-byte call number, not a
multi-MB image.
@@@langfuseMedia:…@@@ reference; the body goes to the S3 media bucket (deduped by sha256), and blob_storage_file_log records which entity each blob belongs to. Source: packages/shared/src/utils/mediaReferences.ts:6 (MEDIA_REFERENCE_PATTERN).MEDIA_REFERENCE_PATTERN; values illustrative): images/audio aren't embedded in the observation; they're replaced by a @@@langfuseMedia:…@@@ reference token, while the real bytes go to S3 at {{projectId}}/{{mediaId}}. The wide-table row stays small and aggregatable, and the UI dereferences to S3 on demand — the “light queue, heavy body” idea applied to media.// media in events is replaced by this small reference string; ClickHouse stores only it (~bytes) export const MEDIA_REFERENCE_PATTERN = /@@@langfuseMedia:.+?@@@/g; // e.g. @@@langfuseMedia:type=image/png|id=abc123|source=base64@@@ // blob_storage_file_log: a ledger of all blobs (again Lesson 8's ReplacingMergeTree wide table) CREATE TABLE blob_storage_file_log ( project_id String, entity_type String, entity_id String, event_id String, bucket_name String, bucket_path String, -- where this blob lives event_ts DateTime64(3), is_deleted UInt8, ) ENGINE = ReplacingMergeTree(event_ts, is_deleted) ORDER BY (project_id, entity_type, entity_id, event_id);
Why split this way? Because telemetry data and media blobs have fundamentally different "constitutions", and forcing them together hurts both. A quick comparison makes it obvious:
| dimension | telemetry (trace/observation) | media blob (image/audio/file) |
|---|---|---|
| size | small, a few KB of structured JSON/text | large, often several MB of binary |
| access | frequent query, filter, aggregate | almost only fetched whole by id, never queried inside |
| where it belongs | ClickHouse wide tables (Lesson 8) — built for analytics | S3 object storage — built for big files, cheap |
| what stays in the event | — | only the @@@langfuseMedia:…@@@ reference |
How does media get into S3? The key: the SDK uploads directly to S3, the body never passing through Langfuse's app
servers. The flow: the SDK first reports the media's fingerprint (sha256 hash), type and size to POST /api/public/media;
the server decides — has this media been uploaded before?
prisma.media (unique by projectId+sha256); already uploaded → returns uploadUrl: null to skip, else a presigned URL for the SDK to upload directly to S3. The body never touches the app layer. Source: web/src/features/media/server/mediaService.ts:66-122.Computes the media's sha256, contentType, contentLength, POST /api/public/media (no body yet).
Looks up prisma.media by (projectId, sha256Hash); already uploaded with same type → returns uploadUrl: null, instant pass.
For new media, compute mediaId, bucketPath, and return a time-limited direct-to-S3 address.
The SDK PUTs the body straight into the S3 media bucket via the URL, bypassing Langfuse app servers — saves bandwidth, doesn't clog the API.
The media is linked to the trace/observation; blob_storage_file_log records which entity this blob belongs to, for lifecycle and export.
Content-addressed dedup pays off dramatically in practice. Imagine an "image Q&A" app where every conversation carries the same company logo
as a watermark, or a few-shot prompt fixed with the same example images — over a day that could be tens of thousands of traces
referencing one image. By sha256 fingerprint, that image is stored once in S3; every subsequent "upload" is caught at step 2 with an
instant uploadUrl: null — saving storage, bandwidth, and the SDK's repeated upload time. That's the beauty of deciding "sameness" by content hash
rather than filename or timestamp — identical bytes, only ever one copy, however many traces or conversations within a project reference it.
Retrieval is the reverse: GET /api/public/media/[mediaId] returns a time-limited download address, and the UI or your code
fetches the body from S3 with it. That "time-limited" also handles access control: the download link is signed by the server only after auth
and expires quickly, so media is neither left publicly exposed nor readable across the project boundary (Lesson 10) by another tenant. Across the whole
lifecycle, the multi-MB binary only flows between the SDK and S3; Langfuse's app layer and ClickHouse only ever touch the featherweight
reference string — exactly what keeps bulky payloads off the hot path.
Several MB of base64 sit in the input column, the wide table bloats; even a query like "fetch the latest 100 traces" that never touches the image must scan past these huge fields, slowing the whole table — one bad apple spoils the barrel.
ClickHouse stores a few-dozen-byte reference, the wide table stays lean and scans fast; images rest in cheap object storage, fetched by id only when needed. Each in its best-fit place, neither dragging the other.
@@@langfuseMedia@@@ reference; plus sha256
content addressing for natural dedup and presigned URLs to let bodies bypass the app layer. Behind this combo is a plain
engineering wisdom: let each kind of data live in the storage that fits it best — fittingly closing out Part 3, "the ingestion path".
@@@langfuseMedia:…@@@ (MEDIA_REFERENCE_PATTERN).(projectId, sha256); already uploaded → uploadUrl: null skip — the same file stored only once.blob_storage_file_log (Lesson 8's ReplacingMergeTree wide table) records which entity each blob belongs to, for lifecycle and export. The core wisdom: let each kind of data live in the storage that fits it best.