Label Studio 组织级设置实战指南：从权限、访问令牌到模型提供商与支持报告的完整配置手册
【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio
本文基于 Label Studio 官方文档中的 Organization Settings 系列指南，系统讲解在企业部署中如何配置组织级（org-wide）设置：包括 Usage & License 页面上的席位、会话超时与功能开关，访问令牌（Personal Access Token 与 Legacy Token）的启用与使用，模型提供商的接入方式，角色权限的自定义，以及支持报告的生成与投递。读者读完本文后，将能够以 Owner / Admin 身份完成 Label Studio Enterprise 与 Starter Cloud 的全部组织级管理操作，并理解这些设置在后端源码（label_studio/session_policy、label_studio/jwt_auth）中的底层实现逻辑。
组织级设置总览：五个配置入口
在 Label Studio 中，组织级（org-wide）设置分散在若干页面中，分别面向不同的管理职责与角色开放。下表总结了全部入口及其访问权限：
| 设置页面 | 访问角色 | 功能说明 |
|---|---|---|
| Usage & License | Owner / Admin | 混合型设置页：Admin 可启用邮件通知；Owner 可启用 AI、存储代理（Storage Proxy）与早期尝鲜（Early Adopter）功能 |
| Access Token | Owner / Admin | 控制组织内可用的访问令牌类型（Personal Access Token / Legacy Token） |
| Model Providers | Owner / Admin | 配置模型提供商，供 Prompts 与 Chat 标签 使用 |
| Permissions | Owner | 针对具体角色细粒度定制权限 |
| Support reports | Owner / Admin | 生成匿名化的运维报告，帮助 HumanSignal 支持团队理解部署状况、诊断问题并给出工作流与性能优化建议 |
其中 Permissions 页面仅对 Owner 角色可见，而其余页面同时面向 Owner 与 Admin 开放。值得注意的是，在 User roles and permissions 的权限矩阵中，Owner 拥有“配置组织设置”的完整权限，而 Admin 仅为Partial（部分）权限——这正是admin_usage.md中“仅 Owner 可更新”的若干设置的来源。
Usage & License：席位、许可与组织级功能开关
在Organization > Settings > Usage & License页面，可以查看套餐与席位使用情况，并配置一系列组织级行为。
席位（Seats）与许可信息
Seats in use（席位占用）区域显示许可证允许的席位数量与实际活跃用户数的对比。每个组织的许可证都包含固定数量的席位，如需增加席位，需要联系 HumanSignal 客户代表。
对于本地部署（On-premise），可通过设置LICENSE_MAX_USERS_OVERRIDE环境变量，让部署使用少于许可证允许的席位。注意两个限制：
- 该变量只能降低已许可的席位数量，若设置得更高，部署将无法启动；
- 席位是跨部署内所有组织统一统计的。
该环境变量可借助 Helm 的global.extraEnvironmentVars注入，详见 Available Helm values 中关于global.extraEnvironmentVars的说明。
License info（许可信息）部分包含许可证的签发时间与到期时间，并展示以下用量统计：
- Projects（项目数）：Cloud/SaaS 下统计当前组织拥有的所有项目（无论 draft/published 状态，包含沙箱项目）；On-prem 下统计服务器上的全部项目（不区分状态与工作区）。
- Results（标注结果数）：组织在所有项目中创建的标注区域（region）总数。一个 result 即一条标注
result数组中的一项——一个边界框、一段文本跨度（span）、区域间的关系（relation）等。
安全设置（仅 Owner 可更新）
Session Timeout Policy（会话超时策略）由两个字段控制：
| 字段 | 说明 |
|---|---|
| Max session age (minutes) | 用户可保持空闲的最大分钟数。超过该限制后，用户在下一次触发请求时被自动登出。任何与后端的交互（触发 API 调用的点击、保存、轮询等）都会重置该计时器 |
| Max time between activity (minutes) | 会话的绝对生命周期。无论用户是否活跃，会话从登录起不得超过该分钟数；一旦到达，用户必须重新认证 |
在源码层面，该策略由label_studio/session_policy应用实现：models.py 中的SessionTimeoutPolicy模型定义了max_session_age与max_time_between_activity字段，serializers.py 将其暴露为 API 字段，admin.py 则在 Django Admin 中列出。测试用例 test_session_policy.py 显示默认值按分钟计算（如 8 天 =8 * 24 * 60分钟），且更新策略会立即反映到 API 响应中。
Single Sign-On（SSO）指示组织是否可以使用单点登录。注意：试用组织或许可证未启用 SSO 时不可用。
Embedding 与功能开关（Features）
Embedding字段用于配置 Label Studio Embeds（嵌入标注界面）。该能力并非对所有客户开放，需要联系 HumanSignal 客户经理启用。
Features区域仅 Owner 可更新或申请，包括：
| 功能开关 | 说明 |
|---|---|
| Invite external annotators to projects | 启用后，可向承包商/合作伙伴发送邮件邀请，授予其项目级访问权限（Annotator 角色）。禁用时，只能将已有组织成员加入项目，新用户需通过常规方式（如 SSO/SCIM）开通 |
| Access to Activity Log | 组织是否可访问活动日志 |
| Prompts | 组织是否可使用 Prompts 功能 |
| Whitelabel | 是否启用白标（whitelabeling） |
| Plugins | 组织是否可访问插件；启用后还可决定 Manager 角色能否创建和更新插件 |
| Early Adopter | 提前体验尚未公开发布的新功能 |
| Enable Storage Proxy | 允许 Label Studio 代理云端存储数据（Pre-signed URLs 与 Storage proxies 的对比见 storage 文档） |
| Enable AI Features | 为标注界面配置启用 AI Assistant |
| Enable Ask AI | 为通用 Label Studio 帮助启用 AI Assistant |
邮件通知设置
该区域决定用户在Account & Settings页面可见的邮件偏好选项。需要注意：
- 新用户的邮件偏好默认启用；
- 若在此处禁用某类通知，该偏好将从所有用户的Account and Settings页面隐藏，并对组织内所有用户生效；
- 若重新启用，该偏好会重新出现在用户的设置页中，并恢复为禁用前用户各自的状态。
企业版计费常见问题
- 套餐失效后会怎样？订阅到期或取消后，无法再执行标注、审核标注或向组织添加新用户，但仍可登录并导出已完成的标注。
- 活跃用户超出限制会怎样？需要购买额外席位。用户被分配角色即视为活跃用户；已受邀但未接受邀请的用户显示为 "Not activated"，不计入席位上限。
Label Studio Starter Cloud 的 Usage & Billing
Starter Cloud 拥有独立的Usage & Billing页面（仅组织 Owner 可访问），订阅包含两部分：
- 基础订阅（Base subscription）：包含 1 个席位；
- 附加席位（Additional seats）：可按需购买最多 11 个附加席位（总计 12 个）。
添加席位：Owner 进入Organization > Usage & Billing，点击Manage Seats增加席位数量。加购费用按比例分摊并体现在下一张发票中。
移除席位：必须先停用相关用户（Organization > Members 页面将用户角色设为Deactivated），再点击Manage Seats减少席位，因为活跃用户数不能超过席位数。
取消与续订：Owner 在Usage & Billing点击Cancel取消；取消后账户在付费周期结束前仍可完整使用全部功能，但无法添加席位；周期结束后仍可访问 Label Studio 并下载数据，但无法导入新数据、标注现有数据或创建新项目。不取消则自动续订。升级到 Enterprise 需联系销售。
访问令牌：Personal Access Token 与 Legacy Token 的完整用法
Label Studio 的访问令牌（Access Token）即通常所说的 "API keys"，用于与 Label Studio API 和 SDK 交互，分为两类：
| 对比维度 | Personal Access Token (PAT) | Legacy Token |
|---|---|---|
| 有效期 | 可在组织级别设置 TTL（Enterprise 独有） | 永不过期 |
| 可见性 | 仅创建时可见一次 | 一直列在账户设置中 |
| 令牌类型 | JWT refresh token | 普通令牌 |
| 吊销方式 | 可手动吊销 | 可手动吊销 |
| HTTP API 使用 | 需额外步骤换取短期 access token，请求头Authorization: Bearer <token> | 直接使用，请求头Authorization: Token <token> |
| SDK 使用 | 只需设置一次 | 只需设置一次 |
术语说明：Label Studio 中的 "access tokens" 与 "API keys" 含义相同，可互换使用。
查找与启用访问令牌
点击右上角用户图标，选择Account & Settings即可查看自己的 API keys。如果看不到Personal Access Tokens或Legacy Tokens页面，说明组织尚未启用对应令牌类型。
启用路径：进入Organization页面，选择Settings > Access Token Settings（Enterprise 中 Organization 页面仅对 Admin 和 Owner 角色可用）。在此可以启用/禁用令牌类型：
- 某类令牌被禁用后，现有该类令牌将无法再通过 Label Studio 平台认证；
- Enterprise 可使用Personal Access Token Time-to-Live为个人访问令牌设置过期时间。
在源码层面，令牌能力由label_studio/jwt_auth应用承载：models.py 中的JWTSettings模型（含api_tokens_enabled等开关）控制组织级令牌启用状态；LSAPIToken 扩展了 JWTRefreshToken以支持组织相关的令牌签发，并提供blacklist()手动吊销能力；middleware.py 中的JWTAuthenticationMiddleware负责识别携带 Bearer JWT 令牌的请求。
通过 SDK 使用令牌
Personal Access Token 可直接写在脚本中，或通过LABEL_STUDIO_API_KEY环境变量注入。Legacy Token 与 PAT 在 Python SDK 中的用法完全相同：
# Define the URL where Label Studio is accessible and the API key for your user account LABEL_STUDIO_URL = 'http://localhost:8080' # API key can be either your PAT or legacy access token LABEL_STUDIO_API_KEY = 'your-token' # Import the SDK and the client module from label_studio_sdk import LabelStudio # Connect to the Label Studio API client = LabelStudio(base_url=LABEL_STUDIO_URL, api_key=LABEL_STUDIO_API_KEY)通过 HTTP API 使用 PAT
由于 PAT 本质是 JWT refresh token，必须先用它换取一个短期的 access token，再用该 token 认证 API 请求：
curl -X POST <your-label-studio-url>/api/token/refresh \ -H "Content-Type: application/json" \ -d '{"refresh": "your-personal-access-token"}'响应为如下 JSON：
{ "access": "your-new-access-token" }之后在 API 请求中通过Authorization: Bearer头携带该 access token：
curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Bearer your-new-access-token'access token 大约5 分钟后过期，过期后请求返回 401，需要使用 PAT 重新换取。该机制为 API 认证增加了一层额外的安全保障。还可通过如下脚本预判令牌过期时间（需先pip install pyjwt）：
from datetime import datetime, timezone import jwt decoded = jwt.decode(token) exp = decoded.get("exp") token_is_expired = (exp <= datetime.now(timezone.utc).timestamp())通过 HTTP API 使用 Legacy Token
Legacy Token 一般不如 PAT 安全（需手动吊销），但无需刷新即可直接使用，请求头格式与 PAT 不同：
curl -X <method> <Label Studio URL>/api/<endpoint> -H 'Authorization: Token <token>'Model Providers：组织级模型提供商配置
使用组织内的某些 AI 功能前，必须先在Organization > Settings配置模型提供商。例如，要在标注界面使用<Chat>标签 与 LLM 交互，就必须先配置模型访问。
注意：这些模型不用于 Label Studio 的 AI Assistant。
访问权限与网络白名单
配置完成后，组织内所有使用 AI 工作流的用户都可以调用这些模型提供商；但只有可访问组织设置的 Owner 和 Admin 能添加和配置模型。若你的网络环境限制了出站访问，可能需要将 HumanSignal 的 IP 地址加入白名单（见 SaaS 出站连接 IP 地址）。
两种接入方式
方式一：每个组织一个提供商连接，可访问一组白名单模型。典型代表：
- OpenAI
- Vertex AI
- Gemini
- Anthropic
方式二：每个模型单独添加一个 API key。典型代表：
- Azure OpenAI
- Azure AI Foundry
- Custom（自定义）
支持的模型
| 提供商 | 支持的模型 |
|---|---|
| OpenAI | gpt-5-2、gpt-5.1、gpt-5、gpt-5-mini、gpt-5-nano |
| Gemini | gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite、gemini-2.0-flash、gemini-2.0-flash-lite |
| Vertex AI | gemini-2.5-pro、gemini-2.5-flash、gemini-2.5-flash-lite、gemini-2.0-flash、gemini-2.0-flash-lite |
| Anthropic | claude-3-5-haiku-latest、claude-3-5-sonnet-latest、claude-3-7-sonnet-latest |
| Azure OpenAI | Azure OpenAI chat 系列模型（不推荐 GPT 3.5：容易出现限流错误且不兼容图像数据） |
| Azure AI Foundry | 支持全部 Azure AI Foundry 模型 |
| Custom | 自定义 LLM |
如果此前已为 Prompts 配置过模型提供商，它们会自动同步为组织级提供商。
各提供商配置要点
OpenAI / Gemini / Vertex AI / Anthropic（组织级单 key）：每个组织每种提供商只能有一个 key，对应一组白名单模型。Vertex AI 必须提供 JSON 格式的 credentials 文件，可选择性提供 GCP 环境关联的 project ID 与 location。
Azure OpenAI（按模型部署添加 key）：每个 Azure key 绑定一个特定 deployment，而每个 deployment 只包含一个模型。如需使用多个模型，必须为每个模型创建 deployment 并分别添加 key。添加时需提供：
| 字段 | 说明 |
|---|---|
| Deployment | 部署名称。默认与模型名相同，但创建时可自定义；若两者不同，必须使用 deployment 名称而非底层模型名 |
| Endpoint | Azure 提供的目标 URI |
| API key | Azure 提供的密钥 |
以上信息均可在 Azure OpenAI Studio 中对应 deployment 的Details部分找到。
Azure AI Foundry：通过模型目录部署模型后，在部署模型的 Details 页面Endpoint区域获取连接信息，添加时提供：
| 字段 | 说明 |
|---|---|
| Model | 模型名称（作为参数随 Endpoint 信息提供） |
| Endpoint | AI Foundry 提供的Target URI |
| API key | AI Foundry 提供的Key |
Custom LLM（自定义模型）：可使用自托管或微调模型，前提是满足两个条件：
- 服务器必须支持 LLM 的JSON mode——API 须接受
response_format参数（type: json_object）并附带合法 JSON schema：{"response_format": {"type": "json_object", "schema": <schema>}}； - 服务器 API 必须遵循OpenAI 格式（chat/completions 的
response_format）。
兼容示例包括 Ollama 与 sglang 的 OpenAI 兼容 API。添加自定义模型需填写：模型名称、端点 URL（如https://my.openai.endpoint.com/v1）、API key（可选，绑定账户、组织内共享访问）以及 Auth token（可选，提供服务器级 API 访问）。
Ollama 配置示例：
- 启动 Ollama：
ollama run llama3.2； - 验证本地 OpenAI 兼容 API 可用（如
http://localhost:11434/v1）； - 创建对外端点（如
https://my.openai.endpoint.com/v1→http://localhost:11434/v1）； - 在 Label Studio 中添加连接：Name 填
llama3.2（须与 Ollama 中的模型名一致）、Endpoint 填https://my.openai.endpoint.com/v1（v1后缀必填）、API key 填ollama（默认）、Auth token 留空。
Hugging Face Inference Endpoints 示例：
- 选用 DeepSeek 模型（如
deepseek-ai/DeepSeek-R1）； - 在 API Keys 中添加到 Custom provider：Name 填
deepseek-ai/DeepSeek-R1、Endpoint 填https://router.huggingface.co/together/v1、API key 填自己的 HF key、Auth token 留空。
Permissions：自定义组织权限
Permissions页面仅对 Owner 角色可见，用于为各角色细粒度定制权限。要点如下：
- Owner 角色的权限不可配置；
- 可对哪些角色能执行哪些动作进行更精细的控制；
- 任何限制都会同样作用于 API——例如限制 Manager 配置云存储，则 Manager 无法通过 UI 或 API 完成该操作。
可配置的权限及其默认角色如下：
| 权限 | 默认角色 |
|---|---|
| Invite members to organization | Manager+ |
| Create API Tokens | 所有角色 |
| Edit Plugins | Manager+ |
| Manage Cloud Storage | Manager+ |
| Manage Webhooks | Manager+ |
| Access Project Dashboard | Manager+ |
| Access Member Performance Dashboard | 所有角色 |
| Access Project Members Dashboard | Manager+ |
| Use AI Assistant | Manager+ |
| Delete Tasks | Manager+ |
| Reset Project Cache | Manager+ |
| Drop All Tabs | Manager+ |
| Delete Project | Manager+ |
补充说明：Annotator、Reviewer、Manager 的权限本身已局限于其创建的项目（Manager）或被显式授予访问权限的项目，详见 Project setup。页面上提供Reset to Defaults按钮，可一键将所有权限恢复默认值。角色与默认权限的完整矩阵见 User roles and permissions。
Support Reports：匿名化支持报告（Beta）
Support Reports 提供了一种安全、低门槛的方式，让 HumanSignal 团队了解 Label Studio Enterprise 部署内部的实际运行状况。报告汇总匿名化的运维指标与环境细节，用于：
- 理解用户实际遇到的困难；
- 发现瓶颈与配置问题；
- 给出具体的工作流与性能优化建议；
- 为产品团队的功能优先级提供依据。
生成报告
- 进入Organization > Settings > Support Reports；
- 在Reports下点击Generate New Report；
- 报告状态在Pending → Running → Completed之间流转。对于数据量大的组织，生成可能耗时数分钟。
报告完成后，可通过操作图标：直接下载 ZIP 检查内容，或触发邮件投递。
注意：要下载 ZIP 文件，必须已配置持久化存储。生成支持报告时，Label Studio 会先将报告产物持久化到所配置的存储后端，然后才可下载。未配置持久化存储或凭据无效时，下载 ZIP 会报错。
配置自动投递
可在设置中指定报告自动发送到的邮箱地址（多个地址用逗号分隔）。可以为每份新生成的报告自动开启邮件投递，也可以手动在Reports区域的操作中触发。
报告包含的信息
报告兼顾调试与规划价值，同时保持安全可共享：
- 运维指标与使用模式：如项目与任务量、队列大小与处理速率、常见标注操作与功能使用情况；
- 环境画像：部署类型（云/本地）、Label Studio 与 Enterprise 版本、所连接服务（数据库、存储后端）的类型与配置开关级别信息——不含凭据。
报告本质上是一个包含 JSON 文档的 ZIP 文件，可本地打开、喂给内部工具链，或直接附在工单中。
隐私与安全
报告设计上刻意保守：
- 不含原始任务数据与标注：绝不包含标签文本、文档、图片、音频、标注 payload 或其他标注数据；
- 不含 PII：无标签文本、图片、音频、用户名，只有聚合与匿名化统计；
- 配置不含机密：环境细节关注“启用了什么、如何配置”，不含凭据、密钥或专有 URL；
- 共享由你决定：报告在部署内生成，可自行下载检查 JSON，再决定是否以及如何与 HumanSignal 共享。
如需更严格的管控（如内部审查与审批流程），支持报告天然适配：纯 JSON + ZIP、按需生成、完全可由安全与合规团队检查。
何时生成报告
建议在以下场景生成支持报告：
- 提交支持工单时——涉及性能问题（队列慢、超时、UI 卡顿）、难以复现的错误、复杂项目或工作流中的不明确行为；
- 规划扩容或迁移时——迁移到更大数据集、新增团队或项目、收紧标注交付 SLA；
- 想做部署健康检查时——是否高效使用 Label Studio、工作流是否符合最佳实践。
多数情况下，在初始工单中附上一份最新的支持报告，可以直接跳过若干诊断步骤，快速进入修复与优化建议阶段。
总结：组织级管理的实施要点
围绕 Organization settings 这一入口，Label Studio 的组织级管理可以归结为三条主线：合规与安全（通过 Usage & License 中的会话超时、SSO、令牌 TTL 与 Permissions 的细粒度控制）、AI 能力接入（通过 Model Providers 统一配置 LLM 供 Chat 标签与 Prompts 使用）、以及可观测性（通过 Support Reports 与 Activity Log 掌握部署状态）。这些配置不仅作用于 UI，也完整地反映在 API 与 SDK 访问路径上——例如label_studio/session_policy与label_studio/jwt_auth两个 Django 应用即为会话超时策略与 JWT 令牌机制的直接实现。管理员可以按照本文的路径逐项核对组织设置，确保席位合规、令牌策略合理、AI 提供商可用，并能在出现问题时快速产出可供支持团队直接分析的报告。
【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
