> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-zh.cn/llms.txt
> Use this file to discover all available pages before exploring further.
# 概述
本概述涵盖了在 LangSmith 中管理用户、组织、工作区和应用程序的相关主题。
## 资源层级结构
### 组织
组织是 LangSmith 内用户的逻辑分组，它定义了适用于其所有工作区的共享设置。这些设置管理组织层面的关注点，而非工作区内的单个项目。常见的组织级配置包括用户管理、单点登录（SSO）、OAuth 提供商配置、自定义角色创建、计费和用量跟踪。通常，每个公司对应一个组织。一个组织可以拥有多个工作区。更多详情，请参阅[设置指南](/langsmith/set-up-hierarchy#set-up-an-organization)。
首次登录时，系统会自动为您创建一个个人组织。如果您想与他人协作，可以创建一个单独的组织并邀请您的团队成员加入。个人组织和共享组织之间存在一些重要区别：
| 功能特性 | 个人组织 | 共享组织 |
| ------- | ------- | -------------------------------------------------------------- |
| 最大工作区数量 | 1 | 可变，取决于计划（参见[定价页面](https://www.langchain.com/pricing-langsmith) |
| 协作 | 无法邀请用户 | 可以邀请用户 |
| 计费：付费计划 | 仅限开发者计划 | 所有其他计划可用 |
### 工作区
工作区以前称为租户。在过渡期间，部分代码和 API 可能仍会引用旧名称一段时间。
工作区是组织内用户和资源的逻辑分组。工作区通常用于隔离团队或业务单元，提供项目及其关联资源之间的分离。工作区为资源和访问控制划分了信任边界。用户在**工作区级别**被授予权限，这些权限决定了他们对该工作区内资源的访问权限，包括追踪项目、数据集、标注队列和提示。有关设置详情，请参阅[设置指南](/langsmith/set-up-hierarchy#set-up-a-workspace)；有关权限详情，请参阅[工作区（RBAC）](/langsmith/administration-overview#workspace-roles-rbac)。
我们建议为组织内的每个团队创建一个单独的工作区。为了进一步组织资源，您可以使用[应用程序](#applications)对工作区内的资源进行分组。有关根据团队隔离需求的不同工作区组织模型的指导，请参考[工作负载隔离](/langsmith/workload-isolation)。
### 应用程序
应用程序是工作区内资源的逻辑分组。应用程序通常是智能体，但您也可以将其用于团队内的任何项目。应用程序通过仅显示与当前上下文中的应用程序相关联的资源，来保持用户界面的有序性。
应用程序建立在[资源标签](/langsmith/administration-overview#resource-tags)之上，并可用于通过[ABAC](/langsmith/organization-workspace-operations#access-policies)控制资源访问。
在 [LangSmith 用户界面](https://smith.langchain.com)的主导航侧边栏中切换应用程序。使用侧边栏顶部的**应用程序**下拉菜单来选择应用程序。
任何资源都可以在不标记到应用程序的情况下创建。这些资源将在选择**所有应用程序**选项时可见。
### 资源
资源是用于构建、运行和观察应用程序和智能体的具体实体，例如追踪项目、提示、数据集和部署。资源的作用域限定在特定的应用程序。
### 附加信息
下图解释了组织、工作区、应用程序和资源之间的关系：
有关哪些功能在哪些作用域中可用，请参阅下表：
| 资源/设置 | 作用域 |
| -------------------------- | -------- |
| 追踪项目 | 工作区或应用程序 |
| 标注队列 | 工作区或应用程序 |
| 部署 | 工作区或应用程序 |
| 数据集和实验 | 工作区或应用程序 |
| 提示 | 工作区或应用程序 |
| 资源标签 | 工作区 |
| API 密钥 | 工作区 |
| 设置（包括密钥、反馈配置、模型、规则和共享 URL） | 工作区 |
| 用户管理：邀请用户到工作区 | 工作区 |
| RBAC：分配工作区角色 | 工作区 |
| 数据保留、用量限制 | 工作区\* |
| 计划和计费、积分、发票 | 组织 |
| 用户管理：邀请用户到组织 | 组织\*\* |
| 添加工作区 | 组织 |
| 分配组织角色 | 组织 |
| RBAC：创建/编辑/删除自定义角色 | 组织 |
\* 数据保留设置和用量限制也即将在组织级别可用 \*\* 自托管安装可以通过功能标志启用工作区级别的用户邀请到组织。详情请参阅[自托管用户管理文档](/langsmith/self-host-user-management)。
### 资源标签
资源标签允许您进一步隔离工作区内的资源，以便与[ABAC](/langsmith/organization-workspace-operations#access-policies)一起使用。每个标签都是一个键值对，您可以将其分配给资源。
LangSmith 的资源标签与云服务（如 [AWS](https://docs.aws.amazon.com/tag-editor/latest/userguide/tagging.html)）中的标签非常相似。
在 [LangSmith 用户界面](https://smith.langchain.com)中导航到**设置**，然后在侧边栏中选择**资源标签**页面。
## 用户管理和 RBAC
### 用户
用户是拥有 LangSmith 访问权限的个人。用户可以是一个或多个组织以及这些组织内工作区的成员。
组织成员在**设置**页面的**成员和角色**下进行管理。
工作区成员在**设置**页面的**工作区**下进行管理。
### API 密钥
我们已于 2024 年 10 月 22 日终止了对前缀为 `ls__` 的旧版 API 密钥的支持，转而支持个人访问令牌（PAT）和服务密钥。我们要求所有新集成都使用 PAT 和服务密钥。前缀为 `ls__` 的 API 密钥自 2024 年 10 月 22 日起将不再有效。
#### 过期日期
创建 API 密钥时，您可以选择设置过期日期。为密钥添加过期日期可以增强安全性，并最大限度地降低未经授权访问的风险。例如，您可以为需要提升权限的临时任务设置密钥的过期日期。
默认情况下，密钥永不过期。一旦过期，API 密钥将不再有效，并且无法重新激活或修改其过期时间。
#### 个人访问令牌（PAT）
个人访问令牌（PAT）用于对 LangSmith API 的请求进行身份验证。它们由用户创建，并限定于用户。PAT 将拥有创建它的用户相同的权限。我们建议不要使用这些令牌来验证来自应用程序的请求，而是将其用于与 LangSmith API 交互的个人脚本或工具。如果与 PAT 关联的用户从组织中移除，该 PAT 将不再有效。
PAT 的前缀为 `lsv2_pt_`
#### 服务密钥
服务密钥类似于 PAT，但用于代表服务账户对 LangSmith API 的请求进行身份验证。只有管理员可以创建服务密钥。我们建议将这些密钥用于需要与 LangSmith API 交互的应用程序/服务，例如 LangGraph 智能体或其他集成。服务密钥可以限定在单个工作区、多个工作区或整个组织，并可用于对其有权访问的任何工作区的 LangSmith API 请求进行身份验证。
服务密钥的前缀为 `lsv2_sk_`
使用 `X-Tenant-Id` 请求头来指定目标工作区。
* **使用 PAT 时**：如果省略此请求头，请求将在与该密钥关联的默认工作区上运行。
* **使用组织范围的服务密钥时**：访问工作区范围的资源时必须包含 `X-Tenant-Id` 请求头。没有它，请求将失败并返回 `403 Forbidden` 错误。
要了解如何创建服务密钥或个人访问令牌，请参阅[设置指南](/langsmith/create-account-api-key)
### 组织角色
组织角色与[企业功能工作区 RBAC](#workspace-roles-rbac) 不同，用于多个[工作区](#workspaces)的上下文。您的组织角色决定了您的工作区成员资格特征以及您的[组织级权限](/langsmith/organization-workspace-operations)。
所选的组织角色也会影响工作区成员资格，如下所述：
* [组织管理员](/langsmith/rbac#organization-admin) 授予管理所有组织配置、用户、计费和工作区的完全访问权限。
* 组织管理员对组织中的所有工作区拥有 `Admin` 访问权限。
* [组织用户](/langsmith/rbac#organization-user) 可以读取组织信息，但无法在组织级别执行任何写入操作。组织用户可以创建[个人访问令牌](#personal-access-tokens-pats)。
* 组织用户可以添加到一部分工作区，并像往常一样分配工作区角色（如果启用了 RBAC），这些角色指定了工作区级别的权限。
* [组织查看者](/langsmith/rbac#organization-viewer) 等同于组织用户，但**不能**创建个人访问令牌。（对于自托管，在 Helm chart 版本 0.11.25+ 中可用）。
Organization User 和 Organization Viewer 角色仅在 [Plus 和 Enterprise 计划](https://langchain.com/pricing) 的组织中可用。在开发者组织（单工作区）中，所有用户默认被分配 Organization Admin 角色。
有关如何为整个组织禁用 PAT 创建的说明，请参阅[安全设置](/langsmith/manage-organization-by-api#security-settings)。
有关设置组织和工作区的更多信息，请参考[组织设置指南](/langsmith/set-up-hierarchy#organization-roles)以获取更多信息。
下表提供了组织级权限的概述：
| | 组织查看者 | 组织用户 | 组织管理员 |
| -------------- | ----- | ---- | ----- |
| 查看组织配置 | ✅ | ✅ | ✅ |
| 查看组织角色 | ✅ | ✅ | ✅ |
| 查看组织成员 | ✅ | ✅ | ✅ |
| 查看数据保留设置 | ✅ | ✅ | ✅ |
| 查看用量限制 | ✅ | ✅ | ✅ |
| 创建个人访问令牌（PAT） | ❌ | ✅ | ✅ |
| 对所有工作区的管理员访问权限 | ❌ | ❌ | ✅ |
| 管理计费设置 | ❌ | ❌ | ✅ |
| 创建工作区 | ❌ | ❌ | ✅ |
| 创建、编辑和删除组织角色 | ❌ | ❌ | ✅ |
| 邀请新用户到组织 | ❌ | ❌ | ✅ |
| 删除用户邀请 | ❌ | ❌ | ✅ |
| 从组织中移除用户 | ❌ | ❌ | ✅ |
| 更新数据保留设置 | ❌ | ❌ | ✅ |
| 更新用量限制 | ❌ | ❌ | ✅ |
如需获取所需权限的完整列表，以及可执行这些操作的操作和角色，请参阅 [组织和工作区参考](/langsmith/organization-workspace-operations)。
### 工作区角色（RBAC）
RBAC（基于角色的访问控制）是仅面向企业客户的功能。如果您对此功能感兴趣，请[联系我们的销售团队](https://www.langchain.com/contact-sales)。其他计划默认对所有用户使用管理员角色。
角色用于定义用户在工作区内拥有的权限集合。有三个无法编辑的内置系统角色：
* [工作区管理员](/langsmith/rbac#workspace-admin) 拥有工作区内所有资源的完全访问权限。
* [工作区编辑者](/langsmith/rbac#workspace-editor) 拥有除工作区管理（添加/移除用户、更改角色、配置服务密钥）之外的所有权限。
* [工作区查看者](/langsmith/rbac#workspace-viewer) 对工作区内的所有资源拥有只读访问权限。
[组织管理员](/langsmith/rbac#organization-admin) 还可以为不同资源创建/编辑具有特定权限的自定义角色。
您可以在**组织设置** > **成员和角色**下管理角色，并选择**角色**选项卡。
* 有关角色和权限的全面文档，请参阅[基于角色的访问控制](/langsmith/rbac)指南。
* 有关分配和创建角色的更多详情，请参阅[用户管理](/langsmith/user-management)指南。
* 如需获取所需权限的完整列表，以及可执行这些操作的操作和角色，请参阅 [组织和工作区参考](/langsmith/organization-workspace-operations)。
## 最佳实践
### 环境分离
使用[资源标签](#resource-tags)通过默认标签键 `Environment` 和环境的不同值（例如 `dev`、`staging`、`prod`）来按环境组织资源。我们不建议使用单独的工作区进行环境分离，因为资源无法跨工作区共享，这将阻止您在环境之间提升资源（如提示）。
**提示管理中的资源标签与提交标签**
虽然两种类型的标签都可以使用环境术语，如 `dev`、`staging` 和 `prod`，但它们的目的不同：
* **资源标签** (`Environment: prod`)：使用这些标签在您的工作区中*组织和筛选*资源。将资源标签应用于追踪项目、数据集和其他资源（包括提示），以按环境对它们进行分组，从而在用户界面中实现筛选。
* [提交标签](/langsmith/manage-prompts#commit-tags) (`prod` 标签)：使用这些标签来管理您的代码引用的[提示版本](/langsmith/prompt-engineering)。提交标签是指向提示历史记录中特定提交的标签。当您的代码按标签名称拉取提示时（例如 `client.pull_prompt("prompt-name:prod")`），它会检索该标签当前指向的提交。要将提示从 `staging` 提升到 `prod`，请将提交标签移动到指向所需的版本。
资源标签组织**哪些资源**属于某个环境。提交标签让您无需更改代码本身即可控制您的代码引用的**哪个版本**的提示。
## 用量和计费
### 数据保留
本节介绍数据保留在 LangSmith 中的工作原理及其计费方式。
#### 保留的重要性
* **隐私**：许多数据隐私法规，例如欧洲的 GDPR 或加利福尼亚州的 CCPA，要求组织在个人数据不再用于收集目的时将其删除。设置保留期限有助于遵守此类法规。
* **成本**：LangSmith 对数据保留时间短的追踪收费较低。更多信息，请了解如何[强制执行支出限制](/langsmith/billing#enforce-spend-limits)。
#### 工作原理
LangSmith 根据数据保留有两个追踪层级，具有以下特征：
| | 基础 | 扩展 |
| -------- | ----------------------------------------------------- | ----------------------------------------------------- |
| **价格** | [参见定价页面](https://www.langchain.com/pricing-langsmith) | [参见定价页面](https://www.langchain.com/pricing-langsmith) |
| **保留期限** | 14 天 | 400 天 |
**保留期结束后的数据删除**
在指定的保留期结束后，追踪将无法在追踪项目用户界面或通过 API 访问。与追踪相关的所有用户数据（例如输入和输出）将在此后一天内从我们的内部系统中删除。与每个追踪相关的一些元数据可能会无限期保留，用于分析和计费目的。
**数据保留自动升级**
自动升级可能会影响您的账单。请仔细阅读本节，以充分了解您预估的 LangSmith 追踪成本。
当您将某些功能与 `基础` 层级的追踪一起使用时，它们的数据保留将自动升级到 `扩展` 层级。这将增加保留期限和追踪的成本。
追踪将在以下情况下自动升级的完整场景列表：
* 向追踪（或线程中的任何追踪）上的任何运行添加**反馈**，无论是通过[手动标注](/langsmith/annotate-traces-inline)、使用[在线评估器](/langsmith/online-evaluations-llm-as-judge)自动添加，还是通过 SDK [以编程方式](/langsmith/attach-user-feedback)添加。
* **[标注队列](/langsmith/annotation-queues#assign-runs-to-a-single-run-queue)** 收到来自追踪的任何运行。
* **[自动化规则](/langsmith/rules#create-a-rule)** 匹配追踪内的任何运行。
**为什么自动升级追踪？**
我们对追踪采用自动升级模型有两个原因：
1. 我们认为匹配任何这些条件的追踪从根本上比其他追踪更有趣，因此用户能够将它们保留更长时间是有益的。
2. 从哲学上讲，我们希望为可能没有进行有意义交互的追踪收取低一个数量级的费用。我们认为自动升级使我们的定价模型与 LangSmith 带来的价值保持一致，只有具有有意义交互的追踪才会以更高的费率收费。
如果您对我们的定价模型有疑问或疑虑，请随时通过 [support.langchain.com](https://support.langchain.com) 联系支持人员并告诉我们您的想法！
**数据保留如何影响下游功能？**
* **标注队列、运行规则和反馈**：使用这些功能的追踪将被[自动升级](#data-retention-auto-upgrades)。
* **监控**：即使在基础层级追踪的数据保留期结束后，监控选项卡仍将继续工作。它由存在超过 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 分钟窗口内，每个服务密钥或 PAT 的 API 调用次数超过了固定数量。窗口的开始时间会略有不同——不保证从时钟分钟的开始开始——并且可能会根据应用程序部署事件而变化。
在收到最大事件数后，我们将响应 429，直到达到评估窗口开始后的 60 秒，然后该过程重复。
此 429 由我们的应用程序负载均衡器抛出，是所有 LangSmith 用户（与计划层级无关）为确保所有用户的服务连续性而设置的机制。
| 方法 | 端点 | 限制 | 窗口 |
| ---------------- | ------------- | ---- | ---- |
| `DELETE` | `/sessions*` | 30 | 1 分钟 |
| `POST` 或 `PATCH` | `/runs*` | 5000 | 1 分钟 |
| `GET` | `/runs/:id` | 30 | 1 分钟 |
| `POST` | `/feedbacks*` | 5000 | 1 分钟 |
| `*` | `*` | 2000 | 1 分钟 |
LangSmith SDK 采取措施，通过将来自单个会话 ID 的至多 100 次运行批量处理为单个 API 调用，以最大限度地降低在运行相关端点上达到这些限制的可能性。
#### 计划级别的每小时追踪事件限制
此 429 是由于达到您每小时的最大事件摄入量，并在 UTC 每个时钟小时开始时的一个固定窗口中进行评估，并在每个新小时的开始时重置。
此上下文中的事件是运行的创建或更新。如果运行在同一小时内创建并随后更新，则会计为该限制的 2 个事件。
此限制由我们的应用程序抛出，并因计划层级而异，我们的 Startup/Plus 和企业计划层级的组织比我们的免费和开发者计划层级（专为个人使用设计）具有更高的每小时限制。
| 计划 | 限制 | 窗口 |
| ------------ | ----------- | ---- |
| 开发者（未绑定支付方式） | 50,000 个事件 | 1 小时 |
| 开发者（已绑定支付方式） | 250,000 个事件 | 1 小时 |
| Startup/Plus | 500,000 个事件 | 1 小时 |
| 企业 | 自定义 | 自定义 |
#### 计划级别的每小时追踪数据摄入限制
此 429 是由于达到您的追踪输入、输出和元数据中摄入的最大数据量，并在 UTC 每个时钟小时开始时的一个固定窗口中进行评估，并在每个新小时的开始时重置。
通常，输入、输出和元数据在运行创建和更新事件中都会发送。如果运行在 2.0MB 时创建，并在同一小时内更新到 3.0MB，则会计为该限制的 5.0MB 存储量。
此限制由我们的应用程序抛出，并因计划层级而异，我们的 Startup/Plus 和企业计划层级的组织比我们的免费和开发者计划层级（专为个人使用设计）具有更高的每小时限制。
| 计划 | 限制 | 窗口 |
| ------------ | ----- | ---- |
| 开发者（未绑定支付方式） | 500MB | 1 小时 |
| 开发者（已绑定支付方式） | 2.5GB | 1 小时 |
| Startup/Plus | 5.0GB | 1 小时 |
| 企业 | 自定义 | 自定义 |
#### 计划级别的每月唯一追踪限制
此 429 是由于达到您每月最大追踪摄入量，并在 UTC 每个日历月开始时的一个固定窗口中进行评估，并在每个新月的开始时重置。
此限制由我们的应用程序抛出，仅适用于未绑定支付方式的开发者计划层级。
| 计划 | 限制 | 窗口 |
| ------------ | --------- | ---- |
| 开发者（未绑定支付方式） | 5,000 条追踪 | 1 个月 |
#### 自行配置的每月用量限制
此 429 是由于达到您的组织管理员配置的用量限制，并在 UTC 每个日历月开始时的一个固定窗口中进行评估，并在每个新月的开始时重置。
此限制由我们的应用程序抛出，并根据组织的配置设置而异。
#### 每条追踪的最大运行次数
每条追踪最多限制为 25,000 次运行。一旦该追踪达到此限制，LangSmith 将拒绝您为此追踪发送的任何额外运行。
#### 运行查询端点
[`POST /runs/query`](https://api.smith.langchain.com/redoc#tag/run/operation/query_runs_api_v1_runs_query_post) 端点根据查询参数有额外的按租户速率限制。详情请参阅[使用 SDK 查询追踪](/langsmith/export-traces#rate-limits)。
#### 在您的应用程序中处理 429 响应
由于某些 429 响应是暂时的，并且可能在后续调用中成功，如果您直接在应用程序中调用 LangSmith API，我们建议实施带有指数退避和抖动的重试逻辑。
为方便起见，使用 LangSmith SDK 构建的 LangChain 应用程序内置了此功能。
需要注意的是，如果您长时间使端点饱和，重试可能无效，因为您的应用程序最终会积压大量请求，耗尽所有重试次数。
如果是这种情况，我们希望能更具体地讨论您的需求。请通过 [LangSmith 支持](https://support.langchain.com) 联系支持人员，提供有关您的应用程序吞吐量需求的详细信息以及示例代码，我们可以与您合作，更好地了解最佳方法是修复错误、更改应用程序代码还是选择不同的 LangSmith 计划。
### 用量限制
LangSmith 允许您配置追踪的用量限制。请注意，这些是*用量*限制，而不是*支出*限制，这意味着它们允许您限制某些事件的发生次数，而不是您将花费的总金额。
LangSmith 允许您设置两种不同的每月限制，反映了我们在前述数据保留指南中讨论的可计费指标：
* 所有追踪限制
* 扩展数据保留追踪限制
这些限制允许您分别限制总追踪数和扩展数据保留追踪数。
#### 用量限制的特性
用量限制是近似值，这意味着我们不保证限制的精确性。在极少数情况下，在用量限制开始应用之前，可能会有少量时间处理超出限制阈值的额外追踪。
#### 扩展数据保留追踪限制的副作用
扩展数据保留追踪限制有副作用。如果已达到限制，任何可能导致追踪层级自动升级的功能将变得不可访问。这是因为追踪的自动升级将导致创建另一个扩展保留追踪，而这反过来不应被限制允许。因此，您将无法再：
1. 匹配运行规则
2. 向追踪添加反馈
3. 将运行添加到标注队列
这些功能中的每一个都可能导致自动升级，因此当达到限制时我们会关闭它们。
#### 更新用量限制
用量限制可以从`设置`页面下的`用量和计费`中更新。限制值会被缓存，因此可能需要一两分钟才能应用新的限制。
### 相关内容
* 关于如何[强制执行支出限制](/langsmith/billing#enforce-spend-limits)的教程
## 附加资源
* **[发布版本](/langsmith/release-versions)**：了解 LangSmith 的版本支持政策，包括活跃、关键、生命周期终止和已弃用的支持级别。
***
[Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/i18n\zh-CN\langsmith\administration-overview.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
[Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.