概览

本概览涵盖在 LangSmith 中管理用户、组织、工作区和应用程序的相关主题。

​

资源层级

​

组织

组织是 LangSmith 中用户的逻辑分组，定义了适用于其所有工作区的共享设置。这些设置管理的是组织范围内的问题，而非工作区内的单个项目。常见的组织级配置包括用户管理、单点登录 (SSO)、OAuth 提供商配置、自定义角色创建、计费和用量跟踪。通常，每个公司有一个组织。一个组织可以有多个工作区。更多详情，请参阅设置指南。 首次登录时，系统会自动为您创建一个个人组织。如果您希望与他人协作，可以创建一个单独的组织并邀请团队成员加入。您的个人组织与共享组织之间有几个重要区别：

​

工作区

工作区是组织内用户和资源的逻辑分组。工作区通常用于隔离团队或业务部门，提供项目及其相关资源之间的分离。工作区为资源和访问控制分离了信任边界。用户在工作区级别被授予权限，这些权限决定了他们对该工作区中资源的访问权限，包括跟踪项目、数据集、标注队列和提示。有关设置详情，请参阅设置指南；有关权限详情，请参阅工作区 (RBAC)。 我们建议为组织内的每个团队创建一个单独的工作区。为了进一步组织资源，您可以使用应用程序来分组工作区内的资源。有关基于团队隔离需求的不同工作区组织模型的指导，请参阅工作负载隔离。

​

应用程序

应用程序是工作区内资源的逻辑分组。应用程序通常是代理，但您可以将它们用于团队内的任何项目。应用程序通过仅显示当前上下文中关联的应用程序资源来保持 UI 的整洁。 应用程序构建在资源标签之上，可用于使用 ABAC 控制资源访问。 在 LangSmith UI 的主导航栏中切换应用程序。使用侧边栏顶部的 Application 下拉菜单选择一个应用程序。 任何资源都可以在不标记到应用程序的情况下创建。当选择 All applications 选项时，这些资源将可见。

​

资源

资源是用于构建、运行和观察应用程序及代理的具体实体，例如跟踪项目、提示、数据集和部署。资源的作用域限定于特定的应用程序。

​

附加信息

下图说明了组织、工作区、应用程序和资源之间的关系： 有关哪些功能在哪些范围内可用，请参见下表： * 数据保留设置和用量限制也将很快适用于组织级别 ** 自托管安装可以通过功能标志启用工作区级别的用户邀请到组织。详情请参阅自托管用户管理文档。

​

资源标签

资源标签允许您进一步区分工作区内的资源，以便与 ABAC 一起使用。每个标签是一个键值对，您可以将其分配给资源。 LangSmith 资源标签与 AWS 等云服务中的标签非常相似。 在 LangSmith UI 中导航至 Settings，在侧边栏中选择 Resource tags 页面。

​

用户管理与 RBAC

​

用户

用户是可以访问 LangSmith 的人员。用户可以是一个或多个组织及其内工作区的成员。 组织成员在 Settings 页面的 Members and roles 下进行管理。 工作区成员在 Settings 页面的 Workspaces 下进行管理。

​

API 密钥

​

过期日期

创建 API 密钥时，您可以选择设置过期日期。为密钥添加过期日期可增强安全性并最大限度地降低未经授权访问的风险。例如，您可以为需要提升权限的临时任务设置密钥的过期日期。 默认情况下，密钥永不过期。一旦过期，API 密钥将不再有效，无法重新激活或修改其过期时间。

​

个人访问令牌 (PAT)

个人访问令牌 (PAT) 用于向 LangSmith API 发送请求进行身份验证。它们由用户创建，并限定于特定用户。PAT 将拥有与创建它的用户相同的权限。我们建议不要使用这些令牌来验证来自应用程序的请求，而是将其用于与 LangSmith API 交互的个人脚本或工具。如果与 PAT 关联的用户从组织中移除，该 PAT 将不再有效。 PAT 以 lsv2_pt_ 为前缀

​

服务密钥

服务密钥类似于 PAT，但用于代表服务账户向 LangSmith API 发送请求进行身份验证。只有管理员可以创建服务密钥。我们建议将这些密钥用于需要与 LangSmith API 交互的应用程序/服务，例如 LangGraph 代理或其他集成。服务密钥可以限定于单个工作区、多个工作区或整个组织，并可用于向其有权访问的工作区发送 LangSmith API 请求进行身份验证。 服务密钥以 lsv2_sk_ 为前缀

​

组织角色

组织角色与企业功能工作区 RBAC 不同，用于多个工作区的上下文中。您的组织角色决定了您的工作区成员资格特征和您的组织级权限。 选择的组织角色也会影响工作区成员资格，如下所述：

• 组织管理员 授予完全访问权限以管理所有组织配置、用户、计费和工作区。
  • 组织管理员对组织中的所有工作区具有 Admin 访问权限。
• 组织用户 可以读取组织信息，但不能在组织级别执行任何写操作。组织用户可以创建个人访问令牌。
  • 组织用户可以被添加到部分工作区，并像往常一样分配工作区角色（如果启用了 RBAC），这些角色指定了工作区级别的权限。
