venice-embeddings

Venice Embeddings

POST /api/v1/embeddings 为字符串返回向量嵌入。它兼容 OpenAI：请求和响应与 https://api.openai.com/v1/embeddings 足够相似，因此 OpenAI SDK 可以搭配 baseURL: "https://api.venice.ai/api/v1" 使用，只有一个例外：不接受令牌 ID 数组（见下文）。

身份验证：Bearer API 密钥或 x402 钱包（SIGN-IN-WITH-X）——参见 venice-auth。

适用场景

• 构建检索 / RAG / 相似度搜索。
• 需要文本聚类、分类、去重或重排功能。
• 希望使用 Venice 运行的 Private 模型（目录中的大多数模型）生成嵌入，而不是使用匿名化的第三方模型——请检查各模型的 model_spec.privacy。

仅支持文本：input 必须是字符串或字符串数组。对于图像，请先通过视觉聊天模型处理图像并生成描述，再对描述生成嵌入。

最简请求

curl https://api.venice.ai/api/v1/embeddings \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  --compressed \
  -d '{
    "model": "text-embedding-bge-m3",
    "input": "Why is the sky blue?"
  }'

{
  "object": "list",
  "model": "text-embedding-bge-m3",
  "data": [
    { "object": "embedding", "index": 0, "embedding": [0.0023, -0.0093, 0.0158, ...] }
  ],
  "usage": { "prompt_tokens": 8, "total_tokens": 8 }
}

请求架构

请求体采用严格校验——不认识的顶层字段（例如 input_type、task、truncate）会被拒绝，并返回 400。

字段	类型	说明
model	string	必填。 来自 GET /models?type=embedding 的模型 ID。text-embedding-ada-002 可作为 text-embedding-bge-m3 的别名使用（此时响应中的 model 会显示为 text-embedding-bge-m3）。
input	string | string[]	必填。 非空字符串，或包含 1–2048 个字符串的数组。令牌 ID 数组（number[] / number[][]）会被拒绝并返回 400——参见注意事项。
encoding_format	"float" | "base64"	默认值为 "float"。"base64" 会将每个向量作为 base64 编码字符串返回，数据量小得多；请在客户端解码。
dimensions	integer ≥ 1	可选。请求的输出维度。仅当模型的 model_spec.supportsCustomDimensions 为 true 时才会生效；否则会原样转发，服务提供方可能忽略或拒绝该字段。
user	string	为兼容 OpenAI 而接受；不用于推理，但会按不同值拆分错误预算（参见 venice-errors）。

输入限制

• 每个条目： Venice 按 ceil(chars / 3.2 × 0.95) 估算令牌数，任何字符串超过 8192 个估算令牌（约 27,500 个字符）都会被拒绝，并返回 400 "Input text exceeds the maximum token limit of 8192 tokens"。此上限适用于所有模型，包括 maxInputTokens 为 32768 的模型。
• 模型限制： model_spec.maxInputTokens 较小的模型（例如 text-embedding-multilingual-e5-large-instruct 为 512，gemini-embedding-2-preview 为 2048）会自行执行该限制；Venice 的预检查不会执行。请按模型的 maxInputTokens 对输入分块。
• 批次： 每个请求最多包含 2048 个字符串。Venice 会按顺序为每个元素返回一个嵌入，并提供对应的 index。

响应头与压缩

发送 Accept-Encoding: gzip, br（curl：--compressed；大多数 HTTP 客户端会自动解码）；响应会设置 Content-Encoding。对于大型批次，这很重要——JSON 中的浮点向量数据量很大。

还会返回：

• x-ratelimit-limit-* / x-ratelimit-remaining-* / x-ratelimit-reset-*（requests、tokens）——参见 venice-errors。
• x-venice-balance-usd / x-venice-balance-diem——当前余额，仅在余额非零时返回。
• X-Balance-Remaining——规范中列出了该字段，供 x402 调用方使用，但服务器目前不会设置；请改为轮询 GET /x402/balance/{walletAddress}。

使用 OpenAI SDK

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: process.env.VENICE_API_KEY,
  baseURL: 'https://api.venice.ai/api/v1',
})

const res = await client.embeddings.create({
  model: 'text-embedding-bge-m3',
  input: ['first doc', 'second doc'],
})

const vec0 = res.data[0].embedding

如果未指定 encoding_format，OpenAI Node SDK 会请求 base64 并在客户端解码。Venice 会将 encoding_format 转发给模型；如果解码后的向量看起来不正确，请显式传入 encoding_format: 'float'。

LangChain

