ai-sdk/cohere 演进全解AI SDK 中 Cohere 提供者的能力变迁与源码级实现剖析【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai本篇文章以开源仓库中packages/cohere/CHANGELOG.md的完整版本历史为主线结合packages/cohere/README.md的安装与使用说明以及packages/cohere/src/下的真实源码系统梳理 AI SDK 的 Cohere Provider 从首个版本到当前版本的核心能力演进文本生成与流式、工具调用、嵌入Embedding、重排序Reranking、推理Reasoning、多模态图片输入、工作流序列化与 ESM-only 迁移等。读完本文你将掌握ai-sdk/cohere的安装配置、Provider 实例创建、三类模型对话 / 嵌入 / 重排序的选项参数以及历次大版本升级AI SDK 5 / 6 / 7中需要关注的破坏性变更与迁移路径。一、包概览ai-sdk/cohere是什么ai-sdk/cohere是 AI SDK 官方维护的 Cohere Provider 模块为 TypeScript 应用提供对 Cohere API 的语言模型Language Model、嵌入模型Embedding Model与重排序模型Reranking Model支持。它遵循 AI SDK 的 Provider 规范当前源码中provider.specificationVersion v4见 cohere-provider.ts通过统一的generateText、embed、rerank等 AI SDK 高阶 API 即可调用 Cohere 模型。从 CHANGELOG.md 的版本号演进可以看出该包经历了0.0.x早期孵化→1.xAI SDK 4→2.xAI SDK 5→3.xAI SDK 6→4.xAI SDK 7五个主要阶段每一次主版本号提升都对应一次 AI SDK 核心规范的大版本升级。二、安装与 Provider 实例创建2.1 安装根据 README.md通过 npm 安装即可npm i ai-sdk/cohere2.2 默认 Provider 实例与最小示例包默认导出一个已配置好的cohere实例可直接传入模型 ID 使用import { cohere } from ai-sdk/cohere; import { generateText } from ai; const { text } await generateText({ model: cohere(command-r-plus), prompt: Write a vegetarian lasagna recipe for 4 people., });从源码看cohere-provider.ts中的createCohere()是工厂函数cohere只是createCohere()的默认实例。Provider 实例本身可被直接调用等价于languageModel()并挂载了四个模型工厂方法cohere(modelId)/cohere.languageModel(modelId)— 创建文本生成语言模型cohere.embedding(modelId)/cohere.embeddingModel(modelId)— 创建嵌入模型textEmbedding/textEmbeddingModel为已废弃别名cohere.reranking(modelId)/cohere.rerankingModel(modelId)— 创建重排序模型cohere.imageModel()— 统一抛出NoSuchModelErrorCohere 图片生成能力不在本包范围。2.3 自定义 Provider 配置项CohereProviderSettings支持以下配置cohere-provider.ts配置项类型说明baseURLstringAPI 地址前缀默认https://api.cohere.com/v2可指向代理服务器apiKeystringAPI Key通过Authorization: Bearer头发送默认读取COHERE_API_KEY环境变量headersRecordstring, string自定义请求头会合并进默认请求头fetchFetchFunction自定义 fetch 实现可用于拦截请求或测试generateId() string生成每个请求唯一 ID 的函数默认使用generateId注意CHANGELOG 4.0.0 中记录了headers变为可选这一非破坏性变更——自定义 Provider 实现构造模型配置时可以省略headers这在模型从工作流步骤边界反序列化、鉴权单独提供的场景下非常有用。三、能力演进时间线从文本生成到多模态与工作流CHANGELOG 完整记录了该包的能力发展脉络以下是关键里程碑版本关键能力0.0.1首个版本支持 Cohere 文本生成与流式输出0.0.6支持stopSequences、topK、responseFormat设置0.0.12修复随请求发送最后一条消息而非第一条0.0.18支持工具调用tool calls0.0.22新增嵌入embedding支持0.0.28切换至 Cohere v2 API1.0.0AI SDK 4 大版本对齐1.1.x支持 tool-plan 响应内容透传、无参数工具、全部 tool choice 选项、对象生成json 模式 / tool 模式、tool calls finish reason、command-a模型 ID2.0.0AI SDK 5工具调用修复、raw chunk 支持、Embedding V2 接口、引用citations支持、迁移到providerOptions2.0.9推理reasoning模型支持command-a-reasoning-08-20253.0.0AI SDK 6Provider V3 / LanguageModel V3 / EmbeddingModel V3、重排序reranking、raw finish reason、扩展 token usage、工具执行审批3.0.16嵌入模型新增outputDimension选项4.0.0AI SDK 7ESM-only、provider references、工作流序列化、顶层reasoning参数、图片输入、Node.js 224.0.5实验性流式转写transcription支持配合 OpenAIgpt-realtime-whisper、xAI WebSocket STT4.0.33修复保留完整的原始 usage 对象下面选取几个核心技术点深入展开。四、对话语言模型模型 ID 与推理选项4.1 支持的对话模型 IDcohere-chat-language-model-options.ts中定义的CohereChatModelId包括command-a-03-2025 command-a-reasoning-08-2025 command-a-vision-07-2025 command-r7b-12-2024 command-r-plus-04-2024 command-r-plus command-r-08-2024 command-r-03-2024 command-r command command-nightly command-light command-light-nightly类型末尾带有(string {})意味着也可传入任意字符串例如 Cohere 后续发布的新模型 ID运行时不做死限制。4.2 推理Reasoning配置CHANGELOG 2.0.9 首次引入 reasoning 支持针对command-a-reasoning-08-2025并在 4.0.0 迁移到 AI SDK 顶层的reasoning参数。在 Provider 层CohereLanguageModelChatOptions.thinking用于控制推理行为cohere-chat-language-model-options.ts{ thinking: { type: enabled | disabled, // 可选默认 enabled tokenBudget: number, // 可选思考可用 token 上限正整数 } }tokenBudget表示模型可用于思考的最大 token 数达到预算后模型会停止思考并继续生成回复。源码 cohere-chat-language-model.ts 中该选项会被映射为 Cohere v2 API 的thinking.type与thinking.token_budget字段在流式解析时thinking类型的内容会被转换为 AI SDK 的reasoning文本块见同文件第 190-191 行、305-326 行。五、嵌入模型输入类型、截断与输出维度5.1 支持的嵌入模型 IDcohere-embedding-model-options.ts定义的CohereEmbeddingModelIdembed-english-v3.0 embed-multilingual-v3.0 embed-english-light-v3.0 embed-multilingual-light-v3.0 embed-english-v2.0 embed-english-light-v2.0 embed-multilingual-v2.05.2 嵌入选项CohereEmbeddingModelOptions提供三个参数参数取值说明inputTypesearch_document/search_query/classification/clustering输入类型默认search_query。search_document用于入库向量、search_query用于检索查询向量、classification用于文本分类、clustering用于聚类truncateNONE/START/END超长输入处理方式默认END丢弃末尾NONE超限直接报错START丢弃开头outputDimension256/512/1024/1536输出嵌入向量维度仅embed-v4.0及更新模型可用默认1536其中outputDimension是 CHANGELOG 3.0.16 明确记录的新增能力用于控制输出向量大小以节省存储与带宽。六、重排序模型Reranking 能力重排序reranking在 CHANGELOG 3.0.0 中引入commitd1bdadb随后9524761增加了重排序模型的简写名。源码位于独立的packages/cohere/src/reranking/目录包含 API 封装、模型实现与测试。支持的模型 IDcohere-reranking-model-options.tsrerank-v3.5 rerank-english-v3.0 rerank-multilingual-v3.0选项参数参数默认值说明maxTokensPerDoc4096长文档自动截断到指定 token 数priority0请求优先级使用方式import { cohere } from ai-sdk/cohere; import { rerank } from ai; const result await rerank({ model: cohere.reranking(rerank-v3.5), query: ..., documents: [..., ...], });七、图片输入与多模态CHANGELOG 4.0.0 中f2919d5记录add support for passing images to Cohere models。对应地cohere-chat-language-model-options.ts 定义了图片部分的 Provider 选项{ image: { detail: auto | low | high // 可选作为 image_url.detail 透传给 Cohere chat API } }配合command-a-vision-07-2025视觉模型可以在 AI SDK 的对话消息中直接传入图片使用 AI SDK 的 file/image 数据部分并通过providerOptions.cohere.image.detail控制采样的精细度low更省 tokenhigh细节更丰富auto由服务端决定。同一版本还提到文件上传数据部分改为带类型标签9bd6512移除 image part 类型、file part 数据属性带类型标记这意味着多模态内容统一走 file part 通道。八、稳定性与健壮性修复要点CHANGELOG 中记录了大量值得注意的健壮性修复对自建 Agent 应用有直接参考价值工具调用无参数场景1.1.8fix (provider/cohere): deal gracefully with tools with no parameters—— 零参数工具不再导致请求异常tool-plan 内容隔离1.1.7omit tool plan content from normal response text—— 避免规划内容混入最终回复文本流式工具参数解析加固4.0.0 / 3cfb762Harden streamed tool call argument parsing against prototype keys—— 防止原型链污染类攻击空 usage 对象集中化4.0.18在 provider-utils 中集中创建空的语言模型 usage统一各 Provider 行为原始 usage 完整保留4.0.33preserve complete raw usage objects确保计费与监控数据的完整性工具执行拒绝默认消息更精确4.0.0 / 58a2ad7工具被拒绝时的默认提示更准确错误类型前缀保留4.0.0 / 6fd51c0getErrorMessage不再丢失错误类型前缀消息顺序修复0.0.12请求中发送最后一条用户消息而非第一条保证多轮对话上下文正确。九、大版本迁移指南重点9.1 AI SDK 74.0.0ESM-only 与运行时要求ESM-only所有包移除 CommonJS 导出type: module使用require()的消费者必须迁移到 ESMimport语法Node.js 版本要求提升最低支持 Node.js 22支持 22 / 24 / 26顶层reasoning参数推理配置从 Provider 私有选项迁移为 AI SDK 统一顶层参数各 Provider 跟进支持工作流序列化所有 Provider 模型类新增WORKFLOW_SERIALIZE与WORKFLOW_DESERIALIZE静态方法模型实例可跨工作流步骤边界传输而不报序列化错误ai-sdk/provider-utils新增serializeModel()辅助函数提取可序列化属性、过滤函数第三方 Provider 作者可借此为自己的模型接入工作流支持Provider references支持按 Provider 上传文件导出符号重命名Provider 实现代码模式统一部分导出符号更名但旧名称通过 deprecated 别名继续可用04e9009。9.2 AI SDK 63.0.0Embedding V3 与重排序ProviderV3/LanguageModelV3/EmbeddingModelV3规范落地Embedding API 重命名移除泛型参数调用方式从model.textEmbeddingModel(my-model-id);变更为model.embeddingModel(my-model-id);textEmbeddingModel/textEmbedding保留为 deprecated 别名新增重排序能力及重排序模型简写名扩展 token usage3bd2689、raw finish reason 暴露cbf52cd、工具执行审批e8109d3等核心规范能力。9.3 AI SDK 52.0.0providerOptions 化与引用修复工具调用ef4f44e新增 raw chunk 支持与 Embedding V2 接口response字段重命名自rawResponse为文本文档新增引用citations支持4fd442bProvider 特有参数统一迁移到providerOptions77e5975并统一使用 optional 而非 nullish 混用6f231db内部切换到 Zod 4d1a034f。十、源码结构与测试验证packages/cohere/src/的模块划分如下便于读者按图索骥深入阅读cohere-provider.ts — Provider 工厂、设置项与四个模型工厂cohere-chat-language-model.ts — 对话模型实现含 thinking 解析与流式处理cohere-embedding-model.ts — 嵌入模型实现cohere-reranking-model.ts — 重排序模型实现cohere-error.ts — 错误封装map-cohere-finish-reason.ts — finish reason 映射对应 CHANGELOG 中的 finish reason 相关修复convert-to-cohere-chat-prompt.ts — AI SDK 消息到 Cohere 请求格式的转换cohere-prepare-tools.ts — 工具参数 schema 的准备与转换。测试方面仓库提供了完整的 vitest 测试cohere-chat-language-model.test.ts、cohere-embedding-model.test.ts、cohere-reranking-model.test.ts、cohere-prepare-tools.test.ts等并配有fixtures目录中的真实响应夹具cohere-text.json、cohere-tool-call.json、cohere-reasoning.json、cohere-citations.json、cohere-null-args.json、cohere-max-tokens.json等与snapshots快照覆盖了 CHANGELOG 中记录的绝大多数修复场景如空参数工具、null 参数、推理流式块、引用等是理解实现细节的一手资料。十一、结语如何用好这份演进史ai-sdk/cohere的 CHANGELOG 不只是变更记录更是理解 AI SDK Provider 规范演进的最佳样本从早期简单的文本生成到工具调用、嵌入、引用、推理、重排序、多模态再到 ESM-only 与工作流序列化每一步都对应 AI SDK 核心抽象LanguageModelV3/V4、EmbeddingModelV3/V4、RerankingModelV4的能力扩展。开发者可以据此判断升级 AI SDK 主版本时ai-sdk/cohere需要同步处理哪些破坏性变更ESM 迁移、embeddingModel重命名、顶层reasoning参数、Node.js 22 基线也可以把packages/cohere/src/当作编写自研 Provider 的参考实现。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考