Registry / llm-agents / voyageai

voyageai

JSON →
library0.5.0pypypi✓ verified 23d ago

Voyage AI provides a Python library (`voyageai`) that offers API endpoints for its state-of-the-art embedding and reranking models. These models convert unstructured data (text, images, video) into dense numerical vectors (embeddings), enabling advanced information retrieval tasks like semantic search and Retrieval-Augmented Generation (RAG). The library is actively maintained, with version 0.3.7 released recently, and it integrates seamlessly with various AI stacks.

pip install -U voyageai
INSTALL
IMPORT
SIG · VOYAGEAI
V
voyageai
llm-agentspythonv0.5.0
Install
14.3s avg
Import
2346ms
Disk
220MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.5.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 2.442s · 219.9MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 14.3s · import 2.250s · 208MB
220MB installed
● package 220MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
from voyageai import Client

This quickstart demonstrates how to initialize the Voyage AI client and generate text embeddings and rerank documents using recommended models. It emphasizes setting the API key via an environment variable (`VOYAGE_API_KEY`) and configuring `max_retries` for robustness.

import os from voyageai import Client # It's recommended to set your API key as an environment variable (VOYAGE_API_KEY). # For demonstration, you can set it directly, but avoid this in production. api_key = os.environ.get('VOYAGE_API_KEY', 'YOUR_VOYAGE_API_KEY') if not api_key or api_key == 'YOUR_VOYAGE_API_KEY': print("Warning: VOYAGE_API_KEY environment variable not set or is a placeholder. Please set it for actual use.") # Exit or raise error if API key is critical for quickstart execution # For this example, we'll proceed with a dummy key but it will fail API calls. client = Client(api_key=api_key, max_retries=3) # max_retries=3 added for robustness texts = [ "hello, world", "welcome to voyage ai!", "Voyage AI provides cutting-edge embedding and reranking models." ] try: # Generate embeddings using a recommended model from the Voyage 4 series result = client.embed( texts, model="voyage-4-large", input_type="document" # Recommended for optimal retrieval ) print(f"Generated {len(result.embeddings)} embeddings.") print(f"Each embedding has {len(result.embeddings[0])} dimensions.") print(f"First embedding (truncated): {result.embeddings[0][:10]}...") print(f"Total tokens used: {result.total_tokens}") # Example of reranking query = "AI models for text processing" documents = [ "Voyage AI offers models for natural language understanding.", "The latest phone has a great camera and long battery life.", "Our embedding models are state-of-the-art for semantic search." ] rerank_result = client.rerank(query, documents, model="rerank-2.5") print("\nReranking results:") for i, r in enumerate(rerank_result.results): print(f" Rank {i+1}: Score={r.relevance_score:.4f}, Document='{r.document.text}'") except Exception as e: print(f"An error occurred: {e}") print("Please ensure your VOYAGE_API_KEY is correctly set and you have network access.")
Debug
Known issues
breakingPython versions 3.8 and lower are no longer supported. Users should upgrade to Python 3.9 or higher.
fix
Upgrade your Python environment to version 3.9 or newer.
affects: <=0.3.x
deprecatedOlder embedding models (e.g., `voyage-01`, `voyage-lite-01`, `voyage-lite-01-instruct`) are superseded by the Voyage 4 series (`voyage-4-large`, `voyage-4`, `voyage-4-lite`). The new series offers improved accuracy and a shared embedding space, making it easier to switch models without re-indexing.
fix
Migrate to Voyage 4 series models (e.g., `voyage-4-large`, `voyage-4`) for new projects and consider updating existing ones. Refer to the official documentation for model migration guides.
affects: <0.3.0
gotchaThe `voyageai.Client` by default has `max_retries=0`, meaning it will not automatically retry API requests in case of transient errors (e.g., rate limits, temporary network issues).
fix
When initializing the client, set `max_retries` to a positive integer (e.g., `Client(api_key=..., max_retries=3)`) to enable automatic retries with exponential backoff.
affects: All
gotchaUsers on the free tier or without a payment method are subject to strict API rate limits (e.g., 3 requests per minute, 10,000 tokens per minute). Exceeding these limits will result in `429 (Rate Limit Exceeded)` errors.
fix
Monitor your usage, implement client-side rate limiting, configure `max_retries` in the client, or upgrade your usage tier by adding a payment method or requesting an increase.
affects: All
gotchaFor optimal retrieval and search performance, specify the `input_type` parameter (e.g., `"query"` or `"document"`) when calling `client.embed()`. This allows Voyage AI to prepend an appropriate prompt, making the embeddings more tailored for the intended use case.
fix
Always include `input_type="query"` or `input_type="document"` in your `embed` calls, depending on the nature of the text being embedded.
affects: All
Upgrade
Version history
0.5.0latest on PyPI · released Jul 10, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
60 hits · last 30 days
node
50
Perplexity
1
OpenAI (training)
1
Resources