资源层级
组织
组织是 LangSmith 中用户的逻辑分组，它定义了适用于其所有工作区的共享设置。这些设置管理的是组织范围内的事务，而不是工作区内的单个项目。常见的组织级配置包括用户管理、单点登录（SSO）、OAuth 提供程序配置、自定义角色创建、计费和使用情况跟踪。通常，每个公司有一个组织。一个组织可以有多个工作区。有关更多详细信息，请参阅设置指南。 当您首次登录时，系统会自动为您创建一个个人组织。如果您想与他人协作，可以创建一个单独的组织并邀请您的团队成员加入。您的个人组织与共享组织之间有几个重要区别：工作区
工作区以前称为租户。在过渡期间，某些代码和 API 可能仍会引用旧名称。
应用程序
应用程序是工作区内资源的逻辑分组。应用程序通常是代理，但您可以将它们用于团队内的任何项目。应用程序通过只显示当前上下文中与应用程序关联的资源来保持 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+ 开始使用）。
The Organization User and Organization Viewer roles are only available in organizations on Plus and Enterprise plans. In Developer organizations (single workspace), all users are assigned the Organization Admin role by default.有关如何为整个组织禁用 PAT 创建的说明，请参阅安全设置。
For a comprehensive list of required permissions along with the operations and roles that can perform them, refer to the Organization and workspace reference.
工作区角色（RBAC）
RBAC（基于角色的访问控制）是仅对企业客户可用的功能。如果您对此功能感兴趣，请联系我们的销售团队。其他套餐默认对所有用户使用 Admin 角色。
- 有关角色和权限的全面文档，请参阅基于角色的访问控制指南。
- 有关分配和创建角色的更多详细信息，请参阅用户管理指南。
- For a comprehensive list of required permissions along with the operations and roles that can perform them, refer to the Organization and workspace reference.
最佳实践
环境分离
使用资源标签通过默认标签键Environment 和不同的环境值（例如 dev、staging、prod）按环境组织资源。我们不建议使用单独的工作区进行环境分离，因为资源无法跨工作区共享，这会阻止您在不同环境之间提升资源（如提示词）。
用于提示词管理的资源标签与提交标签虽然两种类型的标签都可以使用环境术语，如
dev、staging 和 prod，但它们的用途不同：- 资源标签（
Environment: prod）：使用这些标签来组织和筛选工作区中的资源。将资源标签应用于追踪项目、数据集和其他资源（包括提示词），以按环境对它们进行分组，从而在 UI 中实现筛选。 - 提交标签（
prod标签）：使用这些标签来管理您的代码引用的提示词版本。提交标签是指向提示词历史中特定提交的标签。当您的代码按标签名称拉取提示词时（例如client.pull_prompt("prompt-name:prod")），它会检索该标签当前指向的任何提交。要将提示词从staging提升到prod，请将提交标签移动到指向所需版本。
使用与计费
数据保留
本节介绍 LangSmith 中数据保留的工作原理及其定价。为什么保留很重要
- 隐私：许多数据隐私法规，例如欧洲的 GDPR 或加利福尼亚州的 CCPA，要求组织在个人数据不再用于收集目的时删除这些数据。设置保留期限有助于遵守此类法规。
- 成本：LangSmith 对低数据保留的追踪收取较低费用。有关更多信息，请了解如何强制执行支出限制。
工作原理
LangSmith 根据数据保留有两个追踪层级，具有以下特征：企业客户可以自定义每个工作区的扩展保留期限。更改仅适用于新的追踪——现有追踪不受影响。请参阅自定义扩展保留策略。
数据保留自动升级
大多数追踪使用基础保留。某些操作，如在线评估器和自动化规则，可以将追踪延长到更长的保留期，但成本更高。您控制哪些操作会延长保留。 当您对base 层级的追踪使用某些功能时，其数据保留可能会自动升级到 extended 层级。这会增加保留期限和追踪的成本。
按操作划分的保留行为：
- 通过 API 或 SDK 反馈：通过 API 或 SDK 调用显式传递
extend_trace_retention=true（在 TypeScript 中为extendTraceRetention: true）将反馈添加到追踪上的任何运行（或线程中的任何追踪）。有关更多信息，请参阅附加用户反馈。LangSmith UI 发送反馈和备注时不会延长保留期。 - 在线评估器：在线评估器对追踪进行评分，并且其保留设置已启用。追踪级和线程级评估器都可以选择退出此升级。
- 自动化规则：启用了保留扩展的自动化规则匹配追踪中的任何运行。
- 手动添加到标注队列（无升级）：手动将运行或线程添加到标注队列默认不会升级保留。
当您在追踪项目上创建或编辑在线评估器时，您可以选择退出升级该评估器评分的追踪，使其保持在基础保留。仅当项目的默认保留为基础层级时，此选项才可用。有关分步说明，请参阅管理评估器追踪保留。
保留扩展默认对新在线评估器和自动化规则启用。您可以在配置每个评估器或规则时选择退出。
- 我们认为符合这些条件中的任何一个的追踪本质上比其他追踪更有趣，因此用户能够将它们保留更长时间是有益的。
- 从哲学上讲，我们希望为可能没有被有意义地交互的追踪向客户收取低一个数量级的费用。我们认为自动升级使我们的定价模型与 LangSmith 带来的价值保持一致，只有具有有意义交互的追踪才会以更高的费率收费。
- 实验：默认在扩展保留策略下创建运行记录。
- 自动化规则与评估器：当启用保留设置时，会将匹配的追踪升级至扩展保留策略。
- 用户反馈、备注与标注队列：保持追踪的保留层级不变。
- 监控：即使基础层级追踪的数据保留期结束，监控标签页仍将继续正常工作。其运行依赖于存在时间超过30天的追踪元数据，这意味着您的监控图表即使在
基础层级追踪上也将保持准确性。 - 数据集：数据集拥有无限期的数据保留策略。换句话说，若您将追踪的输入输出添加到数据集中，这些数据将永远不会被删除。我们建议：如果您正在使用LangSmith进行数据收集，请充分利用数据集功能。
计费模型
可计费指标 在您的 LangSmith 发票上，您将看到我们收取费用的两个指标：- LangSmith 追踪（基础费用）
- LangSmith 追踪（扩展数据保留升级）。
base 层级和 extended 层级的追踪数量？
虽然我们理解这会更直接，但它不能正确适应追踪升级。考虑一个在 6 月 30 日记录的 base 层级追踪，并在 7 月 3 日升级到 extended 层级。base 层级追踪发生在 6 月的计费周期，但升级发生在 7 月的计费周期。因此，我们需要能够独立衡量这两个事件，以便正确地向客户计费。
如果您的追踪被记录为扩展保留追踪，那么 base 和 extended 指标都将以相同的时间戳记录。
速率限制
LangSmith 具有速率限制，旨在确保所有用户的服务稳定性。 为了确保访问和稳定性，在以下情况下，LangSmith 将返回 HTTP 状态代码 429，表示已超过速率或使用限制：应用程序负载均衡器上 1 分钟内的临时吞吐量限制
此 429 是在 1 分钟窗口内，每个服务密钥或 PAT 超过固定数量的 API 调用所致。窗口的开始时间会略有变化——不保证在时钟分钟开始时开始——并且可能因应用程序部署事件而改变。 在收到最大事件数后，我们将返回 429，直到评估窗口开始后 60 秒，然后重复该过程。 此 429 由我们的应用程序负载均衡器抛出，是适用于所有 LangSmith 用户的机制，无论套餐层级如何，以确保所有用户的服务连续性。LangSmith SDK 采取措施，通过将来自单个会话 ID 的最多 100 个运行批处理到单个 API 调用中，来最小化达到这些运行相关端点限制的可能性。
套餐级每小时追踪事件限制
此 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 每个日历月开始，并在每个新月初重置。 这由我们的应用程序抛出，并因组织而异，具体取决于其配置的设置。每个追踪的最大运行数
运行查询端点
POST /runs/query 端点根据查询参数具有额外的每租户速率限制。有关详细信息，请参阅使用 SDK 查询追踪。
在应用程序中处理 429 响应
由于某些 429 响应是临时的，并且可能在后续调用中成功，如果您直接在应用程序中调用 LangSmith API，我们建议实现带有指数退避和抖动的重试逻辑。 为方便起见，使用 LangSmith SDK 构建的 LangChain 应用程序内置了此功能。需要注意的是，如果您长时间饱和端点，重试可能无效，因为您的应用程序最终将积累足够大的积压，耗尽所有重试。如果是这种情况，我们希望更具体地讨论您的需求。请通过 LangSmith 支持 联系支持人员，并提供有关您的应用程序吞吐量需求和示例代码的详细信息，我们可以与您合作，更好地了解最佳方法是修复错误、更改应用程序代码还是使用不同的 LangSmith 套餐。
使用限制
LangSmith 允许您在追踪上配置使用限制。请注意，这些是使用限制，而不是支出限制，这意味着它们允许您限制某个事件发生的数量，而不是您将花费的总金额。 LangSmith 允许您设置两个不同的每月限制，与上述数据保留指南中讨论的可计费指标相对应：- 所有追踪限制
- 扩展数据保留追踪限制
有关评估器运行的支出限制，请参阅跟踪和限制评估器支出。
使用限制的属性
使用限制是近似的，这意味着我们不保证限制的精确性。在极少数情况下，在应用使用限制之前，可能会有短暂的时间处理超过限制阈值的额外追踪。扩展数据保留追踪限制的副作用
扩展数据保留追踪限制有副作用。如果已达到限制，任何可能导致追踪层级自动升级的功能都将变得不可访问。这是因为追踪的自动升级会导致创建另一个扩展保留追踪，而限制不应允许这样做。因此，您不能再：- 匹配运行规则
- 向追踪添加反馈
- 将运行添加到标注队列
更新使用限制
使用限制可以从Settings 页面的 Usage and Billing 下更新。限制值会被缓存，因此新限制可能需要一两分钟才能生效。
每个项目和每个用户的追踪限制
除了工作区范围限制之外，您还可以限制单个追踪项目或单个工作区成员的每月追踪数。这可以防止一个项目或用户消耗工作区追踪预算的不成比例份额。 要配置这些限制，请打开 Settings，转到 Usage configuration，然后选择 Project & user limits 选项卡。选择 Add limit，然后设置：- 范围：Project 以限制单个追踪项目，或 User 以限制单个工作区成员。
- 工作区：包含项目或成员的工作区。
- 项目或用户：要限制的目标。
- 每月追踪限制：每个日历月允许的最大追踪数。
Update usage limits）。
与工作区限制一样，每个项目和每个用户的限制按 UTC 日历月评估，并在每个月初重置。一旦项目或用户达到其限制，其新追踪将被丢弃，并且在限制重置之前不会再次摄入。执行是近似的，因此在限制生效之前可能会处理少量超过阈值的追踪。这些限制适用于云和自托管。
每个项目和每个用户的限制是额外于您的工作区范围和套餐限制的。追踪必须满足所有适用的限制才能被摄入。每个用户的限制仅计算归属于特定工作区成员的追踪。使用未与成员关联的 API 密钥或服务密钥发送的追踪不计入每个用户的限制。限制值会被缓存，因此新的或更改的限制可能需要一两分钟才能生效。
相关内容
- 关于如何强制执行支出限制的教程
其他资源
- 发布策略：了解自托管发布渠道、节奏和版本编号。
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.