主题
本概述涵盖了 LangSmith 中与管理用户、组织、工作区和应用程序相关的主题。
资源层级结构
组织
组织是 LangSmith 内用户的逻辑分组，拥有自己的计费配置。通常，每个公司对应一个组织。一个组织可以拥有多个工作区。更多详情，请参阅设置指南。
首次登录时，系统会自动为您创建一个个人组织。如果您想与他人协作，可以创建一个单独的组织并邀请您的团队成员加入。个人组织和共享组织之间存在一些重要区别：
| 特性 | 个人组织 | 共享组织 |
|---|---|---|
| 最大工作区数量 | 1 | 可变，取决于计划（参见定价页面 |
| 协作 | 无法邀请用户 | 可以邀请用户 |
| 计费：付费计划 | 仅限开发者计划 | 所有其他计划可用 |
工作区
工作区以前称为租户。在过渡期间，部分代码和 API 可能仍会引用旧名称一段时间。
工作区是组织内用户的逻辑分组。工作区为资源和访问控制划分了信任边界。用户在工作区中可能拥有权限，这些权限授予他们访问该工作区内资源的权利，包括追踪项目、数据集、标注队列和提示。有关设置的详细信息，请参阅设置指南；有关权限的详细信息，请参阅工作区（RBAC）。
建议为组织内的每个团队创建一个单独的工作区。为了进一步组织资源，您可以使用应用程序来对工作区内的资源进行分组。
下图显示了一个示例工作区设置页面：
应用程序
应用程序是工作区内资源的逻辑分组。应用程序通常是代理，但也可以用于团队内的任何项目。应用程序通过仅显示与当前上下文中的应用程序相关联的资源来保持用户界面的组织性。
应用程序建立在资源标签之上，并可用于通过ABAC（目前处于私有预览阶段）来控制资源访问。
下图显示了如何在主导航栏中管理和切换应用程序：
任何资源都可以在不标记到应用程序的情况下创建。当选择显示所有应用程序选项时，这些资源将是可见的。
附加信息
下图解释了组织、工作区、应用程序和资源之间的关系：
有关哪些功能在哪些范围内可用的详细信息，请参见下表：
| 资源/设置 | 范围 |
|---|---|
| 追踪项目 | 工作区或应用程序 |
| 标注队列 | 工作区或应用程序 |
| 部署 | 工作区或应用程序 |
| 数据集与实验 | 工作区或应用程序 |
| 提示 | 工作区或应用程序 |
| 资源标签 | 工作区 |
| API 密钥 | 工作区 |
| 设置（包括密钥、反馈配置、模型、规则和共享 URL） | 工作区 |
| 用户管理：邀请用户到工作区 | 工作区 |
| RBAC：分配工作区角色 | 工作区 |
| 数据保留、使用限制 | 工作区* |
| 计划和计费、积分、发票 | 组织 |
| 用户管理：邀请用户到组织 | 组织** |
| 添加工作区 | 组织 |
| 分配组织角色 | 组织 |
| RBAC：创建/编辑/删除自定义角色 | 组织 |
* 数据保留设置和使用限制也即将在组织级别可用。** 自托管安装可以通过功能标志启用工作区级别的用户邀请到组织。详情请参阅自托管用户管理文档。
资源标签
资源标签允许您进一步隔离工作区内的资源，以便与ABAC一起使用。每个标签都是一个可以分配给资源的键值对。
LangSmith 的资源标签与云服务（如AWS）中的标签非常相似。
用户管理与 RBAC
用户
用户是拥有 LangSmith 访问权限的个人。用户可以是一个或多个组织的成员，也可以是这些组织内一个或多个工作区的成员。
组织成员在组织设置中进行管理：
工作区成员在工作区设置中进行管理：
API 密钥
我们已于 2024 年 10 月 22 日结束了对以 ls__ 为前缀的旧版 API 密钥的支持，转而支持个人访问令牌（PAT）和服务密钥。我们要求所有新集成都使用 PAT 和服务密钥。以 ls__ 为前缀的 API 密钥自 2024 年 10 月 22 日起将不再有效。
过期日期
创建 API 密钥时，您可以选择设置过期日期。为密钥添加过期日期可以增强安全性，并最大限度地降低未经授权访问的风险。例如，您可以为需要提升访问权限的临时任务设置密钥的过期日期。
默认情况下，密钥永不过期。一旦过期，API 密钥将不再有效，并且无法重新激活或修改其过期时间。
个人访问令牌（PATs）
个人访问令牌（PATs）用于对 LangSmith API 的请求进行身份验证。它们由用户创建，并限定于用户。PAT 将拥有创建它的用户相同的权限。我们建议不要使用这些令牌来验证来自您应用程序的请求，而是将其用于与 LangSmith API 交互的个人脚本或工具。如果与 PAT 关联的用户从组织中移除，该 PAT 将不再有效。
PATs 的前缀为 lsv2_pt_
服务密钥
服务密钥类似于 PATs，但用于代表服务账户对 LangSmith API 的请求进行身份验证。只有管理员可以创建服务密钥。我们建议将这些密钥用于需要与 LangSmith API 交互的应用程序/服务，例如 LangGraph 代理或其他集成。服务密钥可以限定在单个工作区、多个工作区或整个组织，并可用于对其有权访问的任何工作区的 LangSmith API 请求进行身份验证。
服务密钥的前缀为 lsv2_sk_
使用 X-Tenant-Id 请求头来指定目标工作区。
- 使用 PATs 时：如果省略此请求头，请求将针对与该密钥关联的默认工作区运行。
- 使用组织范围的服务密钥时：访问工作区范围的资源时必须包含
X-Tenant-Id请求头。没有它，请求将失败并返回403 Forbidden错误。
要了解如何创建服务密钥或个人访问令牌，请参阅设置指南
组织角色
组织角色与企业功能工作区 RBAC不同，用于多个工作区的上下文中。您的组织角色决定了您的工作区成员资格特征以及您的组织级权限。
所选的组织角色也会影响工作区成员资格，如下所述：
- 组织管理员授予管理所有组织配置、用户、计费和工作区的完全访问权限。
- 组织管理员对组织中的所有工作区拥有
Admin访问权限。
- 组织管理员对组织中的所有工作区拥有
- 组织用户可以读取组织信息，但无法在组织级别执行任何写入操作。组织用户可以创建个人访问令牌。
- 组织用户可以添加到一部分工作区，并像往常一样分配工作区角色（如果启用了 RBAC），这些角色指定了工作区级别的权限。
- 组织查看者等同于组织用户，但不能创建个人访问令牌。（对于自托管，在 Helm chart 版本 0.11.25+ 中可用）。
有关设置组织和工作区的更多信息，请参阅组织设置指南以获取更多信息。
下表概述了组织级别的权限：
| 组织查看者 | 组织用户 | 组织管理员 | |
|---|---|---|---|
| 查看组织配置 | ✅ | ✅ | ✅ |
| 查看组织角色 | ✅ | ✅ | ✅ |
| 查看组织成员 | ✅ | ✅ | ✅ |
| 查看数据保留设置 | ✅ | ✅ | ✅ |
| 查看使用限制 | ✅ | ✅ | ✅ |
| 创建个人访问令牌（PATs） | ❌ | ✅ | ✅ |
| 对所有工作区的管理员访问权限 | ❌ | ❌ | ✅ |
| 管理计费设置 | ❌ | ❌ | ✅ |
| 创建工作区 | ❌ | ❌ | ✅ |
| 创建、编辑和删除组织角色 | ❌ | ❌ | ✅ |
| 邀请新用户到组织 | ❌ | ❌ | ✅ |
| 删除用户邀请 | ❌ | ❌ | ✅ |
| 从组织中移除用户 | ❌ | ❌ | ✅ |
| 更新数据保留设置 | ❌ | ❌ | ✅ |
| 更新使用限制 | ❌ | ❌ | ✅ |
如需查看完整的权限列表以及可执行的操作和角色，请参阅组织和空间参考。
工作区角色（RBAC）
RBAC（基于角色的访问控制）是一项仅面向企业客户的功能。如果您对此功能感兴趣，请联系我们的销售团队。其他计划默认对所有用户使用管理员角色。
角色用于定义用户在工作区内拥有的权限集合。有三个无法编辑的内置系统角色：
组织管理员还可以为不同资源创建/编辑具有特定权限的自定义角色。
角色可以在组织设置下的角色选项卡中进行管理：
最佳实践
环境分离
使用资源标签通过默认标签键 Environment 和环境的不同值（例如 dev、staging、prod）来按环境组织资源。我们不建议使用单独的工作区进行环境分离，因为资源无法跨工作区共享，这将阻止您在环境之间提升资源（如提示）。
用于提示管理的资源标签与提交标签
虽然两种类型的标签都可以使用环境术语，如 dev、staging 和 prod，但它们有不同的用途：
- 资源标签 (
Environment: prod)：使用这些标签来组织和筛选工作区中的资源。将资源标签应用于追踪项目、数据集和其他资源（包括提示），以按环境对它们进行分组，从而在用户界面中启用筛选。 - 提交标签 (
prod标签)：使用这些标签来管理您的代码引用的提示版本。提交标签是指向提示历史中特定提交的标签。当您的代码按标签名称拉取提示时（例如client.pull_prompt("prompt-name:prod")），它会检索该标签当前指向的任何提交。要将提示从staging提升到prod，请将提交标签移动到指向所需的版本。
资源标签组织哪些资源属于一个环境。提交标签让您可以控制您的代码引用的哪个版本的提示，而无需更改代码本身。
使用与计费
数据保留
本节介绍数据保留在 LangSmith 中的工作原理及其计费方式。
保留的重要性
- 隐私：许多数据隐私法规，例如欧洲的 GDPR 或加利福尼亚的 CCPA，要求组织在个人数据不再为收集目的所需时将其删除。设置保留期限有助于遵守此类法规。
- 成本：LangSmith 对数据保留期短的追踪收费较低。有关详细信息，请参阅我们关于如何优化支出的教程。
工作原理
LangSmith 根据数据保留将追踪分为两个层级，具有以下特征：
| 基础层 | 扩展层 | |
|---|---|---|
| 价格 | $.50 / 1k 条追踪 | $5 / 1k 条追踪 |
| 保留期限 | 14 天 | 400 天 |
保留期结束后的数据删除
在指定的保留期结束后，追踪将无法在追踪项目用户界面或通过 API 访问。与该追踪相关的所有用户数据（例如输入和输出）将在其后一天内从我们的内部系统中删除。与每条追踪相关的一些元数据可能会无限期保留，用于分析和计费目的。
数据保留自动升级
自动升级可能会影响您的账单。请仔细阅读本节，以充分了解您预估的 LangSmith 追踪成本。
当您对 基础层 追踪使用某些功能时，它们的数据保留将自动升级到 扩展层。这将同时增加保留期限和追踪的成本。
追踪将在以下情况下自动升级的完整场景列表：
为什么自动升级追踪？
我们对追踪采用自动升级模型有两个原因：
- 我们认为匹配上述任何条件的追踪从根本上比其他追踪更有趣，因此用户能够将它们保留更长时间是有益的。
- 从理念上讲，我们希望为那些可能没有进行有意义交互的追踪向客户收取低一个数量级的费用。我们认为自动升级使我们的定价模型与 LangSmith 带来的价值保持一致，只有具有有意义交互的追踪才会以更高的费率收费。
如果您对我们的定价模型有任何疑问或疑虑，请随时通过 support.langchain.com 联系支持人员，并告诉我们您的想法！
数据保留如何影响下游功能？
- 标注队列、运行规则和反馈：使用这些功能的追踪将被自动升级。
- 监控：即使在基础层追踪的数据保留期结束后，监控选项卡仍将继续工作。它由存在超过 30 天的追踪元数据提供支持，这意味着您的监控图表即使在
基础层追踪上也将继续保持准确。 - 数据集：数据集具有无限的数据保留期。换句话说，如果您将追踪的输入和输出添加到数据集中，它们将永远不会被删除。我们建议，如果您使用 LangSmith 进行数据收集，请利用数据集功能。
计费模型
可计费指标
在您的 LangSmith 发票上，您将看到我们收费的两个指标：
- LangSmith 追踪（基础费用）
- LangSmith 追踪（扩展数据保留升级）。
第一个指标包括所有追踪，无论层级如何。第二个指标仅计算扩展保留追踪的数量。
为什么测量所有追踪 + 升级，而不是基础层和扩展层追踪？
在考虑我们的定价时，一个很自然的问题是：为什么不在发票上直接显示 基础层 和 扩展层 追踪的数量？
虽然我们理解这样会更直接，但它不能恰当地处理追踪升级。考虑一个在 6 月 30 日记录的 基础层 追踪，并在 7 月 3 日升级到 扩展层。基础层 追踪发生在 6 月的计费周期，但升级发生在 7 月的计费周期。因此，我们需要能够独立测量这两个事件，以便正确向客户收费。
如果您的追踪是作为扩展保留追踪记录的，那么 基础层 和 扩展层 指标都将以相同的时间戳记录。
成本细分
追踪的基础费用为每条追踪 0.05 美分。我们对升级的定价使得 扩展层 保留追踪的成本是基础层追踪价格的 10 倍（每条追踪 0.50 美分），包括两个指标。因此，每次升级的成本为 0.45 美分。
速率限制
LangSmith 设有速率限制，旨在确保所有用户的服务稳定性。
为确保访问和稳定性，在以下情况下，LangSmith 将响应 HTTP 状态码 429，表示速率或使用限制已超出：
在我们的应用程序负载均衡器上超过 1 分钟内的临时吞吐量限制
此 429 是由于在 1 分钟窗口内，基于每个 API 密钥/访问令牌超过了固定的 API 调用次数。窗口的开始时间会略有不同——