GPT4All TypeScript 绑定 v4 破坏性变更：EmbeddingResult 与移除的类型如何迁移

GPT4All TypeScript 绑定 v4 破坏性变更EmbeddingResult 与移除的类型如何迁移【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all如果你用 Node.js / TypeScript 项目通过 npm 包gpt4all调用本地 LLM把包升级到 v4 后会遇到三处破坏性变更createEmbedding与EmbeddingModel.embed()的返回值从Float32Array变成了EmbeddingResult对象废弃类型ModelType与ModelFile被删除以及“只传一个字符串路径”初始化模型的用法被移除。这篇文章给出基于仓库文档的迁移路径升级包、改写 embedding 调用、替换被移除的模型初始化方式并验证迁移结果。适用环境要求 Node.js 18.x.x见 package.json 中的engines字段当前仓库版本为4.0.0。v4 的三处变更gpt4all-bindings/typescript/README.md 的 “Changes” 一节明确列出 Version 4 的 breaking changescreateEmbedding与EmbeddingModel.embed()返回对象EmbeddingResult而不再是 float32array移除了废弃类型ModelType和ModelFile移除了只以字符串路径初始化模型的废弃用法Removed deprecated initiation of model by string path only。此外 README 提示旧的 gpt4all-ts 仓库绑定已过时应迁移到本仓库的 Node.js 绑定。升级到 v4 包按 README 给出的安装命令用任一包管理器更新依赖yarn add gpt4alllatest # 或 npm install gpt4alllatest # 或 pnpm install gpt4alllatest模型默认会下载到(homedir)/.cache/gpt4all/此路径来自 src/gpt4all.d.ts 中DEFAULT_DIRECTORY的注释后端动态库的默认搜索顺序为DEFAULT_DIRECTORY/libraries、cwd/libraries最后是cwd。迁移 embedding 代码从 Float32Array 到 EmbeddingResultv3 时代createEmbedding/EmbeddingModel.embed()直接返回一个Float32Array因此旧代码通常把返回值当数组直接索引或计算。v4 中这两个函数的返回值变为EmbeddingResult。按 gpt4all.d.ts 的定义interface EmbeddingResultT { /** * Encoded token count. Includes overlap but specifically excludes tokens used for the prefix/task_type, BOS/CLS token, and EOS/SEP token */ n_prompt_tokens: number; embeddings: T; }类型参数T取决于输入传入单个stringcreateEmbedding返回EmbeddingResultFloat32Array即embeddings是单个向量传入string[]返回EmbeddingResultFloat32Array[]embeddings是向量数组见createEmbedding的第二个重载。对应地旧代码里直接使用返回值的写法要改为从结果对象取embeddings// v3 风格返回值被当作 Float32Array 使用 // const vec createEmbedding(embedder, text); // vec.length、vec[i] 等 // v4返回值是 EmbeddingResult 对象 const result createEmbedding(embedder, text); const vec result.embeddings; // Float32Array console.debug(result.n_prompt_tokens); // 编码的 token 数n_prompt_tokens是新返回值带来的附加信息它是编码 token 数包含 overlap但不包含 prefix/task_type、BOS/CLS、EOS/SEP 所消耗的 token引自 d.ts 注释。如果你之前自己估算 token 用量可以直接改用这个字段。README 中的 Embedding 示例模型名与参数均照抄原文import { loadModel, createEmbedding } from ../src/gpt4all.js const embedder await loadModel(nomic-embed-text-v1.5.f16.gguf, { verbose: true, type: embedding}) console.log(createEmbedding(embedder, Maybe Minecraft was the friends we made along the way));从 npm 安装的包应改为从gpt4all导入README “Offline usage” 一节即使用import { ... } from gpt4all。embedding 调用时的可选项EmbeddingOptionsd.ts 中定义提供了四个可选项迁移时如果旧代码用别的方式控制这些行为需要改走选项对象prefix任务前缀不带结尾冒号。对 Nomic Embed可为search_query、search_document、classification、clustering。仓库示例 spec/embed.mjs 中的用法是console.log(createEmbedding(embedder, [Accept your current situation, 12312], { prefix: search_document }))dimensionality用于 Matryoshka-capable models 的嵌入维度默认全尺寸。实现上src/gpt4all.js 的createEmbeddingdimensionality未传时按-1处理传了0或负数会抛Dimensionality must be undefined or a positive integer错误低于model.MIN_DIMENSIONALITY时会打印性能可能下降的警告。longTextModemean或truncate默认mean控制超出模型长度限制的长文本如何处理atlas默认false开启后追求与 Atlas API 完全兼容d.ts 注释long_text_modemean时超过 8192 tokens 的文本会报错。EmbeddingModel.embed()的低层签名是embed(text, prefix, dimensionality, doMean, atlas)createEmbedding是它的高层封装迁移时优先改createEmbedding的调用即可。处理被移除的 ModelType / ModelFile 与字符串路径初始化ModelType与ModelFile两个类型不再从模块导出引用它们的 import 语句需要删除。模型初始化统一改用loadModel(modelName, options)loadModel的第一个参数是模型名如nomic-embed-text-v1.5.f16.gguf不是完整路径返回类型由options.type决定type: embedding时返回EmbeddingModel否则默认inference返回InferenceModel见 gpt4all.js 中loadModel的实现非法type会抛出Invalid model type默认行为是“本地没有就从 GPT4ALL 官网下载”allowDownload默认为truemodelPath默认为DEFAULT_DIRECTORY。离线使用可配合modelConfigFile指定本地模型配置文件例如 README 示例中的const model await loadModel(mistral-7b-openorca.gguf2.Q4_0.gguf, { verbose: true, device: gpu, modelConfigFile: ./models3.json })如果确实要直接构造原生LLModel低层用法构造函数现在接收的是LLModelOptions对象而不是字符串路径interface LLModelOptions { type?: string; // 目前仅作描述性标识无实际功能 model_name: string; model_path: string; library_path?: string; }model_name与model_path均为必填字符串路径初始化不再可用。验证迁移结果类型层面TypeScript 项目升级后src/gpt4all.d.ts是类型的权威来源。凡是把createEmbedding返回值当Float32Array使用的地方如直接vec.length、传入期望Float32Array的参数编译器会报类型不匹配改为解构embeddings后应通过类型检查。运行层面仓库 spec/ 目录下的示例展示了 v4 的调用形态其中 spec/embed.mjs 覆盖了 embedding 路径运行前需保证工作目录中已有对应模型文件和本地库README 说明 spec 示例“Should work assuming a model and libraries are installed locally in working directory”。成功标志是createEmbedding输出为含n_prompt_tokens与embeddings字段的对象而非裸数组。单测按 README 的 Test 一节执行yarn testjest跑仓库导出的函数单测。限制与注意README 的 Roadmap 明确写着“breaking changes may happen until the api stabilizes”v4 之后仍可能出现破坏性变更升级时建议锁定版本并核对 Changes 一节。示例与 README 的 Known Issues 均要求在脚本结束时调用model.dispose()/embedder.dispose()否则 GPU 占用可能不释放这是 embedding 迁移后代码容易遗漏的一步。本文的变更清单只覆盖 README “Changes” 一节列出的三项v3 到 v4 的其他行为差异如流式、会话接口不在本次迁移范围内。参考文档gpt4all-bindings/typescript/README.md —— 变更清单、安装命令、示例与测试方式gpt4all-bindings/typescript/src/gpt4all.d.ts ——EmbeddingResult、EmbeddingOptions、loadModel等类型定义gpt4all-bindings/typescript/src/gpt4all.js ——loadModel/createEmbedding的实现与默认值gpt4all-bindings/typescript/spec/embed.mjs —— v4 形态的 embedding 调用示例【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考