企业官网建设流程全解析

使用 AI SDK 集成 Voyage AI：Embedding 向量化与 Rerank 重排实战指南

【免费下载链接】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-sdk/voyage是 AI SDK 官方提供的 Voyage AI Provider 集成包，它把 Voyage AI 的文本向量（Embedding）与重排（Reranking）能力封装为符合 AI SDK 统一规范（specificationVersion v4）的模型接口，让你可以用embedMany、rerank等标准 API 直接调用 Voyage 模型。读完本文，你将掌握该包的安装方式、Provider 初始化、Embedding 与 Rerank 两种能力的完整用法，以及底层请求结构、模型清单和可配置参数，能够直接在 RAG、语义检索与搜索精排场景中落地。

包安装与前置准备

Voyage AI Provider 发布在@ai-sdk/voyage模块下，安装命令与 packages/voyage/package.json 中声明的包名一致：

npm i @ai-sdk/voyage

安装完成后，需要准备 Voyage AI 的 API Key。从源码实现看，Provider 在构造请求头时通过loadApiKey读取密钥，其读取顺序是：优先使用初始化时显式传入的apiKey，否则从环境变量VOYAGE_API_KEY读取（见 voyage-provider.ts）。因此最简配置是设置环境变量：

export VOYAGE_API_KEY=your-voyage-api-key

该包的运行环境要求 Node.js>= 22（见 package.json），并依赖zod作为 peer dependency（支持^3.25.76 || ^4.1.8）。源码中请求体的序列化与响应解析正是基于 zod schema 完成的。

如果你使用 Claude Code、Cursor 等编码 Agent 开发本项目，官方还推荐把 AI SDK 技能加入仓库以辅助开发：

npx skills add vercel/ai

创建 Provider 实例

@ai-sdk/voyage默认导出一个开箱即用的 Provider 实例voyage：

import { voyage } from '@ai-sdk/voyage';

该实例由createVoyage()在包内部创建（见 voyage-provider.ts）。如果你的场景需要自定义配置（例如使用代理网关、覆盖默认 API 地址、注入自定义请求头或替换 fetch 实现），可以使用createVoyage手动创建：

