概念

本概念指南涵盖与在 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 可能仍会在一段时间内引用旧名称。

工作区是组织内用户和资源的逻辑分组。工作区用于划分资源和访问控制的信任边界。 用户可在工作区中拥有相应权限，从而获得对该工作区中各类资源的访问权限，包括追踪项目、数据集、标注队列和提示词（prompts）。更多详细信息，请参阅设置指南。

建议为组织内的每个团队分别创建一个独立的工作区。如需进一步整理资源，您可使用资源标签对工作区内的资源进行分组。

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

以下示意图说明了组织、工作区以及作用域限定于工作区内部或工作区内的各类资源之间的关系：

有关各项功能在不同范围（组织或工作区）内的可用性详情，请参见下方表格：

Resource/Setting	作用域
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 等云服务中的标签非常相似。

用户管理与基于角色的访问控制（RBAC）

用户

用户是指能够访问 LangSmith 的人员。用户可以是一个或多个组织及其内部工作区的成员。

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

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

API 密钥

旧版密钥已于2024年10月22日停用

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

个人访问令牌 (PAT)

个人访问令牌（PAT）用于对发送至 LangSmith API 的请求进行身份验证。PAT 由用户创建，并限定于该用户的作用域内。该 PAT 拥有与创建它的用户相同的权限。

PAT以lsv2_pt_开头

服务密钥

服务密钥与个人访问令牌（PAT）类似，但用于代表服务账户向 LangSmith API 发出的身份验证请求。

服务密钥以 lsv2_sk_ 开头

笔记

如需了解如何创建服务密钥或个人访问令牌，请参阅设置指南

组织角色

组织角色与下方的企业功能（基于角色的访问控制，RBAC）不同，适用于多个工作区的场景。您的组织角色决定了您在工作区中的成员身份特征以及组织级别的权限。有关更多信息，请参阅组织设置指南。

所选的组织角色也会影响工作区成员身份，具体说明如下：

• Organization Admin 具有完全权限，可管理组织的所有配置、用户、账单和工作区。Organization Admin 对组织内的所有工作区拥有 Admin 权限
• Organization User 可以读取组织信息，但无法在组织级别执行任何写入操作。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 机制将提供细粒度的访问控制方式，限制对生产环境追踪项目的访问权限。我们不建议您使用“工作区”（Workspaces）来实现环境隔离，因为您无法在不同工作区之间共享资源。若您希望将提示词从 staging 环境提升至 prod 环境，我们建议您改用提示词标签（prompt tags）。更多信息请参阅 文档。

使用方法与计费

数据保留

2024年5月，LangSmith 引入了追踪数据（traces）最长保存期限为400天的限制。2024年6月，LangSmith 推出了基于数据保存期限的新定价模式，客户可通过配置更短的追踪数据保存期限，最高节省达10倍费用。在本页面中，我们将详细介绍 LangSmith 中数据保存机制的工作原理及其计费方式。

为何留存率至关重要

• 隐私保护：许多数据隐私法规（例如欧洲的《通用数据保护条例》（GDPR）或美国加州的《加州消费者隐私法案》（CCPA））要求组织在个人数据不再为最初收集目的所必需时将其删除。设定数据保留期限有助于满足此类法规的合规性要求。
• 费用：LangSmith 对数据保留时间较短的追踪记录收取更低的费用。请参阅我们的教程，了解如何优化支出。

工作原理

LangSmith 目前根据数据保留策略，将追踪记录（traces）分为两个层级，具体特性如下：

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

保留期结束后删除数据

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

数据保留自动升级

注意

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

当您对“0”级追踪使用某些功能时，其数据保留级别将自动升级为“1”级。这将同时延长数据保留期限并增加追踪成本。

跟踪将升级的完整场景列表，包括以下情况：

• 反馈 会添加到跟踪中的任何运行
• 标注队列 接收跟踪中的任何运行
• 运行规则（Run Rule） 匹配跟踪（trace）内的任意一次运行

为何自动升级追踪功能？

我们采用自动升级追踪模型的策略，主要有两个原因：

1. 我们认为，符合上述任一条件的追踪记录本质上比其他追踪记录更值得关注， 因此，让用户能够更长时间地保留这些追踪记录是很有益的。
2. 我们在理念上希望对那些可能不会被有意义地交互的追踪数据，向客户收取低一个数量级的费用。 我们认为，自动升级机制能使我们的定价模式与 LangSmith 所带来的价值保持一致——只有那些存在有意义交互的追踪数据，才会按更高费率计费。

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

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