LangChain 的 OpenAIEmbeddings 默认会对输入进行分词，并发送令牌数组，而 Venice 会拒绝这种输入。关闭此功能：

import os
from langchain_openai import OpenAIEmbeddings

emb = OpenAIEmbeddings(
    model="text-embedding-bge-m3",
    base_url="https://api.venice.ai/api/v1",
    api_key=os.environ["VENICE_API_KEY"],
    check_embedding_ctx_length=False,
)

未设置此标志、且内部构建 OpenAIEmbeddings 的封装（例如 gpt-researcher 的 openai 提供商）也会遇到相同的 400 错误。

批量嵌入模式

async function embedBatch(texts: string[], batchSize = 64) {
  const out: number[][] = []
  for (let i = 0; i < texts.length; i += batchSize) {
    const slice = texts.slice(i, i + batchSize)
    const res = await client.embeddings.create({
      model: 'text-embedding-bge-m3',
      input: slice,
      encoding_format: 'float',
    })
    for (const row of res.data) out[i + row.index] = row.embedding
  }
  return out
}

• 每个字符串都要低于上述单项限制；批次大小上限为 2048。
• 遇到 429 时，采用指数退避并将批次大小减半 — 参见 venice-errors。

选择模型

查询 GET /models?type=embedding 获取当前目录。每个条目的 model_spec 都会公开以下信息：

• embeddingDimensions — 原生输出维度（例如，text-embedding-bge-m3 为 1024，text-embedding-qwen3-8b 为 4096）。
• maxInputTokens — 模型对每个输入的令牌数限制。
• supportsCustomDimensions — 仅在支持 dimensions 的模型中存在且值为 true（其他模型中不存在）。
• privacy — "private"（不保留数据）或 "anonymized"（第三方模型；请求不包含你的身份信息）。
• pricing.input / pricing.output — 每百万令牌的 { usd, diem } 价格。

有代表性的 ID：text-embedding-bge-m3（private，1024 维）、text-embedding-qwen3-8b（private，4096 维，支持自定义维度）、text-embedding-multilingual-e5-large-instruct（private，输入上限为 512 个令牌）、text-embedding-3-small / text-embedding-3-large（anonymized，OpenAI，支持自定义维度）、gemini-embedding-2-preview（anonymized，支持自定义维度）。列表会变化 — 始终从 /models 读取。

始终固定模型 ID — 不同嵌入模型之间的余弦距离不可比较。

错误处理

代码	含义
400	缺少 model，或出现验证错误（details 会标明字段）：令牌数组输入、空字符串/数组、超过 2048 个条目、单项超过 8192 个令牌的估算限制、未知字段。非 JSON Content-Type → "'Content-Type' must be 'application/json'"。也包括模型端拒绝（例如输入超过模型自身的限制）；如果能提取到模型返回的信息，就会附上该信息，否则返回通用的 "Invalid request parameters…"。
401	API 密钥或 SIWX 签名无效。
402	余额不足，或达到密钥的 USD/DIEM 消费限额。Bearer → "Insufficient USD or Diem balance…"；x402 → 付款要求响应正文 + PAYMENT-REQUIRED 标头。完全没有凭据的请求也会收到 402（x402 发现质询），而非 401。
403	API 密钥的 modelPrivacy 为 PRIVATE_TEXT 或 PRIVATE_ONLY，且模型为 anonymized。也可能是区域/提供商限制，或账户已禁用 API 访问。
404	未知模型（消息中可能会建议一个相近的匹配项）。
429	请求过于频繁，受到速率限制。
500	推理失败；使用随机抖动后重试。
503	模型暂时离线；稍后重试。

注意事项

• 不接受令牌数组。 input: [101, 2023, ...] 或 [[101, ...]] 会返回 400 "Token array inputs are not supported. Pass a string or an array of strings."。请发送文本。
• 嵌入也受 API 密钥隐私设置约束。 modelPrivacy: PRIVATE_TEXT（或 PRIVATE_ONLY）的密钥只能调用 private 嵌入模型；text-embedding-3-* 和 gemini-embedding-2-preview 会返回 403。参见 venice-api-keys。
• 顶层空字符串会被拒绝并返回 400，但数组内部的空字符串不会预先检查 — 请自行过滤。
• 请求必须使用 Content-Type: application/json；其他值都会在身份验证或验证开始前被拒绝，并返回 400 "'Content-Type' must be 'application/json'"。
• 返回向量是否经过 L2 归一化取决于模型 — 在假定已归一化前，请使用 Math.hypot(...v) ≈ 1 验证。
• 对于 RAG，请将 model（以及设置时的 dimensions）与每个向量一同存储，以便升级时重新生成嵌入。