API 与参考通过 SDK 查询

通过 SDK 查询数据

Litefuse 是开放的，使用 Litefuse 追踪的数据也是开放的。你可以通过 SDK 与 API 查询数据。导出功能请参阅 导出数据。

常见用例：

  • 在 Litefuse 中的生产 trace 上训练或微调模型。例如，在某个用例下使用大模型上线后再蒸馏出一个小模型。
  • 收集 few-shot 示例以提升输出质量。
  • 通过编程方式创建 datasets。

如果你是 Litefuse 新手，建议先熟悉 Litefuse 数据模型。

新数据通常在上报后 15-30 秒内可供查询，但处理时间偶尔会有所波动。如遇问题请访问 status.litefuse.ai。

SDK

通过 Python 与 JS/TS 的 SDK，你可以轻松查询 API，无需自己编写 HTTP 请求。

如果你需要的是聚合指标（例如计数、成本、用量）而非单个实体，可考虑使用 Metrics API。它针对聚合查询做了优化，且限流额度更高。

pip install langfuse
from langfuse import get_client
langfuse = get_client()  # uses environment variables to authenticate

api 命名空间是基于公共 API（OpenAPI）自动生成的。方法名与 REST 资源对应，并支持过滤器和分页。

⚠️

从 Python SDK v4 与 JS/TS SDK v5 起，高性能端点已经成为默认：

  • api.observations（原 api.observations_v_2 / api.observationsV2）
  • api.scores（原 api.score_v_2 / api.scoreV2）
  • api.metrics（原 api.metrics_v_2 / api.metricsV2）

旧的 v2 别名已在这些主版本中移除。Legacy v1 端点 现位于 api.legacy.*（Python：*_v1，JS/TS：*V1）。

Traces

traces = langfuse.api.trace.list(limit=100, user_id="user_123", tags=["production"])  # pagination via cursor
trace = langfuse.api.trace.get("traceId")

Observations

# Default high-performance endpoint (formerly observations_v_2)
observations = langfuse.api.observations.get_many(
    trace_id="abcdef1234",
    type="GENERATION",
    limit=100,
    fields="core,basic,usage"
)
 
# Legacy v1 endpoint
legacy_observations = langfuse.api.legacy.observations_v1.get_many(
    trace_id="abcdef1234",
    type="GENERATION",
    limit=100
)
legacy_observation = langfuse.api.legacy.observations_v1.get("observationId")

Sessions

sessions = langfuse.api.sessions.list(limit=50)

Scores

# Default high-performance endpoint (formerly score_v_2)
langfuse.api.scores.get_many(score_ids = "ScoreId")
 
# Legacy v1 endpoint
langfuse.api.legacy.score_v1.get(score_ids = "ScoreId")

Prompts

获取 prompt 的方式请参阅 prompt 管理文档。

Datasets

# Namespaces:
# - langfuse.api.datasets.*
# - langfuse.api.dataset_items.*
# - langfuse.api.dataset_run_items.*

Metrics

# Default high-performance endpoint (formerly metrics_v_2)
query_v2 = """
{
  "view": "observations",
  "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
  "dimensions": [{"field": "providedModelName"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""
 
langfuse.api.metrics.get(query = query_v2)
 
# Legacy v1 endpoint
query_v1 = """
{
  "view": "traces",
  "metrics": [{"measure": "count", "aggregation": "count"}],
  "dimensions": [{"field": "name"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""
 
langfuse.api.legacy.metrics_v1.metrics(query = query_v1)

异步等价方法

# All endpoints are also available as async under `async_api`:
trace = await langfuse.async_api.trace.get("traceId")
traces = await langfuse.async_api.trace.list(limit=100)

通用过滤与分页

  • limit、cursor（分页）
  • 时间范围过滤器（例如 start_time、end_time）
  • 实体过滤器：user_id、session_id、trace_id、type、name、tags、level 等

每个资源的具体参数请查阅 Public API。

相关资源

  • 对于大规模的数据导出（例如用于微调或分析的全部 trace），可考虑使用 对象存储导出，按计划自动同步数据到 S3、GCS 或 Azure，无需通过 API 翻页获取。
  • 要从 Litefuse UI 手动导出过滤后的数据，请参阅 从 UI 导出。
Public API
这个页面对你有帮助吗？
支持