概述

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

​

资源层次结构

​

组织

组织是 LangSmith 中用户的逻辑分组，具有自己的计费配置。通常，每个公司一个组织。一个组织可以有多个工作区。有关更多详细信息，请参阅设置指南。 当您首次登录时，将自动为您创建一个个人组织。如果您想与他人协作，可以创建一个单独的组织并邀请您的团队成员加入。您的个人组织和共享组织之间有一些重要区别：

​

工作区

工作区是组织内用户和资源的逻辑分组。工作区分隔资源和访问控制的信任边界。用户可以在工作区中拥有权限，授予他们访问该工作区中资源的权限，包括跟踪项目、数据集、注释队列和提示。有关更多详细信息，请参阅设置指南。 建议为组织内的每个团队创建单独的工作区。要进一步组织资源，您可以使用资源标签来对工作区内的资源进行分组。 下图展示了一个示例工作区设置页面： 下图解释了组织、工作区与工作区内各类资源之间的关系： 下表列出了各项功能在组织或工作区范围内的可用情况： * 组织级别的数据保留设置与使用量上限即将推出；** 自托管部署可通过特性开关允许在工作区层级邀请用户加入组织，详情见自托管用户管理文档。

​

资源标签

资源标签有助于组织工作区内的资源。每个标签都是一个可分配给资源的键值对。您可以在 UI 与 API 中使用标签对工作区范围的资源进行筛选，例如项目、数据集、注释队列、部署与实验。 新建的工作区默认包含两个标签键：Application 与 Environment。顾名思义，这些标签用于按应用与环境对资源分类。您可以按需添加更多标签。 LangSmith 的资源标签与 AWS 等云服务中的标签机制非常相似。

​

用户管理与 RBAC

​

用户

用户指拥有 LangSmith 访问权限的人员。用户可以同时属于一个或多个组织及其下的工作区。 组织成员通过组织设置进行管理： 工作区成员通过工作区设置进行管理：

​

API 密钥

​

到期日期

创建 API 密钥时，可以选择为其设置到期日期。设置到期时间有助于提升安全性并降低未授权访问的风险。例如，您可以为临时性、需要更高权限的任务设置到期日期。 默认情况下，密钥不会过期。一旦过期，该密钥将失效，无法重新激活或修改到期时间。

​

个人访问令牌（PAT）

PAT 用于对 LangSmith API 发起请求时进行身份验证，由用户创建并绑定到该用户。PAT 拥有与创建者相同的权限。我们建议不要在生产应用中使用 PAT，而是将其用于个人脚本或工具访问 LangSmith API。如果 PAT 所属用户被移出组织，该 PAT 将随之失效。 PAT 前缀为 lsv2_pt_

​

服务密钥

服务密钥与 PAT 类似，但用于代表服务账号访问 LangSmith API。仅管理员可创建服务密钥。建议将其用于需要与 LangSmith API 交互的应用或服务（如 LangGraph 智能体或其他集成）。服务密钥可以限定在单个工作区、多个工作区或整个组织范围内，并可在授权范围内对 API 请求进行认证。 服务密钥前缀为 lsv2_sk_

​

Organization roles

​

组织角色

组织角色不同于下文的企业功能（RBAC），主要在拥有多个工作区的场景中使用。组织角色决定了您的工作区成员属性及组织层级权限。详情请参阅组织设置指南。 所选组织角色也会影响工作区成员身份：

• Organization Admin：可完全管理组织配置、用户、计费与所有工作区。组织管理员对组织内所有工作区都具有 Admin 权限。
• Organization User：可查看组织信息，但无法在组织层执行写操作，可创建个人访问令牌。组织用户可加入部分工作区，并像往常一样（若启用 RBAC）被分配工作区角色，以指定工作区层级权限。
• Organization Viewer：与 Organization User 类似，但无法创建个人访问令牌。（自托管环境需要 Helm Chart 0.11.25+）

