OpenRouter 安全与可观测

OpenRouter 安全与可观测

广播概览

3 分钟阅读

广播（Broadcast）

将追踪发送到外部可观测性平台

广播可将 OpenRouter 请求中的追踪自动发送到外部可观测性和分析平台。借助该功能，你可以在常用工具中监控、调试和分析 LLM 用量，而无需在应用代码中额外埋点。

启用广播

要为你的账户或组织启用广播：

  1. 在 OpenRouter 控制台前往 设置 > 可观测性（Settings > Observability）
  2. 打开 启用广播（Enable Broadcast） 开关以启用该功能
  3. 添加一个或多个用于接收追踪的目标端

如果你使用的是组织账户，必须具备组织管理员权限才能编辑广播设置。

启用后，OpenRouter 会自动将你所有 API 请求的追踪数据发送到已配置的目标端。

支持的目标端

目前可用的目标端如下：

每个目标端都有各自的配置要求，例如 API 密钥、端点或项目标识符。添加目标端时，系统会提示你提供所需凭据；这些凭据会加密后安全存储。

要查看最新的可用目标端列表，请访问控制台中的 广播设置页。

即将推出

以下目标端正在开发中，即将可用：

  • AWS Firehose
  • Dynatrace
  • Evidently
  • Fiddler
  • Galileo
  • Helicone
  • HoneyHive
  • Keywords AI
  • Middleware
  • Mona
  • OpenInference
  • Phoenix
  • Portkey
  • Supabase
  • WhyLabs

追踪数据

每条广播追踪都包含关于 API 请求的完整信息：

  • 请求与响应数据：输入消息和模型输出（为提高效率，多模态内容已被剥离）
  • Token 用量：消耗的提示词 Token、补全 Token 以及 Token 总量
  • 费用信息：该请求的总费用
  • 时间信息：请求开始时间、结束时间以及延迟指标
  • 模型信息：该请求使用的模型 slug 和模型服务提供商名称
  • 工具使用情况：请求中是否包含工具，以及是否发生了工具调用

可选追踪数据

你可以在 API 请求中加入以下可选字段，为追踪补充更多上下文：

  • 用户 ID：通过 user 字段（最多 128 个字符）将追踪与特定终端用户关联。这有助于分析用量模式，并为单个用户排查问题。
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Hello, world!"
    }
  ],
  "user": "user_12345"
}
  • 会话 ID：通过 session_id 字段（最多 256 个字符）将相关请求归为一组（例如一次对话或智能体工作流）。也可以通过 x-session-id HTTP 请求头传入。
{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Hello, world!"
    }
  ],
  "session_id": "session_abc123"
}

自定义元数据

对于更高级的可观测性工作流，你可以使用 trace 字段向追踪传入任意元数据。该字段接受任意 JSON 对象，并会透传到所有已配置的广播目标端。

{
  "model": "openai/gpt-4o",
  "messages": [
    {
      "role": "user",
      "content": "Summarize this document..."
    }
  ],
  "trace": {
    "trace_id": "workflow_12345",
    "trace_name": "Document Processing",
    "span_name": "Summarization Step",
    "generation_name": "Generate Summary",
    "environment": "production",
    "feature": "customer-support",
    "version": "1.2.3"
  }
}

trace 字段很灵活，可接受任意键值对。部分键会因可观测性目标端而具有特殊含义。各平台识别哪些键，请参阅对应目标端的文档。

常用元数据键

这些元数据键在各可观测性平台中较为常用：

键说明
trace_id将多次 API 请求归入同一条追踪。在多个请求中使用相同 ID，即可跟踪多步骤工作流。
trace_name可观测性平台中根追踪的自定义名称。未设置时默认为模型名称。
span_name创建一个用于归组 LLM 操作的父 Span，形成由该 Span 包含生成过程的层次结构。
generation_name特定 LLM 生成/调用的自定义名称。未设置时默认为模型名称。
parent_span_id将 OpenRouter 追踪关联到你自己追踪系统（例如 OpenTelemetry）中已有的 Span。

使用这些字段后，追踪会在 Langfuse 等平台中以层次结构显示：

Document Processing (trace_id: workflow_12345)
└── Summarization Step (span)
    └── Generate Summary (generation)

关联外部追踪

如果你已有自己的追踪埋点（例如 OpenTelemetry），可以使用 parent_span_id 将 OpenRouter 调用嵌套到现有 Span 之下：

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "trace": {
    "trace_id": "your-existing-trace-id",
    "parent_span_id": "your-existing-span-id"
  }
}

