Langfuse 文档 中文 英文原文 ↗
文档 / 通过 Blob 存储集成导出

通过 Blob 存储集成导出

Blob 存储导出在 Pro 计划(团队附加项)、Enterprise 计划和自托管版本中可用;Hobby 和 Core 计划不可用。

你可以安排导出到 Blob 存储,例如 S3、GCS 或 Azure Blob Storage。导出包含丰富的 observations(每个 observation 行包括其 trace 属性)和 scores;每次运行都写入你存储桶中 / 下的 observations_v2/、scores/ 和 manifests/。

这些导出可以每 20 分钟运行一次,或按 hourly、daily 或 weekly 计划运行。 导航到你的项目设置并选择 Integrations > Blob Storage 以设置新的导出。 选择你要使用 S3、S3 兼容存储、Google Cloud Storage 还是 Azure Blob Storage。

关于每个导出文件中每一列的内容,参见导出字段参考。

本页其余部分将介绍设置导出(文件格式、导出的列以及回溯导出的范围)、在你的流水线中消费导出(什么落在你的存储桶中以及如何检测完成的运行),以及监控和重新配置运行中的集成。

较旧的集成可能仍通过已弃用的旧版源导出,带有单独的 traces 和 observations 文件;差异和升级路径参见旧版导出源。

设置导出

创建集成

要设置导出,导航到 Your Project > Settings > Integrations > Blob Storage。

填写设置以向你的厂商进行身份验证,启用集成,然后按保存。 启用集成后不久即开始初始导出,然后按你选择的计划继续。 该导出支持 Parquet(默认)、CSV、JSON 和 JSONL 文件格式。参见文件格式。 阅读我们的 blob 存储文档,了解如何获取特定厂商的凭证。

Blob 存储集成设置

文件格式

导出可以写为 Apache Parquet、CSV、JSON 或 JSONL 文件。新集成默认为 Parquet。

Parquet observation 导出不包含每单位模型价格列(input_price、output_price、total_price)。这些列在导出时快照模型定义价格,未来可能弃用。请使用 cost_details 和 total_cost 获取成本数据,它们包含在每种文件类型中。细节参见字段参考中的 Parquet 导出说明。

运行 ClickHouse < 25.11 的自托管部署: Parquet 导出失败可能不会作为错误显现。一次运行可能完成(并写入其清单),而 Parquet 输出不完整或无效。请升级到 ClickHouse >= 25.11,或使用文本格式(CSV、JSON 或 JSONL)以可靠地检测失败。

选择导出哪些列

字段组让你选择 observation 导出每行中出现哪些列组。十一个组覆盖完整行,其中十个可切换;在 Project Settings → Integrations → Blob Storage 下的 Export Field Groups 中切换它们。

组按它们在 UI 中出现的顺序列出;每个组内的字段按字母顺序排序。core 组是必需的,始终导出。

组 字段(observations_v2)
core end_time、id、parent_observation_id、project_id、start_time、trace_id、type
basic bookmarked、environment、level、name、public、session_id、status_message、user_id、version
time completion_start_time、created_at、updated_at
io input、output
metadata metadata
model input_price、model_id、model_parameters、output_price、provided_model_name、total_price
usage cost_details、total_cost、usage_details、usage_pricing_tier_id、usage_pricing_tier_name
prompt prompt_id、prompt_name、prompt_version
metrics latency、time_to_first_token
trace_context release、tags、trace_name
tools tool_call_names、tool_calls、tool_definitions

字段组也适用于旧版导出源,其中三个组(basic、usage、trace_context)包含较少的列;参见该节中的对比。

每单位定价字段(input_price、output_price、total_price)位于 model 组中;它们来自匹配的模型定义。取消选择 model 会完全跳过工作端的模型定价查找。usage_pricing_tier_id 和 usage_pricing_tier_name 字段保留在 usage 组中。使用 Parquet 文件类型时,即使选择了 model,这三个价格列也不包含。参见文件格式。