下表列出了组织层的全部权限：

​

Workspace roles (RBAC)

角色用于定义用户在某个工作区内拥有的权限集合。系统内置三种不可编辑的角色：

• Admin：对工作区内所有资源具有完全访问权限
• Viewer：对所有资源仅可读
• Editor：拥有除工作区管理（添加/移除用户、修改角色、配置服务密钥）外的全部权限 组织管理员还可以创建或编辑自定义角色，为不同资源设置具体权限。 角色可在组织设置的 Roles 选项卡中管理：

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

​

Best Practices

​

最佳实践

​

Environment Separation

建议使用默认标签键 Environment 的资源标签按环境组织资源，为不同环境（如 dev、staging、prod）设置不同标签值。我们不推荐借助多个工作区来区分环境，因为跨工作区无法共享资源，难以在环境之间推广资源（例如提示）。

​

Usage and Billing

​

使用与计费

​

Data Retention

本节介绍 LangSmith 的数据保留机制及其计费方式。

​

Why retention matters

• 隐私：GDPR、CCPA 等隐私法规要求在个人数据不再用于最初目的时进行删除，设置保留期有助于满足这些要求。
• 成本：数据保留时间越短的跟踪费用越低。详情可参阅成本优化指南。

​

How it works

LangSmith 基于数据保留时间提供两种跟踪等级： | | 基础（Base） | 扩展（Extended） | | 价格 | $0.50 / 每千条 |$5 / 每千条 | | 保留时长 | 14 天 | 400 天 | 保留期结束后的数据删除 After the specified retention period, traces are no longer accessible in the tracing project UI or via the API. All user data associated with the trace (e.g. inputs and outputs) is deleted from our internal systems within a day thereafter. Some metadata associated with each trace may be retained indefinitely for analytics and billing purposes. 当您在 base 等级的跟踪上使用某些功能时，该跟踪会自动升级到 extended 等级，从而增加保留时间和费用。 以下场景会触发升级：

• 反馈：无论通过手动标注、在线评估器自动生成，或通过 SDK程序化添加，只要向该跟踪（或线程中的任意跟踪）写入反馈，就会升级。
• **注释队列**收到该跟踪中的任何运行。
• **自动化规则**匹配到该跟踪中的任何运行。

为何要自动升级跟踪？ 我们设计自动升级模型主要基于两点原因：

1. 满足上述条件的跟踪通常更值得保留，延长其保留期能帮助用户保留重要数据。
2. 我们希望未被深入使用的跟踪成本更低。自动升级使定价与 LangSmith 的价值保持一致，仅对发生有意义交互的跟踪收取更高费用。

若您对定价模型有任何疑问，欢迎联系 support@langchain.dev 告诉我们您的想法。 数据保留对下游功能的影响

• 注释队列、运行规则与反馈：使用这些功能的跟踪会被自动升级。
• 监控：即便 base 等级跟踪的保留期结束，监控选项卡仍可使用。其依赖保存超过 30 天的跟踪元数据，因此监控图表仍然准确。
• 数据集：数据集的保留期无限。如果将跟踪的输入输出添加到数据集中，它们不会被删除。若您使用 LangSmith 做数据收集，建议充分利用数据集功能。

​

计费模型

计费指标 LangSmith 发票上会显示两项计费指标：

• LangSmith Traces（基础费用）
• LangSmith Traces（扩展保留升级）

第一项包含所有跟踪（不论等级），第二项只统计被升级为扩展保留的跟踪数量。 为何分别统计“全部跟踪”和“升级次数”？ 可能会有人疑惑为什么不直接在发票上展示 base 和 extended 的条目数量。原因在于升级发生的时间可能跨越不同的计费周期。例如：某条 base 跟踪在 6 月 30 日创建，并在 7 月 3 日升级为 extended。创建发生在 6 月账期，升级发生在 7 月账期，因此需要分别记录以便准确计费。 如果跟踪在生成时就是扩展保留级别，那么基础费用和扩展升级两项会记录相同的时间戳。 成本构成 每条基础跟踪费用为 0.05 美分。我们将升级费用定价为基础跟踪的 10 倍，即扩展保留跟踪总成本为 0.50 美分（包含基础与升级两项），因此单次升级的费用为 0.45 美分。

