文档 / 通过 SDK 查询数据

通过 SDK 查询数据

Langfuse 是开源的,用 Langfuse 追踪的数据也是开放的。使用 Python 和 JS/TS SDK 查询相同的公共 API,而无需编写原始 HTTP 请求。

常见用例:

查询行级 observations,用于评估流水线、few-shot 示例或微调数据集。
查询聚合的成本、用量、延迟、体量和分数指标,用于仪表盘或计费工作流。
以编程方式创建数据集。

如果你初次接触 Langfuse,我们建议先熟悉 Langfuse 数据模型。

新数据通常在接入后 15-30 秒内可供查询,尽管处理时间有时会有所不同。如果遇到问题,请访问 status.langfuse.com。

SDK

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

api 命名空间是从 Public API(OpenAPI)自动生成的。方法名镜像 REST 资源,并支持过滤和分页。

从 Python SDK v4 和 JS/TS SDK v5 起,高性能数据 API 是默认值:

api.observations(原 api.observations_v_2 / api.observationsV2)

api.scores_v3 / api.scoresV3——v3 分数读取;api.scores(v2 读取)已弃用,参见已弃用 API 的迁移

api.metrics(原 api.metrics_v_2 / api.metricsV2)

旧的 v2 别名在 Python SDK v4 和 JS/TS SDK v5 中已被移除。

api.legacy.* 资源调用已弃用的端点;替换方案和端点参考参见已弃用 API 的迁移。

bash

pip install langfuse

python

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

Observations

python

observations = langfuse.api.observations.get_many(
    trace_id="abcdef1234",
    type="GENERATION",
    limit=100,
    fields="core,basic,usage"
)

使用 trace_id 检索属于单个 trace 的 observations。需要时使用响应中的 parent_observation_id 重建 observation 树。

Metrics

完整的查询 schema、支持的维度、过滤器和示例,参见 Metrics API v2 文档。

python

query = """
{
  "view": "observations",
  "metrics": [{"measure": "totalCost", "aggregation": "sum"}],
  "dimensions": [{"field": "providedModelName"}],
  "filters": [],
  "fromTimestamp": "2025-05-01T00:00:00Z",
  "toTimestamp": "2025-05-13T00:00:00Z"
}
"""

metrics = langfuse.api.metrics.get(query = query)

其他资源

Sessions:

python

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

Scores:

python

# Scores API v3 (recommended)
scores = langfuse.api.scores_v3.get_many_v3(id="ScoreId")

# Scores API v2 (deprecated)
scores = langfuse.api.scores.get_many(score_ids="ScoreId")

要将现有 v2 分数读取迁移到 v3,参见已弃用 API 的迁移。

Prompts:

获取提示词请参阅提示词管理文档。

Datasets:

python

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

异步等价方法

python

# All endpoints are also available as async under `async_api`:
observations = await langfuse.async_api.observations.get_many(
    trace_id="abcdef1234",
    limit=100,
    fields="core,basic,usage",
)
metrics = await langfuse.async_api.metrics.get(query = query)

行级 observation 过滤器、字段选择和游标分页,参见 Observations API v2 文档。

langfuse.api 上的方法是从 API 参考自动生成的,涵盖所有实体。你可以通过 Intellisense 探索更多实体。

bash

npm install @langfuse/client

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

Observations

const observations = await langfuse.api.observations.getMany({
  traceId: "abcdef1234",
  type: "GENERATION",
  limit: 100,
  fields: "core,basic,usage",
});

使用 traceId 检索属于单个 trace 的 observations。需要时使用响应中的 parentObservationId 重建 observation 树。

行级 observation 过滤器、字段选择和游标分页,参见 Observations API v2 文档。

Metrics

完整的查询 schema、支持的维度、过滤器和示例,参见 Metrics API v2 文档。

const query = {
  view: "observations",
  metrics: [{ measure: "totalCost", aggregation: "sum" }],
  dimensions: [{ field: "providedModelName" }],
  filters: [],
  fromTimestamp: "2025-05-01T00:00:00Z",
  toTimestamp: "2025-05-13T00:00:00Z",
};

const metrics = await langfuse.api.metrics.get({
  query: JSON.stringify(query),
});

其他资源

Sessions:

const sessions = await langfuse.api.sessions.list({ limit: 50 });

Scores:

// Scores API v3 (recommended)
const scoresV3 = await langfuse.api.scoresV3.getManyV3();

// Scores API v2 (deprecated)
const scores = await langfuse.api.scores.getMany();

要将现有 v2 分数读取迁移到 v3,参见已弃用 API 的迁移。

Prompts:

获取提示词请参阅提示词管理文档。

Datasets:

// Namespaces:
// - langfuse.api.datasets.*
// - langfuse.api.datasetItems.*
// - langfuse.api.experiments.*

通过 langfuse.api 上的 Intellisense 探索更多实体。

通过 SDK 查询数据

SDK

Observations

Metrics

其他资源

异步等价方法

Observations

Metrics

其他资源

相关资源