import { createVoyage } from '@ai-sdk/voyage'; const voyage = createVoyage({ // 可选：自定义 API 基础地址，默认为 https://api.voyageai.com/v1 baseURL: 'https://api.voyageai.com/v1', // 可选：显式指定 API Key（否则读 VOYAGE_API_KEY 环境变量） apiKey: 'your-voyage-api-key', // 可选：附加的自定义请求头 headers: { 'X-Custom-Header': 'value' }, // 可选：自定义 fetch 函数（用于代理、日志、重试等） fetch: (...args) => fetch(...args), });

从源码看，createVoyage的完整配置项定义在VoyageProviderSettings中（voyage-provider.ts），各字段含义如下：

每次请求都会自动带上Authorization: Bearer <apiKey>，并在 User-Agent 中追加ai-sdk/voyage/<version>标识（便于服务端识别 SDK 版本）。需要说明的是，Voyage Provider 仅提供 Embedding 与 Reranking 两类模型能力——在 voyage-provider.ts 中，languageModel与imageModel会直接抛出NoSuchModelError，这符合 Voyage AI 的产品定位（不提供对话/图像生成模型）。

Embedding：文本向量化

基础用法

Voyage 的向量模型通过embedMany使用。包内为 Embedding 模型提供了四个等价的访问方法：embedding、embeddingModel、textEmbedding、textEmbeddingModel，它们都指向同一个创建函数（见 voyage-provider.ts），可按个人偏好选择。

以官方 README 中的示例为基础：

import { voyage } from '@ai-sdk/voyage'; import { embedMany } from 'ai'; const { embeddings } = await embedMany({ model: voyage.textEmbedding('voyage-3'), values: [ 'Sunny days are great for hiking', 'Machine learning is a subset of AI', ], });

embeddings是与values一一对应的二维数组（每个文本对应一个数值向量），可以直接存入向量数据库用于语义检索。单次调用对输入的values数量存在上限：源码中VoyageEmbeddingModel声明了maxEmbeddingsPerCall = 128，当传入超过 128 条文本时会抛出TooManyEmbeddingValuesForCallError（见 voyage-embedding-model.ts）；同时该模型支持并行调用（supportsParallelCalls = true），配合 AI SDK 可对大批量文本自动并发切分。

支持的 Embedding 模型

模型 ID 的完整类型定义在 voyage-embedding-model-options.ts 中，当前内置的模型 ID 包括：

• 通用旗舰/均衡系列：voyage-4-large、voyage-4、voyage-4-lite、voyage-4-nano、voyage-3-large、voyage-3.5、voyage-3.5-lite、voyage-3、voyage-3-lite、voyage-2
• 代码向量系列：voyage-code-3.5、voyage-code-3、voyage-code-2
• 领域专用系列：voyage-finance-2（金融）、voyage-law-2（法律）、voyage-multilingual-2（多语言）

类型定义还包含(string & {})兜底，意味着也允许传入未被枚举的最新模型 ID，便于在 SDK 发布新模型前先行使用。

Embedding 请求参数与底层结构

通过embedMany的providerOptions（命名空间voyage）可以透传 Voyage 特有的参数。这些参数由 zod schema 校验，完整定义见 voyage-embedding-model-options.ts：

实际使用时，把参数放在providerOptions.voyage下：

const { embeddings } = await embedMany({ model: voyage.textEmbedding('voyage-3'), values: ['需要检索的文档内容'], providerOptions: { voyage: { inputType: 'document', outputDtype: 'binary', }, }, });

在底层，doEmbed会把上述参数序列化为对POST {baseURL}/embeddings的 JSON 请求，请求体结构为{ input, model, input_type, truncation, output_dimension, output_dtype }（见 voyage-embedding-model.ts）。响应解析使用 zod schema 校验data（按index排序后提取embedding）与usage.total_tokens，因此embedMany的返回值会同时携带embeddings、usage.tokens以及完整的原始response。测试用例（voyage-embedding-model.test.ts）验证了向量提取、usage 统计、input_type透传与原始响应暴露等行为，可作为理解返回结构的参考。

Reranking：检索结果精排

基础用法

除向量化外，Voyage Provider 还提供重排（Rerank）模型。使用方式与 Embedding 类似，通过reranking或rerankingModel方法获取模型：

import { voyage } from '@ai-sdk/voyage'; import { rerank } from 'ai'; const { ranking } = await rerank({ model: voyage.rerankingModel('rerank-2.5'), query: 'rainy day', documents: ['Sunny days are great for hiking', 'Rainy days are great for reading'], topN: 1, });

ranking是重排结果数组，每个元素包含index（对应documents的原始下标）与relevanceScore（相关性分数），按相关度从高到低排列。典型场景是把向量检索召回的 Top-K 候选文档交给重排模型做精细化排序，从而提升 RAG 或搜索系统的最终质量。

支持的重排模型

重排模型 ID 定义在 voyage-reranking-model-options.ts 中：

• rerank-2.5、rerank-2.5-lite
• rerank-2、rerank-2-lite
• rerank-1、rerank-lite-1

同样支持(string & {})兜底以兼容更新模型。

重排参数与底层结构

重排模型的 providerOptions（命名空间voyage）支持两个参数：

底层请求会发送到POST {baseURL}/rerank，请求体为{ query, documents, model, top_k, return_documents, truncation }（见 voyage-reranking-model.ts），其中topN由 AI SDK 的rerank参数映射为top_k。

一个值得注意的实现细节：当documents以对象（object）类型传入时，SDK 会将其JSON.stringify为字符串后再发送（因为 Voyage API 要求文档为字符串），同时返回一个compatibility类型的 warning 说明这一转换行为（见 voyage-reranking-model.ts）。测试用例（voyage-reranking-model.test.ts）验证了对象文档的字符串化请求体、鉴权请求头以及带 warning 的返回结果，可直接查阅对照。

错误处理与响应约定

当 Voyage API 返回非 2xx 状态码时，SDK 通过统一的错误处理器解析响应体中的detail字段作为错误信息（见 voyage-error.ts），并包装为 AI SDK 的标准错误对象抛出，因此你可以用常规的try/catch捕获网络错误、鉴权失败、参数校验错误等异常，无需针对 Voyage 单独处理响应格式。

此外，doEmbed与doRerank的返回值中都包含完整的原始response（含响应头与响应体），便于你在需要自定义日志、监控或调试时直接访问底层 HTTP 信息。

从零到一的完整示例

综合以上内容，一个完整的 RAG 场景代码示例如下：

import { createVoyage } from '@ai-sdk/voyage'; import { embedMany, rerank } from 'ai'; // 1. 创建 Provider（也可直接用默认实例 voyage） const voyage = createVoyage({ apiKey: process.env.VOYAGE_API_KEY }); // 2. 文档入库：批量向量化（记得设置 inputType: 'document'） const { embeddings, usage } = await embedMany({ model: voyage.textEmbedding('voyage-3'), values: [ 'Sunny days are great for hiking', 'Machine learning is a subset of AI', 'Rainy days are great for reading', ], providerOptions: { voyage: { inputType: 'document' } }, }); console.log('向量维度:', embeddings[0].length, '| 消耗 tokens:', usage.tokens); // 3. 检索精排：对候选文档按查询相关性重排 const { ranking } = await rerank({ model: voyage.rerankingModel('rerank-2.5'), query: 'how is AI related to machine learning?', documents: [ 'Sunny days are great for hiking', 'Machine learning is a subset of AI', 'Rainy days are great for reading', ], topN: 2, }); console.log('重排结果:', ranking); // 按相关性降序

深入阅读

• 包的入口与公开类型导出见 packages/voyage/src/index.ts：对外导出voyage、createVoyage、VoyageProvider、VoyageProviderSettings、VoyageEmbeddingModelOptions、VoyageRerankingModelOptions等。
• Embedding 模型完整实现见 voyage-embedding-model.ts，含请求构造、响应解析与 128 条/次上限。
• Rerank 模型完整实现见 reranking/voyage-reranking-model.ts，含对象文档转换与 warning 机制。
• 测试用例见 voyage-embedding-model.test.ts 与 reranking/voyage-reranking-model.test.ts，其中使用了src/__fixtures__/voyage-embedding.json与src/reranking/__fixtures__/voyage-reranking.1.json作为真实响应样例。
• 该包的发布历史与版本变更记录见 packages/voyage/CHANGELOG.md。

整体而言，@ai-sdk/voyage的价值在于把 Voyage AI 的向量与重排能力无缝接入 AI SDK 的统一抽象：Embedding 用于离线建库与在线召回，Rerank 用于结果精排，两者配合即可搭建一条完整的高质量语义检索链路，且全程享受 AI SDK 的类型提示、流式与错误处理等标准能力。

【免费下载链接】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