Langfuse 可观测性

Langfuse 是一个开源的 LLM 可观测性平台。Nantian AI 网关可以直接将追踪（trace）、生成（generation）、评分（score）和提示词使用数据写入你的 Langfuse 实例，让你从一个仪表盘监控模型性能、调试生产问题并追踪成本。

工作原理

当在 AIService 上配置 Langfuse 后，网关将每次 AI 请求记录为一条 Langfuse 追踪。该追踪中的每次模型调用会生成一条生成记录，包含令牌用量、延迟、输入内容和输出内容。你还可以为追踪附加评分以进行自定义评估。网关异步地将这些数据发送到 Langfuse 写入 API。

从网关角度看，数据写入是即发即忘的。对 Langfuse 的 HTTP 调用发生在请求路径之外，因此不会增加客户端响应的延迟。如果写入失败，网关记录错误但不重试，也不会影响正在处理的请求。

当 Langfuse 公钥留空或客户端被显式禁用（空操作模式）时，所有写入方法变为静默空操作。不会发起 HTTP 请求，也不会抛出错误。

配置

Langfuse 需要三个配置值：

字段	描述
`host`	你的 Langfuse 实例的基础 URL（例如 `https://langfuse.example.com`）。
`publicKey`	你的 Langfuse 项目公钥。
`secretKey`	你的 Langfuse 项目私钥。

认证使用 HTTP Basic Auth，以公钥为用户名、私钥为密码，进行 base64 编码。

超时

用于 Langfuse 通信的 HTTP 客户端有两个超时值：

超时	值	描述
请求超时	10 秒	完整 HTTP 请求-响应周期的最大时间。
连接超时	5 秒	建立到 Langfuse 主机的 TCP 连接的最大时间。

这些值是硬编码的，不可配置。由于写入是非阻塞的，写入调用的超时仅意味着该条追踪或生成记录丢失，而非客户端请求失败。

追踪

追踪代表单次 AI 请求通过网关的完整生命周期。每条追踪包含：

字段	描述
`traceId`	此追踪的唯一标识符。
`userId`	可选的用户标识符，将追踪限定到特定最终用户。
`sessionId`	可选的会话标识符，用于对多次用户交互进行分组。
`metadata`	附加到追踪的任意键值对。
`timestamp`	追踪创建时间的 ISO 8601 时间戳。

追踪在请求开始处理时创建。所有后续生成记录和评分都引用相同的追踪 ID，便于在 Langfuse 中重建完整的请求链路。

生成记录

生成记录代表一次追踪中单次对 AI 模型的调用。每条生成记录记录：

字段	描述
`traceId`	此生成记录所属的父追踪。
`model`	模型名称（例如 `gpt-4o`、`claude-3-sonnet`）。
`usage.input`	消耗的输入（提示）令牌数。
`usage.output`	产生的输出（补全）令牌数。
`usage.total`	输入和输出令牌的总和。
`latency`	从请求到响应的往返时间，以秒为单位。
`input`	发送到模型的完整请求负载，JSON 格式。
`output`	模型返回的完整响应负载，JSON 格式。
`metadata`	附加到此生成记录的任意键值元数据。

如果请求通过降级链路多次尝试多个模型，每个模型尝试都会在同一追踪下产生各自的生成记录。这意味着你可以看到哪个模型最终成功，以及进行了多少次尝试。

评分

评分为追踪附加自定义数值指标。使用评分来追踪评估结果、质量信号或任何与 AI 流量相关的量化测量。

字段	描述
`traceId`	此评分适用的追踪。
`name`	评分的标签（例如 `toxicity`、`relevance`、`latency_score`）。
`value`	数值（浮点数）。
`comment`	可选的关于评分的自由文本注释。

评分独立于生成记录写入，可以在追踪完成后添加，因此适用于异步运行的离线评估工作流。

提示词管理

网关可以从 Langfuse 提示词管理（v2 API）获取提示词模板。获取到的提示词模板包括：

字段	描述
`name`	Langfuse 中提示词模板的名称。
`prompt`	编译后的提示词文本，变量已解析。
`version`	模板版本号。
`config`	附加到模板的任意配置数据（JSON 格式）。
`variables`	模板中使用的变量名称列表。

你可以请求特定版本，也可以让 Langfuse 返回最新版本。此集成让你可以在 Langfuse 的 UI 中管理提示词，并让网关在运行时拉取它们，无需重新部署。

配置示例

通过 observability 块在 AIService 上配置 Langfuse：

apiVersion: gateway.nantian.dev/v1alpha1
kind: AIService
metadata:
  name: observed-openai
  namespace: nantian-demo
spec:
  provider: openai
  format: openai
  model: gpt-4o
  observability:
    langfuse:
      host: https://langfuse.example.com
      publicKey: pk-lf-abc123
      secretKey: sk-lf-xyz789

使用此配置，每次通过 observed-openai 服务路由的请求都会自动将追踪、生成记录和任何附加的评分写入 langfuse.example.com 的 Langfuse 实例。

生产环境注意事项

写入是尽力而为的。网关不会缓冲或重试失败的写入调用。如果你的 Langfuse 实例不可达，追踪和生成记录将被静默丢弃。这种设计使网关保持快速和弹性：可观测性优雅降级，而不是导致请求失败。

监控网关日志中的写入错误以检测连通性问题。如果看到持续失败，请检查数据平面 Pod 能否访问 Langfuse 主机以及凭据是否仍然有效。