Voyage AI

LiteLLM에서 Voyage AI의 임베딩 및 리랭크 모델을 사용하는 방법을 알아봐요.

출처: 문서

본문

Voyage embeddings docs

API 키

# env variable
os.environ['VOYAGE_API_KEY']

사용 예시 - 임베딩

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 임베딩은 다음 선택 파라미터를 지원해요:

input_type: 검색 최적화를 위한 입력 타입 지정
- "query": 검색 쿼리에 사용
- "document": 인덱싱 중인 문서에 사용
dimensions: 출력 임베딩 차원 (256, 512, 1024, 또는 2048)
encoding_format: 출력 형식 ("float", "int8", "uint8", "binary", "ubinary")
truncation: 최대 토큰을 초과하는 입력을 잘라낼지 여부 (기본값: 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-large	`embedding(model="voyage/voyage-4-large", input)`
voyage-4	`embedding(model="voyage/voyage-4", input)`
voyage-4-lite	`embedding(model="voyage/voyage-4-lite", input)`
voyage-code-4	`embedding(model="voyage/voyage-code-4", input)`
voyage-context-4	`embedding(model="voyage/voyage-context-4", input)`
voyage-context-3	`embedding(model="voyage/voyage-context-3", input)`
voyage-3.5	`embedding(model="voyage/voyage-3.5", input)`
voyage-3.5-lite	`embedding(model="voyage/voyage-3.5-lite", input)`
voyage-3-large	`embedding(model="voyage/voyage-3-large", input)`
voyage-3	`embedding(model="voyage/voyage-3", input)`
voyage-3-lite	`embedding(model="voyage/voyage-3-lite", input)`
voyage-code-3	`embedding(model="voyage/voyage-code-3", input)`
voyage-finance-2	`embedding(model="voyage/voyage-finance-2", input)`
voyage-law-2	`embedding(model="voyage/voyage-law-2", input)`
voyage-code-2	`embedding(model="voyage/voyage-code-2", input)`
voyage-multilingual-2	`embedding(model="voyage/voyage-multilingual-2", input)`
voyage-large-2-instruct	`embedding(model="voyage/voyage-large-2-instruct", input)`
voyage-large-2	`embedding(model="voyage/voyage-large-2", input)`
voyage-2	`embedding(model="voyage/voyage-2", input)`
voyage-lite-02-instruct	`embedding(model="voyage/voyage-lite-02-instruct", input)`
voyage-01	`embedding(model="voyage/voyage-01", input)`
voyage-lite-01	`embedding(model="voyage/voyage-lite-01", input)`
voyage-lite-01-instruct	`embedding(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 proxy 라우트가 동작해요. 입력과 응답 형태만 일반 모델과 다를 뿐이에요.

입력 형태

문자열의 평면 리스트나 단일 문자열은 각 문자열을 별도의 문서로 임베딩해요. LiteLLM은 이를 enable_auto_chunking: true, chunk_size: 32000, input_type: "document"와 함께 전달하므로, 최대 32,000토큰의 문자열은 하나의 임베딩으로 돌아오고 더 긴 문자열은 Voyage 측에서 최대 32,000토큰 청크로 분할돼요. 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 ***" \
  -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 ***" \
  -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 ***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "voyage-context-4",
    "input": [["The quick brown fox", "jumps over the lazy dog"]]
  }'

사양

모델	청크당	요청당	출력 차원	가격/M 토큰
voyage-context-4	32,000 토큰	120,000 토큰, 1,000 입력, 16,000 청크	256, 512, 1024 (기본), 2048	$0.12
voyage-context-3	32,000 토큰	120,000 토큰, 1,000 입력, 16,000 청크	256, 512, 1024 (기본), 2048	$0.18

한도는 Voyage의 것이며, 요청별 토큰 총합은 호출의 모든 청크를 계산해요.

컨텍스트 임베딩을 언제 사용할까

긴 문서를 청크로 분할하고 주변 문서가 각 청크의 임베딩을 알려줘야 할 때, 구조·섹션 참조·청크 간 의존성이 중요할 때 voyage-context-4를 사용해요. 독립된 텍스트 조각과 짧은 쿼리에는 voyage-4-large, voyage-4, voyage-4-lite를 사용하세요. 문서 컨텍스트가 더할 게 없고 표준 모델이 더 저렴하고 빠르거든요.

모델 선택 가이드

모델	최적 용도	컨텍스트 길이	가격/M 토큰
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는 쿼리와의 관련성에 따라 문서를 재정렬하여 검색 관련성을 높이는 리랭크 모델을 제공해요.

빠른 시작

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 ***" \
  -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
  }'

지원 리랭크 모델

모델	컨텍스트 길이	설명	가격/M 토큰
rerank-2.5	32K	최고 품질, 다국어, 명령 수행	$0.05
rerank-2.5-lite	32K	지연 시간·비용 최적화	$0.02
rerank-2	16K	레거시 모델	$0.05
rerank-2-lite	8K	레거시 모델, 더 빠름	$0.02

지원 파라미터

파라미터	타입	설명
`model`	string	모델 이름 (예: `voyage/rerank-2.5`)
`query`	string	검색 쿼리
`documents`	list	리랭크할 문서 목록
`top_n`	int	반환할 상위 결과 수
`return_documents`	bool	응답에 문서 텍스트 포함 여부

더 알아보기 (Learn more)

Voyage AI 문서
LiteLLM 리랭크