Label Studio Enterprise Embed 集成指南JWT 授权、Embed SDK 接入与排障实战【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio Enterprise 的 Embed 能力允许你将标注Labeling与审核Review功能无缝嵌入到自有应用页面中让终端用户无需离开你的产品即可完成数据标注工作流。本文以docs/source/guide/embed.md为骨架结合仓库源码如 JWT 认证中间件、JWT 配置模型 与 前端参考文档深入讲解授权握手、JWT 签发、Embedding 配置、Embed SDK 页面搭建与常见故障排查读完即可在自己的应用里落地一个可用的嵌入标注工作台。注意Embed 属于 Label Studio EnterpriseLSE功能并非所有客户默认可用需联系你的 HumanSignal 客户经理开通。开始前的准备工作集成 Embed 前需要同时在 Label Studio 侧与你的外部应用侧完成如下准备Label StudioLSE侧你的账户必须拥有Owner所有者角色进入Organization Settings Access Token Settings确保「legacy API tokens」或「个人访问令牌access tokens」中至少启用一项。这是因为 Embed 流程最终会由 Label Studio 签发自己的内部令牌该内部令牌的可用性依赖于组织级的令牌策略开关详见下文源码解析。你的外部应用侧后端服务器具备访问 LSE 后端的能力用于生成签名令牌确定 Embed 将要托管的前端页面 URL该域名后续需要登记到 LSE 的 Supported Domains。授权机制一次安全的 JWT 握手Embed 的整体流程可以理解为你自己的应用与 Label Studio Enterprise 之间的一次安全握手用户在你的外部应用中完成登录你的后端使用自己的私钥签发一个包含user_email与organization_id的 JWT你的前端使用id、url、token三个参数初始化 Label Studio EmbedLabel Studio 用你配置的公钥验证 JWT 合法性验证通过后签发它自己的内部令牌随后标注/审核功能即可正常使用。从源码看LSE 内部对 JWT 的身份识别走的是 jwt_auth 中间件当请求携带Authorization: Bearer token且令牌符合 JWT 结构通过 is_jwt_formatted 判定该函数仅解析结构、不验签时中间件会用rest_framework_simplejwt完成认证并在组织开启 JWT 令牌后把用户挂载到请求上。同时令牌中的embed_project_idclaim 会被提取为request.embed_project_id用于把嵌入会话限定到具体项目作用域。因此Embed 的整个鉴权链路是外部 JWT验证身份→ LSE 签发内部令牌承载授权→ 项目级作用域控制数据访问。在服务端生成 JWT开始集成前你需要生成两类关键凭证JWT用于认证 Label StudioBase64-URL 编码的公钥用于添加进 Label Studio 的组织配置Public Verification Key。JWT 必须包含以下 claims{ user_email: userexample.com, organization_id: 12345, iat: 1692445200, // (可选) 签发时间戳 exp: 1692452400 // (可选) 过期时间戳 }要点说明organization_id可以在 Label Studio 的Organization页面找到示例使用 RS256 作为验证算法完整支持的算法列表可以在Organization Usage License Embedding页面查看公钥必须以base64-url 编码格式存储在 Label Studio 中。Node.js 签发示例jsonwebtokenconst jwt require(jsonwebtoken); const fs require(fs); const privateKey fs.readFileSync(./private.pem); const token jwt.sign( { user_email: userexample.com, organization_id: 12345, }, privateKey, { algorithm: RS256, expiresIn: 1h } ); console.log(token);在仓库后端实现中LSE 自身的 API 令牌也是基于 JWT 的LSAPIToken类扩展了rest_framework_simplejwt的RefreshToken见 jwt_auth/models.py其默认生命周期长达 200 年约等于永久且通过自定义的LSTokenBackend将令牌的签名部分截断后再存储避免把签名暴露给前端。这说明该组织内部令牌体系与你在服务端签发的 RS256 外部 JWT 是两套独立机制——外部 JWT 只负责「你是谁」内部令牌才负责「你能访问什么」。在 Label Studio 中配置 Embedding进入Organization Usage License Embedding完成以下字段字段说明Supported domains登记你的外部应用域名列表只有这些域名上的嵌入页面才会被信任Public Verification Key必须使用 base64-url 编码的公钥Public Verification Algorithms创建密钥时使用的算法如 RS256Embed SDK需要添加到你的应用中用于初始化嵌入的 SDK 脚本地址其中「Supported domains」与「Public Verification Key/Algorithm」共同构成了信任边界域名白名单防止其他站点冒用你的嵌入页面公钥则让 LSE 能够验证你后端签发的 JWT 签名二者缺一不可。在你的外部应用中搭建嵌入页面至少需要在应用的一个 HTML 页面中加入Embed SDK脚本script srchttps://app.humansignal.com/react-app/embed-sdk.js/script为了最大化嵌入体验你还可以结合 前端参考文档 引入更多 Label Studio 前端元素如config、interfaces、user、事件系统等并根据业务需要定制界面。完整示例页面html body !-- Embed 出口WebComponent -- label-studio-embed idembed-1/label-studio-embed !-- 引入 EmbedSDK 脚本 -- script srchttps://app.humansignal.com/react-app/embed-sdk.js/script !-- 实现示例 -- script // 初始化 Label Studio Embed SDK const sdk LabelStudioEmbedSDK.create({ id: embed-1, // 对应 label-studio-embed WebComponent 的 id作为嵌入出口 url: https://app.humansignal.com, // 目标 LabelStudioEnterprise 实例地址 token: signed-jwt-of-current-user, // 使用与组织配置的公钥配对的私钥签发的 JWT // 结构为 {user_email: targetuseremail.com, organization_id: yourlseorg_id:int} mode: label // 以标注为目的为用户加载任务与标注并提供预配置界面 }); // 监听 ready 事件每次带任务加载完成后触发一次 sdk.on(ready, () { console.log(LSE Embed - SDK ready for task); }); // 监听 error 事件 sdk.on(error, (error) { console.error(LSE Embed - SDK error:, error); }); // 监听任务加载事件 sdk.on(taskLoad, (task) { console.error(LSE Embed - Task load:, task); }); // 监听标注选中切换/加载标注事件 sdk.on(selectAnnotation, (annotation) { console.error(LSE Embed - Annotation select:, annotation); }); // 监听实体区域/标签数据创建事件 sdk.on(entityCreate, (entity) { console.log(LSE Embed - Entity create:, entity); }); // 监听实体区域/标签数据删除事件 sdk.on(entityDelete, (entity) { console.log(LSE Embed - Entity delete:, entity); }); // 监听标注提交事件 sdk.on(submitAnnotation, (annotation) { console.log(LSE Embed - Annotation submitted:, annotation); }); // 监听标注更新事件 sdk.on(updateAnnotation, (annotation) { console.log(LSE Embed - Annotation updated:, annotation); }); // 设置选项 // 例按任务 id 加载任务LSE 任务 id用户必须有权访问该任务 // 否则会抛出 403 授权错误 sdk.setOptions({ taskId: 1 }); // 若该用户存在标注则加载其最近的标注 // 例按任务 id 与标注 id 选中标注LSE 标注 id无权限会抛 403 sdk.setOptions({ taskId: 1, annotationId: 2 }); // 找到并加载该标注 // 例按任务 id 与预测 id 选中预测LSE 预测 id无权限会抛 403 sdk.setOptions({ taskId: 1, predictionId: 3 }); // 找到并加载该预测 // 例切换嵌入实例的主题配色 sdk.setOptions({ colorScheme: dark }); // 可选 dark、light 或 auto /script /body /html初始化参数与 setOptions 速查参数用途id对应label-studio-embedWebComponent 的 id即嵌入出口url目标 Label Studio Enterprise 实例地址token使用与组织公钥配对的私钥签发的 JWTmode加载模式如label标注模式加载任务与预配置界面taskId指定要加载的 LSE 任务 idannotationId指定要选中的 LSE 标注 id需与 taskId 组合predictionId指定要选中的 LSE 预测 id需与 taskId 组合colorScheme主题配色dark/light/autoSDK 事件一览SDK 采用事件驱动模型与 前端参考文档 中 LSF 的内置事件系统一脉相承。可监听的事件包括ready嵌入组件随某个任务完整加载后触发errorSDK 运行出错时触发回调携带错误对象taskLoad任务加载完成selectAnnotation标注被选中切换/加载标注entityCreate实体区域/标签数据被创建entityDelete实体被删除submitAnnotation标注被提交updateAnnotation标注被更新。这些事件回调可以帮助你在宿主应用中同步数据状态、埋点统计或触发后续业务逻辑。若需要更细粒度的前端控制例如通过interfaces数组控制撤销/重做/提交/跳过按钮、通过onSubmitAnnotation等回调感知操作结果可继续阅读 前端参考文档。Troubleshooting 排障指南白屏 / 空白页面出现空白页面时按以下顺序排查你的域名没有列入 Label Studio 的Supported DomainsPublic Verification Key配置错误或缺失Public Verification Algorithms配置错误或缺失外部 JWT 验证失败一个或多个 claims 校验未通过无效 JWT用户当前的活动组织active organization与 JWT claims 中声明的组织不一致组织未启用 legacy API tokens 或个人访问令牌至少需要启用一项JWT 中user_email对应的用户在 Label Studio Enterprise 中不存在。SDK 中的 HTTP 错误403权限错误常见于用户不是该 Project 的成员任务未分配给该用户却尝试加载该任务用户对该标注或预测没有访问权限却尝试加载它。404任务未找到Task not found。其他非 HTTP 错误系统中出现逻辑性问题导致加载失败。从代码实现看403/404 的判定链与 jwt_auth 中间件 的项目作用域机制直接相关JWT 通过embed_project_idclaim 限定嵌入会话可访问的项目范围而任务、标注、预测的访问还叠加了项目成员关系与分配关系assignment的权限校验。因此排障时应同时核对JWT claims 中的organization_id与用户实际所属组织、embed_project_id指向的项目以及用户在该项目中的成员/分配关系是否一致。小结Label Studio Enterprise Embed 是一条「外部 JWT 验身份 内部令牌授权限 项目作用域控数据」的完整安全链路先在服务端用私钥签发包含user_email与organization_id的 JWT再把 base64-url 编码的公钥与算法配置到 LSE 组织设置中前端通过label-studio-embedWebComponent 与 Embed SDK 完成初始化、事件监听与setOptions动态切换任务/标注/预测/主题。遇到白屏优先检查域名白名单、公钥算法与 JWT claims 一致性遇到 403 则重点核对项目成员关系与任务分配关系。按上述步骤配置完成后你的应用即可获得与 LSE 原生界面一致的标注与审核体验。【免费下载链接】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），仅供参考 Label Studio Enterprise Embed 集成指南：JWT 授权、Embed SDK 接入与排障实战
Label Studio Enterprise Embed 集成指南JWT 授权、Embed SDK 接入与排障实战【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studioLabel Studio Enterprise 的 Embed 能力允许你将标注Labeling与审核Review功能无缝嵌入到自有应用页面中让终端用户无需离开你的产品即可完成数据标注工作流。本文以docs/source/guide/embed.md为骨架结合仓库源码如 JWT 认证中间件、JWT 配置模型 与 前端参考文档深入讲解授权握手、JWT 签发、Embedding 配置、Embed SDK 页面搭建与常见故障排查读完即可在自己的应用里落地一个可用的嵌入标注工作台。注意Embed 属于 Label Studio EnterpriseLSE功能并非所有客户默认可用需联系你的 HumanSignal 客户经理开通。开始前的准备工作集成 Embed 前需要同时在 Label Studio 侧与你的外部应用侧完成如下准备Label StudioLSE侧你的账户必须拥有Owner所有者角色进入Organization Settings Access Token Settings确保「legacy API tokens」或「个人访问令牌access tokens」中至少启用一项。这是因为 Embed 流程最终会由 Label Studio 签发自己的内部令牌该内部令牌的可用性依赖于组织级的令牌策略开关详见下文源码解析。你的外部应用侧后端服务器具备访问 LSE 后端的能力用于生成签名令牌确定 Embed 将要托管的前端页面 URL该域名后续需要登记到 LSE 的 Supported Domains。授权机制一次安全的 JWT 握手Embed 的整体流程可以理解为你自己的应用与 Label Studio Enterprise 之间的一次安全握手用户在你的外部应用中完成登录你的后端使用自己的私钥签发一个包含user_email与organization_id的 JWT你的前端使用id、url、token三个参数初始化 Label Studio EmbedLabel Studio 用你配置的公钥验证 JWT 合法性验证通过后签发它自己的内部令牌随后标注/审核功能即可正常使用。从源码看LSE 内部对 JWT 的身份识别走的是 jwt_auth 中间件当请求携带Authorization: Bearer token且令牌符合 JWT 结构通过 is_jwt_formatted 判定该函数仅解析结构、不验签时中间件会用rest_framework_simplejwt完成认证并在组织开启 JWT 令牌后把用户挂载到请求上。同时令牌中的embed_project_idclaim 会被提取为request.embed_project_id用于把嵌入会话限定到具体项目作用域。因此Embed 的整个鉴权链路是外部 JWT验证身份→ LSE 签发内部令牌承载授权→ 项目级作用域控制数据访问。在服务端生成 JWT开始集成前你需要生成两类关键凭证JWT用于认证 Label StudioBase64-URL 编码的公钥用于添加进 Label Studio 的组织配置Public Verification Key。JWT 必须包含以下 claims{ user_email: userexample.com, organization_id: 12345, iat: 1692445200, // (可选) 签发时间戳 exp: 1692452400 // (可选) 过期时间戳 }要点说明organization_id可以在 Label Studio 的Organization页面找到示例使用 RS256 作为验证算法完整支持的算法列表可以在Organization Usage License Embedding页面查看公钥必须以base64-url 编码格式存储在 Label Studio 中。Node.js 签发示例jsonwebtokenconst jwt require(jsonwebtoken); const fs require(fs); const privateKey fs.readFileSync(./private.pem); const token jwt.sign( { user_email: userexample.com, organization_id: 12345, }, privateKey, { algorithm: RS256, expiresIn: 1h } ); console.log(token);在仓库后端实现中LSE 自身的 API 令牌也是基于 JWT 的LSAPIToken类扩展了rest_framework_simplejwt的RefreshToken见 jwt_auth/models.py其默认生命周期长达 200 年约等于永久且通过自定义的LSTokenBackend将令牌的签名部分截断后再存储避免把签名暴露给前端。这说明该组织内部令牌体系与你在服务端签发的 RS256 外部 JWT 是两套独立机制——外部 JWT 只负责「你是谁」内部令牌才负责「你能访问什么」。在 Label Studio 中配置 Embedding进入Organization Usage License Embedding完成以下字段字段说明Supported domains登记你的外部应用域名列表只有这些域名上的嵌入页面才会被信任Public Verification Key必须使用 base64-url 编码的公钥Public Verification Algorithms创建密钥时使用的算法如 RS256Embed SDK需要添加到你的应用中用于初始化嵌入的 SDK 脚本地址其中「Supported domains」与「Public Verification Key/Algorithm」共同构成了信任边界域名白名单防止其他站点冒用你的嵌入页面公钥则让 LSE 能够验证你后端签发的 JWT 签名二者缺一不可。在你的外部应用中搭建嵌入页面至少需要在应用的一个 HTML 页面中加入Embed SDK脚本script srchttps://app.humansignal.com/react-app/embed-sdk.js/script为了最大化嵌入体验你还可以结合 前端参考文档 引入更多 Label Studio 前端元素如config、interfaces、user、事件系统等并根据业务需要定制界面。完整示例页面html body !-- Embed 出口WebComponent -- label-studio-embed idembed-1/label-studio-embed !-- 引入 EmbedSDK 脚本 -- script srchttps://app.humansignal.com/react-app/embed-sdk.js/script !-- 实现示例 -- script // 初始化 Label Studio Embed SDK const sdk LabelStudioEmbedSDK.create({ id: embed-1, // 对应 label-studio-embed WebComponent 的 id作为嵌入出口 url: https://app.humansignal.com, // 目标 LabelStudioEnterprise 实例地址 token: signed-jwt-of-current-user, // 使用与组织配置的公钥配对的私钥签发的 JWT // 结构为 {user_email: targetuseremail.com, organization_id: yourlseorg_id:int} mode: label // 以标注为目的为用户加载任务与标注并提供预配置界面 }); // 监听 ready 事件每次带任务加载完成后触发一次 sdk.on(ready, () { console.log(LSE Embed - SDK ready for task); }); // 监听 error 事件 sdk.on(error, (error) { console.error(LSE Embed - SDK error:, error); }); // 监听任务加载事件 sdk.on(taskLoad, (task) { console.error(LSE Embed - Task load:, task); }); // 监听标注选中切换/加载标注事件 sdk.on(selectAnnotation, (annotation) { console.error(LSE Embed - Annotation select:, annotation); }); // 监听实体区域/标签数据创建事件 sdk.on(entityCreate, (entity) { console.log(LSE Embed - Entity create:, entity); }); // 监听实体区域/标签数据删除事件 sdk.on(entityDelete, (entity) { console.log(LSE Embed - Entity delete:, entity); }); // 监听标注提交事件 sdk.on(submitAnnotation, (annotation) { console.log(LSE Embed - Annotation submitted:, annotation); }); // 监听标注更新事件 sdk.on(updateAnnotation, (annotation) { console.log(LSE Embed - Annotation updated:, annotation); }); // 设置选项 // 例按任务 id 加载任务LSE 任务 id用户必须有权访问该任务 // 否则会抛出 403 授权错误 sdk.setOptions({ taskId: 1 }); // 若该用户存在标注则加载其最近的标注 // 例按任务 id 与标注 id 选中标注LSE 标注 id无权限会抛 403 sdk.setOptions({ taskId: 1, annotationId: 2 }); // 找到并加载该标注 // 例按任务 id 与预测 id 选中预测LSE 预测 id无权限会抛 403 sdk.setOptions({ taskId: 1, predictionId: 3 }); // 找到并加载该预测 // 例切换嵌入实例的主题配色 sdk.setOptions({ colorScheme: dark }); // 可选 dark、light 或 auto /script /body /html初始化参数与 setOptions 速查参数用途id对应label-studio-embedWebComponent 的 id即嵌入出口url目标 Label Studio Enterprise 实例地址token使用与组织公钥配对的私钥签发的 JWTmode加载模式如label标注模式加载任务与预配置界面taskId指定要加载的 LSE 任务 idannotationId指定要选中的 LSE 标注 id需与 taskId 组合predictionId指定要选中的 LSE 预测 id需与 taskId 组合colorScheme主题配色dark/light/autoSDK 事件一览SDK 采用事件驱动模型与 前端参考文档 中 LSF 的内置事件系统一脉相承。可监听的事件包括ready嵌入组件随某个任务完整加载后触发errorSDK 运行出错时触发回调携带错误对象taskLoad任务加载完成selectAnnotation标注被选中切换/加载标注entityCreate实体区域/标签数据被创建entityDelete实体被删除submitAnnotation标注被提交updateAnnotation标注被更新。这些事件回调可以帮助你在宿主应用中同步数据状态、埋点统计或触发后续业务逻辑。若需要更细粒度的前端控制例如通过interfaces数组控制撤销/重做/提交/跳过按钮、通过onSubmitAnnotation等回调感知操作结果可继续阅读 前端参考文档。Troubleshooting 排障指南白屏 / 空白页面出现空白页面时按以下顺序排查你的域名没有列入 Label Studio 的Supported DomainsPublic Verification Key配置错误或缺失Public Verification Algorithms配置错误或缺失外部 JWT 验证失败一个或多个 claims 校验未通过无效 JWT用户当前的活动组织active organization与 JWT claims 中声明的组织不一致组织未启用 legacy API tokens 或个人访问令牌至少需要启用一项JWT 中user_email对应的用户在 Label Studio Enterprise 中不存在。SDK 中的 HTTP 错误403权限错误常见于用户不是该 Project 的成员任务未分配给该用户却尝试加载该任务用户对该标注或预测没有访问权限却尝试加载它。404任务未找到Task not found。其他非 HTTP 错误系统中出现逻辑性问题导致加载失败。从代码实现看403/404 的判定链与 jwt_auth 中间件 的项目作用域机制直接相关JWT 通过embed_project_idclaim 限定嵌入会话可访问的项目范围而任务、标注、预测的访问还叠加了项目成员关系与分配关系assignment的权限校验。因此排障时应同时核对JWT claims 中的organization_id与用户实际所属组织、embed_project_id指向的项目以及用户在该项目中的成员/分配关系是否一致。小结Label Studio Enterprise Embed 是一条「外部 JWT 验身份 内部令牌授权限 项目作用域控数据」的完整安全链路先在服务端用私钥签发包含user_email与organization_id的 JWT再把 base64-url 编码的公钥与算法配置到 LSE 组织设置中前端通过label-studio-embedWebComponent 与 Embed SDK 完成初始化、事件监听与setOptions动态切换任务/标注/预测/主题。遇到白屏优先检查域名白名单、公钥算法与 JWT claims 一致性遇到 403 则重点核对项目成员关系与任务分配关系。按上述步骤配置完成后你的应用即可获得与 LSE 原生界面一致的标注与审核体验。【免费下载链接】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），仅供参考