这将形成如下追踪结构：

Your Application Trace
└── Your Application Span (parent_span_id)
    └── openai/gpt-4o (generation from OpenRouter)

这样你可以：

  • 跟踪跨越多次 LLM 调用的端到端工作流
  • 按业务逻辑而非单次 API 调用组织追踪
  • 使用有意义的追踪名称构建更丰富的可观测性仪表盘
  • 将 OpenRouter 追踪与现有应用追踪集成
  • 向可观测性平台传递所需的任意自定义数据

目标端专属元数据

各可观测性平台识别的元数据键可能不同。详情见对应目标端指南：

  • Langfuse - 支持追踪命名、用户/会话 ID 以及任意元数据
  • LangSmith - 支持标签、会话跟踪和元数据
  • Datadog - 支持标签、用户 ID 和会话 ID
  • Braintrust - 支持标签和自定义元数据字段
  • W&B Weave - 支持追踪数据中的自定义属性
  • Arize AX - 支持 OpenInference Span 属性和元数据
  • Comet Opik - 支持追踪/Span 元数据以及费用跟踪
  • Grafana Cloud - 支持可用 TraceQL 查询的 Span 属性
  • New Relic - 支持可用 NRQL 查询的 Span 属性
  • Sentry - 支持用于性能监控的 Span 属性
  • OpenTelemetry Collector - 支持面向任意后端的 OTLP Span 属性
  • Webhook - OTLP JSON 载荷中的自定义元数据
  • PostHog - 支持用于 LLM 分析的事件属性
  • Raindrop - 支持用于 AI 可观测性的自定义事件属性
  • Ramp - 支持用于 AI 费用跟踪的 OTLP Span 属性
  • Snowflake - 可通过 VARIANT 列函数查询
  • ClickHouse - 可通过 JSONExtract 函数查询
  • Google BigQuery - 可通过 JSON 函数查询
  • S3 - 存储在追踪 JSON 文件中

API 密钥筛选

每个目标端都可以配置为仅接收来自特定 API 密钥的追踪。这在以下场景中很有用：

  • 将应用不同部分的追踪路由到不同的可观测性平台
  • 为特定用例隔离监控
  • 或让生产 API 密钥的追踪采样率低于开发密钥

添加或编辑目标端时，你可以从账户中选择一个或多个 API 密钥。只有使用这些选定 API 密钥发出的请求，其追踪才会发送到该目标端。如果未选择任何 API 密钥，该目标端将接收来自你所有 API 密钥或聊天室请求的追踪。

采样率

每个目标端都可以配置采样率，以控制发送追踪的百分比。对于高流量应用，这有助于在降低成本或数据量的同时，仍保持对 LLM 用量的可见性。采样率为 1.0 时发送全部追踪，0.5 则大约发送 50% 的追踪。

采样是确定性的：当你提供 session_id 时，该会话内的所有追踪会被一并包含或排除。这样你在可观测性平台中看到的始终是完整会话，而不是碎片化数据。

每个目标端都会收到完整会话，但不同目标端收到的会话不一定相同。

隐私模式

每个目标端都可以按需启用隐私模式（Privacy Mode），从追踪中排除提示词和补全内容。启用隐私模式后，发送追踪前会剥离以下数据：

  • 输入消息（发送给模型的提示词）
  • 输出选项（模型返回的补全）

其余追踪数据（包括 Token 计数、费用、时间信息、模型信息以及自定义元数据）仍会正常发送。

这适用于你希望监控 LLM 用量指标和费用、但不暴露对话实际内容的场景，例如为了满足数据隐私法规或内部政策。

要启用隐私模式，请在配置目标端时，在 隐私（Privacy） 部分勾选 隐私模式（Privacy Mode） 复选框。

隐私模式按目标端分别配置。你可以将完整追踪发送到一个用于调试的目标端，同时将经过隐私脱敏的追踪发送到另一个用于费用监控的目标端。

安全性

目标端凭据在存储前会加密，仅在发送追踪时解密。追踪在请求完成后异步发送，因此启用广播不会增加 API 响应的延迟。

组织支持

广播可在个人用户和组织两个层级配置。组织管理员可以设置适用于组织内所有 API 密钥的共享目标端，从而保证团队可观测性的一致性。

分步指南

配置特定可观测性目标端的分步指南：

上一页模型服务提供商日志下一页 Arize AX