Skip to main content
Embeddings are numerical representations of text that capture semantic meaning in a high-dimensional vector space. They are a foundational building block for many LLM-powered applications, enabling machines to understand relationships between words, phrases, and documents. Polyglot’s Embeddings class provides a unified interface for generating vector embeddings across multiple providers. You write your code once, and switch between OpenAI, Cohere, Gemini, Jina, Mistral, or any other supported provider by changing a single preset name.

​
Understanding Embeddings

Before diving into the API, it helps to understand the core concepts:
  • Vectors — Embeddings represent text as arrays of floating-point numbers in a high-dimensional space (typically 256 to 3072 dimensions).
  • Semantic similarity — Texts with similar meaning produce vectors that are closer together, measurable through cosine similarity, Euclidean distance, or dot product.
  • Provider models — Different providers offer models with varying dimension counts, language support, and performance characteristics.
Common use cases for embeddings include:
  • Semantic search — Find documents similar to a query based on meaning, not just keywords.
  • Clustering — Group related documents together automatically.
  • Classification — Assign categories to text based on content.
  • Recommendations — Suggest related items based on vector proximity.
  • RAG (Retrieval-Augmented Generation) — Retrieve relevant context for LLM prompts.

​
The Embeddings Class

The Embeddings class is a facade that combines provider configuration, request building, and result handling into a fluent, immutable API. Every method that modifies state returns a new instance, making the class safe to reuse and compose.

​
Architecture Overview

The class is built from several focused components:
ComponentResponsibility
EmbeddingsFacade with fluent API and static factory methods
EmbeddingsRuntimeOrchestrates driver creation, HTTP clients, and event dispatching
EmbeddingsProviderResolves configuration and optional explicit drivers
PendingEmbeddingsExecutes the request with retry logic and returns the response
EmbeddingsDriverRegistryMaps driver names to concrete driver implementations

​
Entry Points

You can create an Embeddings instance in several ways, depending on how much control you need: 
<?php

use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;

// From a named preset (most common)
$embeddings = Embeddings::using('openai');

// From a configuration object
$config = new EmbeddingsConfig(
    apiUrl: 'https://api.openai.com/v1',
    apiKey: getenv('OPENAI_API_KEY'),
    endpoint: '/embeddings',
    model: 'text-embedding-3-small',
    dimensions: 1536,
    maxInputs: 2048,
    driver: 'openai',
);
$embeddings = Embeddings::fromConfig($config);

// From a provider instance (for advanced composition)
$embeddings = Embeddings::fromProvider($provider);

// From a custom runtime (full control over driver and events)
$embeddings = Embeddings::fromRuntime($runtime);
// @doctest id="7ac1"

​
Request Methods

Configure what to embed before executing the request:
MethodDescription
withInputs(string|array $input)Set one or more texts to embed
withModel(string $model)Override the model from the preset
withOptions(array $options)Pass provider-specific options
withRetryPolicy(EmbeddingsRetryPolicy $policy)Configure retry behavior
withRequest(EmbeddingsRequest $request)Replace the entire request object
with($input, $options, $model)Shorthand combining inputs, options, and model

​
Execution Methods

Three convenience methods execute the request and return results at different levels of detail:
MethodReturnsDescription
get()EmbeddingsResponseFull response with vectors, usage, and metadata
vectors()Vector[]Array of all embedding vectors
first()?VectorThe first vector, or null if empty
For advanced use cases, create() returns a PendingEmbeddings instance that you can inspect or execute manually.

​
Supported Providers

Polyglot ships with presets for the following providers:
PresetDriverDefault ModelDimensions
openaiOpenAItext-embedding-3-small1536
azureAzure OpenAI(configured per deployment)(varies)
cohereCohereembed-multilingual-v3.01024
geminiGemini(configured per preset)(varies)
jinaJina(configured per preset)(varies)
mistralOpenAI-compatible(configured per preset)(varies)
ollamaOpenAI-compatible(configured per preset)(varies)
Note: Mistral and Ollama use the OpenAI-compatible driver, since their APIs follow the same format.

​
Custom Driver Registration

You can register your own driver for providers not bundled with Polyglot by creating a custom EmbeddingsDriverRegistry: 
<?php

use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\Creation\BundledEmbeddingsDrivers;

// Start from the bundled registry and add your driver (by class name or factory callable)
$registry = BundledEmbeddingsDrivers::registry()
    ->withDriver('custom-provider', CustomEmbeddingsDriver::class);

// Or register with a factory callable
$registry = BundledEmbeddingsDrivers::registry()
    ->withDriver('custom-provider', function ($config, $httpClient, $events) {
        return new CustomEmbeddingsDriver($config, $httpClient, $events);
    });
// @doctest id="43a0"
Your custom driver must implement the CanHandleVectorization contract.

​
Events

The embeddings system dispatches events at key points during execution, which you can listen to through the runtime:
EventWhen
EmbeddingsDriverBuiltAfter the driver is created from configuration
EmbeddingsRequestedWhen an embeddings request is initiated
EmbeddingsResponseReceivedAfter a successful response is received
EmbeddingsFailedWhen the request fails after all retry attempts