概念

本概念指南涵盖与在 LangSmith 中管理用户、组织和工作区相关的主题。

资源层级​

组织​

组织是 LangSmith 内用户的逻辑分组，拥有独立的计费配置。通常每个公司对应一个组织。一个组织可以包含多个工作区。更多详情，请参阅 设置指南。

首次登录时，系统会自动为您创建一个个人组织。如果您希望与他人协作，可以创建一个独立组织并邀请团队成员加入。 个人组织与共享组织之间存在一些重要区别：

功能	个人	共享
Maximum workspaces	1	Variable, depending on plan (see pricing page
Collaboration	Cannot invite users	Can invite users
Billing: paid plans	Developer plan only	All other plans available

工作区​

信息

工作区以前称为租户。在过渡期间，一些代码和 API 可能仍会引用旧名称。

工作区是组织内用户和资源的逻辑分组。工作区将资源和访问控制的信任边界分离开来。 用户在工作区中可能拥有权限，这些权限授予他们访问该工作区内资源的权限，包括跟踪项目、数据集、标注队列和提示词。更多详细信息，请参阅设置指南。

建议为组织内的每个团队创建独立的工作区。为了进一步组织资源，您可以使用 资源标签 将工作区内的资源进行分组。

以下图片展示了一个示例工作区设置页面：

下图解释了组织、工作区以及作用域内和工作区内的不同资源之间的关系：

有关各功能在哪些范围（组织或工作区）中可用，请参阅下表：

资源/设置	范围
Trace Projects	Workspace
Annotation Queues	Workspace
Deployments	Workspace
Datasets & Experiments	Workspace
Prompts	Workspace
Resource Tags	Workspace
API Keys	Workspace
Settings including Secrets, Feedback config, Models, Rules, and Shared URLs	Workspace
User management: Invite User to Workspace	Workspace
RBAC: Assigning Workspace Roles	Workspace
Data Retention, Usage Limits	Workspace*
Plans and Billing, Credits, Invoices	Organization
User management: Invite User to Organization	Organization**
Adding Workspaces	Organization
Assigning Organization Roles	Organization
RBAC: Creating/Editing/Deleting Custom Roles	Organization

* 数据保留设置和使用限制很快也将适用于组织级别 ** 自托管安装可能通过功能标志启用将用户邀请到组织的工作区级别的邀请。 有关详细信息，请参阅自托管用户管理文档。

资源标签​

资源标签允许您在工作区中组织资源。每个标签都是一个键值对，可以分配给资源。 标签可用于在 UI 和 API 中过滤工作区范围内的资源：项目、数据集、标注队列、部署和实验。

每个新工作区都带有两个默认标签键：Application 和 Environment；正如名称所示，这些标签可用于根据资源所属的应用程序和环境对其进行分类。 可根据需要添加更多标签。

LangSmith 资源标签与 AWS 等云服务中的标签非常相似。

用户管理和基于角色的访问控制​

用户​

用户是拥有 LangSmith 访问权限的人。用户可以是一个或多个组织及其工作区的成员。

组织成员在组织设置中进行管理：

工作区成员在工作区设置中进行管理：

API 密钥​

自2024年10月22日起，传统密钥已弃用

我们已于2024年10月22日停止支持以ls__开头的旧版API密钥，转而采用个人访问令牌（PAT）和服务密钥。所有新集成均要求使用PAT和服务密钥。自2024年10月22日起，以ls__开头的API密钥将不再有效。

个人访问令牌 (PATs)​

个人访问令牌（PAT）用于对 LangSmith API 的请求进行身份验证。它们由用户创建，并限定于特定用户。PAT 将拥有与其创建者相同的权限。

PATs 以 lsv2_pt_ 开头

服务密钥​

服务密钥类似于 PAT，但用于代表服务账户对 LangSmith API 发起请求进行身份验证。

服务密钥以 lsv2_sk_ 开头

注意

要查看如何创建服务密钥或个人访问令牌，请参阅 设置指南。

组织角色​

组织角色与下方的企业功能（RBAC）不同，用于多个 工作区 的上下文中。您的组织角色决定了您的工作区成员资格特征以及组织级别的权限。有关更多信息，请参阅 组织设置指南。

所选的组织角色也会影响工作区成员资格，说明如下：

• Organization Admin 拥有完全访问权限，可管理所有组织配置、用户、计费和工作区。An Organization Admin 对组织中的所有工作区具有 Admin 访问权限
• Organization User 可以读取组织信息，但无法在组织级别执行任何写入操作。An Organization User 可以被添加到工作区的子集，并像往常一样分配工作区角色（如果启用了 RBAC），这些角色指定了工作区级别的权限。

信息

Organization User角色仅在具有多个工作区的计划的组织中使用。在仅限单个工作区的组织中，所有用户均为Organization Admins。 自定义组织范围的角色尚不可用。

查看下表以了解所有组织权限：

	组织用户	组织管理员
View organization configuration	✅	✅
View organization roles	✅	✅
View organization members	✅	✅
View data retention settings	✅	✅
View usage limits	✅	✅
Admin access to all workspaces		✅
Manage billing settings		✅
Create workspaces		✅
Create, edit, and delete organization roles		✅
Invite new users to organization		✅
Delete user invites		✅
Remove users from an organization		✅
Update data retention settings*		✅
Update usage limits*		✅

工作区角色 (RBAC)​

注意

RBAC（基于角色的访问控制）是一项仅面向企业客户的特性。如果您对该功能感兴趣，请联系我们的销售团队 sales@langchain.dev。 其他计划默认将所有用户设置为管理员角色。

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

• Admin - 拥有工作区内所有资源的完全访问权限
• Viewer - 拥有对工作区内所有资源的只读访问权限
• Editor - 拥有除工作区管理（添加/移除用户、更改角色、配置服务密钥）之外的全部权限

组织管理员还可以创建/编辑具有特定权限的自定义角色，用于管理不同的资源。

角色可以在组织设置下的Roles标签页中管理：

有关分配和创建角色的更多详细信息，请参阅访问控制设置指南。

最佳实践

环境隔离​

使用 资源标签 通过默认标签键 Environment 和环境值（例如 dev、staging、prod）来按环境组织资源。这种标记结构将允许您今天组织您的追踪项目，并在我们发布基于属性的访问控制（ABAC）时轻松实施权限。资源标签上的 ABAC 将提供一种细粒度的方式来限制对生产追踪项目的访问，例如。我们不建议您使用工作区进行环境分离，因为您无法在工作区间共享资源。如果您希望将提示从 staging 升级到 prod，我们建议您使用提示标签。有关更多信息，请参阅 文档。

使用与计费​

数据保留​

2024 年 5 月，LangSmith 为追踪数据引入了最长 400 天的数据保留期限。2024 年 6 月，LangSmith 推出了基于数据保留期的新定价模式，客户可以配置更短的追踪数据保留期，以换取高达 10 倍的费用节省。在本页中，我们将介绍 LangSmith 中数据保留的工作机制及定价方式。

为什么留存很重要​

• 隐私: 许多数据隐私法规，如欧洲的 GDPR 或加州的 CCPA，要求组织在个人数据不再用于收集目的时将其删除。设置保留期限有助于遵守此类法规。
• 成本: LangSmith 对数据保留期较短的追踪收取较低费用。有关详细信息，请参阅我们关于如何优化支出的教程。

工作原理

LangSmith 现在根据数据保留策略提供两个层级的追踪，其特点如下：

	基础	扩展
Price	$.50 / 1k traces	$5 / 1k traces
Retention Period	14 days	400 days

保留期结束后删除数据

在指定的保留期结束后，跟踪记录将无法通过运行表或 API 访问。与该跟踪关联的所有用户数据（例如输入和输出）将在随后的一天内从我们的内部系统中删除。与每个跟踪关联的某些元数据可能会为分析和计费目的而无限期保留。

数据保留自动升级

注意

自动升级可能会影响您的账单。请仔细阅读本节，以充分了解您的 预估 LangSmith 追踪费用。

当您使用具有 base 级追踪的某些功能时，其数据保留期将自动升级为 extended 级。这将同时增加追踪的保留期和成本。

以下是在哪些情况下跟踪将升级的完整列表：

• 反馈 已添加到跟踪上的任何运行中
• 一个标注队列接收来自追踪的任何运行
• A 运行规则 匹配跟踪中的任何运行

为什么需要自动升级追踪？

我们采用追踪自动升级模型有两个原因：

1. 我们认为，符合以下任一条件的追踪结果本质上比其他追踪结果更有趣， 因此让用户能够更长时间地保留它们是很好的。
2. 从哲学层面而言，我们希望为那些可能不会被有意义地交互的追踪数据收取低一个数量级的费用。 我们认为自动升级使我们的定价模型与 LangSmith 所带来的价值保持一致：只有那些具有有意义交互的追踪数据才会按更高的费率收费。

如果您对我们的定价模型有任何疑问或担忧，请随时联系 support@langchain.dev 并告诉我们您的想法！

数据保留如何影响下游功能？

• 注释队列、运行规则和反馈：使用这些功能的追踪将 自动升级。
• 监控: 即使基础层追踪的数据保留期结束，监控标签页仍将继续工作。它由存在超过>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 错误表示在基于每个 API 密钥/访问令牌的 1 分钟时间窗口内，API 调用次数超过了固定限制。该窗口的起始时间会略有不同——并不保证从时钟分钟的开始时刻启动——且可能因应用程序部署事件而发生变化。

在收到最大事件数后，我们将返回 429 状态码，直到评估窗口开始后的 60 秒到达，然后该过程会重复。

此 429 错误由我们的应用程序负载均衡器抛出，是 LangSmith 所有用户（无论计划层级如何）为确保服务连续性而实施的机制。

方法	端点	限制	窗口
DELETE	Sessions	30	1 minute
POST OR PATCH	Runs	5000	1 minute
POST	Feedback	5000	1 minute
*	*	2000	1 minute

注意

LangSmith SDK 通过批处理来自同一会话 ID 的最多 100 个运行并合并为单个 API 调用，采取措施降低在运行相关端点上达到这些限制的可能性。

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

此 429 错误表示已达到每小时摄入事件的最大限制，该限制在 UTC 时间每个整点开始的固定窗口内进行评估，并在每个新小时的开始时刻重置。

在此上下文中，事件是指运行的创建或更新。因此，如果运行被创建，随后在同一小时窗口内被更新，这将计为针对此限制的2个事件。

这是由我们的应用程序抛出的，并根据计划层级有所不同。使用我们 Startup/Plus 和 Enterprise 计划层级的组织拥有更高的小时限额，而 Free 和 Developer Plan Tiers 则是为个人使用设计的。

计划	限制	窗口
Developer (no payment on file)	50,000 events	1 hour
Developer (with payment on file)	250,000 events	1 hour
Startup/Plus	500,000 events	1 hour
Enterprise	Custom	Custom

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

此 429 错误表示您已超出追踪输入、输出和元数据的最大数据摄入限制。该限制基于每个协调世界时（UTC）整点开始的固定时间窗口进行评估，并在每个新小时开始时重置。

通常，输入、输出和元数据会在运行创建和更新事件中发送。因此，如果某个运行在创建时大小为 2.0MB，并在同一小时窗口内更新时大小变为 3.0MB，则这将计入该限制下的 5.0MB 存储用量。

这是由我们的应用程序抛出的，并根据计划层级有所不同。使用我们 Startup/Plus 和 Enterprise 计划层级的组织拥有更高的小时限额，而 Free 和 Developer Plan Tiers 则是为个人使用设计的。

计划	限制	窗口
Developer (no payment on file)	500MB	1 hour
Developer (with payment on file)	2.5GB	1 hour
Startup/Plus	5.0GB	1 hour
Enterprise	Custom	Custom

计划级月度独立追踪限制​

此429错误是由于已用完每月最大摄入的追踪量所致。该限制在UTC时间每个日历月开始时以固定窗口进行评估，并在每个月初重置。

此错误由我们的应用程序抛出，仅适用于开发者计划层级，且当未保存支付方式时生效。

计划	限制	窗口
Developer (no payment on file)	5,000 traces	1 month

自配置月度使用限制​

此 429 错误是由于达到了组织管理员配置的用量限制所致。该限制基于协调世界时（UTC）每月月初开始的固定窗口期进行评估，并在每个月初重置。

这是由我们的应用程序抛出的，并根据各组织根据其配置的设置而有所不同。

处理应用程序中的429响应​

由于部分 429 响应是暂时的，并在后续调用中可能成功，如果您在应用程序中直接调用 LangSmith API，我们建议实现带有指数退避和随机抖动的重试逻辑。

为了方便起见，使用 LangSmith SDK 构建的 LangChain 应用程序已内置此功能。

注意

需要注意的是，如果您长时间饱和端点，重试可能无效，因为您的应用程序最终会积累足够大的积压队列以耗尽所有重试机会。

如果是这种情况，我们希望能更具体地讨论您的需求。请通过 LangSmith 支持团队 联系我们，并提供关于您的应用吞吐量需求及示例代码的详细信息。我们将与您合作，共同确定最佳方案是修复错误、调整您的应用代码，还是切换至不同的 LangSmith 计划。

使用限制​

LangSmith 允许您配置追踪的使用量限制。请注意，这些是使用量限制，而非支出限制，这意味着它们用于限制某些事件发生的数量，而不是您将要花费的总金额。

LangSmith 允许您设置两种不同的月度限额，这与我们在前述数据保留指南中讨论的可计费指标相呼应：

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

这些功能可分别限制总追踪数量和数据保留追踪的时长。

使用限制的属性​

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

长期数据保留的副作用痕迹限制​

扩展数据保留跟踪限制会产生副作用。如果已达到该限制，任何可能导致跟踪层级自动升级的功能都将无法使用。这是因为跟踪的自动升级会创建另一个扩展数据保留跟踪，而根据限制本应不允许这样做。因此，您将无法再：

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

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

更新使用限制​

使用限制可从 Settings 页面下的 Usage and Billing 进行更新。限制值会被缓存，因此新限制可能需要一分钟左右才会生效。

相关内容​

• 关于如何优化支出的教程