Corsair 集成 AsticaAI 插件基于 corsair-dev/asticaai 的语音转写与图像 OCR 接入指南【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本指南围绕 Corsair 仓库中的 AsticaAI 官方插件packages/asticaai/README.md展开讲解如何在 Corsair 应用中接入 Astica AI 的两大认知能力——通过readText.read完成图像文字提取OCR通过analyzeAudio.analyze完成语音转写speech-to-text。读完本文你将掌握该插件的安装方式、全部端点与入参出参格式、API Key 鉴权与租户凭据管理机制以及底层请求封装、错误分类、限流退避和结果持久化的完整实现细节。插件概览Corsair 如何封装 Astica AIcorsair-dev/asticaai是 Corsair 的官方插件包当前版本 0.1.2协议 Apache-2.0它把 Astica AI 的视觉Vision与听觉ListenAPI 封装为一组类型安全、带输入输出 Schema 校验、支持租户级鉴权与统一错误处理的 Corsair 端点。插件本体声明在 packages/asticaai/index.ts 的asticaai()工厂函数中插件 ID 为asticaai采用api_key作为默认鉴权类型。从源码结构看插件包划分为四个清晰层次目录/文件职责endpoints/端点实现readText.read、analyzeAudio.analyze及 Zod 输入/输出 Schemaclient.ts底层 HTTP 请求封装、API 基址、限流配置与密钥脱敏error-handlers.ts将 Astica 错误归并为 Corsair 统一的错误类型schema/数据库表结构定义转写结果、OCR 结果的持久化字段安装与接入插件通过 pnpm 安装核心依赖为corsair0.1.0与zod^4.1.13二者以 peerDependencies 形式声明见 packages/asticaai/package.jsonpnpm add corsair-dev/asticaai安装后在 Corsair 应用中注册插件可选配置项包括authType、key、hooks、errorHandlers与permissions见 packages/asticaai/index.ts 的AsticaAiPluginOptionsimport { asticaai } from corsair-dev/asticaai; export const asticaAi asticaai({ // authType 缺省即为 api_key可省略 authType: api_key, // 可选静态 key仅当 keyBuilder 的 source 为 endpoint 时生效 // key: process.env.ASTICA_API_KEY, });关于key选项需要注意它仅在keyBuilder的source endpoint时被直接返回其余情况都会走租户密钥管理详见下文鉴权章节。端点速览插件暴露两个端点来自 packages/asticaai/index.ts 的端点注册表操作Operation ID风险等级说明analyzeAudio.analyzeasticaai.api.analyzeAudio.analyzeread使用 Astica speech-to-text 转写音频readText.readasticaai.api.readText.readread使用 Astica OCR 从图像中提取文本两个端点均被声明为read风险级别endpointMeta见 packages/asticaai/index.ts即只读取/转换用户提供的媒体不产生写入性副作用适合在权限配置中以较低敏感度开放。readText.read图像 OCR 端点readText.read调用 Astica Vision 接口/describe请求基址为https://vision.astica.ai见 client.ts。实现位于 endpoints/read-text.ts。输入参数Zod Schema 定义于 endpoints/types.ts参数类型必填说明inputstring是HTTPS 图片 URL 或 Base64 编码的图片数据最大 20MB、16000×16000pxmodelVersion枚举否视觉模型版本默认2.5_full可选2.5_full、2.1_full、2.0_full、1.0_fullmodelVersion的合法取值由常量ASTICA_VISION_MODEL_VERSIONendpoints/types.ts约束传入非法值会在请求发出前被 Zod 拦截。请求体构造端点内部将请求体组装为{ input, modelVersion, visionParams: text_read }read-text.ts其中visionParams: text_read是固定写死的参数用于告诉 Astica 本次任务是纯文字提取而非通用图像描述。输出结构响应经过AsticaReadTextOutputSchema校验endpoints/types.ts核心字段如下字段类型说明statusstringsuccess或error注意Astica 失败时返回 HTTP 200errorstring?失败时的错误信息readResult.contentstring?从图像中识别出的完整文本readResult.pagesPage[]?分页结果每页含pageNumber、height、width、angle、words[]含confidence置信度与boundingBox、lines[]、spans[]等字段调用方拿到readResult.pages后可以聚合各页lines得到逐行文本与包围盒坐标用于版面分析、表格还原等进阶场景。analyzeAudio.analyze语音转写端点analyzeAudio.analyze调用 Astica Listen 接口/transcribe请求基址为https://listen.astica.ai见 client.ts。实现位于 endpoints/analyze-audio.ts。输入参数endpoints/types.ts参数类型必填默认值说明inputstring是—HTTPS 音频 URL 或 Base64 编码的音频数据modelVersionstring否1.0_full转写模型版本doStream0 \| 1否0是否边生成边返回部分转写结果low_priority0 \| 1否0置 1 时任务进入队列并以更低价格执行响应中返回resultURI供轮询输出结构endpoints/types.ts字段类型说明statusstringsuccess或errorerrorstring?失败时的错误信息textstring?转写文本low_priority时缺省或为 nullresultURIstring?仅low_priority1时返回需轮询该 URI 获取最终结果因此使用low_priority的调用方需要自行实现轮询逻辑先消费resultURI待任务完成后获取text。doStream1则适用于实时转写类场景。API Key 鉴权与租户凭据管理插件鉴权类型为api_keyREADME 中明确说明Corsair 会在首次使用时向你的租户tenant提示录入凭据。这正是 Corsair 多租户模型的体现——插件不要求你在部署时写死全局密钥而是让每个租户提供自己的 Astica API Key。底层实现位于 index.ts 的keyBuilder当source endpoint且传入options.key时优先使用静态配置的 key否则从ctx.keys.get_api_key()获取当前租户的密钥取不到密钥时抛出AuthMissingError(asticaai, api_key)触发 Corsair 的凭据缺失流程。鉴权配置asticaAiAuthConfig将账号维度绑定到tenant_external_idindex.ts即密钥与租户的外部标识挂钩天然支持按租户隔离调用额度与账单。一个值得注意的实现细节Astica 的 API Key 是放在请求体tkn字段中提交的client.ts而非常见的 Authorization 请求头。这意味着密钥会出现在请求体里插件因此在错误处理时专门做了脱敏详见下文。请求封装、错误分类与限流退避统一的请求封装所有 Astica 调用都经由 client.ts 的makeAsticaAiRequest()发起它根据端点选择ASTICAAI_VISION_API_BASE或ASTICAAI_LISTEN_API_BASE作为BASE以POSTapplication/json发送请求体并把tkn: apiKey注入请求体将底层ApiError包装为AsticaAiAPIError仅透传status、statusText、retryAfter三个字段对错误消息执行redactKey()脱敏将消息中的 API Key 替换为[REDACTED]。关于第 3 点源码注释给出了明确理由Astica 的密钥在请求体里ApiError.request.body会残留密钥而 Corsair 核心的脱敏器只清理 URL 与查询串、不处理请求体因此插件刻意不把原始ApiError作为cause保留只传递上面三个元数据字段杜绝密钥泄露路径。致命特性Astica 用 HTTP 200 报告失败Astica 的 API 在业务失败如密钥无效、配额耗尽时返回 HTTP 200 且响应体为{status:error, error:…}不会走传输层的错误路径。插件通过 endpoints/shared.ts 的assertAsticaOk()在每次响应后主动检查if (response.status?.toLowerCase() error) { throw new AsticaAiAPIError(response.error ?? Astica API returned an error); }正是这个检查让后续的AUTH_ERROR与RATE_LIMIT_ERROR处理器能够捕获到这类藏在 200 里的错误。限流识别与退避client.ts 定义了ASTICA_RATE_LIMIT_CONFIG开启限流重试最多重试 3 次初始退避 1000ms、指数退避倍率 2读取retry-after、x-ratelimit-reset、x-ratelimit-remaining、x-ratelimit-limit响应头。限流判定isRateLimitError做了双重匹配状态码为 429或响应体符合bodyReportsRateLimit()client.tsstatus为error且error字段命中/rate.?limit|too many requests|\b429\b/i。重试完全留在传输层完成插件本地不再叠加第二层重试循环避免对已限流的 API 造成传输层重试 × 本地重试的放大效应。错误分类处理器error-handlers.ts 将包装后的错误归并为 Corsair 统一的四类处理器均返回maxRetries: 0注释说明bind.ts会丢弃重试调用结果并重抛原始错误因此重试只会平白增加延迟由调用方依据错误上保留的元数据自行重试处理器匹配条件说明RATE_LIMIT_ERROR状态 429 或消息含429/rate limit/rate_limited/too many requests携带headersRetryAfterMs供上层调度AUTH_ERROR状态 401/403或消息含invalid api token/unauthorized/invalid_auth/invalid api key/authentication覆盖HTTP 200 体内报错的坏密钥场景两个主机对坏密钥恰好都返回invalid api tokenSERVER_ERROR状态码 500服务端故障DEFAULT兜底其余所有错误结果持久化不落原始媒体只存指纹每次调用成功后端点会把结果写入 Corsair 数据库见 schema/database.tsOCR 结果readTextResults表AsticaAiReadTextResultinputFingerprint、inputKind、inputLength、modelVersion、content展平自readResult.content、pageCount、lineCount、readAt转写结果audioTranscripts表AsticaAiAudioTranscriptinputFingerprint、inputKind、inputLength、modelVersion、text、resultURI、transcribedAt。两张表都以inputFingerprint作为实体主键upsertByEntityId。指纹与安全策略由 endpoints/shared.ts 实现inputFingerprint()对完整输入做 SHA-256 摘要。注释指出不能截断输入作为主键——同一格式的 base64 媒体共享文件头所有 base64 JPEG 都以/9j/4AAQSkZJRgABAQ…开头截断必然碰撞inputEntityId()直接以指纹作为实体 ID同名输入幂等去重describeInput()仅记录inputKindurl或inline按/^https?:\/\//i判断与inputLength。原始输入图片/音频本体或带签名查询串的 URL永不落库内联输入就是媒体本身URL 输入可能携带签名参数。这样既避免存储超大 blob也防止签名泄露同时通过 SHA-256 指纹维持了可去重、可关联的语义。每次调用还会通过logEventFromContext记录事件asticaai.analyze_audio/asticaai.read_text事件元数据同样只含输入描述、模型版本等安全信息analyze-audio.ts、read-text.ts。测试验证插件配备完整的测试体系packages/asticaai 目录单元测试endpoints.test.ts、client.test.ts、schema.test.ts覆盖输入解析、请求体构造、Schema 校验与持久化逻辑实网测试api.test.ts是live套件test:live脚本单独运行默认被 CI 排除使用 Astica 官方文档提供的样例资源https://www.astica.org/inputs/analyze_3.jpg与asticaListen_sample.wav并断言响应status为success、readResult.content为字符串、写入记录的实体 ID 等于输入 SHA-256、且落库记录不含input字段验证原始输入不持久化的安全约束。运行方式ASTICA_API_KEY... pnpm test:liveWebhook 与许可插件不提供任何 Webhook——asticaAiWebhooksNested为空对象index.tsREADME 亦明确 No webhooks。因此该插件的异步能力依赖客户端主动轮询如low_priority的resultURI而非服务端推送。插件以 Apache-2.0 协议开源。更完整的类型说明与使用示例可查阅仓库内文档 docs/plugins/asticaai以及插件包自身的声明文件 packages/asticaai/README.md。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考