Weave Code
Embedding Laravel Package
x-laravel/embedding
Laravel package that automatically generates and stores vector embeddings for Eloquent models via laravel/ai. Define named slots, re-embed only changed fields with queued jobs, filter by payload, and run driver-based similarity search with optional reranking.
Automatic vector embedding generation for Laravel Eloquent models using laravel/ai.
Frequently asked questions about Embedding
- How do I install x-laravel/embedding in a Laravel application?
- Run composer require x-laravel/embedding, then publish the migrations with php artisan vendor:publish --tag=embedding-migrations and run php artisan migrate. Migrations are not loaded automatically, so this step is required. If you plan to use a database driver such as pgvector or MySQL HeatWave, publish the driver migrations instead. Optionally publish the config file with the embedding-config tag, then add the Embeddable trait and implement toEmbeddingText() on the models you want embedded.
- Which Laravel and PHP versions does x-laravel/embedding support?
- The package requires PHP 8.3 or newer and supports Laravel 12 and 13. It depends on laravel/ai ^0.6 for the underlying embedding and reranking gateways. If laravel/ai is already in your stack the added dependency surface is small; otherwise expect a second evolving package to track.
- What is a slot and why would I define multiple embedding slots?
- A slot is a named embedding channel on a model, each with its own text builder and its own set of trigger fields. Define several when you want different granularity, for example a title-only slot for fast lookups and a body or full-text slot for deeper semantic search. Because each slot listens to specific fields, only the slots whose sources changed are re-embedded when a model is saved.
- Does the package re-embed the whole model every time it is saved?
- No. Each slot tracks the trigger fields you list in $embeddable, and on save only the slots whose source fields actually changed are queued for regeneration. Unchanged slots keep their existing vectors, so updates to unrelated columns cost nothing. This incremental behavior is what makes the package practical for high-write models.
- Are embeddings generated synchronously or through queued jobs?
- Embedding generation runs in a queued job per slot, so saving a model never blocks on an HTTP call to the embedding provider. You need a running queue worker for vectors to appear, or a sync queue driver in tests. Because the work is asynchronous, embeddings can lag slightly behind the write, which is normally fine for search but worth planning for.
- Which similarity search drivers are supported?
- The default PHP driver computes cosine similarity in memory and works on any database, which is ideal for prototypes and modest datasets. Native drivers are available for PostgreSQL with pgvector, MySQL HeatWave, MariaDB 11.7+, Oracle 26ai, SQL Server 2025 and Qdrant, pushing the search down into the database. You can start on the PHP driver and switch later without changing your model code.
- How does payload filtering work with similarity search?
- Publish scalar model attributes as an embedding payload using the #[EmbedPayload] attribute, then pass filter: to your similarity search to constrain results at the database level. Filtering happens alongside the vector query instead of after it, so you do not waste candidate slots on rows you would discard anyway. It is the usual way to scope searches by tenant, status, category or published flag.
- Can I add reranking to improve search relevance?
- Yes. Reranking is an optional second stage that takes the fast, coarse cosine candidates and reorders them with a cross-encoder model through laravel/ai's rerank gateway, with Cohere, Voyage and Jina supported. It meaningfully improves relevance for RAG pipelines, at the cost of extra latency and third-party API spend. It is opt-in, so enable it only where result quality justifies the overhead.
- Can I store embeddings on a different database connection than my models?
- Yes. Since v1.0.3 the model table and the embeddings table may live on separate database connections. That supports topologies such as your app database on MySQL or Postgres with embeddings on a dedicated vector connection, or embeddings served from a read replica. v1.0.3 also fixed the placeholder-limit failures that previously made this setup unreliable at scale.
- How does it scale to large tables, and what changed in v1.0.3?
- The PHP driver is not intended for very large corpora, so beyond roughly 100K embeddings plan on a native driver such as pgvector or Qdrant. v1.0.3 removed the 65,535-placeholder ceiling in the status and clean commands by replacing a single IN list with windowed key-set comparison, which previously caused hard failures for large cross-connection ID sets. The trade-off is that those console commands now make several batched round trips, so budget extra runtime in maintenance windows and cron scheduling.
Weaver
How can I help you explore Laravel packages today?