• 组织查看者 等同于组织用户，但不能创建个人访问令牌。（对于自托管，适用于 Helm chart 版本 0.11.25+）。

有关设置组织和工作区的更多信息，请参阅组织设置指南。 下表概述了组织级别的权限： 有关所需权限的完整列表以及可执行这些权限的操作和角色，请参阅组织和工作区参考。

​

工作区角色 (RBAC)

角色用于定义用户在工作区内的权限集。有三个内置的系统角色无法编辑：

• 工作区管理员 对工作区内的所有资源具有完全访问权限。
• 工作区编辑者 除了工作区管理（添加/移除用户、更改角色、配置服务密钥）外，拥有完全权限。
• 工作区查看者 对工作区内的所有资源具有只读访问权限。

组织管理员 也可以创建/编辑具有不同资源特定权限的自定义角色。 您可以在 Organization Settings > Members and roles 下管理角色，并选择 Roles 选项卡。

• 有关角色和权限的全面文档，请参阅基于角色的访问控制指南。
• 有关分配和创建角色的更多详情，请参阅用户管理指南。
• 有关所需权限的完整列表以及可执行这些权限的操作和角色，请参阅组织和工作区参考。

​

最佳实践

​

环境分离

使用资源标签通过默认标签键 Environment 和不同的环境值（例如 dev、staging、prod）按环境组织资源。我们不建议使用单独的工作区进行环境分离，因为资源无法跨工作区共享，这将阻止您在环境之间提升资源（如提示）。

​

使用与计费

​

数据保留

本节介绍数据保留的工作原理及其在 LangSmith 中的定价。

​

为什么保留很重要

• 隐私：许多数据隐私法规，如欧洲的 GDPR 或加利福尼亚的 CCPA，要求组织在个人数据不再为收集目的所必需时删除这些数据。设置保留期限有助于遵守此类法规。
• 成本：LangSmith 对数据保留期较短的跟踪收费较低。有关更多信息，请了解如何强制执行支出限制。

​

工作原理

LangSmith 根据数据保留有两个跟踪层级，具有以下特征： 保留期结束后删除数据 在指定的保留期后，跟踪在跟踪项目 UI 或通过 API 中将不再可访问。此后一天内，与该跟踪相关的所有用户数据（例如输入和输出）将从我们的内部系统中删除。与每个跟踪关联的一些元数据可能会被无限期保留，用于分析和计费目的。

​

数据保留自动升级

当您使用某些具有 base 层级跟踪的功能时，其数据保留将自动升级到 extended 层级。这将增加保留期限和跟踪的成本。 跟踪将在以下情况下升级的完整场景列表：

• 向跟踪上的任何运行（或线程中的任何跟踪）添加了反馈，无论是通过手动标注、使用在线评估器自动添加，还是通过 SDK 以编程方式添加。
• 标注队列 接收到来自该跟踪的任何运行。
• 自动化规则 匹配跟踪内的任何运行。

为什么要自动升级跟踪？ 我们对跟踪的自动升级模型有两个原因：

1. 我们认为符合这些条件中的任何一个的跟踪从根本上比其他跟踪更有趣，因此让用户能够更长时间地保留它们是件好事。
2. 从理念上讲，我们希望对可能没有被有意义地交互的跟踪向客户收取低一个数量级的费用。我们认为自动升级使我们的定价模型与 LangSmith 带来的价值保持一致，即只有具有有意义交互的跟踪才按更高的费率收费。

如果您对我们的定价模型有任何疑问或疑虑，请随时通过 support.langchain.com 联系支持团队并告知您的想法！ 数据保留如何影响下游功能？

• 标注队列、运行规则和反馈：使用这些功能的跟踪将被自动升级。
• 监控：即使在基础层级跟踪的数据保留期结束后，监控选项卡仍将继续工作。它由存在超过 30 天的跟踪元数据驱动，这意味着即使对于 base 层级的跟踪，您的监控图表也将继续保持准确。
• 数据集：数据集具有无限的数据保留期。换句话说，如果您将跟踪的输入和输出添加到数据集，它们将永远不会被删除。我们建议如果您使用 LangSmith 进行数据收集，请利用数据集功能。

​

计费模型

可计费指标 在您的 LangSmith 发票上，您将看到我们收取的两个指标：

• LangSmith 跟踪（基础费用）
• LangSmith 跟踪（扩展数据保留升级）。

第一个指标包括所有跟踪，无论层级如何。第二个指标仅计算扩展保留跟踪的数量。 为什么测量所有跟踪 + 升级，而不是基础和扩展跟踪？ 在考虑我们的定价时，一个自然的问题是为什么不直接在发票上显示 base 层级和 extended 层级跟踪的数量？ 虽然我们理解这会更直接，但它不能正确处理跟踪升级。考虑一个在 6 月 30 日记录的 base 层级跟踪，并在 7 月 3 日升级到 extended 层级。base 层级跟踪发生在 6 月计费周期，但升级发生在 7 月计费周期。因此，我们需要能够独立测量这两个事件，以便正确地向客户收费。 如果您的跟踪是作为扩展保留跟踪记录的，那么 base 和 extended 指标将以相同的时间戳记录。 成本明细 跟踪的基础费用为每跟踪 .05¢。我们将升级定价为 extended 保留跟踪的成本是基础层级跟踪价格的 10 倍（每跟踪 .50¢），包括两个指标。因此，每次升级的成本为 .45¢。

