设置资源标签

虽然工作区有助于分隔信任边界和访问控制，但标签可以帮助您在工作区内组织资源。标签是可附加到资源上的键值对。

请注意与提交标签区分：资源标签是用于组织和筛选工作区资源（项目、数据集、提示词等）的键值对。提交标签是指引用提示词提交历史中特定版本的标签。尽管这两种标签类型可能使用相似的术语（如 prod 或 staging），但资源标签帮助您组织工作区内的资源，而提交标签则控制代码中使用提示词的哪个版本。

您可以通过 LangSmith 用户界面或通过 REST API 以编程方式管理资源标签：

用户界面
API

创建标签

要创建资源标签，您必须拥有 workspaces:manage 权限（默认授予工作区管理员角色）。编辑者可以对其拥有更新访问权限的资源应用应用标签，但创建标签键或应用其他标签类型需要此权限。有关将标签应用于资源的更多信息，请参阅工作区操作的标签部分。

创建标签的步骤：

导航到工作区设置页面，然后单击左侧边栏中的资源标签。
在此处，您将看到按键分组的现有标签值。LangSmith 默认创建 Application 和 Environment 键。您可以使用 Application 键来筛选用户界面中显示的资源。
选择页面顶部的 新建标签。系统会提示您输入标签的键和值。请注意，您可以使用现有键或创建新键。

将标签分配给资源

在用于创建新标签的同一侧边面板中，您也可以将资源分配给标签。在分配资源部分搜索相应的资源，并选择您想要打标签的资源。

您只能使用资源标签为工作区范围内的资源打标签。这包括跟踪项目、注释队列、部署、实验、数据集和提示词。

要取消资源上的标签，请在标签面板和资源标签面板中，单击标签旁边的回收站图标。

删除标签

您可以从设置页面 > 资源标签页面删除标签的键或值。要删除键，请单击键旁边的回收站图标。要删除值，请单击值旁边的回收站图标。如果您删除一个键，LangSmith 将删除与该键关联的所有值。当您删除一个值时，您将丢失该值与资源之间的所有关联。

通过 API 管理标签

您可以使用 LangSmith REST API 以编程方式创建、分配和查询资源标签。所有标签端点都位于 /api/v1/workspaces/current/ 下，并且需要 API 密钥。

设置

导入 requests 库并配置您的 API 密钥和标头。以下所有示例都假设这些变量在作用域内：

import os
import requests

LANGSMITH_API_URL = "https://api.smith.langchain.com"
LANGSMITH_API_KEY = os.environ["LANGSMITH_API_KEY"]
headers = {"x-api-key": LANGSMITH_API_KEY, "Content-Type": "application/json"}

创建标签键

创建标签键需要 workspaces:manage 权限。如果您想使用默认的 Application 键，请跳过此步骤，改为列出现有键。

response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys",
    headers=headers,
    json={"key": "Environment", "description": "部署环境"},
)
response.raise_for_status()
tag_key = response.json()
tag_key_id = tag_key["id"]

创建标签值

response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys/{tag_key_id}/tag-values",
    headers=headers,
    json={"value": "production"},
)
response.raise_for_status()
tag_value = response.json()
tag_value_id = tag_value["id"]

将标签分配给资源

response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/taggings",
    headers=headers,
    json={
        "tag_value_id": tag_value_id,
        "resource_type": "project",
        "resource_id": "<project-uuid>",
    },
)
response.raise_for_status()
tagging_id = response.json()["id"]

有效的 resource_type 值：project, dataset, prompt, experiment, queue, deployment, dashboard, evaluator, mcp_server, fleet_integration。

权限：分配 Application 标签只需要对目标资源的更新访问权限，因此编辑者无需 workspaces:manage 权限即可执行此操作。分配任何其他标签键需要 workspaces:manage 权限。

应用现有标签：如果键和值已经存在（例如默认的 Application 键），请先检索它们的 ID，然后直接进入分配步骤：

tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags",
    headers=headers,
).json()
# tags 是一个列表，元素结构为 {id, key, values: [{id, value}, ...]}

在创建资源时打标签

您可以在创建项目、数据集或提示词（包括分叉和克隆操作）时提供 tag_value_ids。标签会在与资源创建相同的事务中原子性地应用，因此资源不会短暂地处于未标记状态——这在实施 ABAC 策略时很重要。标签值必须已存在。将它们的 UUID 作为列表传递（最多 100 个）：

# 查找您想要应用的标签值 ID
tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags",
    headers=headers,
).json()
# tags 是一个列表，元素结构为 {id, key, values: [{id, value}, ...]}
env_tag_value_id = next(
    v["id"]
    for t in tags if t["key"] == "Environment"
    for v in t["values"] if v["value"] == "production"
)

# 创建一个项目并立即为其打标签
response = requests.post(
    f"{LANGSMITH_API_URL}/api/v1/sessions",
    headers=headers,
    json={
        "name": "my-project",
        "tag_value_ids": [env_tag_value_id],
    },
)
response.raise_for_status()
project = response.json()

以下端点接受相同的 tag_value_ids 字段：

端点	描述
`POST /api/v1/sessions`	创建跟踪项目
`POST /api/v1/datasets`	创建数据集（在 CSV 上传和实验上传的变体上也接受）
`POST /api/v1/datasets/{dataset_id}/clone`	克隆数据集
`POST /api/v1/repos`	创建提示词
`POST /api/v1/repos/{repo_id}/fork`	分叉提示词

权限：在创建时应用 Application 标签只需要对该资源类型的更新访问权限。应用任何其他标签键需要 workspaces:manage 权限。

如果您正在使用 LangSmith SDK 进行跟踪，并且项目是在跟踪数据摄取期间自动创建的，则该自动创建路径上不提供 tag_value_ids 参数。为确保从一开始即强制执行 ABAC 策略，请在开始跟踪会话之前，通过 POST /api/v1/sessions 预先创建项目并指定所需的 tag_value_ids。

查询标签

# 工作区中的所有标签键和值
tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags",
    headers=headers,
).json()

# 特定资源上的标签
resource_tags = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tags/resource",
    headers=headers,
    params={"resource_type": "project", "resource_id": "<project-uuid>"},
).json()

# 所有标记了特定值的资源
taggings = requests.get(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/taggings",
    headers=headers,
    params={"tag_value_id": tag_value_id},
).json()

从资源移除标签

requests.delete(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/taggings/{tagging_id}",
    headers=headers,
)

删除标签键或值

# 删除一个值（移除该值的所有资源分配）
requests.delete(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys/{tag_key_id}/tag-values/{tag_value_id}",
    headers=headers,
)

# 删除一个键（同时删除其所有值）
requests.delete(
    f"{LANGSMITH_API_URL}/api/v1/workspaces/current/tag-keys/{tag_key_id}",
    headers=headers,
)

有关请求/响应字段的完整列表，请参阅 API 参考文档。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Organization

Users & access control

Tools

Auditing

Data & compliance

Additional resources

创建标签

将标签分配给资源

删除标签

通过 API 管理标签

设置

创建标签键

创建标签值

将标签分配给资源

在创建资源时打标签

查询标签

从资源移除标签

删除标签键或值

​创建标签

​将标签分配给资源

​删除标签

​通过 API 管理标签

​设置

​创建标签键

​创建标签值

​将标签分配给资源

​在创建资源时打标签

​查询标签

​从资源移除标签

​删除标签键或值

创建标签

将标签分配给资源

删除标签

通过 API 管理标签

设置

创建标签键

创建标签值

将标签分配给资源

在创建资源时打标签

查询标签

从资源移除标签

删除标签键或值