Embeddings

从文本和图像生成向量嵌入

原文链接：https://openrouter.ai/docs/api/reference/embeddings

Embeddings 是捕获语义含义的文本数值表示。它们将文本转换为向量（数字数组），可用于各种机器学习任务。OpenRouter 提供统一 API 来访问多个 providers 的 embedding 模型。

什么是 Embeddings？

Embeddings 将文本转换为高维向量，其中语义相似的文本在向量空间中靠得更近。例如，"cat" 和 "kitten" 将具有相似的 embeddings，而 "cat" 和 "airplane" 将相距甚远。

这些向量表示使机器能够理解文本片段之间的关系，使它们对许多 AI 应用程序至关重要。

常见用例

Embeddings 用于各种应用程序：

RAG (Retrieval-Augmented Generation)：构建 RAG 系统，在生成答案之前从知识库中检索相关上下文。Embeddings 帮助找到最相关的文档以包含在 LLM 的上下文中。

语义搜索：将文档和查询转换为 embeddings，然后通过比较向量相似性找到最相关的文档。这比传统关键字匹配提供更准确的结果，因为它理解含义而不仅仅是匹配单词。

推荐系统：为项目（产品、文章、电影）和用户偏好生成 embeddings 以推荐相似项目。通过比较 embedding 向量，你可以找到语义相关但没有明显共同关键字的项目。

聚类和分类：通过分析 embedding 模式将相似文档分组或将文本分类到类别中。具有相似 embeddings 的文档可能属于相同主题或类别。

重复检测：通过比较 embedding 相似性来识别重复或近乎重复的内容。即使文本被改述或改写，这也能工作。

异常检测：通过识别远离数据集中典型模式的 embeddings 来检测异常或异常内容。

如何使用 Embeddings

基本请求

要生成 embeddings，请向 /embeddings 发送 POST 请求，包含你的文本输入和选择的模型：

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

const openRouter = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const response = await openRouter.embeddings.generate({
  model: '{{MODEL}}',
  input: 'The quick brown fox jumps over the lazy dog',
});

console.log(response.data[0].embedding);

批处理

你可以通过传递字符串数组在单个请求中为多个文本生成 embeddings：

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

const openRouter = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const response = await openRouter.embeddings.generate({
  model: '{{MODEL}}',
  input: [
    'Machine learning is a subset of artificial intelligence',
    'Deep learning uses neural networks with multiple layers',
    'Natural language processing enables computers to understand text'
  ],
});

// Process each embedding
response.data.forEach((item, index) => {
  console.log(`Embedding ${index}: ${item.embedding.length} dimensions`);
});

图像输入

某些 embedding 模型支持图像输入，支持捕获视觉内容以及文本的多模态 embeddings。这对于图像搜索、视觉相似性和跨模态检索任务很有用。

要发送图像，请在 multimodal 格式中包装你的输入，包含 content 数组和 image_url 对象。你还可以在单个输入块中组合文本和图像。

import requests

response = requests.post(
  "https://openrouter.ai/api/v1/embeddings",
  headers={
    "Authorization": f"Bearer {{API_KEY_REF}}",
    "Content-Type": "application/json"
  },
  json={
    "model": "{{MODEL}}",
    "input": [
      {
        "content": [
          {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}}
        ]
      }
    ],
    "encoding_format": "float",
  }
)

data = response.json()
embedding = data["data"][0]["embedding"]
print(f"Embedding dimension: {len(embedding)}")

你还可以组合文本和图像在单个输入中生成联合 embedding。

可用模型

OpenRouter 提供对来自不同 providers 的各种 embedding 模型的访问。你可以在以下位置查看所有可用的 embedding 模型：

https://openrouter.ai/models?fmt=cards&output_modalities=embeddings

实用示例：语义搜索

以下是使用 embeddings 构建语义搜索系统的完整示例：

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

const openRouter = new OpenRouter({
  apiKey: '{{API_KEY_REF}}',
});

const documents = [
  "The cat sat on the mat",
  "Dogs are loyal companions",
  "Python is a programming language",
  "Machine learning models require training data",
  "The weather is sunny today"
];

function cosineSimilarity(a: number[], b: number[]): number {
  const dotProduct = a.reduce((sum, val, i) => sum + val * b[i], 0);
  const magnitudeA = Math.sqrt(a.reduce((sum, val) => sum + val * val, 0));
  const magnitudeB = Math.sqrt(b.reduce((sum, val) => sum + val * val, 0));
  return dotProduct / (magnitudeA * magnitudeB);
}

async function semanticSearch(query: string, documents: string[]) {
  const response = await openRouter.embeddings.generate({
    model: '{{MODEL}}',
    input: [query, ...documents],
  });

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

  const results = documents.map((doc, i) => ({
    document: doc,
    similarity: cosineSimilarity(
      queryEmbedding as number[],
      docEmbeddings[i].embedding as number[]
    ),
  }));

  results.sort((a, b) => b.similarity - a.similarity);
  return results;
}

const results = await semanticSearch("pets and animals", documents);
console.log("Search results:");
results.forEach((result, i) => {
  console.log(`${i + 1}. ${result.document} (similarity: ${result.similarity.toFixed(4)})`);
});

最佳实践

选择正确的模型：不同的 embedding 模型有不同的优势。较小的模型（如 qwen/qwen3-embedding-0.6b 或 openai/text-embedding-3-small）更快、更便宜，而较大的模型（如 openai/text-embedding-3-large）提供更好的质量。测试多个模型以找到最适合你用例的模型。

批处理你的请求：处理多个文本时，在单个请求中发送它们，而不是进行单独的 API 调用。这减少了延迟和成本。

缓存 Embeddings：相同文本的 embeddings 是确定性的（它们不会改变）。将 embeddings 存储在数据库或向量存储中以避免重复生成。

规范化比较：比较 embeddings 时，使用余弦相似性而不是欧几里得距离。余弦相似性是尺度不变的，对高维向量效果更好。

考虑上下文长度：每个模型都有最大输入长度（上下文窗口）。较长的文本可能需要分块或截断。在处理长文档之前检查模型的规格。

使用适当的分块：对于长文档，将它们分成有意义的块（段落、章节）而不是任意字符限制。这保留了语义连贯性。

Provider 路由

你可以使用 provider 参数控制哪些 providers 服务你的 embedding 请求。这对于：

确保特定 providers 的数据隐私
针对成本或延迟进行优化
使用 provider 特定功能

错误处理

你可能遇到的常见错误：

400 Bad Request：输入格式无效或缺少必需参数。检查你的 input 和 model 参数格式是否正确。

401 Unauthorized：API key 无效或缺失。验证你的 API key 正确并包含在 Authorization header 中。

402 Payment Required：积分不足。在你的 OpenRouter 账户中添加积分。

404 Not Found：指定的模型不存在或不可用于 embeddings。检查模型名称并验证它是一个 embedding 模型。

429 Too Many Requests：超过速率限制。实施指数退避和重试逻辑。

529 Provider Overloaded：provider 暂时过载。启用 allow_fallbacks: true 以自动使用备份 providers。

限制

无流式传输：与 chat completions 不同，embeddings 作为完整响应返回。不支持流式传输。
Token 限制：每个模型都有最大输入长度。超过此限制的文本将被截断或拒绝。
确定性输出：相同输入文本的 embeddings 将始终相同（无 temperature 或随机性）。
语言支持：某些模型针对特定语言进行了优化。检查模型文档以了解语言能力。