Embeddings

Generate vector embeddings for semantic search, RAG, and similarity matching.

Prism Reference

Atlas embeddings wraps Prism's embeddings API. For detailed documentation including all configuration options, see Prism Embeddings.

Basic Usage

use Atlasphp\Atlas\Atlas;

$response = Atlas::embeddings()
    ->using('openai', 'text-embedding-3-small')
    ->fromInput('What is the return policy?')
    ->asEmbeddings();

$vector = $response->embeddings[0];  // Array of floats

Batch Embeddings

Process multiple texts in a single request:

$response = Atlas::embeddings()
    ->using('openai', 'text-embedding-3-small')
    ->fromInput([
        'How do I return an item?',
        'What is your shipping policy?',
        'Do you offer refunds?',
    ])
    ->asEmbeddings();

// $response->embeddings contains 3 vectors
foreach ($response->embeddings as $index => $vector) {
    // Process each embedding vector
}

Semantic Search Example

// Index documents
$documents = Document::all();
foreach ($documents as $doc) {
    $response = Atlas::embeddings()
        ->using('openai', 'text-embedding-3-small')
        ->fromInput($doc->content)
        ->asEmbeddings();

    $doc->embedding = $response->embeddings[0];
    $doc->save();
}

// Search with query
$queryResponse = Atlas::embeddings()
    ->using('openai', 'text-embedding-3-small')
    ->fromInput('How do I reset my password?')
    ->asEmbeddings();

$queryEmbedding = $queryResponse->embeddings[0];

// Find similar documents (using pgvector)
$results = Document::query()
    ->orderByRaw('embedding <-> ?', [json_encode($queryEmbedding)])
    ->limit(5)
    ->get();

RAG Implementation

Combine embeddings with agents for retrieval-augmented generation:

class RagService
{
    public function answer(string $question): string
    {
        // 1. Generate query embedding
        $response = Atlas::embeddings()
            ->using('openai', 'text-embedding-3-small')
            ->fromInput($question)
            ->asEmbeddings();

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

        // 2. Find relevant documents
        $context = Document::query()
            ->orderByRaw('embedding <-> ?', [json_encode($queryEmbedding)])
            ->limit(3)
            ->pluck('content')
            ->join("\n\n");

        // 3. Generate answer with context
        $response = Atlas::agent('rag-agent')
            ->withVariables(['context' => $context])
            ->chat($question);

        return $response->text;
    }
}

Database Storage

PostgreSQL with pgvector

CREATE EXTENSION vector;

CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT,
    embedding vector(1536)
);

CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops);

MySQL with JSON

CREATE TABLE documents (
    id INT AUTO_INCREMENT PRIMARY KEY,
    content TEXT,
    embedding JSON
);

Best Practices

Batch When Possible

// Good - single request for multiple texts
$response = Atlas::embeddings()
    ->using('openai', 'text-embedding-3-small')
    ->fromInput($texts)
    ->asEmbeddings();

// Less efficient - multiple requests
foreach ($texts as $text) {
    $response = Atlas::embeddings()
        ->using('openai', 'text-embedding-3-small')
        ->fromInput($text)
        ->asEmbeddings();
}

Cache Embeddings

$cacheKey = 'embedding:' . md5($text);

$embedding = Cache::remember($cacheKey, 3600, function () use ($text) {
    $response = Atlas::embeddings()
        ->using('openai', 'text-embedding-3-small')
        ->fromInput($text)
        ->asEmbeddings();

    return $response->embeddings[0];
});

Pipeline Hooks

Embeddings support pipeline middleware for observability:

Pipeline	Trigger
embeddings.before_embeddings	Before generating embeddings
embeddings.after_embeddings	After generating embeddings

use Atlasphp\Atlas\Contracts\PipelineContract;

class LogEmbeddings implements PipelineContract
{
    public function handle(mixed $data, Closure $next): mixed
    {
        $result = $next($data);

        Log::info('Embeddings generated', [
            'count' => count($result['response']->embeddings),
        ]);

        return $result;
    }
}

$registry->register('embeddings.after_embeddings', LogEmbeddings::class);

Next Steps

• Prism Embeddings — Complete embeddings reference
• Chat — Use embeddings in RAG workflows
• Pipelines — Add observability to embeddings