​
The Embeddings Class

Polyglot provides the Embeddings class as the primary interface for generating and working with vector embeddings.

​
Creating an Embeddings Instance

<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

// Create a basic embeddings instance with default settings
$embeddings = new Embeddings();

// Create an embeddings instance with a specific connection
$embeddings = new Embeddings('openai');

// Alternative method to specify connection
$embeddings = (new Embeddings())->using('openai');
// @doctest id="90e1"

​
Key Methods

The Embeddings class provides several important methods:
  • create(): Generates embeddings for input text
  • using(): Specifies which connection preset to use
  • withConfig(): Sets a custom configuration
  • withHttpClient(): Specifies a custom HTTP client
  • withModel(): Overrides the default model
  • findSimilar(): Finds documents similar to a query

​
Generating Embeddings

The core functionality of the Embeddings class is to transform text into vector representations.

​
Basic Embedding Generation

<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

$embeddings = new Embeddings();
$result = $embeddings->with('The quick brown fox jumps over the lazy dog.')->get();

// Get the vector values from the first (and only) result
$vector = $result->first()?->values();

echo "Generated a vector with " . count($vector) . " dimensions.\n";
// @doctest id="c7f4"

​
Embedding Multiple Texts

You can generate embeddings for multiple texts in a single request, which is more efficient than making separate requests: 
<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

$embeddings = new Embeddings();

$documents = [
    "The quick brown fox jumps over the lazy dog.",
    "Machine learning models can process text into vector representations.",
    "Embeddings capture semantic relationships between words and documents."
];

$result = $embeddings->with($documents)->get();

// Get all vectors
$vectors = $result->vectors();

foreach ($vectors as $index => $vector) {
    echo "Document " . ($index + 1) . " has a vector with " . count($vector->values()) . " dimensions.\n";
}
// @doctest id="d4b4"

​
Accessing Embedding Results

The create() method returns an EmbeddingsResponse object with several useful methods: 
<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

$embeddings = new Embeddings();
$result = $embeddings->with('Sample text for embedding')->get();

// Get the first vector
$firstVector = $result->first();

// Get the last vector (useful when processing multiple inputs)
$lastVector = $result->last();

// Get all vectors
$allVectors = $result->vectors();

// Get all vector values as a simple array of arrays
$valuesArray = $result->toValuesArray();

// Get usage information
$usage = $result->usage();
echo "Input tokens: " . $usage->input() . "\n";
echo "Output tokens: " . $usage->output() . "\n";
echo "Total tokens: " . $usage->total() . "\n";
// @doctest id="666b"

​
Working with Vector Objects

Each vector in the response is represented by a Vector object with its own methods: 
<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

$embeddings = new Embeddings();
$result = $embeddings->with('Sample text for embedding')->get();
$vector = $result->first();

// Get vector values
$values = $vector->values();

// Get vector ID (index)
$id = $vector->id();

// Compare with another vector
$otherVector = $result->with('Another text for comparison')->first();
$similarity = $vector->compareTo($otherVector, 'cosine');
// @doctest id="0326"

​
Working with Different Providers

Polyglot supports multiple embedding providers, each with their own strengths and characteristics.

​
Switching Between Providers

<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

// Compare embeddings from different providers
$text = "Artificial intelligence is transforming industries worldwide.";

// OpenAI embeddings
$openaiEmbeddings = new Embeddings('openai');
$openaiResult = $openaiEmbeddings->with($text)->get();
echo "OpenAI embedding dimensions: " . count($openaiResult->first()?->values()) . "\n";

// Cohere embeddings
$cohereEmbeddings = new Embeddings('cohere');
$cohereResult = $cohereEmbeddings->with($text)->get();
echo "Cohere embedding dimensions: " . count($cohereResult->first()?->values()) . "\n";

// Mistral embeddings
$mistralEmbeddings = new Embeddings('mistral');
$mistralResult = $mistralEmbeddings->with($text)->get();
echo "Mistral embedding dimensions: " . count($mistralResult->first()?->values()) . "\n";
// @doctest id="105f"

​
Provider-Specific Options

Different providers may support additional options for embedding generation: 
<?php
use Cognesy\Polyglot\Embeddings\Embeddings;

// Example with OpenAI-specific options
$openaiEmbeddings = new Embeddings('openai');
$response = $openaiEmbeddings->with(
    input: ["Sample text for embedding"],
    options: [
        'encoding_format' => 'float',  // Get float values instead of base64
        'dimensions' => 512,           // Request a specific vector size (if supported)
    ]
)->get();

// Example with Cohere-specific options
$cohereEmbeddings = new Embeddings('cohere');
$response = $cohereEmbeddings->with(
    input: ["Sample text for embedding"],
    options: [
        'input_type' => 'classification',  // Cohere-specific option
        'truncate' => 'END',               // How to handle texts that exceed the token limit
    ]
)->get();
// @doctest id="972f"

​
Models and Dimensions

Different embedding models produce vectors of different dimensions: 
<?php
use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;use Cognesy\Polyglot\Embeddings\Embeddings;

// Create custom configuration with a specific model
$config = new EmbeddingsConfig(
    apiUrl: 'https://api.openai.com/v1',
    apiKey: getenv('OPENAI_API_KEY'),
    endpoint: '/embeddings',
    model: 'text-embedding-3-large',  // Use the larger model
    dimensions: 3072,                 // Specify expected dimensions
);

$embeddings = new Embeddings();
$embeddings->withConfig($config);

$response = $embeddings->with("Test text for large embedding model")->get();
echo "Vector dimensions: " . count($response->first()?->values()) . "\n";
// @doctest id="ae33"