• 标注队列、运行规则和反馈：使用这些功能的追踪记录将被自动升级。
• 监控：即使基础层级追踪的数据保留期已结束，监控标签页仍将继续正常工作。该功能依托于保留时间超过30天的追踪元数据，这意味着即使对于base层级的追踪，您的监控图表仍能持续保持准确性。
• 数据集：数据集的数据保留期限为无限期。换言之，如果您将某个追踪记录的输入和输出添加到数据集中，则这些数据将永远不会被删除。我们建议，如果您使用 LangSmith 进行数据收集，请充分利用数据集功能。

计费模式

可计费指标

在您的 LangSmith 账单上，您将看到我们收费的两项指标：

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

第一个指标包含所有追踪记录，无论其所属层级。第二个指标仅统计扩展保留追踪记录的数量。

为什么要测量所有追踪（traces）及升级版本，而不是仅测量基础追踪和扩展追踪？

在考虑我们的定价时，一个很自然的问题是：为何不在账单上直接显示 base 级和 extended 级追踪的数量？

虽然我们理解这种方式会更直接，但它无法恰当地支持追踪升级功能。例如，一条等级为base的追踪记录于6月30日生成，并于7月3日升级为extended等级。而base等级的追踪发生在6月计费周期内，但此次升级操作却发生在7月计费周期内。因此，我们需要能够独立计量这两次事件，以便向客户进行准确计费。

如果您的追踪记录为扩展保留期追踪，则 base 和 extended 指标将使用相同的时间戳进行记录。

成本明细

单次追踪的基础费用为每追踪0.05美分。我们为升级版定价，使得保留期为extended的追踪费用为基础层级追踪费用的10倍（即每追踪0.50美分），该价格已包含全部两项指标。因此，每次升级费用为0.45美分。

速率限制

LangSmith 设有速率限制，旨在确保服务对所有用户的稳定性。

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

应用场景

应用程序负载均衡器在1分钟时间窗口内的临时吞吐量限制

此 429 错误是由于在每分钟时间窗口内，针对单个 API 密钥/访问令牌超出了固定的 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 小时的整点开始，并于每个新小时的整点重置。

在此上下文中，一个事件指的是运行（run）的创建或更新。因此，如果某个运行被创建，随后又在同一小时时间窗口内被更新，这将计入该限制的2个事件。

此异常由我们的应用程序抛出，且因订阅计划等级而异：选择“初创/增强版”或“企业版”计划的组织，其每小时调用限额高于面向个人使用的“免费版”和“开发者版”计划。

计划	限制	窗口
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的存储量计入此限制。

此异常由我们的应用程序抛出，且因订阅计划等级而异：选择“初创/增强版”或“企业版”计划的组织，其每小时调用限额高于面向个人使用的“免费版”和“开发者版”计划。

计划	限制	窗口
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 Plan Tier），且仅在未登记付款方式时触发。

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

自定义的月度使用限额

此 429 错误是由于您已达到组织管理员为您配置的用量限制所致；该限制按固定时间窗口进行评估，时间窗口从每月 UTC 时间的月初开始，并于每个新月份初重置。

此异常由我们的应用程序抛出，具体类型因组织所配置的设置而异。

在您的应用程序中处理 429 响应

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

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

笔记

需要注意的是，如果您长时间持续占用端点资源，重试机制可能将失效，因为您的应用程序最终会积压大量待处理任务，从而耗尽所有重试次数。

如果情况确实如此，我们希望能更具体地了解您的需求。请将您的应用吞吐量需求详情及示例代码发送给 LangSmith 支持团队，我们将与您共同分析，以确定最佳解决方案：是修复某个 Bug、调整您的应用程序代码，还是更换其他 LangSmith 套餐。

使用限制

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

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

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

这些设置分别用于限制总追踪数量以及扩展数据保留的追踪数量。

使用限制属性

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

延长数据保留期的副作用会限制跟踪功能

延长数据保留追踪的限额限制会产生副作用。如果该限额已被达到，则任何可能触发追踪层级自动升级的功能都将不可用。这是因为追踪的自动升级会创建另一条延长保留期限的追踪，而根据限额规定，这是不允许的。因此，您将无法再执行以下操作：

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

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

更新使用限额

使用限制可在 Settings 页面下的 Usage and Billing 中进行更新。限制值已缓存，因此新限制可能需要一到两分钟才会生效。

相关内容

• 如何优化支出的教程