🚀 Vercel AI SDK Core 使用指南：向量嵌入 (Embeddings)

在构建 AI 应用（尤其是 RAG 检索增强生成系统）时，向量嵌入 (Embeddings) 是最核心的概念之一。它将文本转换为数字向量，使得我们可以通过数学方式（如余弦相似度）来计算文本之间的语义相关性。

Vercel AI SDK Core 提供了简洁且统一的 API 来处理嵌入任务，无论你使用的是 OpenAI、Mistral 还是 Google 的模型。

本文将带你详细了解如何使用 embed、embedMany 以及 cosineSimilarity 等核心功能。

📦 前置准备

确保你已经安装了 Vercel AI SDK 和相应的模型提供商 SDK（以 OpenAI 为例）：

Bash

npm install ai @ai-sdk/openai

1. 单个文本嵌入 (Embedding a Single Value)

如果你只需要为一个字符串生成向量（例如用户的搜索查询），可以使用 embed 函数。

代码示例

TypeScript

import { embed } from 'ai';
import { openai } from '@ai-sdk/openai';

async function main() {
  // 生成单个嵌入
  const { embedding, usage } = await embed({
    model: openai.embedding('text-embedding-3-small'),
    value: '阳光明媚的海滩',
  });

  console.log(`维度: ${embedding.length}`); // 例如: 1536
  console.log(`Token 使用量: ${usage.tokens}`);
  console.log(embedding); // 输出向量数组 [0.012, -0.003, ...]
}

main();

关键点：

• model: 指定使用的嵌入模型。
• value: 需要转换的文本字符串。
• embedding: 返回的数字数组（number[]）。
• usage: 返回本次操作消耗的 Token 数量，方便计费统计。

---

2. 批量文本嵌入 (Embedding Many Values)

在处理大量数据时（例如为知识库建立索引），使用 embedMany 效率更高。它能一次性发送多个文本，减少网络请求次数。

代码示例

TypeScript

import { embedMany } from 'ai';
import { openai } from '@ai-sdk/openai';

async function batchEmbed() {
  const { embeddings, usage } = await embedMany({
    model: openai.embedding('text-embedding-3-small'),
    values: [
      '阳光明媚的海滩',
      '城市里下雨的午后',
      '山间雪夜',
    ],
  });

  console.log(`生成了 ${embeddings.length} 个向量`);
  // embeddings 是一个二维数组 (number[][])
  // 顺序与输入的 values 数组一致
  console.log(`第一个向量的维度: ${embeddings[0].length}`);
}

batchEmbed();

---

3. 计算相似度 (Cosine Similarity)

生成向量的最终目的是为了比较它们。Vercel AI SDK 提供了一个极其方便的工具函数 cosineSimilarity 来计算两个向量的余弦相似度。

• 1.0: 完全相同
• 0: 完全无关
• -1.0: 完全相反

实战：简易语义搜索

TypeScript

import { embed, embedMany, cosineSimilarity } from 'ai';
import { openai } from '@ai-sdk/openai';

async function findMostSimilar() {
  const model = openai.embedding('text-embedding-3-small');

  // 1. 假设这是我们的知识库数据
  const dbData = [
    '如何使用 React Hooks',
    'Vue.js 组件生命周期',
    'Vercel AI SDK 的流式传输功能',
    '美味的红烧肉做法',
  ];

  // 2. 将知识库批量向量化
  const { embeddings: dbEmbeddings } = await embedMany({
    model,
    values: dbData,
  });

  // 3. 用户查询
  const userQuery = '我想学习前端框架';
  const { embedding: queryEmbedding } = await embed({
    model,
    value: userQuery,
  });

  // 4. 计算相似度并排序
  const results = dbData.map((item, index) => {
    const similarity = cosineSimilarity(queryEmbedding, dbEmbeddings[index]);
    return { item, similarity };
  })
  .sort((a, b) => b.similarity - a.similarity); // 降序排列

  // 5. 输出结果
  console.log(`查询: "${userQuery}"`);
  console.log('--- 匹配结果 ---');
  results.forEach(res => {
    console.log(`${res.similarity.toFixed(4)} - ${res.item}`);
  });
}

findMostSimilar();

---

4. 高级配置 (Advanced Settings)

自定义模型参数 (Provider Options)

有些模型（如 OpenAI 的新模型）允许你调整输出向量的维度以节省存储空间。

TypeScript

const { embedding } = await embed({
  model: openai.embedding('text-embedding-3-large'),
  value: '...',
  // 特定提供商的参数
  providerOptions: {
    openai: {
      dimensions: 512, // 强制缩减维度
    },
  },
});

错误重试与超时控制

生产环境中，网络波动是常态。你可以通过 maxRetries 和 abortSignal 来增强健壮性。

TypeScript

const { embedding } = await embed({
  model: openai.embedding('text-embedding-3-small'),
  value: '...',
  maxRetries: 3, // 最多重试 3 次（默认是 2）
  abortSignal: AbortSignal.timeout(5000), // 5秒后超时
});

5. 支持的模型与提供商 (Providers & Models)

Vercel AI SDK Core 的一大优势是中立性。你可以在不同的模型提供商之间无缝切换，只需更改两行代码。

以下是 SDK 原生支持的主流 Embedding 模型及其输出维度（Dimensions）。维度的数值非常重要，因为在使用向量数据库（如 Pinecone, Milvus, pgvector）建表时，必须指定与模型一致的维度。

主流模型参数速查表

提供商 (Provider)	模型名称 (Model ID)	输出维度 (Dimensions)
OpenAI	text-embedding-3-large	3072
	text-embedding-3-small	1536
	text-embedding-ada-002	1536
Google	text-embedding-004	768
	gemini-embedding-001	768 / 3072 (取决于任务类型)
Mistral	mistral-embed	1024
Cohere	embed-english-v3.0	1024
	embed-multilingual-v3.0	1024
	embed-english-light-v3.0	384
Amazon Bedrock	amazon.titan-embed-text-v2:0	1024
	amazon.titan-embed-text-v1	1536

如何切换提供商？

假设你想从 OpenAI 切换到 Google 的 Gemini 模型，只需更改导入和模型调用即可，其余业务逻辑完全不用动：

TypeScript

// 1. 更改导入
// import { openai } from '@ai-sdk/openai';
import { google } from '@ai-sdk/google'; 
import { embed } from 'ai';

async function main() {
  const { embedding } = await embed({
    // 2. 更改模型
    // model: openai.embedding('text-embedding-3-small'),
    model: google.embedding('text-embedding-004'), 
    value: '切换模型就是这么简单',
  });
  
  console.log(embedding.length); // 输出: 768
}

提示：在使用任何提供商之前，请确保已在环境变量（.env）中配置了对应的 API Key（例如 GOOGLE_GENERATIVE_AI_API_KEY 或 MISTRAL_API_KEY）。

---

总结

Vercel AI SDK Core 的 Embeddings API 极其精简，通过 embed 和 embedMany 两个函数即可覆盖绝大多数 RAG 和语义搜索的场景。配合 cosineSimilarity，你可以快速构建出具备语义理解能力的 AI 应用。

---

希望这篇教程对你有帮助！别忘了点赞关注，获取更多 AI 开发干货。