Embeddings

Embeddings represent content as vectors for semantic search, similarity comparisons and retrieval. Supported input types depend on the provider and model.

Quick Start#

Generate an embedding from text:

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::embeddings()
    ->using(Provider::OpenAI, 'text-embedding-3-large')
    ->fromInput('Your text goes here')
    ->asEmbeddings();

// Get your embeddings vector
$embeddings = $response->embeddings[0]->embedding;

// Check token usage
echo $response->usage->tokens;

Generating multiple embeddings#

You can generate multiple embeddings at once with providers that support batch embeddings:

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::embeddings()
    ->using(Provider::OpenAI, 'text-embedding-3-large')
    // First embedding
    ->fromInput('Your text goes here')
    // Second embedding
    ->fromInput('Your second text goes here')
    // Third and fourth embeddings
    ->fromArray([
        'Third',
        'Fourth'
    ])
    ->asEmbeddings();

/** @var Embedding $embedding */
foreach ($response->embeddings as $embedding) {
    // Do something with your embeddings
    $embedding->embedding;
}

// Check token usage
echo $response->usage->tokens;

Input Methods#

Supply text directly or read it from a file:

Direct Text Input#

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::embeddings()
    ->using(Provider::OpenAI, 'text-embedding-3-large')
    ->fromInput('Analyze this text')
    ->asEmbeddings();

From File#

Read input from a text file:

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::embeddings()
    ->using(Provider::OpenAI, 'text-embedding-3-large')
    ->fromFile('/path/to/your/document.txt')
    ->asEmbeddings();

Multimodal Embeddings#

For supported providers, use images, audio, video or documents as embedding inputs. These embeddings can support media similarity search and cross-modal retrieval.

Single Image#

Generate an embedding from a single image:

use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Image;

$response = Prism::embeddings()
    ->using('gemini', 'gemini-embedding-2')
    ->fromImage(Image::fromLocalPath('/path/to/product.jpg'))
    ->asEmbeddings();

$embedding = $response->embeddings[0]->embedding;

Multiple Images#

Process multiple images in a single request:

use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Image;

$response = Prism::embeddings()
    ->using('gemini', 'gemini-embedding-2')
    ->fromImages([
        Image::fromLocalPath('/path/to/image1.jpg'),
        Image::fromUrl('https://example.com/image2.png'),
    ])
    ->asEmbeddings();

foreach ($response->embeddings as $embedding) {
    // Process each image embedding
    $vector = $embedding->embedding;
}

Audio, Video, and Documents#

The plural helpers fromAudios(array $audios), fromVideos(array $videos) and fromDocuments(array $documents) append one content entry per item, just like repeated calls to the singular helper. They do not combine parts into one embedding. Use a multimodal embedding provider/model such as the Gemini integration described in its embedding guide; input support is not implied by the builder method's availability.

use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Audio;
use Prism\Prism\ValueObjects\Media\Document;
use Prism\Prism\ValueObjects\Media\Video;

$response = Prism::embeddings()
    ->using('gemini', 'gemini-embedding-2')
    ->fromAudio(Audio::fromLocalPath('/path/to/sample.mp3'))
    ->fromVideo(Video::fromLocalPath('/path/to/sample.mp4'))
    ->fromDocument(Document::fromLocalPath('/path/to/report.pdf'))
    ->asEmbeddings();

Grouped Multimodal Content#

Use fromContent() when you want a single embedding generated from multiple parts within the same content entry:

use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Image;

$response = Prism::embeddings()
    ->using('gemini', 'gemini-embedding-2')
    ->fromContent([
        'Find similar products in red',
        Image::fromBase64($productImage, 'image/png'),
    ])
    ->asEmbeddings();

Use fromContents() when you want multiple embeddings in a single request:

use Prism\Prism\Facades\Prism;
use Prism\Prism\ValueObjects\Media\Image;

$response = Prism::embeddings()
    ->using('gemini', 'gemini-embedding-2')
    ->fromContents([
        ['The dog is cute'],
        [Image::fromLocalPath('/path/to/dog.png')],
    ])
    ->asEmbeddings();

You can still chain fromInput() and fromImage() in any order. Each chained call creates a separate content entry.

Common Settings#

Just like with text generation, you can fine-tune your embeddings requests:

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;

$response = Prism::embeddings()
    ->using(Provider::OpenAI, 'text-embedding-3-large')
    ->fromInput('Your text here')
    ->withClientOptions(['timeout' => 30]) // Adjust request timeout
    ->withClientRetry(3, 100) // Add automatic retries
    ->asEmbeddings();

Response Handling#

Provider options are model-specific: for example, OpenAI uses dimensions, Voyage AI text embeddings use outputDimension, and Gemini/Vertex use outputDimensionality. See the provider guide before setting one; unknown options are not handled consistently across integrations.

The response exposes meta (ID, model and rate limits when reported) and optional raw payload data. usage->tokens can be null when unreported; Vertex maps a billable-character count into this field. Raw payloads may contain input content or identifiers, so apply your retention policy before storing them.

Read results and metadata from the embeddings response:

use Prism\Prism\ValueObjects\Embedding;

// Get an array of Embedding value objects
$embeddings = $response->embeddings;

// Just get first embedding
$firstVectorSet = $embeddings[0]->embedding;

// Loop over all embeddings
/** @var Embedding $embedding */
foreach ($embeddings as $embedding) {
    $vectorSet = $embedding->embedding;
}

// Check token usage
$tokenCount = $response->usage->tokens;

Error Handling#

Handle request failures:

fromFile() throws PrismException for a missing or unreadable local file. A provider without embeddings raises an unsupported-action PrismException. Invalid provider responses can also raise PrismException; media inputs refused by an explicit guarded fetch raise PrismUrlRefused. A builder accepting a media object does not guarantee that the selected embedding provider sends it.

use Prism\Prism\Facades\Prism;
use Prism\Prism\Enums\Provider;
use Prism\Prism\Exceptions\PrismException;

try {
    $response = Prism::embeddings()
        ->using(Provider::OpenAI, 'text-embedding-3-large')
        ->fromInput('Your text here')
        ->asEmbeddings();
} catch (PrismException $e) {
    Log::error('Embeddings generation failed:', [
        'error' => $e->getMessage()
    ]);
}

Usage Notes#

Vector Storage: Consider using a vector database like Milvus, Qdrant, or pgvector to store and query your embeddings efficiently.

Text Preprocessing: Follow the model's input requirements. Avoid removing case, punctuation or characters that carry meaning in your content.