@mastra/voyageai 完整实践指南：VoyageAI 文本、多模态与上下文感知 Embedding 及 Reranker 深度解析

mastra/voyageai 完整实践指南VoyageAI 文本、多模态与上下文感知 Embedding 及 Reranker 深度解析【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastramastra/voyageai 是 Mastra 框架中对接 VoyageAI 官方 TypeScript SDK 的 Embedding 集成包位于仓库embedders/voyageai目录提供文本嵌入、多模态嵌入文本 图片 视频、上下文感知Contextualized分块嵌入以及文档相关性 Reranker 四大能力。本文以该包 CHANGELOG 所记录的功能演进为主线结合仓库源码embedders/voyageai/src与测试用例系统讲解每个能力的配置方式、调用姿势、参数语义与底层实现帮助你在一套代码里同时完成 RAG 索引、多模态检索和召回重排的完整落地。一、包定位与版本演进脉络mastra/voyageai是对 VoyageAI 嵌入生态的封装层包描述为 “VoyageAI embeddings integration for Mastra - text, multimodal, and contextualized chunk embeddings”见 embedders/voyageai/package.json。它并不重新实现算法而是通过依赖voyageai^0.3.1官方 SDK把 VoyageAI 的模型能力以 Mastra 统一的 Embedding 模型接口暴露出来。从 embedders/voyageai/CHANGELOG.md 的版本记录可以清晰还原该包的能力演进版本类型核心变更0.1.0Minor包初版加入文本、多模态、上下文嵌入与 Reranker 四大能力0.2.0Minor版本号随机提升无功能变更0.3.0Minor新增voyage-context-4上下文感知模型preview支持 256/512/1024/2048 灵活输出维度0.4.0Minor修复多模态嵌入文本被序列化为裸字符串导致 HTTP 400 的 Bug新增baseUrl配置项0.4.1Patch更新 README从 npm 发布物中移除 CHANGELOG 以减小包体积其中 0.1.0 奠定了整个包的功能骨架0.3.0 与 0.4.0 是影响用法最深的两次变更后文将逐一展开。二、安装与前置准备包本身采用 ESM 优先、同时提供 CJS 输出的双格式构建main/exports字段见 embedders/voyageai/package.jsonNode.js 版本要求22.13.0。安装方式与 README 一致npm install mastra/voyageai使用前需要配置 VoyageAI API Key两种方式任选其一设置环境变量VOYAGE_API_KEY推荐在模型配置中显式传入apiKey字段。从源码 text-embedding.ts 可以看到API Key 的解析顺序是“配置优先、环境变量兜底”两者都缺失时会直接抛出VoyageAI API key is required. Set VOYAGE_API_KEY environment variable or pass apiKey in config.错误。这一校验逻辑在文本、多模态、上下文嵌入和 Reranker 四个模块中保持一致测试用例should throw error if no API key is available见tests/text-embedding.test.ts也对此做了验证。三、文本 Embeddingtoken 感知批处理的完整实现3.1 快速上手按 embedders/voyageai/README.md 的用法文本嵌入既可以直接用预配置的voyage对象默认模型voyage-3.5也可以用工厂函数按需指定模型import { voyage, voyageEmbedding } from mastra/voyageai; // 使用默认模型voyage-3.5 const result await voyage.doEmbed({ values: [Hello world] }); console.log(result.embeddings[0].length); // 使用特定模型并自定义参数 const model voyageEmbedding({ model: voyage-3-large, inputType: query, outputDimension: 512, }); const queryResult await model.doEmbed({ values: [search query] });3.2 支持的文本模型CHANGELOG 0.1.0 明确列出文本嵌入覆盖 “voyage-4 和 voyage-3 系列外加 code/finance/law 专用模型”。具体清单由 types.ts 中的VoyageTextModel联合类型定义voyage-4 系列voyage-4-large、voyage-4、voyage-4-litevoyage-3 系列voyage-3-large、voyage-3.5、voyage-3.5-lite领域专用voyage-code-3、voyage-finance-2、voyage-law-2同文件 types.ts 中的TEXT_MODEL_INFO记录了每个模型的关键元数据最大输入 token 数如voyage-4-lite高达 1,000,000voyage-code-3为 32,000、默认维度 1024、以及统一支持的灵活输出维度[256, 512, 1024, 2048]。这些元数据直接服务于下文要讲的批处理逻辑。3.3 配置项全解文本嵌入配置接口VoyageTextEmbeddingConfigtypes.ts包含以下字段字段类型默认值说明modelVoyageTextModel必填使用的嵌入模型apiKeystring环境变量VOYAGE_API_KEYAPI KeybaseUrlstring官方端点自定义 API 地址可指向第三方托管的 Voyage 端点0.4.0 新增inputTypequery \| document \| null不指定检索优化query会前置查询专用 promptdocument前置文档专用 promptnull表示不加outputDimension256 \| 512 \| 1024 \| 2048模型默认1024输出向量维度outputDtypefloat \| int8 \| uint8 \| binary \| ubinaryfloat输出数据类型量化类型可显著降低存储truncationbooleantrue输入超过上下文长度时是否截断3.4 底层原理token 感知批处理CHANGELOG 0.1.0 强调文本嵌入带有 “token-aware batching via the SDKtokenize()method”。这是该包最值得一提的实现细节每次调用前先用 SDK 的tokenize()精确统计每个文本的 token 数然后按模型的最大输入 token 上限与单次最多 1000 条输入这两个约束动态分批而非粗暴地按条数平均切分。核心实现位于 text-embedding.ts 的createTokenAwareBatches函数maxInputTokens则取自TEXT_MODEL_INFO元数据查不到时回退到 32000见 text-embedding.ts。测试用例完整验证了这条链路tests/text-embedding.test.ts两个各 20 万 token 的文本合计超过voyage-3.5的 32 万上限会被拆成 2 个批次分别调用1000 条短文本在限制内时只发一次请求1500 条输入时自动拆成 1000 500 两批返回结果会按index排序后再拼装保证最终向量顺序与输入顺序一一对应。3.5 运行时覆盖providerOptions模型支持 V2AI SDK v5 风格与 V3AI SDK v6 风格两套规范实现VoyageTextEmbeddingModelV2/VoyageTextEmbeddingModelV3见 text-embedding.ts。V3 是 V2 的包装仅在返回结构中追加warnings: []字段用于向前兼容新规范。在调用层面doEmbed允许通过providerOptions.voyage在运行时覆盖inputType、outputDimension、outputDtype、truncation且运行时值优先级高于构造时配置text-embedding.ts。测试should allow providerOptions to override configtests/text-embedding.test.ts验证了“配置 document/1024、运行时改 query/256”最终以运行时为准的行为。这一机制非常适合同一模型在索引与查询两个阶段使用不同inputType的场景。四、多模态 Embedding文本 图片 视频的联合向量4.1 能力与模型多模态嵌入支持voyage-multimodal-3与voyage-multimodal-3.5两个模型types.ts其中视频输入仅voyage-multimodal-3.5支持见 types.ts 中video_url内容类型的注释。CHANGELOG 0.1.0 的原始描述为 “Multimodal embeddings (text images video) via voyage-multimodal-3/3.5”。4.2 输入结构interleaved content 数组与文本嵌入不同多模态输入不是字符串数组而是“内容数组”结构——每个输入是一个对象其content字段是文本、图片、视频等类型化内容的交错序列。支持的内容类型types.ts内容类型结构文本{ type: text, text: string }图片 URL{ type: image_url, image_url: string }Base64 图片{ type: image_base64, image_base64: string }视频 URL仅 3.5{ type: video_url, video_url: string }典型用法来自 index.ts 的示例import { voyageMultimodalEmbedding } from mastra/voyageai; const multimodal voyageMultimodalEmbedding(voyage-multimodal-3.5); const result await multimodal.doEmbed({ values: [{ content: [ { type: text, text: A cat playing }, { type: image_url, image_url: https://example.com/cat.jpg } ] }] });4.3 0.4.0 关键修复裸字符串序列化 BugCHANGELOG 0.4.0 记录的修复是本文最值得强调的坑之一此前多模态文本内容会被错误地序列化为裸字符串导致 Voyage API 直接返回 HTTP 400原文“multimodal text was serialized as inputs:[[text]]- HTTP 400”。修复后每个输入都被正确包裹为{ content: [...] }对象且content数组内是带type字段的类型化对象。修复前后对比CHANGELOG 0.4.0 原文示例// Before文本被序列化为裸字符串触发 HTTP 400 // inputs: [[text]] // After文本以类型化对象形式发送 const embedder voyage.multimodalEmbedding({ model: voyage-multimodal-3.5, baseUrl: https://ai.mongodb.com/v1, });对应的序列化逻辑在 multimodal-embedding.ts 的toSdkContent/toSdkInput中实现——四种内容类型分别映射为{ type: text, text }、{ type: image_url, image_url }、{ type: image_base64, image_base64 }、{ type: video_url, video_url }未知类型直接抛错。测试用例wraps each input as an object with a content array (not a bare array)与serializes text content as a typed object, never a bare stringtests/multimodal-embedding.test.ts专门锁定了这一行为防止回归。4.4 与向量库的配合由于多模态输入结构不同于字符串该类刻意不实现EmbeddingModelV2string接口而是提供独立的doEmbed与单条便捷方法embedOnemultimodal-embedding.ts。源码注释明确建议在多模态 RAG 管线中将其直接与向量存储配合使用例如vectorStore.upsert({ vectors: result.embeddings, ... })。多模态配置同样支持inputType与truncation字段types.ts。五、上下文感知Contextualized分块嵌入5.1 解决的问题普通分块嵌入最大的痛点是“上下文丢失”文档被切成独立 chunk 后每个 chunk 的向量只反映其局部语义。上下文感知模型让每个 chunk 在嵌入时“看到”同文档的其他 chunk同时捕获局部细节与文档级上下文CHANGELOG 0.3.0 原话“Each chunk is embedded with awareness of the other chunks in the same document, capturing both local detail and document-level context”。5.2 输入格式嵌套分组数组上下文嵌入的输入是嵌套数组外层对应文档内层是同一文档的 chunk 列表。支持voyage-context-3与 0.3.0 新增的voyage-context-4preview两个模型types.ts。CHANGELOG 0.3.0 原文示例import { voyage, voyageContextualizedEmbedding } from mastra/voyageai; // 预配置模型 const result await voyage.context4.doEmbed({ values: [[Paragraph 1 from doc 1..., Paragraph 2 from doc 1...], [Content from doc 2...]], inputType: document, }); // 或显式配置 const model voyageContextualizedEmbedding({ model: voyage-context-4, outputDimension: 512 });源码中的等价示例contextualized-embedding.ts展示了更真实的场景文档侧用inputType: document嵌入多个 chunk查询侧则用inputType: query且每个内层列表只放一条查询文本。5.3 灵活输出维度CHANGELOG 0.3.0 特别强调voyage-context-4支持 256、512、1024、2048 四种输出维度与元数据CONTEXTUALIZED_MODEL_INFO中supportedDimensions: [256, 512, 1024, 2048]一致见 types.ts。维度选择直接影响存储成本与检索速度小维度如 256/512适合大规模语料库1024/2048 则保留更高精度。5.4 返回结构与便捷方法doEmbed返回{ embeddings, chunkCounts }——所有 chunk 的向量被扁平化为一维数组chunkCounts记录每个文档包含多少个 chunk便于调用方还原分组。此外还提供了三个高封装方法contextualized-embedding.tsdoEmbedGrouped返回embeddingsByDocument按文档天然分组embedQuery(query)单条查询嵌入内部包装为[[query]]inputType: queryembedDocumentChunks(chunks)单文档多 chunk 嵌入内部包装为[chunks]inputType: document。实现上调用 SDK 的contextualizedEmbed方法返回结构为response.data[docIndex].data[chunkIndex].embedding代码会先按文档index排序再扁平化contextualized-embedding.ts。模型级限制为单次最多 1000 个输入、全部文档合计最多 16000 个 chunkcontextualized-embedding.ts。六、Reranker召回后的相关性重排6.1 定位与模型CHANGELOG 0.1.0 将 Reranker 描述为 “Rerankers (rerank-2.5 and rerank-2 families) implementingRelevanceScoreProvider”。它实现的是mastra/core中RelevanceScoreProvider接口包内为避免引入 core 依赖而自行声明了同名接口见 reranker.ts可无缝接入 Mastra 的重排体系。支持模型与上下文长度types.ts模型上下文长度定位rerank-2.532000最佳质量支持指令跟随rerank-2.5-lite32000延迟与质量均衡优化rerank-216000第二代多语言支持rerank-2-lite8000第二代延迟优化rerank-18000第一代质量优先rerank-lite-14000第一代延迟优化6.2 使用方式两种典型用法reranker.ts 与 reranker.ts 的示例import { VoyageRelevanceScorer, createVoyageReranker } from mastra/voyageai; import { rerank } from mastra/rag; // 方式一直接构造评分器与 mastra/rag 的 rerank 配合 const scorer new VoyageRelevanceScorer({ model: rerank-2.5 }); const rerankedResults await rerank(vectorResults, search query, scorer, { topK: 5 }); // 方式二接入向量查询工具 const reranker createVoyageReranker(rerank-2.5-lite); const tool createVectorQueryTool({ vectorStore, model: embedder, reranker: { model: reranker, options: { topK: 5 }, }, });VoyageRelevanceScorer提供两个核心方法getRelevanceScore(query, document)单条打分内部以topK: 1调用 SDKrerank接口并取出relevanceScorererankDocuments(query, documents, topK?)批量重排单次 API 调用即可完成全部文档打分reranker.ts比逐条打分更高效。七、baseUrl 自定义端点0.4.0 带来的关键能力7.1 为什么需要 baseUrlCHANGELOG 0.4.0 说明该选项的用途是“point the embedder, reranker, and contextualized models at a provider-hosted Voyage endpoint”——即把嵌入、重排、上下文模型全部指向第三方托管的 Voyage 兼容端点。典型场景是 MongoDB Atlas 等平台提供的https://ai.mongodb.com/v1这类托管入口。7.2 底层传递链路baseUrl的传递实现非常一致四个模块文本、多模态、上下文、Reranker的构造器都会把config.baseUrl透传给官方 SDK 客户端this.client new VoyageAIClient({ apiKey, ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}) });该行代码同时出现在 text-embedding.ts、multimodal-embedding.ts、contextualized-embedding.ts 与 reranker.ts。未提供baseUrl时该字段会从客户端选项中省略保持官方默认端点。测试用例对这条链路做了双重验证passes baseUrl through to the VoyageAIClient when provided断言baseUrl会原样传入客户端omits baseUrl from client options when not provided断言缺省时不传见tests/multimodal-embedding.test.ts文本侧同理见tests/text-embedding.test.ts。7.3 使用示例import { voyageEmbedding, voyageMultimodalEmbedding, createVoyageReranker } from mastra/voyageai; // 文本嵌入指向托管端点 const text voyageEmbedding({ model: voyage-3-large, baseUrl: https://ai.mongodb.com/v1, }); // 多模态嵌入指向托管端点 const multimodal voyageMultimodalEmbedding({ model: voyage-multimodal-3.5, baseUrl: https://ai.mongodb.com/v1, }); // Reranker 同样支持 const reranker createVoyageReranker({ model: rerank-2.5, baseUrl: https://ai.mongodb.com/v1 });八、预配置便捷对象 voyage 全览index.ts提供了开箱即用的voyage单例对象默认voyage-3.5内部通过惰性缓存lazy()按需创建模型实例避免在未设置VOYAGE_API_KEY时于导入阶段直接崩溃index.ts。这个设计在测试无 Key 环境下尤其重要。可用属性与 CHANGELOG 记录的能力一一对应文本模型V3voyage.v4large/voyage.v4/voyage.v4litevoyage-4 系列voyage.large/voyage.v35/voyage.v35lite/voyage.code/voyage.finance/voyage.lawvoyage-3 系列及领域模型。文本模型V2 兼容同名属性追加V2后缀如voyage.v35V2用于需要EmbeddingModelV2规范的旧场景。多模态模型voyage.multimodal3.5、voyage.multimodal3、voyage.multimodal35。上下文模型voyage.contextualized3、voyage.context3、voyage.context4。Rerankervoyage.reranker2.5、voyage.reranker25、voyage.reranker25lite、voyage.reranker2、voyage.reranker2lite。工厂函数voyage.embedding、voyage.embeddingV2、voyage.multimodalEmbedding、voyage.contextualizedEmbedding、voyage.createReranker。组合示例来自 index.tsimport { voyage } from mastra/voyageai; // 默认模型voyage-3.5 const result await voyage.doEmbed({ values: [Hello] }); // 指定模型 const largeResult await voyage.large.doEmbed({ values: [Hello] }); const codeResult await voyage.code.doEmbed({ values: [function foo() {}] }); // 多模态 const multimodalResult await voyage.multimodal.doEmbed({ values: [{ content: [{ type: text, text: Hello }] }] }); // 上下文感知 const contextResult await voyage.contextualized.doEmbed({ values: [[chunk1, chunk2]], inputType: document, });九、版本演进中的运维事项CHANGELOG 还记录了两个偏工程侧的变更值得升级时留意0.4.1减小 npm 包体积。发布物中移除了CHANGELOG.mdfiles字段仅保留dist见 embedders/voyageai/package.json同时 README 更新为准确的最新信息。升级到 0.4.1 以上可获得更小的安装体积。0.1.1供应链安全修复。该补丁版本用于规避 2026-06-17 “easy-day-js” 供应链事件发布干净版本并将latestdist-tag 前移取代了声明恶意easy-day-js依赖的受影响版本。如果你正在使用该时间段内发布的旧版本应尽快升级到 0.1.1 及以后的安全版本。十、源码结构速览与测试验证整个包结构清晰五个核心模块与测试一一对应embedders/voyageai/ ├── src/ │ ├── index.ts # 便捷对象 voyage 与全部导出 │ ├── text-embedding.ts # 文本嵌入V2/V3 token 感知批处理 │ ├── multimodal-embedding.ts # 多模态嵌入 │ ├── contextualized-embedding.ts # 上下文感知嵌入 │ ├── reranker.ts # Reranker / RelevanceScoreProvider │ ├── types.ts # 全部模型、配置与元数据定义 │ └── __tests__/ # 单测integration / multimodal / reranker / text-embedding ├── README.md └── package.json测试覆盖了本文讲到的全部关键行为批处理切分边界tests/text-embedding.test.ts、多模态类型化序列化tests/multimodal-embedding.test.ts、baseUrl透传tests/reranker.test.ts 及多模态/文本测试、providerOptions 运行时覆盖等。阅读这些测试是快速理解包内行为契约的最佳入口。结语从 CHANGELOG 的演进可以完整看到mastra/voyageai的设计脉络0.1.0 一次性建立文本/多模态/上下文/Reranker 四大能力骨架0.3.0 引入voyage-context-4与灵活维度强化上下文感知场景0.4.0 修复多模态裸字符串序列化 Bug 并新增baseUrl托管端点支持是用法层面的两个关键转折点。实践中最值得记住的三点文本嵌入由 SDKtokenize()驱动 token 感知分批多模态内容必须以类型化对象发送切勿传裸字符串以及baseUrl让同一套代码可以无缝切换到 MongoDB 等第三方托管端点。如需了解更完整的模型列表与参数映射可继续阅读 embedders/voyageai/README.md 并深入 embedders/voyageai/src/types.ts 中的元数据定义。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考