使用 Corsair 的 Scale AI 插件让 Agent 直接编排数据标注任务与 Studio 工作流【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsaircorsair-dev/scaleai是 Corsair 生态中面向 Scale AI 为主线结合该插件在仓库中的源码实现index.ts、client.ts、error-handlers.ts 及 endpoints/ 各文件完整讲解安装接入、认证方式、全部操作分组、参数细节与错误处理策略读完后你可以让 Agent 自主完成从导入文件、创建标注任务、跟踪批次进度到管理 Studio 分配与批次优先级的完整闭环。插件概览与安装Scale AI 提供的是人工标注 / 数据标注 API你上传图片、视频、LiDAR 点云、文本或文档由标注人员按你定义的标签体系完成任务。Corsair 的 scaleai 插件把这些 REST 能力折叠进corsair的插件体系中使 LLM Agent 可以通过统一、经过校验的端点创建和管理数据标注任务、批次、项目、文件、团队成员与 Scale Studio 分配。安装命令与 README 一致在 package.json 中包名为corsair-dev/scaleai当前版本0.1.0pnpm add corsair-dev/scaleai该包以corsair与zod作为 peerDependencies见 package.json 的peerDependencies字段corsair 0.1.0、zod ^4.1.13因此你项目中必须已经安装了 Corsair 核心与 Zod 4插件才能正常工作。快速接入在 Corsair 中注册插件在createCorsair的plugins数组中注册scaleai()即可README 给出了最小示例import { createCorsair } from corsair; import { scaleai } from corsair-dev/scaleai; export const corsair createCorsair({ plugins: [ scaleai({ key: process.env.SCALE_API_KEY }), ], });scaleai()工厂函数接受ScaleAiPluginOptions定义见 index.ts各选项含义如下选项类型说明keystringScale AI API Keylive 或 test 模式。传入后优先于账号 Key 仓库account key store使用authTypeapi_key认证类型默认api_key插件内部用defaultAuthType兜底hooksCorsair hooks透传给插件的生命周期钩子errorHandlersCorsairErrorHandler自定义错误处理器与插件内置处理器合并后者优先级更高见 index.tspermissionsPluginPermissionsConfig插件端点权限配置注册完成后所有端点会按tasks.*、batches.*、projects.*、files.*、teams.*、studio.*、audits.*、quality.*分组挂载到 Corsair 上分组结构见 index.ts 的scaleAiEndpointsNestedAgent 即可像调用普通工具一样调用它们。认证机制HTTP Basic Auth 与 live_ / test_ 密钥README 明确说明插件使用 HTTP Basic Auth以你的 Scale API Key 作为用户名、密码为空插件已自动处理。这一点在 client.ts 中得到印证function buildAuthorizationHeader(apiKey: string): string { return Basic ${encodeBase64(${apiKey}:)}; }即最终发送的Authorization头形如Basic base64(apiKey:)冒号后为空密码。所有请求统一发往https://api.scale.com/v1常量SCALEAI_API_BASE见 client.ts且只支持v1。关于密钥模式README 提醒使用live_前缀的 Key 会创建真实计费任务使用test_前缀的 Key 则进入测试模式。开发阶段务必先用test_Key避免误产生账单。Key 的解析顺序keyBuilder见 index.ts决定了密钥的来源优先级调用端点时若options.key存在直接使用该 Key否则从 Corsair 的账号 Key 仓库读取api_keyctx.keys.get_api_key()两者都取不到时抛出AuthMissingError(scaleai, api_key)提醒你需要配置 Key。路径安全由于任务 ID、批次名、项目名等会被拼进 URLclient.ts 的encodeScalePathSegment会拒绝空字符串、.、..等穿越段再对调用方传入的路径片段做encodeURIComponent防止路径注入。任务tasks创建、查询与维护任务组是插件最核心的部分共 18 个端点见 endpoints/tasks.ts覆盖创建、查询、标签、唯一标识、元数据、结果获取与回调重发。创建任务9 类标注任务一键创建所有任务创建端点共用一个createTaskEndpoint(taskType)工厂见 endpoints/tasks.ts统一走POST /task/{taskType}只是taskType不同端点taskTypeURL 路径适用场景createImageAnnotationTaskimageannotation图像标注框、多边形、点等createSegmentationAnnotationTasksegmentannotation语义分割逐像素分类createVideoAnnotationTaskvideoannotation跨帧 / 视频文件标注createVideoPlaybackAnnotationTaskvideoplaybackannotation视频回放物体跟踪createLidarAnnotationTasklidarannotationLiDAR 3D 立方体标注createLidarSegmentationTasklidarsegmentationLiDAR 点云语义分割createNamedEntityRecognitionTasknamedentityrecognition文本命名实体识别createTextCollectionTasktextcollection结构化字段文本采集createDocumentTranscriptionTaskdocumenttranscription文档转录 / 标注每种任务的创建输入 Schema 在 endpoints/types.ts 中共享一个TaskCreateBaseShape基座通用字段如下字段类型说明projectstring任务归属的项目名batchstring任务归属的批次名该批次必须处于未 finalize 状态callback_urlstring任务完成时通知的 URL 或邮箱instructionstringMarkdown 或 Google Doc 支持的标注说明unique_idstring你自己的标识符全局唯一跨项目与任务类型clear_unique_id_on_errorboolean任务出错时自动清除unique_idmetadataobject任意键值数据Scale 不使用仅随任务存储prioritynumber整数任务优先级数值越大越先被处理tagsstring[]官方限制每个任务最多 5 个标签各任务类型再叠加专属字段例如图像标注需要attachment文件 URL与geometries标注几何定义语义分割需要labels最多 50 个并可设置allow_unlabeled视频标注可传attachments数组与events_to_annotateNER 需要labels文本采集需要fields。所有创建 Schema 都以.catchall(z.unknown())结尾兼容 Scale 各任务类型差异巨大的参数体。一个创建图像标注任务的示例const task await corsair.scaleai.tasks.createImageAnnotationTask({ project: coco-detection, batch: batch-001, attachment: https://cdn.example.com/img/001.jpg, geometries: { type: box, label: car }, instruction: 标注所有车辆的外接框, unique_id: order-10086-001, tags: [urgent], priority: 10, });查询任务getTask({ taskId })按任务 ID 获取完整任务对象包含status、response、metadata、audits等走GET /task/{id}listTasks(input)带过滤与游标分页地列出任务走GET /tasks。listTasks的过滤参数Schema 见 endpoints/types.ts参数说明project/batch按项目 / 批次过滤type任务类型枚举imageannotation、videoannotation、lidarannotation、textcollection等 13 种见SCALE_TASK_TYPESstatuspending/completed/canceled/errorcustomer_review_statusaccepted/fixed/commented/rejected/pending支持数组unique_id/tags按唯一标识 / 标签过滤支持数组start_time/end_time、completed_after/completed_before、updated_after/updated_before时间范围ISO 8601include_attachment_url/limited_response是否包含附件 URL / 精简响应limit页大小1–100默认 100next_token上一响应返回的分页游标值得注意的实现细节toQuery见 endpoints/tasks.ts会跳过undefined/null值、把对象序列化为 JSON 字符串、数组原样保留从而支持数组参数以重复键的形式拼入查询串——这一点也被测试 api.test.ts 明确断言tagsa、tagsb同时出现在 URL 中。标签、unique_id 与元数据管理addTaskTags({ taskId, tags })PUT /task/{id}/tags已存在的标签自动忽略去重deleteTaskTags({ taskId, tags })DELETE /task/{id}/tags不存在的标签忽略updateTaskUniqueId({ taskId, unique_id })POST /task/{id}/unique_id设置或更新唯一标识deleteTaskUniqueId({ taskId })DELETE /task/{id}/unique_idsetTaskMetadata({ taskId, metadata })POST /task/{id}/setMetadata整体替换任务元数据幂等。获取标注结果与重发回调getTaskResponseUrl({ taskId, uuid })任务 JSON 中response里通常带有一个安全的response_url和对应的uuid该端点用它们换取经过认证的响应数据走GET /task/{id}/response_url/{uuid}sendTaskCallback({ taskId })对已完成或出错的任务重新发送回调通知走POST /task/{id}/send_callback。批次batches批量任务的组织单位批次用于把一批任务打包管理端点实现见 endpoints/batches.ts端点请求说明createBatchPOST /batches在项目内创建批次finalizeBatchPOST /batches/{name}/finalize定稿批次之后任务才能被标注员处理getBatchGET /batches/{name}按名称获取批次getBatchStatusGET /batches/{name}/status获取批次状态与各状态任务计数listBatchesGET /batches按时间倒序列出批次可分页createBatch的入参见 endpoints/types.ts字段说明project必填批次所属项目name必填项目内唯一的批次名callback批次完成时通知的 URL 或邮箱calibration_batch是否为校准批次self_label_batch是否为自标注批次metadata任意键值元数据getBatchStatus返回的状态对象见 schema/database.ts包含status、tasks_pending、tasks_completed、tasks_error、tasks_canceledAgent 可以用它轮询批次进度实现创建 → 定稿 → 等待 → 统计的闭环。项目projects参数与标签体系管理项目端点在 endpoints/projects.ts共 4 个端点请求说明getProjectGET /projects/{name}按名称获取项目listProjectsGET /projects列出全部项目可用archived过滤setProjectParamsPOST /projects/{name}/setParams设置项目默认任务参数setProjectOntologyPOST /projects/{name}/setOntology设置项目的标签体系ontology即标签类别与属性定义setProjectParams支持patch布尔值为true时与最近的参数合并而非整体替换见 endpoints/types.ts。在创建大量任务之前先通过setProjectParams固化默认参数、用setProjectOntology定义好标签类可以避免每个任务重复传参。文件files资产导入与上传Scale 的标注任务依赖文件资产三个端点实现在 endpoints/files.ts端点请求说明getAssetsGET /files按项目与元数据过滤列出文件资产分页importFilePOST /files/import从远程 URL 导入文件uploadFilePOST /files/upload上传本地文件base64官方上限 80 MBimportFile入参包括file_url必填、project_name、reference_id、attachment_type、metadata见 endpoints/types.ts。uploadFile的入参为file_base64必填、file_name含扩展名、mime_type、project_name、reference_id、metadata。插件在 Schema 层就做了双重校验见 endpoints/types.tsz.base64()确保输入是合法 base64refine将 base64 解码后检查字节数是否超过MAX_UPLOAD_BYTES 80 * 1024 * 102480 MB超限直接拒绝。实现上uploadFile会先把 base64 解码为Uint8Array兼容浏览器与 Node 两种环境见 endpoints/files.ts再以multipart/form-dataFileproject_namereference_id 序列化的metadata提交到files/upload而非 JSON 体。团队teams与 Studio 工作流团队成员管理getTeamsGET /teams列出所有团队成员及角色、通知偏好inviteTeamMember({ emails, role })POST /teams/invite按邮箱邀请成员并授予角色。role的合法取值在SCALE_TEAM_ROLES中定义labeler/member/manager见 endpoints/types.ts。注意实现细节插件会把入参的role映射为请求体的team_role字段见 endpoints/teams.ts。Scale Studio 分配与批次优先级Studio 端点在 endpoints/studio.ts用于管理谁负责哪个项目以及批次按什么顺序被处理端点请求说明getStudioAssignmentsGET /studio/assignments查看每个活跃用户的 Studio 项目分配addStudioAssignmentsPOST /studio/assignments/add按邮箱把项目分配给团队成员removeStudioAssignmentsPOST /studio/assignments/remove按邮箱取消成员的 Studio 项目分配getStudioBatchesGET /studio/batches按优先级列出待处理的 Studio 批次setBatchPrioritiesPOST /studio/batches/set_priorities设置待处理批次的优先级顺序resetBatchPrioritiesPOST /studio/batches/reset_priorities重置批次优先级为默认顺序分配类操作的入参统一为{ emails: string[]; projects: string[] }见 endpoints/types.ts。setBatchPriorities接收batch_names数组按期望优先级排列的全部待处理批次名插件内部会把它映射为{ batches: [{ name }, ...] }提交见 endpoints/studio.ts。审计与质量结果追溯与标注员训练getFixlessAudits({ task_id?, id? })GET /audits按任务 ID 或审计 ID 获取 fixless 审计。Schema 强制要求task_id与id至少提供一个见 endpoints/types.tsgetQualityLabelers({ quality_task_ids?, labeler_emails? })GET /quality/labelers按质量任务 ID 或标注员邮箱获取标注员训练尝试记录同样要求至少提供一个过滤条件见 endpoints/types.ts。输入输出校验与错误处理README 强调了两点设计保证所有操作都用 zod Schema 校验输入输出错误含 429 限流统一路由到插件的错误处理器。双份 Schema 体系插件维护了两套 schema端点 SchemaScaleAiEndpointInputSchemas/ScaleAiEndpointOutputSchemas见 endpoints/types.ts为全部 41 个端点定义输入与输出的 zod 校验并通过scaleAiEndpointSchemas按组.端点的扁平 key 注册见 index.ts同时用satisfies RequiredPluginEndpointSchemas做编译期强约束数据模型 SchemaScaleAiSchema见 schema/index.ts定义tasks、batches、batchStatuses、projects、files、teammates六个实体version1.0.0其中 Task、Batch、Project 等对象 Schema 都刻意保持宽松.loose()/ 可选字段因为 Scale 的 params / response 结构因任务类型差异巨大见 schema/database.ts 顶部注释kept permissive。此外每个端点都标注了riskLevelread/write与一句话描述见 index.ts 的scaleAiEndpointMeta便于权限系统与 Agent 理解每个操作的风险。错误处理器按状态码智能重试插件的内置错误处理器定义在 error-handlers.ts覆盖五类错误处理器匹配条件策略RATE_LIMIT_ERRORHTTP 429或消息含rate_limited/429/too many requests最多重试 5 次并透传retryAfter若ApiError携带作为退避依据AUTH_ERRORHTTP 401 / 403或消息含unauthorized/invalid_auth/forbidden/no valid api key不重试maxRetries: 0NOT_RETRYABLE_CLIENT_ERRORHTTP 402Not enabled任务类型需联系销售开通、404、409unique_id/ 幂等键已被占用不重试这类错误是确定性的SERVER_ERRORHTTP 5xx最多重试 3 次DEFAULT兜底不重试其中 402 / 409 被注释明确为确定性错误——永不重试见 error-handlers.ts例如 409 往往意味着你的unique_id已被用于另一个任务重试没有意义。同时 client.ts 会保留ApiError原样抛出让上层错误处理器能读到status与retryAfter只有非 API 错误才被包装为ScaleAiAPIError。你还可以在scaleai({ errorHandlers })中注入自定义处理器与内置处理器合并自定义覆盖同 key 的内置项。可观测性与测试保障所有端点执行成功后都会通过logEventFromContext写入形如scaleai.tasks.create.imageannotation、scaleai.batches.getStatus的事件含task_id、count、has_more等上下文方便接入 Corsair 的审计与日志体系。插件的正确性由 api.test.ts 覆盖它通过 mockfetch捕获发出的请求断言请求打到https://api.scale.com/v1/tasks且Authorization头是Basic base64(apiKey:)Basic Auth、空密码——见 api.test.ts写请求以application/json序列化 body数组查询参数以重复键追加tagsatagsb。仓库中还提供schema.test.tsSchema 校验与integration.test.ts集成级验证运行pnpm testjest即可执行全部测试运行pnpm typecheck做类型检查pnpm buildtsc --build --force tsup产出构建产物。小结一条完整的数据标注自动化链路把以上能力串起来一个典型的 Agent 标注工作流可以是files.uploadFile上传数据集或files.importFile从 URL 导入projects.setProjectOntology/projects.setProjectParams定义标签体系与默认参数batches.createBatch创建批次逐条tasks.createImageAnnotationTask等创建标注任务并挂到批次下batches.finalizeBatch定稿批次任务进入标注队列轮询batches.getBatchStatus或tasks.listTasks跟踪进度用tasks.addTaskTags/tasks.setTaskMetadata管理任务任务完成后tasks.getTaskResponseUrl取回标注结果必要时tasks.sendTaskCallback重发回调需要人工编排时用teams.inviteTeamMember、studio.addStudioAssignments、studio.setBatchPriorities调整团队分配与批次优先级。在整个过程中zod 校验保证入参正确性错误处理器对限流与临时故障自动重试、对确定性错误直接失败live_/test_密钥机制则确保你可以在不产生账单的前提下放心调试。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考