新集成默认为全部十一个组,因此除非你缩小选择,否则行为与早期导出匹配。

通过 REST API 配置

GET 和 PUT /api/public/integrations/blob-storage 接受并返回:

完整 schema 参见 API 参考。

导出模式

Export Mode 决定集成从多早开始导出:

模式 起始于 何时使用
Full history 你项目中最早的数据 你想要所有现有数据的完整一次性回填,以及持续的导出。
From setup date 你启用集成的时刻 你只关心未来的数据,不需要历史;这是开始的最轻量选项。
From custom date 你选择的开始日期 你想要从特定点(例如季度开始)的历史,而不导出其之前的所有内容。

更改模式会重置同步位置,因此它也是重新扫描历史的机制。参见重新导出数据和配置更改。

在你的流水线中消费导出

导出如何运行

每次运行将一个时间窗口的数据导出到你的存储桶,然后前进并在你配置的计划上导出下一个窗口。

运行完成清单

单次导出运行每个导出的表写一个文件(最多四个,取决于所选导出源),因此仅凭表文件无法告诉你运行何时完成。作为每次成功运行的最后一个对象,Langfuse 写入一个清单文件,列出该运行产生的所有内容:

{prefix}{project-id}/manifests/{max-timestamp}.json

清单严格在该运行的所有表文件之后上传。一旦它出现,它列出的每个文件都在你的存储桶中完全可用;如果任何上传失败,则不写入清单,整个运行重试(表文件在重试时在相同键下被覆盖)。清单键中的时间戳是该运行的 maxTimestamp(UTC),截断到整秒,冒号替换为连字符,毫秒和尾随 Z 被删除(2026-07-13T09:00:00.000Z → 2026-07-13T09-00-00)。这与该运行表文件使用的词干相同(//.),因此一个运行的表文件和其清单共享相同的时间戳词干。

示例清单:

json
{
  "version": 1,
  "projectId": "cm0abcd1234efgh5678ijkl90",
  "exportSource": "OBSERVATIONS_V2",
  "window": {
    "minTimestamp": "2026-07-13T08:00:00.000Z",
    "maxTimestamp": "2026-07-13T09:00:00.000Z"
  },
  "maxTimestamp": "2026-07-13T09:00:00.000Z",
  "createdAt": "2026-07-13T09:02:11.123Z",
  "tables": ["observations_v2", "scores"],
  "files": [
    {
      "key": "my-prefix/cm0abcd1234efgh5678ijkl90/observations_v2/2026-07-13T09-00-00.parquet",
      "table": "observations_v2",
      "fileType": "PARQUET",
      "format": "parquet",
      "compressed": false,
      "contentType": "application/vnd.apache.parquet",
      "sizeBytes": 1048576,
      "rowCount": null
    },
    {
      "key": "my-prefix/cm0abcd1234efgh5678ijkl90/scores/2026-07-13T09-00-00.parquet",
      "table": "scores",
      "fileType": "PARQUET",
      "format": "parquet",
      "compressed": false,
      "contentType": "application/vnd.apache.parquet",
      "sizeBytes": 20480,
      "rowCount": null
    }
  ]
}

关于 schema 的说明:

对完成的导出运行做出反应

Langfuse 在导出运行完成时不发送 webhook。相反,订阅你存储提供商的原生对象创建事件,并对 /manifests/ 使用前缀过滤。由于清单是每次运行的最后一个对象,这给你每个完成运行一个事件。当事件触发时,下载清单并处理 files[].key 中列出的对象。

提供商方案:

对于没有对象创建事件的 S3 兼容提供商(例如 Wasabi 或 DigitalOcean Spaces),请改为轮询清单前缀:按计划列出 /manifests/ 并处理比你的上一个检查点更新的任何清单。清单名称按导出时间戳字典序排序,因此基于标记(start-after)的列表使轮询保持廉价。

存储桶中的空文件

监控和重新配置

导出状态

集成设置页面显示状态徽章:

徽章 含义
Active 已启用并同步;下一次导出计划在未来。
Running 导出作业当前正在进行中(带旋转图标显示)。
Queued 导出到期并等待运行。
Pending 已启用但尚未运行导出(Data exported up to 显示 Never (pending))。
Disabled 集成已关闭。
Error 最近的导出失败;显示错误消息和时间戳。

同一页面上的状态卡片还显示:

如果工作进程在导出中途崩溃,2 小时的安全阀 TTL 确保徽章从 Running 恢复到其底层状态(通常为 Queued),以便下一个计划的运行可以继续。重新加载页面以查看最新状态。

Langfuse 在下一次运行重试失败的导出。重复失败会通过电子邮件和配置的 Slack 或 webhook 渠道通知项目管理员。在 Project Settings → Notifications 下配置它。

重新导出数据和配置更改

旧版导出源

本节仅适用于仍使用已弃用的 Traces and observations (legacy) 导出源的集成。它将在未来版本中移除;请遵循下面的升级路径。新集成使用 Enriched observations (recommended),可以跳过本节。

Export Source 设置决定集成导出哪些表。旧版源导出单独的 traces 和 observations 文件,而非丰富的 observations_v2 文件;无论源如何,scores 始终包含。每个源在 / 下写入的目录:

导出源 写入的目录
Enriched observations (recommended) observations_v2/、scores/
Traces and observations (legacy) and enriched observations traces/、observations/、observations_v2/、scores/
Traces and observations (legacy) traces/、observations/、scores/

关于每个文件中的列,参见字段参考中的导出源概览。

字段组也适用于旧版 observation 导出,但旧版 observations 文件中有三个组包含较少的列;所有其他组与丰富导出相同:

组 丰富(observations_v2) 旧版(observations)
basic bookmarked、environment、level、name、public、session_id、status_message、user_id、version environment、level、name、status_message、version
usage cost_details、total_cost、usage_details、usage_pricing_tier_id、usage_pricing_tier_name 相同,不含 usage_pricing_tier_id
trace_context release、tags、trace_name 无效;这些字段位于单独的 traces 文件中

旧版源仍可用的位置:

在 Langfuse Cloud 上,仍导出旧版源的集成还会在 /DEPRECATION_NOTICE.txt 收到纯文本弃用通知。它在每次成功运行时刷新(在该运行的清单之后尽力写入,且不列在其中),并在集成切换到 Enriched observations (recommended) 后的下一次成功运行时自动移除。清单仍是权威的运行完成标记;如果你的流水线对存储桶内容进行 diff 或订阅不带前缀过滤的对象创建事件,请考虑此对象。

升级路径

要安全地迁移现有旧版集成:

  1. 切换到 Traces and observations (legacy) and enriched observations。
  2. 在两个源都被导出时验证下游作业和数据消费者(此模式按设计创建重复记录)。字段级对比参见丰富导出与旧版导出之间的差异。
  3. 将消费者从 traces/ 和 observations/ 目录重新指向 observations_v2/。优先用运行清单驱动消费者,而非监视目录;每个清单准确列出其运行写入的文件。
  4. 验证完成后切换到 Enriched observations (recommended)。

切换后,traces/ 和 observations/ 目录完全不再接收任何文件,甚至不接收空文件,而空文件否则会为没有数据的窗口写入。仍监视这些目录的流水线会在没有错误信号的情况下静默,因此请在切换前完成步骤 3。由运行清单驱动的流水线不受影响:清单继续准确列出每次运行写入的内容,因此清单驱动的消费者会自动跟随源切换。

替代方案

你也可以通过以下方式导出数据:

非官方中文翻译 · 图片/视频/代码均链接官方资源 · 版权归 Langfuse GmbH 所有 查看英文原文 ↗