feat: Add VoyageAI embedder support

[anatolykoptev]

feat: Add VoyageAI embedder support

Overview

Adds support for VoyageAI embeddings via the universal_api backend, providing state-of-the-art semantic embeddings for production use.

Motivation

VoyageAI offers superior embedding quality compared to standard models:

• 📊 Better retrieval accuracy on benchmark datasets
• 🚀 Optimized for semantic search use cases
• 💰 Cost-effective for production workloads
• 🌍 Multilingual support out of the box

Changes

1. VoyageAI Backend Mapping

Maps MOS_EMBEDDER_BACKEND=voyageai to universal_api embedder with VoyageAI-specific defaults:

# Map voyageai to universal_api
if embedder_backend in ["universal_api", "voyageai"]:
    provider = os.getenv("MOS_EMBEDDER_PROVIDER", "openai")

    # Handle API Key - supports VOYAGE_API_KEY for convenience
    api_key = os.getenv("MOS_EMBEDDER_API_KEY")
    if not api_key and embedder_backend == "voyageai":
        api_key = os.getenv("VOYAGE_API_KEY")

    # Auto-configure VoyageAI base URL
    base_url = os.getenv("MOS_EMBEDDER_API_BASE")
    if not base_url and embedder_backend == "voyageai":
        base_url = "https://api.voyageai.com/v1"

2. Environment Variables

New environment variable support:

• VOYAGE_API_KEY - VoyageAI API key (convenience alias)
• MOS_EMBEDDER_BACKEND=voyageai - Enables VoyageAI mode

Backward compatible with existing MOS_EMBEDDER_API_KEY and MOS_EMBEDDER_API_BASE.

3. Intelligent Defaults

When backend=voyageai:

• ✅ Base URL defaults to https://api.voyageai.com/v1
• ✅ Supports VOYAGE_API_KEY environment variable
• ✅ Falls back to generic MOS_EMBEDDER_* vars if not set

Usage

Basic Configuration

export MOS_EMBEDDER_BACKEND=voyageai
export VOYAGE_API_KEY=pa-your-api-key-here
export MOS_EMBEDDER_MODEL=voyage-3  # or voyage-3-lite, voyage-code-3

Advanced Configuration

export MOS_EMBEDDER_BACKEND=voyageai
export MOS_EMBEDDER_API_KEY=pa-your-key  # Alternative to VOYAGE_API_KEY
export MOS_EMBEDDER_MODEL=voyage-3-large
export MOS_EMBEDDER_PROVIDER=openai  # OpenAI-compatible client

Docker Compose Example

environment:
  MOS_EMBEDDER_BACKEND: voyageai
  VOYAGE_API_KEY: ${VOYAGE_API_KEY}
  MOS_EMBEDDER_MODEL: voyage-3-lite

Available Models

VoyageAI supports multiple models optimized for different use cases:

Model	Dimensions	Use Case
voyage-3-large	1024	Highest quality, general purpose
voyage-3	1024	Balanced quality/speed
voyage-3-lite	512	Fast, cost-effective
voyage-code-3	1024	Optimized for code search
voyage-finance-2	1024	Financial documents
voyage-law-2	1024	Legal documents

See VoyageAI docs for latest models.

Testing

Tested with:

• ✅ voyage-3-lite model (production)
• ✅ Environment variable fallbacks
• ✅ Backward compatibility with universal_api backend
• ✅ Unicode text handling (with PR 👋 Welcome to MemOS Discussions | 欢迎来到 MemOS 讨论区 #2 sanitization)

Impact

• Breaking Changes: None - purely additive
• Dependencies: Uses existing universal_api embedder
• Performance: Depends on VoyageAI API latency (~50-200ms)
• Cost: Pay-per-use VoyageAI API pricing

Migration

Existing users can continue using ollama, sentence_transformer, or universal_api. VoyageAI is opt-in via MOS_EMBEDDER_BACKEND=voyageai.

Related

• Complements PR 👋 Welcome to MemOS Discussions | 欢迎来到 MemOS 讨论区 #2 (Unicode sanitization) for production-ready cloud embedders
• Uses existing UniversalAPIEmbedder infrastructure

Checklist

• Code follows project style
• Self-reviewed the code
• Added inline documentation
• Backward compatible (no breaking changes)
• Environment variables documented
• Example usage provided

References

• VoyageAI Documentation
• VoyageAI Embeddings API
• VoyageAI Pricing