概念
本概念指南涵盖了 LangSmith 中用户、组织和工作区管理相关的主题。
资源层级结构
组织
组织是 LangSmith 中用户的逻辑分组，拥有自己的计费配置。通常，每个公司有一个组织。一个组织可以有多个工作区。更多详情，请参阅设置指南。
首次登录时，系统会自动为您创建一个个人组织。如果您想与他人协作，可以创建一个单独的组织并邀请您的团队成员加入。个人组织和共享组织之间存在一些重要的区别
| 功能 | 个人 | 共享 |
|---|---|---|
| 最大工作区数量 | 1 | 可变，取决于套餐（参见定价页面 |
| 协作 | 无法邀请用户 | 可以邀请用户 |
| 计费：付费套餐 | 仅限开发者套餐 | 所有其他套餐均可用 |
工作区
工作区以前称为租户。在过渡期间，一些代码和 API 可能会在一段时间内继续引用旧名称。
工作区是组织内用户和资源的逻辑分组。工作区将资源的信任边界和访问控制分开。用户可能在工作区中拥有权限，授予他们访问该工作区中资源的权限，包括追踪项目、数据集、标注队列和提示。更多详情，请参阅设置指南。
建议为组织内的每个团队创建一个单独的工作区。为了进一步组织资源，您可以使用资源标签在工作区内对资源进行分组。
下图显示了一个示例工作区设置页面：
下图解释了组织、工作区以及限定在工作区内和工作区之外的不同资源之间的关系
有关哪些功能在哪个范围（组织或工作区）可用，请参阅下表
| 资源/设置 | 范围 |
|---|---|
| 追踪项目 | 工作区 |
| 标注队列 | 工作区 |
| 部署 | 工作区 |
| 数据集和实验 | 工作区 |
| 提示 | 工作区 |
| 资源标签 | 工作区 |
| API 密钥 | 工作区 |
| 设置，包括密钥、反馈配置、模型、规则和共享 URL | 工作区 |
| 用户管理：邀请用户加入工作区 | 工作区 |
| RBAC：分配工作区角色 | 工作区 |
| 数据保留、使用限制 | 工作区* |
| 套餐和计费、积分、发票 | 组织 |
| 用户管理：邀请用户加入组织 | 组织** |
| 添加工作区 | 组织 |
| 分配组织角色 | 组织 |
| RBAC：创建/编辑/删除自定义角色 | 组织 |
* 数据保留设置和使用限制也将很快在组织级别提供 ** 自托管安装可以通过功能标志启用工作区级别的用户邀请到组织。详情请参阅自托管用户管理文档。
资源标签
资源标签允许您在工作区内组织资源。每个标签都是一个可以分配给资源的键值对。标签可用于在 UI 和 API 中筛选工作区范围的资源：项目、数据集、标注队列、部署和实验。
每个新工作区都带有两个默认标签键：`Application`（应用）和 `Environment`（环境）；顾名思义，这些标签可用于根据资源所属的应用和环境对其进行分类。可根据需要添加更多标签。
LangSmith 资源标签与 AWS 等云服务中的标签非常相似。
用户管理和 RBAC
用户
用户是拥有 LangSmith 访问权限的人。用户可以是一个或多个组织及其工作区的成员。
组织成员在组织设置中管理
工作区成员在工作区设置中管理
API 密钥
我们于 2024 年 10 月 22 日停止支持前缀为 `ls__` 的旧版 API 密钥，转而支持个人访问令牌 (PAT) 和服务密钥。我们要求所有新集成使用 PAT 和服务密钥。前缀为 `ls__` 的 API 密钥自 2024 年 10 月 22 日起将不再有效。
个人访问令牌 (PAT)
个人访问令牌（PAT）用于验证对 LangSmith API 的请求。它们由用户创建并作用于用户。PAT 将拥有与创建它的用户相同的权限。我们建议不要将它们用于验证来自您的应用程序的请求，而是将其用于与 LangSmith API 交互的个人脚本或工具。如果与 PAT 关联的用户从组织中移除，PAT 将不再有效。
PAT 的前缀为 `lsv2_pt_`
服务密钥
服务密钥与 PAT 类似，但它们用于代表服务账户验证对 LangSmith API 的请求。只有管理员可以创建服务密钥。我们建议将它们用于需要与 LangSmith API 交互的应用程序/服务，例如 LangGraph 代理或其他集成。服务密钥的作用范围是一个工作区，可用于验证对该工作区的 LangSmith API 的请求。
服务密钥的前缀为 `lsv2_sk_`
要了解如何创建服务密钥或个人访问令牌，请参阅设置指南
组织角色
组织角色与下面的企业功能 (RBAC) 不同，并用于多个工作区的上下文。您的组织角色决定了您的工作区成员资格特性和组织级别的权限。有关更多信息，请参阅组织设置指南。
所选的组织角色也会影响工作区成员资格，如下所述
- `Organization Admin`（组织管理员）授予对所有组织配置、用户、计费和工作区进行完全管理的权限。`Organization Admin`（组织管理员）对组织中的所有工作区具有`Admin`（管理员）访问权限。
- `Organization User`（组织用户）可以读取组织信息，但不能在组织级别执行任何写入操作。`Organization User`（组织用户）可以被添加到工作区的子集并像往常一样分配工作区角色（如果启用了 RBAC），这些角色指定了工作区级别的权限。
“组织用户”角色仅适用于拥有多个工作区的组织套餐。在仅限于单个工作区的组织中，所有用户都是“组织管理员”。自定义组织范围的角色尚不可用。
有关所有组织权限，请参见下表
| 组织用户 | 组织管理员 | |
|---|---|---|
| 查看组织配置 | ✅ | ✅ |
| 查看组织角色 | ✅ | ✅ |
| 查看组织成员 | ✅ | ✅ |
| 查看数据保留设置 | ✅ | ✅ |
| 查看使用限制 | ✅ | ✅ |
| 对所有工作区拥有管理员访问权限 | ✅ | |
| 管理计费设置 | ✅ | |
| 创建工作区 | ✅ | |
| 创建、编辑和删除组织角色 | ✅ | |
| 邀请新用户加入组织 | ✅ | |
| 删除用户邀请 | ✅ | |
| 从组织中移除用户 | ✅ | |
| 更新数据保留设置* | ✅ | |
| 更新使用限制* | ✅ |
工作区角色 (RBAC)
RBAC（基于角色的访问控制）是仅适用于企业客户的功能。如果您对该功能感兴趣，请通过sales@langchain.dev联系我们的销售团队。其他套餐默认为所有用户使用管理员角色。
角色用于定义用户在工作区中拥有的权限集。有三个无法编辑的内置系统角色
- `Admin` - 对工作区内的所有资源拥有完全访问权限
- `Viewer` - 对工作区内的所有资源拥有只读访问权限
- `Editor` - 拥有除工作区管理（添加/移除用户、更改角色、配置服务密钥）之外的所有权限
组织管理员还可以创建/编辑具有不同资源特定权限的自定义角色。
角色可以在组织设置的“角色”选项卡下进行管理。
有关分配和创建角色的更多详情，请参阅访问控制设置指南。
最佳实践
环境分离
使用资源标签，通过默认标签键`Environment`和不同的环境值（例如`dev`、`staging`、`prod`）来按环境组织资源。这种标签结构将允许您今天组织您的追踪项目，并在我们发布基于属性的访问控制（ABAC）时轻松强制执行权限。资源标签上的 ABAC 将提供一种细粒度的方式来限制对生产追踪项目的访问，例如。我们不建议您使用工作区进行环境分离，因为您不能在工作区之间共享资源。如果您想将提示从`staging`提升到`prod`，我们建议您使用提示标签。更多信息请参见文档。
使用和计费
数据保留
2024 年 5 月，LangSmith 引入了追踪数据最长 400 天的保留期。2024 年 6 月，LangSmith 引入了新的基于数据保留的定价模型，客户可以通过配置更短的追踪数据保留期来节省高达 10 倍的成本。在本页中，我们将详细介绍 LangSmith 中数据保留的工作原理和定价方式。
为什么数据保留很重要
- 隐私：许多数据隐私法规，例如欧洲的 GDPR 或加利福尼亚州的 CCPA，要求组织在个人数据不再用于收集目的后将其删除。设置保留期有助于遵守此类法规。
- 成本：LangSmith 对数据保留期较短的追踪收费较低。有关详细信息，请参阅我们关于如何优化支出的教程。
工作原理
LangSmith 现在拥有两个基于数据保留的追踪层级，具有以下特点
| 基础 | 扩展 | |
|---|---|---|
| 价格 | 0.50 美元/1千次追踪 | 5 美元/1千次追踪 |
| 保留期 | 14 天 | 400 天 |
保留期结束后数据删除
在指定的保留期结束后，追踪将无法通过运行表或 API 访问。与追踪相关的所有用户数据（例如输入和输出）将在之后一天内从我们的内部系统中删除。与每个追踪相关的一些元数据可能会无限期保留，用于分析和计费目的。
数据保留自动升级
自动升级可能会影响您的账单。请仔细阅读本节，以充分了解您预估的 LangSmith 追踪成本。
当您对“基础”层追踪使用某些功能时，其数据保留将自动升级到“扩展”层。这将同时增加保留期和追踪成本。
追踪何时升级的完整场景列表：
- 任何运行上添加了反馈
- Annotation Queue（标注队列）接收到追踪中的任何运行
- Run Rule（运行规则）与追踪中的任何运行匹配
为什么自动升级追踪？
我们对追踪的自动升级模型有两个原因
- 我们认为符合这些条件的追踪从根本上来说比其他追踪更有趣，因此用户能够更长时间地保留它们是有益的。
- 我们从哲学上希望对那些可能没有进行有意义交互的追踪收取一个数量级更低的费用。我们认为自动升级使我们的定价模型与 LangSmith 带来的价值相符，只有那些具有有意义交互的追踪才会被收取更高的费用。
如果您对我们的定价模型有疑问或担忧，请随时通过support@langchain.dev联系我们，并告诉我们您的想法！
数据保留如何影响下游功能？
- 标注队列、运行规则和反馈：使用这些功能的追踪将自动升级。
- 监控：即使基础层追踪的数据保留期结束，监控选项卡仍将继续工作。它由保留超过 30 天的追踪元数据提供支持，这意味着即使是“基础”层追踪，您的监控图表也将保持准确。
- 数据集：数据集具有无限期的数据保留期。换句话说，如果您将追踪的输入和输出添加到数据集中，它们将永远不会被删除。我们建议，如果您将 LangSmith 用于数据收集，请利用数据集功能。
计费模式
可计费指标
在您的 LangSmith 发票上，您会看到我们收费的两个指标
- LangSmith 追踪（基础费用）
- LangSmith 追踪（扩展数据保留升级）。
第一个指标包括所有追踪，无论层级如何。第二个指标仅计算扩展保留追踪的数量。
为什么测量所有追踪+升级，而不是基础和扩展追踪？
在考虑我们的定价时，一个自然而然的问题是，为什么不直接在发票上显示“基础”层和“扩展”层追踪的数量呢？
虽然我们理解这会更直观，但它无法正确处理追踪升级。考虑一个在 6 月 30 日记录的基础层追踪，并在 7 月 3 日升级到扩展层。基础层追踪发生在 6 月的计费周期，但升级发生在 7 月的计费周期。因此，我们需要能够独立测量这两个事件，以便正确地向客户计费。
如果您的追踪记录为扩展保留追踪，则“基础”和“扩展”指标都将以相同的时间戳记录。
成本细分
追踪的基础费用为每追踪 0.05 美分。我们将升级定价为，一个“扩展”保留追踪的成本是基础层追踪价格的 10 倍（每追踪 0.50 美分），包括两个指标。因此，每次升级成本为 0.45 美分。
速率限制
LangSmith 设有速率限制，旨在确保所有用户的服务稳定性。
为确保访问和稳定性，在以下情况下，LangSmith 将响应 HTTP 状态码 429，表示已超出速率或使用限制
场景
应用负载均衡器在 1 分钟内的临时吞吐量限制
此 429 响应是由于每 API 密钥/访问令牌在 1 分钟窗口内超过了固定数量的 API 调用。窗口的开始时间会略有不同——不保证从时钟分钟的开始时间开始——并且可能会根据应用程序部署事件而变化。
在收到最大事件数后，我们将响应 429，直到评估窗口开始后 60 秒达到，然后过程重复。
此 429 由我们的应用负载均衡器抛出，是所有 LangSmith 用户（无论套餐层级）为确保服务连续性而实施的机制。
| 方法 | 端点 | 限制 | 窗口 |
|---|---|---|---|
| DELETE | 会话 | 30 | 1 分钟 |
| POST 或 PATCH | 运行 | 5000 | 1 分钟 |
| POST | 反馈 | 5000 | 1 分钟 |
| * | * | 2000 | 1 分钟 |
LangSmith SDK 采取措施，通过将单个会话 ID 中的多达 100 次运行批处理到单个 API 调用中，从而最大限度地降低达到这些运行相关端点限制的可能性。
套餐级每小时追踪事件限制
此 429 响应是由于达到了您的每小时最大事件摄入量，并在 UTC 时间每个时钟小时开始时在一个固定窗口内进行评估，并在每个新小时开始时重置。
在此上下文中，事件是运行的创建或更新。因此，如果运行被创建，然后随后在同一小时窗口内更新，则将计为针对此限制的 2 个事件。
这由我们的应用程序抛出，并因套餐层级而异，我们的启动/Plus 和企业套餐层级的组织比我们为个人使用设计的免费和开发者套餐层级具有更高的每小时限制。
| 套餐 | 限制 | 窗口 |
|---|---|---|
| 开发者（未绑定支付信息） | 50,000 事件 | 1 小时 |
| 开发者（已绑定支付信息） | 250,000 事件 | 1 小时 |
| 启动/Plus | 500,000 事件 | 1 小时 |
| 企业 | 自定义 | 自定义 |
套餐级每小时追踪数据摄入限制
此 429 响应是由于达到您追踪输入、输出和元数据摄入的最大数据量，并在 UTC 时间每个时钟小时开始时在一个固定窗口内进行评估，并在每个新小时开始时重置。
通常，输入、输出和元数据会在运行创建和更新事件时发送。因此，如果一个运行在创建时大小为 2.0MB，并且在同一小时窗口内更新时大小为 3.0MB，则将计入此限制的 5.0MB 存储。
这由我们的应用程序抛出，并因套餐层级而异，我们的启动/Plus 和企业套餐层级的组织比我们为个人使用设计的免费和开发者套餐层级具有更高的每小时限制。
| 套餐 | 限制 | 窗口 |
|---|---|---|
| 开发者（未绑定支付信息） | 500MB | 1 小时 |
| 开发者（已绑定支付信息） | 2.5GB | 1 小时 |
| 启动/Plus | 5.0GB | 1 小时 |
| 企业 | 自定义 | 自定义 |
套餐级每月独立追踪限制
此 429 响应是由于达到了您的每月最大追踪摄入量，并在 UTC 时间每个日历月开始时在一个固定窗口内进行评估，并在每个新月开始时重置。
这由我们的应用程序抛出，并且仅适用于未绑定支付信息的开发者套餐级别。
| 套餐 | 限制 | 窗口 |
|---|---|---|
| 开发者（未绑定支付信息） | 5,000 次追踪 | 1 个月 |
自行配置的每月使用限制
此 429 响应是由于达到您的组织管理员配置的使用限制，并在 UTC 时间每个日历月开始时在一个固定窗口内进行评估，并在每个新月开始时重置。
这由我们的应用程序抛出，并根据组织的配置设置而异。
在您的应用程序中处理 429 响应
由于某些 429 响应是临时的，并且可能会在后续调用中成功，如果您直接在应用程序中调用 LangSmith API，我们建议您实施具有指数退避和抖动的重试逻辑。
为方便起见，使用 LangSmith SDK 构建的 LangChain 应用程序内置了此功能。
需要注意的是，如果您长时间占用端点，重试可能无效，因为您的应用程序最终会运行足够大的积压，从而耗尽所有重试。
如果出现这种情况，我们希望能更具体地讨论您的需求。请联系LangSmith 支持，提供您的应用程序吞吐量需求和示例代码的详细信息，我们将与您一起更好地了解最佳方法是修复错误、更改应用程序代码还是选择不同的 LangSmith 套餐。
使用限制
LangSmith 允许您配置追踪的使用限制。请注意，这些是使用限制，而不是支出限制，这意味着它们允许您限制某个事件的发生数量，而不是您将花费的总金额。
LangSmith 允许您设置两个不同的每月限制，这与我们上述数据保留指南中讨论的可计费指标相对应。
- 所有追踪限制
- 扩展数据保留追踪限制
这些允许您分别限制总追踪数量和扩展数据保留追踪数量。
使用限制的特性
使用限制是近似的，这意味着我们不保证限制的精确性。在极少数情况下，在使用限制开始生效之前，可能会有一小段时间额外追踪处理超过限制阈值。
扩展数据保留追踪限制的副作用
扩展数据保留追踪限制具有副作用。如果已达到限制，任何可能导致追踪层级自动升级的功能都将无法访问。这是因为追踪的自动升级将导致创建另一个扩展保留追踪，而这又应该被限制所禁止。因此，您将无法再执行以下操作：
- 匹配运行规则
- 向追踪添加反馈
- 将运行添加到标注队列
这些功能中的每一个都可能导致自动升级，因此当达到限制时，我们会将其关闭。
更新使用限制
使用限制可以在“设置”页面下的“使用和计费”中更新。限制值会被缓存，因此新限制可能需要一两分钟才能生效。
相关内容
- 关于如何优化支出的教程