以编程方式使用文档

每次通过 LLM Gateway 的调用都会被追踪到 LangSmith，策略违规会在 LangSmith Engine 中进行分类。

网关追踪的显示位置

默认情况下，所有网关代理的调用都会被追踪到 gateway 中的 工作区 相关的项目，以及一个带有以下方案的 API 密钥特定项目 gateway-<short_api_key>-<api_key_id>.

使用以下方式控制对这些追踪项目的访问 RBAC 和 ABAC

追踪元数据

网关代理的调用可以通过其落入的项目及附加到其跨度上的元数据与直接 LLM 调用区分开来：

  • 网关项目： 所有网关流量都写入每个工作区中的中央网关项目，以及一个名为 gateway 的固定 LangSmith 项目，每个 API 密钥的副本位于 gateway-<short_api_key>-<api_key_id> 用于 UI 隔离。按项目过滤（或通过存在 langsmith.metadata.gateway.* 来查找网关代理的调用。
  • 策略评估结果： 每个网关跨度记录哪些策略已被评估及其结果 langsmith.metadata.gateway.policy.matched_ids/_names, passed_ids/_names和 violated_ids/_names以便捕获通过和阻止的情况。
  • 防护规则匹配： 当脱敏策略适用时，防护管道会发出 rule_id → count 映射，作为 policy.matched_rules, passed_rules和 violated_rules附加到跨度上。这些是规则 ID，而非 PII 或密钥类别标签。
  • 成本数据： 令牌数量和成本被内联计算，并输入相同的支出累加器，支出上限策略会对此进行强制执行。

LangSmith Engine 集成

当治理策略被触发时（例如达到支出限制、检测到并脱敏了 PII，或捕获到密钥），该事件会被记录为追踪上的元数据。这些策略违规会在 LangSmith Engine 中显示为问题。

从 Engine 问题中，您可以：

  1. **查看违规情况：** 触发了哪个策略，阻止或脱敏了什么内容。
  2. **点击查看追踪：** 查看代理在策略触发时具体在做什么。
  3. **诊断根本原因：** 是重试循环消耗预算、用户将凭证粘贴到提示中，还是合法工作负载超出其上限等。
  4. **采取行动：** 更新代理的配置、调整策略，或升级。

审计日志

网关记录两类事件：

类别记录内容
**管理变更**策略的创建、修改和删除。与网关访问相关的角色和权限变更。
**网关调用**每个代理调用，包括调用方身份和匹配的策略 ID。

审计日志 可供组织管理员在 企业版.

权限

所需权限

操作所需权限默认拥有者
通过网关发起调用gateway:invoke + workspaces:readWORKSPACE_ADMIN 仅
创建、编辑或删除策略organization:manage组织管理员
查看网关追踪projects:read + runs:readWORKSPACE_ADMIN, WORKSPACE_USER, WORKSPACE_VIEWER
查看审计日志organization:manage组织管理员

内置 WORKSPACE_USER 和 WORKSPACE_VIEWER 角色 **不** 包含 gateway:invoke 并且无法编辑。如需授予网关访问权限但无需完整的workspace管理员权限，请创建自定义workspace角色 gateway:invoke 和 workspaces:read （需要启用RBAC的计划）。有关说明，请参阅 管理员设置.

API密钥范围

始终为网关使用workspace范围的API密钥。不支持使用组织范围的密钥调用网关。

集中化管理提供商凭证

网关将提供商API密钥集中在LangSmith workspace密钥中。个人开发者和代理使用其 LangSmith API密钥 进行身份验证，无需直接访问提供商密钥。

这意味着：

  • 凭证控制： 提供商密钥集中在一处，由管理员管理。撤销访问权限意味着撤销LangSmith API密钥，而不是查找分散的提供商密钥副本。
  • 策略执行： 由于所有调用都通过网关流动，策略能够一致地执行。只要开发者没有单独访问提供商密钥的权限，就无法通过直接调用提供商来绕过成本限制。

为确保按预期工作，请勿在授予网关访问权限的同时向开发者分发提供商API密钥。网关默认集中管理提供商凭证。OAuth流程（如Claude Code Max）也存在透传模式——如果您的组织希望允许或限制此功能，请与我们联系。

限制追踪可见性

网关追踪作为运行记录写入workspace项目，并遵循LangSmith的标准workspace成员资格模型。任何拥有 runs:read （以及 projects:read 查看项目本身的权限）在workspace上可以查看该workspace的网关项目中的追踪。内置角色 WORKSPACE_ADMIN, WORKSPACE_USER和 WORKSPACE_VIEWER 默认都包含这两项权限。

如果需要限制谁可以查看网关追踪，您有两个选项：

  • 独立工作空间 （适用于任何 方案）：创建一个受限成员的工作空间，另一个用于开发者编码代理，具有更广泛的成员。每个工作空间都有自己的提供商密钥和追踪项目。
  • 项目级访问策略 （需要 企业版方案）：编写 ABAC 策略限制 projects:read 和 runs:read 对网关项目上的访问权限设置为特定用户或角色。

后续步骤