{"id":3315,"library":"voyageai","title":"Voyage AI Python Library","description":"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.","status":"active","version":"0.3.7","language":"en","source_language":"en","source_url":"https://github.com/voyage-ai/voyageai-python","tags":["AI","NLP","embeddings","reranking","vector search","RAG","machine learning"],"install":[{"cmd":"pip install -U voyageai","lang":"bash","label":"Install or upgrade the library"}],"dependencies":[],"imports":[{"symbol":"Client","correct":"from voyageai import Client"}],"quickstart":{"code":"import os\nfrom voyageai import Client\n\n# It's recommended to set your API key as an environment variable (VOYAGE_API_KEY).\n# For demonstration, you can set it directly, but avoid this in production.\napi_key = os.environ.get('VOYAGE_API_KEY', 'YOUR_VOYAGE_API_KEY')\n\nif not api_key or api_key == 'YOUR_VOYAGE_API_KEY':\n    print(\"Warning: VOYAGE_API_KEY environment variable not set or is a placeholder. Please set it for actual use.\")\n    # Exit or raise error if API key is critical for quickstart execution\n    # For this example, we'll proceed with a dummy key but it will fail API calls.\n\nclient = Client(api_key=api_key, max_retries=3) # max_retries=3 added for robustness\n\ntexts = [\n    \"hello, world\",\n    \"welcome to voyage ai!\",\n    \"Voyage AI provides cutting-edge embedding and reranking models.\"\n]\n\ntry:\n    # Generate embeddings using a recommended model from the Voyage 4 series\n    result = client.embed(\n        texts, \n        model=\"voyage-4-large\", \n        input_type=\"document\" # Recommended for optimal retrieval\n    )\n    \n    print(f\"Generated {len(result.embeddings)} embeddings.\")\n    print(f\"Each embedding has {len(result.embeddings[0])} dimensions.\")\n    print(f\"First embedding (truncated): {result.embeddings[0][:10]}...\")\n    print(f\"Total tokens used: {result.total_tokens}\")\n\n    # Example of reranking\n    query = \"AI models for text processing\"\n    documents = [\n        \"Voyage AI offers models for natural language understanding.\",\n        \"The latest phone has a great camera and long battery life.\",\n        \"Our embedding models are state-of-the-art for semantic search.\"\n    ]\n    rerank_result = client.rerank(query, documents, model=\"rerank-2.5\")\n    print(\"\\nReranking results:\")\n    for i, r in enumerate(rerank_result.results):\n        print(f\"  Rank {i+1}: Score={r.relevance_score:.4f}, Document='{r.document.text}'\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your VOYAGE_API_KEY is correctly set and you have network access.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to version 3.9 or newer.","message":"Python versions 3.8 and lower are no longer supported. Users should upgrade to Python 3.9 or higher.","severity":"breaking","affected_versions":"<=0.3.x"},{"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.","message":"Older 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.","severity":"deprecated","affected_versions":"<0.3.0"},{"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.","message":"The `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).","severity":"gotcha","affected_versions":"All"},{"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.","message":"Users 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.","severity":"gotcha","affected_versions":"All"},{"fix":"Always include `input_type=\"query\"` or `input_type=\"document\"` in your `embed` calls, depending on the nature of the text being embedded.","message":"For 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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}