跳至主要內容

Voyage AI

https://docs.voyageai.com/embeddings/

API 金鑰​

# env variable
os.environ['VOYAGE_API_KEY']

範例用法 - Embedding​

from litellm import embedding
import os

os.environ['VOYAGE_API_KEY'] = ""
response = embedding(
    model="voyage/voyage-3.5",
    input=["good morning from litellm"],
)
print(response)

支援的參數​

VoyageAI embeddings 支援以下可選參數：

  • input_type：指定用於檢索最佳化的輸入類型
    • "query"：用於搜尋查詢
    • "document"：用於要建立索引的文件
  • dimensions：輸出 embedding 維度（256、512、1024 或 2048）
  • encoding_format：輸出格式（"float"、"int8"、"uint8"、"binary"、"ubinary"）
  • truncation：是否將超過最大 token 數的輸入截斷（預設：True）

含參數的範例​

from litellm import embedding
import os

os.environ['VOYAGE_API_KEY'] = "your-api-key"

# Embedding with custom dimensions and input type
response = embedding(
    model="voyage/voyage-3.5",
    input=["Your text here"],
    dimensions=512,
    input_type="document"
)
print(f"Embedding dimensions: {len(response.data[0]['embedding'])}")

支援的模型​

此處列出的所有模型 https://docs.voyageai.com/embeddings/#models-and-specifics 都支援

模型名稱函式呼叫
voyage-4-largeembedding(model="voyage/voyage-4-large", input)
voyage-4embedding(model="voyage/voyage-4", input)
voyage-4-liteembedding(model="voyage/voyage-4-lite", input)
voyage-code-4embedding(model="voyage/voyage-code-4", input)
voyage-context-4embedding(model="voyage/voyage-context-4", input)
voyage-context-3embedding(model="voyage/voyage-context-3", input)
voyage-3.5embedding(model="voyage/voyage-3.5", input)
voyage-3.5-liteembedding(model="voyage/voyage-3.5-lite", input)
voyage-3-largeembedding(model="voyage/voyage-3-large", input)
voyage-3embedding(model="voyage/voyage-3", input)
voyage-3-liteembedding(model="voyage/voyage-3-lite", input)
voyage-code-3embedding(model="voyage/voyage-code-3", input)
voyage-finance-2embedding(model="voyage/voyage-finance-2", input)
voyage-law-2embedding(model="voyage/voyage-law-2", input)
voyage-code-2embedding(model="voyage/voyage-code-2", input)
voyage-multilingual-2embedding(model="voyage/voyage-multilingual-2", input)
voyage-large-2-instructembedding(model="voyage/voyage-large-2-instruct", input)
voyage-large-2embedding(model="voyage/voyage-large-2", input)
voyage-2embedding(model="voyage/voyage-2", input)
voyage-lite-02-instructembedding(model="voyage/voyage-lite-02-instruct", input)
voyage-01embedding(model="voyage/voyage-01", input)
voyage-lite-01embedding(model="voyage/voyage-lite-01", input)
voyage-lite-01-instructembedding(model="voyage/voyage-lite-01-instruct", input)

情境式嵌入（voyage-context-4, voyage-context-3）​

Voyage 的 voyage-context-4 和 voyage-context-3 模型會產生具情境化的區塊嵌入：每個區塊都會在知道其來源整份文件的情況下進行嵌入，因此在長文件上的擷取效果比只單獨嵌入區塊更好。LiteLLM 會將名稱中包含 context 的任何 Voyage 模型送至 Voyage 的 /v1/contextualizedembeddings 端點，因此相同的 embedding() 呼叫與 /v1/embeddings 代理路由都可運作；只有輸入與回應形狀與一般模型不同

輸入形狀​

平坦的字串清單，或單一字串，會將每個字串作為各自的文件進行嵌入。LiteLLM 會連同 enable_auto_chunking: true、chunk_size: 32000 與 input_type: "document" 一併轉送，因此最多 32,000 token 的字串會作為一個嵌入傳回，而更長的字串會在 Voyage 端被切分成最多 32,000 token 的區塊。傳送 input_type: "query" 會跳過這些預設值，並將每個字串作為搜尋查詢進行嵌入。您自行傳入的任何 input_type、chunk_size 或 enable_auto_chunking 都會取代預設值

from litellm import embedding
import os

os.environ['VOYAGE_API_KEY'] = "your-api-key"

# Each string is embedded as its own document
response = embedding(
    model="voyage/voyage-context-4",
    input=["The quick brown fox", "jumps over the lazy dog"],
)
print(f"Documents embedded: {len(response.data)}")

# Search queries
response = embedding(
    model="voyage/voyage-context-4",
    input=["what does the fox do", "who is lazy"],
    input_type="query",
)

巢狀清單是預先切塊的形式：每個內層清單是一份您已經切成區塊的文件，而 LiteLLM 會保持原樣轉送

# Single document with multiple chunks
response = embedding(
    model="voyage/voyage-context-4",
    input=[
        [
            "Chapter 1: Introduction to AI",
            "This chapter covers the basics of artificial intelligence.",
            "We will explore machine learning and deep learning."
        ]
    ]
)
print(f"Number of chunk groups: {len(response.data)}")

# Multiple documents
response = embedding(
    model="voyage/voyage-context-4",
    input=[
        ["Paris is the capital of France.", "It is known for the Eiffel Tower."],
        ["Tokyo is the capital of Japan.", "It is a major economic hub."]
    ]
)
print(f"Processed {len(response.data)} documents")

