> ## Documentation Index
> Fetch the complete documentation index at: https://cndoc-langchain.site/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)。
### 应用程序
应用程序是工作区内资源的逻辑分组。应用程序通常是代理，但您可以将它们用于团队内的任何项目。应用程序通过仅显示当前上下文中关联的应用程序资源来保持 UI 的整洁。
应用程序构建在[资源标签](/langsmith/administration-overview#resource-tags)之上，可用于使用 [ABAC](/langsmith/organization-workspace-operations#access-policies) 控制资源访问。
在 [LangSmith UI](https://smith.langchain.com) 的主导航栏中切换应用程序。使用侧边栏顶部的 **Application** 下拉菜单选择一个应用程序。
任何资源都可以在不标记到应用程序的情况下创建。当选择 **All applications** 选项时，这些资源将可见。
### 资源
资源是用于构建、运行和观察应用程序及代理的具体实体，例如跟踪项目、提示、数据集和部署。资源的作用域限定于特定的应用程序。
### 附加信息
下图说明了组织、工作区、应用程序和资源之间的关系：
有关哪些功能在哪些范围内可用，请参见下表：
| 资源/设置 | 范围 |
| ------------------------- | -------- |
| 跟踪项目 | 工作区或应用程序 |
| 标注队列 | 工作区或应用程序 |
| 部署 | 工作区或应用程序 |
| 数据集与实验 | 工作区或应用程序 |
| 提示 | 工作区或应用程序 |
| 资源标签 | 工作区 |
| 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 UI](https://smith.langchain.com) 中导航至 **Settings**，在侧边栏中选择 **Resource tags** 页面。
## 用户管理与 RBAC
### 用户
用户是可以访问 LangSmith 的人员。用户可以是一个或多个组织及其内工作区的成员。
组织成员在 **Settings** 页面的 **Members and roles** 下进行管理。
工作区成员在 **Settings** 页面的 **Workspaces** 下进行管理。
### API 密钥
我们已于 2024 年 10 月 22 日终止对以 `ls__` 为前缀的旧版 API 密钥的支持，转而使用个人访问令牌 (PAT) 和服务密钥。我们要求所有新集成都使用 PAT 和服务密钥。自 2024 年 10 月 22 日起，以 `ls__` 为前缀的 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_` 为前缀
使用 `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+）。
组织用户和组织查看者角色仅在 [Plus 和 Enterprise 计划](https://langchain.com/pricing) 的组织中可用。在开发者组织（单一工作区）中，所有用户默认被分配组织管理员角色。
有关如何为整个组织禁用 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) 也可以创建/编辑具有不同资源特定权限的自定义角色。
您可以在 **Organization Settings** > **Members and roles** 下管理角色，并选择 **Roles** 选项卡。
* 有关角色和权限的全面文档，请参阅[基于角色的访问控制](/langsmith/rbac)指南。
* 有关分配和创建角色的更多详情，请参阅[用户管理](/langsmith/user-management)指南。
* 有关所需权限的完整列表以及可执行这些权限的操作和角色，请参阅[组织和工作区参考](/langsmith/organization-workspace-operations)。
## 最佳实践
### 环境分离
使用[资源标签](#resource-tags)通过默认标签键 `Environment` 和不同的环境值（例如 `dev`、`staging`、`prod`）按环境组织资源。我们不建议使用单独的工作区进行环境分离，因为资源无法跨工作区共享，这将阻止您在环境之间提升资源（如提示）。
**资源标签与提交标签用于提示管理**
虽然两种类型的标签都可以使用 `dev`、`staging` 和 `prod` 等环境术语，但它们的用途不同：
* **资源标签** (`Environment: prod`)：使用这些标签来*组织和过滤*工作区中的资源。将资源标签应用于跟踪项目、数据集和其他资源（包括提示），以按环境对它们进行分组，从而在 UI 中启用过滤。
* [提交标签](/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 天 |
**保留期结束后删除数据**
在指定的保留期后，跟踪在跟踪项目 UI 或通过 API 中将不再可访问。此后一天内，与该跟踪相关的所有用户数据（例如输入和输出）将从我们的内部系统中删除。与每个跟踪关联的一些元数据可能会被无限期保留，用于分析和计费目的。
#### 数据保留自动升级
自动升级可能会影响您的账单。请仔细阅读本节，以充分了解您的预估 LangSmith 跟踪成本。
当您使用某些具有 `base` 层级跟踪的功能时，其数据保留将自动升级到 `extended` 层级。这将增加保留期限和跟踪的成本。
跟踪将在以下情况下升级的完整场景列表：
* 向跟踪上的任何运行（或线程中的任何跟踪）添加了**反馈**，无论是通过[手动标注](/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 天的跟踪元数据驱动，这意味着即使对于 `base` 层级的跟踪，您的监控图表也将继续保持准确。
* **数据集**：数据集具有无限的数据保留期。换句话说，如果您将跟踪的输入和输出添加到数据集，它们将永远不会被删除。我们建议如果您使用 LangSmith 进行数据收集，请利用数据集功能。
#### 计费模型
**可计费指标**
在您的 LangSmith 发票上，您将看到我们收取的两个指标：
* LangSmith 跟踪（基础费用）
* LangSmith 跟踪（扩展数据保留升级）。
第一个指标包括所有跟踪，无论层级如何。第二个指标仅计算扩展保留跟踪的数量。
**为什么测量所有跟踪 + 升级，而不是基础和扩展跟踪？**
在考虑我们的定价时，一个自然的问题是为什么不直接在发票上显示 `base` 层级和 `extended` 层级跟踪的数量？
虽然我们理解这会更直接，但它不能正确处理跟踪升级。考虑一个在 6 月 30 日记录的 `base` 层级跟踪，并在 7 月 3 日升级到 `extended` 层级。`base` 层级跟踪发生在 6 月计费周期，但升级发生在 7 月计费周期。因此，我们需要能够独立测量这两个事件，以便正确地向客户收费。
如果您的跟踪是作为扩展保留跟踪记录的，那么 `base` 和 `extended` 指标将以相同的时间戳记录。
**成本明细**
跟踪的基础费用为每跟踪 .05¢。我们将升级定价为 `extended` 保留跟踪的成本是基础层级跟踪价格的 10 倍（每跟踪 .50¢），包括两个指标。因此，每次升级的成本为 .45¢。
### 速率限制
LangSmith 具有速率限制，旨在确保所有用户的服务稳定性。
为确保访问和稳定性，LangSmith 将在以下情况下返回 HTTP 状态码 429，表示速率或用量限制已超出：
#### 在应用负载均衡器上 1 分钟内的临时吞吐量限制
此 429 是在 1 分钟窗口内超出固定数量的 API 调用（基于每个服务密钥或 PAT）的结果。窗口的开始时间会略有不同——不保证在时钟分钟的开始时开始——并且可能根据应用程序部署事件而变化。
在达到最大事件数后，我们将返回 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 和 Enterprise 计划层级的组织比我们的 Free 和 Developer 计划层级（设计用于个人使用）具有更高的每小时限制。
| 计划 | 限制 | 窗口 |
| ------------ | ---------- | ---- |
| 开发者（无支付方式） | 50,000 事件 | 1 小时 |
| 开发者（有支付方式） | 250,000 事件 | 1 小时 |
| Startup/Plus | 500,000 事件 | 1 小时 |
| 企业 | 自定义 | 自定义 |
#### 计划级别的每小时跟踪数据摄入限制
此 429 是达到您跟踪输入、输出和元数据中摄入的最大数据量的结果，在 UTC 每个时钟小时开始时的固定窗口中进行评估，并在每个新小时开始时重置。
通常，输入、输出和元数据在运行创建和更新事件时都会发送。如果一个运行以 2.0MB 创建并在同一小时内更新到 3.0MB，这将计为 5.0MB 的存储，计入此限制。
此限制由我们的应用程序抛出，并因计划层级而异，我们的 Startup/Plus 和 Enterprise 计划层级的组织比我们的 Free 和 Developer 计划层级（设计用于个人使用）具有更高的每小时限制。
| 计划 | 限制 | 窗口 |
| ------------ | ----- | ---- |
| 开发者（无支付方式） | 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. 将运行添加到标注队列
这些功能中的每一个都可能导致自动升级，因此当限制达到时，我们会关闭它们。
#### 更新用量限制
可以从 `Settings` 页面的 `Usage and Billing` 下更新用量限制。限制值会被缓存，因此可能需要一两分钟才能应用新限制。
### 相关内容
* 关于如何[强制执行支出限制](/langsmith/billing#enforce-spend-limits)的教程
## 附加资源
* **[发布策略](/langsmith/release-versions)**：了解自托管发布渠道、节奏和版本编号。
***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
[在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/langsmith/administration-overview.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。