Electron 本地 AI 语言模型创建选项 LanguageModelCreateOptions 深度解析

Electron 本地 AI 语言模型创建选项 LanguageModelCreateOptions 深度解析【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron本文围绕 Electron 实验性 Prompt API 中的LanguageModelCreateOptions结构展开完整讲解LanguageModelUtility.create(options)的每个选项字段signal、initialPrompts及继承自核心选项的expectedInputs/expectedOutputs的取值与语义并结合仓库中 Utility 进程的 C 实现剖析这些选项从 JS 层穿越 Mojo 边界、注入AbortSignal、直至模型实例被校验回传的完整链路帮助开发者正确编写本地语言模型创建逻辑并排查创建失败问题。这个结构在 Prompt API 中的位置LanguageModelCreateOptions是 Electron 本地 AI 能力Prompt API中“创建模型”这一步的入参对象定义见 language-model-create-options.md。它的直接消费方是 LanguageModelUtility 的静态方法LanguageModelUtility.create(options)Experimental接收LanguageModelCreateOptions返回PromiseLanguageModelUtility用提供的options创建一个新的LanguageModelUtility实例而LanguageModelUtility.availability([options])使用的是更小的LanguageModelCreateCoreOptions仅expectedInputs/expectedOutputs两个可选字段这正是LanguageModelCreateOptions所继承的基类定义见 language-model-create-core-options.md。也就是说LanguageModelCreateOptions 核心选项描述预期的输入/输出模态 两个创建专属字段signal与initialPrompts。开发者通常通过 localAIHandler 模块的setPromptAPIHandler()提供自己的模型类由 Electron 内部把渲染进程的 Prompt API 请求转发到 Utility 进程并调用该类的create方法本结构就是这次调用收到的参数。相关使用场景可参考 local-ai-handler 教程。字段说明signalAbortSignal类型AbortSignalNode.js 全局类用于中断正在进行的创建流程。一个值得注意的实现细节是从源码看这个signal并不是由最终开发者自己 new 出来再传入的——Utility 进程在把选项交给你的create()方法之前会先创建一个内部的AbortController并把它的signal写进选项字典再发起调用见 CreateLanguageModelInternalL416–L424 创建AbortController并options_dict.Set(signal, ...)。框架用它做两件事渲染侧断连时主动中止当请求方Mojo 客户端断开连接时OnCreateLanguageModelClientDisconnect 会取出对应AbortController并调用其abort()从而运行signal的监听器让仍在进行的create()有机会及时退出管理器析构时兜底UtilityAIManager析构函数L151–L157会遍历所有进行中的创建请求并触发同样的中止逻辑。因此模型实现方在create()中应监听signal的abort事件例如取消加载、释放已分配资源以便在调用方消失时不悬挂任务。initialPromptsLanguageModelMessage[]可选类型LanguageModelMessage 数组用于在模型实例创建时预置初始提示消息使新实例从创建起就带有上下文。每个LanguageModelMessage的字段为字段类型说明rolestring消息角色取值system/user/assistantcontentLanguageModelMessageContent[]消息内容块数组prefixboolean可选是否为前缀消息其中LanguageModelMessageContent定义见 language-model-message-content.md字段类型说明typestring内容类型取值text/image/audiovalueArrayBuffer | string内容本体文本通常为 string图像/音频为 ArrayBuffer继承字段expectedInputs/expectedOutputs这两个可选字段来自父结构LanguageModelCreateCoreOptions元素类型为 LanguageModelExpected字段类型说明typestring模态类型取值text/image/audiolanguagesstring[]可选语言代码列表expectedInputs声明该模型预期接收的输入模态expectedOutputs声明预期产出的模态。它们的作用不止是文档性声明在 Utility 进程中创建成功回传时框架会直接从expected_inputs收集出“已启用的输入类型集合”HandleLanguageModelResult 中 L267–L272 构造enabled_input_types随OnResult一并交给调用侧用于向渲染进程描述该实例实际支持的 prompt 类型。使用示例结合 language-model-utility.md 的构造约定一个符合约定的模型类与创建选项大致如下在通过ses.registerLocalAIHandler(handler)注册的本地 AI 处理器脚本内const { localAIHandler } require(electron) class MyLanguageModel { // 构造参数 initialState 需要包含 contextUsage 与 contextWindow 两个 number 字段 constructor (initialState) { this.contextUsage initialState.contextUsage this.contextWindow initialState.contextWindow } // 静态方法Electron 内部以 LanguageModelCreateOptions 调用 create static create (options) { // options.signal - AbortSignal创建方断连时会被 abort // options.initialPrompts - 预置消息role: system | user | assistant // options.expectedInputs / options.expectedOutputs - 模态声明 // 返回值需是含 contextUsage、contextWindow 且具备 // prompt/append/measureContextUsage/clone/destroy 的对象可同步返回或返回 Promise return new Promise((resolve) { options.signal.addEventListener(abort, () { // 在此释放模型加载过程中已分配的资源 }) // 模拟加载本地模型…… const model new MyLanguageModel({ contextUsage: 0, contextWindow: 8192 }) // 可在此消费 options.initialPrompts把初始上下文写入模型 resolve(model) }) } static availability () { return available } // 实例方法prompt / append / measureContextUsage / clone / destroy ... } localAIHandler.setPromptAPIHandler(() MyLanguageModel)示例中的关键契约均以 language-model-utility.md 的文档约定为准静态create(options)返回PromiseLanguageModelUtilityavailability()返回available/downloadable/downloading/unavailable四种字符串之一实例需暴露contextUsage、contextWindow属性以及prompt、append、measureContextUsage、clone、destroy方法clone的入参结构见 language-model-clone-options.mdprompt的入参结构见 language-model-prompt-options.md。源码纵深options 从 Mojo 到模型实例的完整链路以下基于 shell/utility/ai/utility_ai_manager.cc 的实现事实按调用顺序拆解。浏览器侧对应的代理入口在 shell/browser/ai/proxying_ai_manager.cc。1. 选项的 V8 化什么字段会被带过来Mojo 层的创建选项在进入 Utility 进程 JS 环境前由 gin 转换器Converterblink::mojom::AILanguageModelCreateOptionsPtr::ToV8转换L104–L131其规则是若expectedInputs非空则设置expectedInputs若expectedOutputs非空则设置expectedOutputs若initial_prompts非空则设置initialPrompts若以上全部为空且无采样参数则整体转换为undefined。也就是说开发者在create(options)中拿到的对象只包含“有内容”的字段空数组不会以空数组形式出现实现时应对缺失字段做容错。2. 调用create()与结果校验CreateLanguageModelL372–L398首先确认已通过setPromptAPIHandler()提供了模型类若没有类直接通过 Mojo 客户端回调OnError(kUnableToCreateSession)。随后进入CreateLanguageModelInternalL400–L485该函数同时服务于create与clone两条路径为当前 Mojo 客户端注册进create_model_client_set_记下client_id创建AbortController存入abort_controllers_并把signal注入options_dict以options_dict为实参调用目标类的create或clone结果处理分三支返回 Promisethen回调中校验结果是“合法的 LanguageModel 对象”UtilityAILanguageModel::IsLanguageModel合法则走HandleLanguageModelResult否则抛TypeError: Invalid return value from LanguageModel.create()并回kUnableToCreateSessioncatch分支同样回kUnableToCreateSession同步返回合法模型对象为便利直接按成功处理其他值抛未捕获异常并回创建错误。HandleLanguageModelResultL245–L297还会校验返回对象必须能解析出contextUsage与contextWindow两个数值字段否则回kUnableToCreateSession校验通过后它把 JS 模型对象包装成UtilityAILanguageModel的 Mojo 接收端并连同AILanguageModelInstanceInfo上下文窗口、初始用量、启用输入类型等经client-OnResult(...)回传给请求方。这解释了为什么 language-model-utility.md 要求构造状态必须提供contextUsage/contextWindow它们是跨进程实例信息的必填入参。3. 可用性探测与状态字符串映射CanCreateLanguageModelL299–L370对应静态方法LanguageModelUtility.availability([options])若尚未通过 handler 提供模型类返回“不可用”若已提供则调用模型类静态availability方法允许返回 Promise 或字符串字符串与内部枚举的映射在Converterblink::mojom::ModelAvailabilityCheckResultL37–L51中完成available→ 可用、unavailable→ 未知不可用、downloading→ 下载中、downloadable→ 可下载。若返回非字符串则抛TypeError: Invalid return value from LanguageModel.availability()并按不可用处理。4. 中断与清理如前所述OnCreateLanguageModelClientDisconnectL159–L179在客户端断开时触发对应AbortSignal。源码注释特别指出abort()会先运行监听器再做微任务检查点这可能同步 settle 挂起的create()Promise 并从abort_controllers_中移除该条目因此实现上先把控制器从 map 中取出来再调用abort()避免跨越调用持有迭代器。这段细节说明signal的中止语义是“尽力通知”模型实现方不应假定abort之后创建调用一定失败而应据此释放资源。与 localAIHandler 的配合关系LanguageModelCreateOptions只在“Utility 进程中的本地 AI 处理器脚本”这一上下文中出现。按 local-ai-handler.md该模块通过ses.registerLocalAIHandler(handler)注册到会话localAIHandler.setPromptAPIHandler(promptAPIHandler)设置绑定处理器promptAPIHandler的details参数包含发起调用的webContentsId、securityOrigin、frameToken、renderProcessId处理器返回模型类typeof LanguageModelUtility形态或null返回null将拒绝渲染进程创建新的 Prompt API 会话文档提醒若渲染进程在setPromptAPIHandler()之前调用 Prompt API请求会被排队设置后统一刷新排队过多时最旧的待处理请求会被丢弃其 Promise 被拒绝因此应尽早调用setPromptAPIHandler()。从 UtilityAIManager::GetLanguageModelClass 可以看到对应的实现事实Electron 缓存 handler 返回的类并强制其必须是构造函数且通过UtilityAILanguageModel::IsLanguageModelClass校验否则抛TypeError: Must provide a constructible class返回null则表示 handler 主动不提供类。小结与注意事项LanguageModelCreateOptions是创建专属的超集结构在LanguageModelCreateCoreOptionsexpectedInputs/expectedOutputs之上增加了signal与initialPromptssignal由 Electron 内部注入并在请求方断连、管理器析构时触发中止模型实现应监听它做资源清理initialPrompts与expectedInputs/expectedOutputs为空时不会传给create()实现需容忍缺省字段create()的返回值必须是带contextUsage、contextWindow且具备完整实例方法的对象否则创建以kUnableToCreateSession失败该 API 目前标记为Experimental字段与行为可能随版本变化以当前仓库的 API 文档 和 Utility 进程源码 为准实现效果可参考仓库测试 spec/api-local-ai-handler-spec.ts。【免费下载链接】electron:electron: Build cross-platform desktop apps with JavaScript, HTML, and CSS项目地址: https://gitcode.com/GitHub_Trending/el/electron创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考