回應形狀​

回應會保留 Voyage 的巢狀版面：data 對應每個輸入各有一個項目，而該項目的 data 則包含每個區塊的一個嵌入。response.data[0]["data"][0]["embedding"] 是第一個輸入的第一個區塊；在平坦輸入與預設區塊大小下，這就是整個字串

LiteLLM Proxy​

將模型加入 config.yaml：

model_list:
  - model_name: voyage-context-4
    litellm_params:
      model: voyage/voyage-context-4
      api_key: os.environ/VOYAGE_API_KEY

平坦清單，每個字串一份文件：

curl http://localhost:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-context-4",
    "input": ["The quick brown fox", "jumps over the lazy dog"]
  }'

平坦清單作為搜尋查詢：

curl http://localhost:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-context-4",
    "input": ["what does the fox do", "who is lazy"],
    "input_type": "query"
  }'

巢狀清單，每份文件已切分為區塊：

curl http://localhost:4000/v1/embeddings \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-context-4",
    "input": [["The quick brown fox", "jumps over the lazy dog"]]
  }'

規格​

模型最適合Context 長度價格/百萬 Tokens
voyage-context-4每個區塊 32,000 token；每個請求 120,000 token、1,000 個輸入、16,000 個區塊256、512、1024（預設）、2048$0.12
voyage-context-3每個區塊 32,000 token；每個請求 120,000 token、1,000 個輸入、16,000 個區塊256、512、1024（預設）、2048$0.18

限制以 Voyage 的為準，來自 https://docs.voyageai.com/docs/contextualized-chunk-embeddings，而每個請求的 token 總數會計算呼叫中的每個區塊

何時使用情境式嵌入​

當您將長文件切成區塊，且周遭文件應該影響每個區塊的嵌入時，請選用 voyage-context-4，因為結構、章節參照以及跨區塊依賴都很重要。對於彼此獨立的文字片段與短查詢，則請選用 voyage-4-large、voyage-4 或 voyage-4-lite；在這些情況下，文件情境無助於提升效果，而標準模型更便宜且更快

模型選擇指南​

模型最適合用於Context 長度價格/百萬 Tokens
voyage-4-large整體最佳且多語言品質最佳32K$0.12
voyage-4通用、多語言32K$0.06
voyage-4-lite對延遲敏感的應用程式32K$0.02
voyage-code-4程式碼擷取與編碼代理程式32K$0.12
voyage-context-4情境式文件嵌入每個區塊 32K，每個請求 120K$0.12
voyage-3.5通用、多語言32K$0.06
voyage-3.5-lite對延遲敏感的應用程式32K$0.02
voyage-3-large整體品質最佳32K$0.18
voyage-code-3程式碼擷取與搜尋32K$0.18
voyage-finance-2金融文件32K$0.12
voyage-law-2法律文件16K$0.12
voyage-context-3情境式文件嵌入每個區塊 32K，每個請求 120K$0.18

重新排序​

Voyage AI 提供 reranking 模型，會根據文件與查詢的相關性重新排序文件，以提升搜尋相關性。

快速開始​

from litellm import rerank
import os

os.environ["VOYAGE_API_KEY"] = "your-api-key"

response = rerank(
    model="voyage/rerank-2.5",
    query="What is the capital of France?",
    documents=[
        "Paris is the capital of France.",
        "London is the capital of England.",
        "Berlin is the capital of Germany.",
    ],
    top_n=3,
)

print(response)

非同步用法​

from litellm import arerank
import os
import asyncio

os.environ["VOYAGE_API_KEY"] = "your-api-key"

async def main():
    response = await arerank(
        model="voyage/rerank-2.5-lite",
        query="Best programming language for beginners?",
        documents=[
            "Python is great for beginners due to simple syntax.",
            "JavaScript runs in browsers and is versatile.",
            "Rust has a steep learning curve but is very safe.",
        ],
        top_n=2,
    )
    print(response)

asyncio.run(main())

LiteLLM Proxy 用法​

新增到您的 config.yaml：

model_list:
  - model_name: rerank-2.5
    litellm_params:
      model: voyage/rerank-2.5
      api_key: os.environ/VOYAGE_API_KEY
  - model_name: rerank-2.5-lite
    litellm_params:
      model: voyage/rerank-2.5-lite
      api_key: os.environ/VOYAGE_API_KEY

使用 curl 測試：

curl http://localhost:4000/rerank \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "rerank-2.5",
    "query": "What is the capital of France?",
    "documents": [
        "Paris is the capital of France.",
        "London is the capital of England.",
        "Berlin is the capital of Germany."
    ],
    "top_n": 3
  }'

支援的 Rerank 模型​

模型內容長度說明每百萬 Token 價格
rerank-2.532K品質最佳、多語言、遵循指令$0.05
rerank-2.5-lite32K針對延遲與成本最佳化$0.02
rerank-216K舊版模型$0.05
rerank-2-lite8K舊版模型、更快$0.02

支援的參數​

參數型別說明
modelstring模型名稱（例如，voyage/rerank-2.5）
querystring搜尋查詢
documentslist要重新排序的文件清單
top_nint要回傳的前幾個結果數量
return_documentsbool是否在回應中包含文件文字
LiteLLM Enterprise
為正式環境打造的 SSO/SAML、稽核記錄、支出追蹤、多團隊管理與防護欄。
深入瞭解 →