​

速率限制

LangSmith 具有速率限制，旨在确保所有用户的服务稳定性。 为确保访问和稳定性，LangSmith 将在以下情况下返回 HTTP 状态码 429，表示速率或用量限制已超出：

​

在应用负载均衡器上 1 分钟内的临时吞吐量限制

此 429 是在 1 分钟窗口内超出固定数量的 API 调用（基于每个服务密钥或 PAT）的结果。窗口的开始时间会略有不同——不保证在时钟分钟的开始时开始——并且可能根据应用程序部署事件而变化。 在达到最大事件数后，我们将返回 429，直到评估窗口开始后 60 秒，然后该过程重复。 此 429 由我们的应用负载均衡器抛出，是适用于所有 LangSmith 用户（无论计划层级如何）的一种机制，以确保所有用户的服务连续性。

​

计划级别的每小时跟踪事件限制

此 429 是达到您每小时最大摄入事件数的结果，在 UTC 每个时钟小时开始时的固定窗口中进行评估，并在每个新小时开始时重置。 在此上下文中，事件是运行的创建或更新。如果一个运行被创建然后在同一小时内更新，这将计为 2 个事件，计入此限制。 此限制由我们的应用程序抛出，并因计划层级而异，我们的 Startup/Plus 和 Enterprise 计划层级的组织比我们的 Free 和 Developer 计划层级（设计用于个人使用）具有更高的每小时限制。

​

计划级别的每小时跟踪数据摄入限制

此 429 是达到您跟踪输入、输出和元数据中摄入的最大数据量的结果，在 UTC 每个时钟小时开始时的固定窗口中进行评估，并在每个新小时开始时重置。 通常，输入、输出和元数据在运行创建和更新事件时都会发送。如果一个运行以 2.0MB 创建并在同一小时内更新到 3.0MB，这将计为 5.0MB 的存储，计入此限制。 此限制由我们的应用程序抛出，并因计划层级而异，我们的 Startup/Plus 和 Enterprise 计划层级的组织比我们的 Free 和 Developer 计划层级（设计用于个人使用）具有更高的每小时限制。

​

计划级别的每月唯一跟踪限制

此 429 是达到您每月最大摄入跟踪数的结果，在 UTC 每个日历月开始时的固定窗口中进行评估，并在每个新月开始时重置。 此限制由我们的应用程序抛出，仅适用于没有支付方式的开发者计划层级。

​

自配置的每月用量限制

此 429 是达到您的组织管理员配置的用量限制的结果，在 UTC 每个日历月开始时的固定窗口中进行评估，并在每个新月开始时重置。 此限制由我们的应用程序抛出，并因组织的配置设置而异。

​

每跟踪最大运行数

每个跟踪最多限制为 25,000 次运行。一旦跟踪达到此限制，LangSmith 将拒绝您为该跟踪发送的任何额外运行。

​

运行查询端点

POST /runs/query 端点具有基于查询参数的额外每租户速率限制。详情请参阅使用 SDK 查询跟踪。

​

在应用程序中处理 429 响应

由于某些 429 响应是临时的，并且可能在后续调用中成功，如果您在应用程序中直接调用 LangSmith API，我们建议实现带有指数退避和抖动的重试逻辑。 为方便起见，使用 LangSmith SDK 构建的 LangChain 应用程序内置了此功能。

​

用量限制

LangSmith 允许您配置跟踪的用量限制。请注意，这些是用量限制，而不是支出限制，这意味着它们允许您限制某些事件的发生次数，而不是您将花费的总金额。 LangSmith 允许您设置两个不同的月度限制，与上述数据保留指南中讨论的可计费指标相对应：

• 所有跟踪限制
• 扩展数据保留跟踪限制

这些限制分别允许您限制总跟踪数和扩展数据保留跟踪数。

​

用量限制的特性

用量限制是近似的，这意味着我们不保证限制的精确性。在极少数情况下，在用量限制开始生效之前，可能会有一小段时间处理超过限制阈值的额外跟踪。

​

扩展数据保留跟踪限制的副作用

扩展数据保留跟踪限制具有副作用。如果限制已经达到，任何可能导致跟踪层级自动升级的功能都将无法访问。因为跟踪的自动升级将导致创建另一个扩展保留跟踪，而这又不应被限制允许。因此，您将无法再：

1. 匹配运行规则
2. 向跟踪添加反馈
3. 将运行添加到标注队列

这些功能中的每一个都可能导致自动升级，因此当限制达到时，我们会关闭它们。

​

更新用量限制

可以从 Settings 页面的 Usage and Billing 下更新用量限制。限制值会被缓存，因此可能需要一两分钟才能应用新限制。

​

相关内容

• 关于如何强制执行支出限制的教程

​

附加资源

• 发布策略：了解自托管发布渠道、节奏和版本编号。

---