​

Rate Limits

LangSmith 设置了速率限制以确保所有用户的服务稳定性。 在以下场景中，LangSmith 会返回 HTTP 429，提示已超出速率或使用限制：

​

负载均衡层的 1 分钟临时吞吐限制

若同一 API 密钥/访问令牌在 1 分钟窗口内调用次数超出固定阈值，会返回 429。窗口起始时间可能略有偏移（不一定从整分钟开始），并可能因部署事件而变化。 达到阈值后，在窗口开始时间的 60 秒内我们会持续返回 429，随后重新进入下一轮评估。 该限制由应用负载均衡器统一施加，与套餐无关，旨在保障所有用户的稳定访问。

​

套餐级小时事件限制

当进入 UTC 每小时的固定窗口后，一旦摄入事件数达到上限，将返回 429，并在下一个整点重置。 此处的事件指运行的创建或更新。如果在同一小时内创建后又更新一次，则计为 2 个事件。

​

套餐级小时数据摄入限制

当跟踪的输入、输出与元数据累计大小达到阈值时，会返回 429。该限制同样在 UTC 每小时的固定窗口中评估，并在下一个整点重置。 通常运行的创建与更新都会发送输入、输出以及元数据。例如运行在创建时大小为 2.0MB，在同一小时窗口内更新后达 3.0MB，则总计 5.0MB 会计入该限制。 该限制由应用层施加，不同套餐的阈值不同。Startup/Plus 与 Enterprise 套餐拥有更高的小时限制，而 Free 与 Developer 套餐面向个人使用，限制较低。

​

套餐级每月唯一跟踪数量限制

当达到每月可摄取跟踪的最高限额时，会返回 429。该限制在 UTC 每个自然月开始时重置，并在固定窗口内计算。 此响应由我们的应用抛出，仅适用于未绑定支付方式的开发者套餐。

​

自定义的每月使用量限制

当达到组织管理员配置的使用上限时，会返回 429。该限制同样在 UTC 每个自然月起始时重置，并在固定窗口内计算。 此响应由我们的应用抛出，具体阈值依组织配置而定。

​

Handling 429s responses in your application

由于部分 429 是暂时性的，并可能在后续调用中成功，如果您的应用直接调用 LangSmith API，建议实现带指数退避和抖动的重试逻辑。 使用 LangSmith SDK 构建的 LangChain 应用已内置此机制。

​

Usage Limits

LangSmith 支持为跟踪配置使用量上限。请注意，这里限制的是使用量而非消费金额，也就是说它约束的是事件发生的次数，而不是总花费。 LangSmith 提供两个与上述计费指标对应的月度限制：

• 全部跟踪数量上限
• 扩展保留跟踪数量上限

它们分别控制总跟踪数量与扩展保留跟踪的数量。

​

使用限制的特性

使用限制为近似值，我们无法保证绝对精确。在极少数情况下，可能会有少量跟踪在阈值之上被处理，然后限制才开始生效。

​

扩展保留限制的副作用

扩展保留上限达到后，任何可能触发跟踪自动升级的功能都将不可用，因为继续升级会创建新的扩展跟踪，违背该限制。因此您将无法：

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

这些功能都可能导致自动升级，所以在达到上限时会被禁用。

​

更新使用限制

可在 Settings > Usage and Billing 页面更新使用限制。由于值会被缓存，新限制可能需要一两分钟才会生效。

​

相关内容

• 成本优化教程

​

额外资源

• 版本发布：了解 LangSmith 的版本支持策略，包括 Active、Critical、End of Life 和 Deprecated 等支持级别。

---