Voyage AI 免费额度怎么领：每个模型赠 200M tokens，向量化与重排通用

接口形态与 base_url

Voyage AI 只提供向量化（Embedding）与重排（Rerank）两类接口，没有对话补全（chat completions）接口，因此不存在可以直接替换 OpenAI 聊天端点的兼容层。它的 base_url 形如 https://api.voyageai.com/v1，常用路径为 /embeddings、/rerank、/multimodalembeddings。如果你在代码里用 OpenAI SDK，需要把聊天请求继续发往其他提供对话模型的厂商 base_url，只把向量化和重排请求交给 Voyage AI。

先把密钥写入环境变量，后文命令都从这里读取：

export VOYAGE_API_KEY="你的密钥"

常用模型名

• 向量化：voyage-4-large（效果优先）、voyage-4（通用）、voyage-4-lite（成本与延迟优先）、voyage-context-4（长上下文文档）、voyage-code-4（代码检索）。
• 重排：rerank-3 系列，用于对初筛出的候选文档做二次排序。
• 模型清单会随版本更新，以控制台或官方文档当前列出的名称为准，写死模型名时建议加注释记录获取时间。

一次向量化调用

下面是直接可用的 curl 示例，input 支持字符串数组，一次批量提交多条文本可以减少往返开销：

curl https://api.voyageai.com/v1/embeddings \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-4",
    "input": ["Voyage AI 提供向量化与重排服务", "RAG 场景需要先做文档切分"],
    "input_type": "document"
  }'

Python 侧用官方 SDK 更省事，注意查询与文档要用不同的 input_type，否则检索效果会明显下降：

import os
from voyageai import Client

client = Client(api_key=os.environ["VOYAGE_API_KEY"])

result = client.embed(
    texts=["如何选择向量模型", "Voyage AI 的 voyage-4 适合通用检索"],
    model="voyage-4",
    input_type="query",
)
print(len(result.embeddings), len(result.embeddings[0]))
print(result.total_tokens)

一次重排调用

重排接口接收一个查询和一批候选文档，返回按相关度排序后的索引与分数：

curl https://api.voyageai.com/v1/rerank \
  -H "Authorization: Bearer $VOYAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-3",
    "query": "免费额度怎么领取",
    "documents": [
      "注册后在控制台创建密钥即可使用赠送额度",
      "周末的天气适合出门散步",
      "批量接口按折扣价计费"
    ],
    "top_k": 2
  }'

关键参数说明

• model：必填，决定扣减哪一份免费额度，也决定向量维度。
• input：必填，文本数组或单条字符串；单次请求的条数与总 token 数有上限，超限会直接报错，长文档请先切分。
• input_type：取 query 或 document，建索引用 document，检索提问用 query，两者必须一致配对使用。
• output_dimension：可选，降维可省存储，但建库与查询必须使用同一维度，中途修改需要重建索引。
• truncation：控制超长输入是截断还是报错，建议显式打开截断避免批量任务中断。
• top_k（重排）：返回的候选数量，按业务需要设置，不必等于输入文档数。

额度耗尽与限流的典型表现

常见报错依次是：HTTP 401 表示密钥错误或未激活；HTTP 400 多为模型名拼错、input_type 传了非法值或单批文本过长；HTTP 429 表示触发速率限制；HTTP 402 或 403 且响应中带有额度相关字样，说明该模型的免费 tokens 已用完。排查顺序建议是：先在控制台用量页确认对应模型的剩余额度，再核对密钥是否来自同一账户，然后检查模型名与参数，接着看 429 响应的重试间隔并按指数退避重试，最后确认是否误把大批量任务走了 Batch API 而产生了计费。若确实需要继续压测，请在控制台配置支付方式转为付费，不要依赖免费额度做长期生产流量。