Download the PHP package x-laravel/embedding without Composer

Embedding

A Laravel package that automatically generates and stores vector embeddings for Eloquent models using laravel/ai.

How It Works

• Add the Embeddable trait to any model — embeddings are generated automatically on save
• Define one or more named slots per model, each with its own text and trigger fields
• When a field changes, only the slots that depend on that field are re-embedded
• Embedding generation is handled by a queued job per slot — no blocking
• Similarity search is driver-based: PHP by default (works with any database), or native DB-level vector search via dedicated drivers for MySQL HeatWave, MariaDB 11.7+, PostgreSQL (pgvector), Oracle 26ai, SQL Server 2025, and Qdrant — see Similarity Drivers
• Optional second-stage reranking reorders candidate results using laravel/ai's rerank gateway (Cohere, Voyage, Jina)

Requirements

• PHP ^8.3
• Laravel ^12.0 | ^13.0
• laravel/ai ^0.6

Installation

Run the migration:

Optionally publish the config file:

Setup

1. Single-slot model

For most use cases, return a string from toEmbeddingText() and list trigger fields in $embeddable:

2. Multi-slot model

Return an array from toEmbeddingText() and use a nested $embeddable map to define which fields trigger each slot:

When title changes, only the title and full slots are re-embedded — body is left untouched.

3. Defining trigger fields with #[EmbedOn]

As an alternative to $embeddable, use the #[EmbedOn] attribute. The attribute is repeatable for multi-slot models:

$embeddable and #[EmbedOn] merge — you can use both.

Usage

Generating embeddings

Suppressing embedding generation

Similarity search

All similarity methods accept an optional slot parameter (defaults to 'default'):

All similarity methods set a similarity_score attribute (float) on each returned model.

threshold defaults to 0.0 — pass a value between 0.0 and 1.0 to filter low-scoring results.

Reranking

Cosine similarity is good at narrowing a large corpus down to candidates, but mixing in a rerank model on top — Cohere, Voyage, Jina — usually produces noticeably better top-K ordering for RAG pipelines. The package exposes this as a Collection macro that delegates to laravel/ai's reranking gateway:

Each returned model carries a rerank_score attribute alongside the existing similarity_score, sorted by rerank score descending. JSON responses include both attributes automatically — formatting and visibility are left to your application layer.

Full signature:

Empty collections and single-item collections short-circuit — no API call is made.

The active provider follows laravel/ai's ai.default_for_reranking config; the package does not add a second layer of provider/model configuration. If you need direct access (e.g. to rerank a manually fetched collection) resolve the service from the container:

Similarity Drivers

The php driver is built-in and works with any database — it loads vectors into PHP and computes cosine similarity in memory. For DB-level vector search, install the appropriate driver:

When a driver is installed, the auto selector detects the DB connection and switches automatically. Override via config or register a custom driver:

Plugins

Optional add-on packages that extend the core with non-storage concerns. Install only the ones you need.

embedding-pulse-plugin

Auto-discovered. Adds four Livewire cards (embedding.throughput, embedding.latency, embedding.failures, embedding.slots) that you drop into your Pulse dashboard:

Recorders listen to ModelEmbedded / ModelEmbedding / JobFailed and write into Pulse's own storage — no extra tables. See the plugin README for configuration details.

Model Events

Callbacks receive $model and $slot as arguments:

Laravel events ModelEmbedding and ModelEmbedded are also fired and each carry $model, $slot, and (for ModelEmbedded) $embedding.

Soft Delete

By default, deleting a model deletes all its slot embeddings. Set embedding.soft_delete to true to preserve them on soft delete.

Per-model override:

Artisan Commands

embedding:generate

When the model argument is omitted, the command scans app/Models (or app/) for classes implementing HasEmbeddings, asks for confirmation if more than one is found, and processes them sequentially. Failures are isolated per model and a summary is printed at the end.

embedding:clear

Bulk-delete stored embeddings. Requires either a model class or --all.

embedding:clean

Tidy up stale rows. By default deletes both orphan records (model class missing or model row no longer exists) and records whose slot is no longer defined in the model's embeddingSlotMap().

embedding:status

Read-only health report — configuration, per-slot coverage, orphan / invalid-slot counts, and storage size. Useful after deployments or as a periodic monitoring check.

Sample output:

Storage metrics are read through the VectorStoreMetrics contract. The core package ships a default implementation (JsonVectorStoreMetrics) that returns the row count via Eloquent and null for every byte field — DB-specific driver packages override the binding in their service provider to provide native byte figures.

You can read the same metrics from your own code:

rows is always an int. The byte fields are int|null — null means the driver cannot or will not supply that metric (insufficient privileges, unsupported backend, etc.) and is rendered as n/a by embedding:status. rows may be approximate when a driver reports it via fast metadata tables (e.g. MySQL information_schema.tables.table_rows); for an exact count, use XLaravel\Embedding\Models\Embedding::count() instead.

Configuration

Database

The core migration creates the vector column as json. DB-specific drivers ship their own migration with a native vector column type (VECTOR, vector). Publish the driver migration instead of the core one when using a driver:

Testing

License

This package is open-sourced software licensed under the MIT license.