OpenRouter Embeddings API 提供统一接口访问多个提供商的向量模型，将文本（或图片）转换为高维向量用于语义搜索、RAG、推荐系统等场景。通过 /api/v1/embeddings 端点发送 POST 请求，支持单条文本、批量数组和多模态图文混合输入。本页包含完整的 API 用法、语义搜索示例代码，以及最佳实践和常见错误码。

OpenRouter Embeddings API

Embedding（向量化）将文本转换为高维数值向量，语义相近的文本在向量空间中距离更近。OpenRouter 提供统一接口访问来自不同提供商的 embedding 模型。

常见应用场景

• RAG（检索增强生成）：在生成前从知识库检索相关上下文，提升回答准确性
• 语义搜索：基于语义相似度而非关键词匹配来查找相关内容
• 推荐系统：通过比较向量相似度推荐语义相关的内容
• 聚类与分类：按语义相似度对文档进行分组或分类
• 重复检测：识别相同或近似内容，即使措辞不同也能命中
• 异常检测：识别与正常模式差异较大的内容

基本用法

向 /api/v1/embeddings 发送 POST 请求：

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({
  apiKey: '<OPENROUTER_API_KEY>',
});

const response = await openRouter.embeddings.generate({
  model: 'openai/text-embedding-3-small',
  input: '快速的棕色狐狸跳过了懒狗',
});

console.log(response.data[0].embedding); // 数值数组

批量处理

一次请求处理多条文本，减少延迟和成本：

const response = await openRouter.embeddings.generate({
  model: 'openai/text-embedding-3-small',
  input: [
    '机器学习是人工智能的子集',
    '深度学习使用多层神经网络',
    '自然语言处理让计算机理解文本',
  ],
});

response.data.forEach((item, index) => {
  console.log(`向量 ${index}: ${item.embedding.length} 维`);
});

图片输入（多模态）

部分模型支持图片输入，用于跨模态检索：

import requests

response = requests.post(
  "https://openrouter.ai/api/v1/embeddings",
  headers={"Authorization": f"Bearer <OPENROUTER_API_KEY>"},
  json={
    "model": "nvidia/llama-nemotron-embed-vl-1b-v2",
    "input": [
      {
        "content": [
          {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
      }
    ],
    "encoding_format": "float",
  }
)

完整示例：语义搜索

import { OpenRouter } from '@openrouter/sdk';

const openRouter = new OpenRouter({ apiKey: '<OPENROUTER_API_KEY>' });

// 余弦相似度计算
function cosineSimilarity(a: number[], b: number[]): number {
  const dot = a.reduce((sum, v, i) => sum + v * b[i], 0);
  const magA = Math.sqrt(a.reduce((sum, v) => sum + v * v, 0));
  const magB = Math.sqrt(b.reduce((sum, v) => sum + v * v, 0));
  return dot / (magA * magB);
}

async function semanticSearch(query: string, documents: string[]) {
  const response = await openRouter.embeddings.generate({
    model: 'openai/text-embedding-3-small',
    input: [query, ...documents],
  });

  const queryEmbedding = response.data[0].embedding as number[];
  const docEmbeddings = response.data.slice(1);

  return documents
    .map((doc, i) => ({
      document: doc,
      similarity: cosineSimilarity(queryEmbedding, docEmbeddings[i].embedding as number[]),
    }))
    .sort((a, b) => b.similarity - a.similarity);
}

查看可用模型

浏览全部 embedding 模型：

curl "https://openrouter.ai/api/v1/models?output_modalities=embeddings"

或通过 SDK：

const models = await openRouter.embeddings.listModels();
console.log(models.data);

最佳实践

建议	说明
选合适的模型	小模型（text-embedding-3-small）更快更便宜，大模型质量更高
批量处理	多条文本合并成一个请求，减少 API 调用次数
缓存 embedding	同一文本的 embedding 结果固定不变，存入数据库避免重复生成
用余弦相似度	比欧氏距离更适合高维向量对比
注意上下文长度	超长文本需要分块处理

限制

• 不支持流式传输：embedding 结果作为完整响应返回
• 有 token 上限：超过最大输入长度的文本会被截断或报错
• 确定性输出：相同输入始终产生相同向量，没有随机性

常见错误

错误码	原因	处理方式
400	输入格式错误或缺少必要参数	检查 input 和 model 格式
401	API key 无效	验证 key 是否正确
402	余额不足	充值后重试
404	模型不存在或不支持 embedding	检查模型名称，确认是 embedding 模型
429	速率限制	实现指数退避重试
529	提供商过载	设置 allow_fallbacks: true 自动切换

---

常见问题

Q: 怎么选择合适的 embedding 模型？

A: 从 text-embedding-3-small 开始，速度快且成本低，适合大多数场景。如果搜索精度不够再考虑更大的模型，建议在你的真实数据上做对比测试。

Q: 每次都要重新生成 embedding 吗？

A: 不需要。同一文本的 embedding 结果是固定的，建议存入向量数据库（如 Pinecone、Qdrant、pgvector），查询时直接用，不用重复调用 API。

Q: 支持中文输入吗？

A: 支持，大多数 embedding 模型支持多语言输入。text-embedding-3-small 对中文的支持较好，但部分较小的模型可能效果较差，建议测试。