Weave Code
Embedding Laravel Package
x-laravel/embedding
Laravel package that auto-generates and stores vector embeddings for Eloquent models via laravel/ai. Supports single or multi-slot embeddings with field-based triggers, queued generation per slot, driver-based similarity search across many databases, and optional reranking.
Automatic vector embedding generation for Laravel Eloquent models using laravel/ai.
Frequently asked questions about Embedding
- How do I enable automatic embedding generation for my Eloquent models?
- Add the `Embeddable` trait to your model and define trigger fields in the `$embeddable` property. For single-slot models, implement `toEmbeddingText()` to return the text to embed. The package handles the rest asynchronously via queued jobs.
- What Laravel versions are supported by this package?
- The package officially supports Laravel 12 and 13. It requires PHP 8.3+ and `laravel/ai ^0.6`. Always check the latest release notes for compatibility updates.
- Can I use multiple embedding slots for a single model?
- Yes, the package supports multi-slot embeddings. Define a nested array in `$embeddable` to map slots to their trigger fields, and return an array from `toEmbeddingText()` with slot-specific text.
- What happens if the embedding job queue fails?
- The package uses Laravel’s queue system, so failures will trigger retries based on your queue configuration. For critical applications, ensure your queue worker has proper error handling and consider a dead-letter queue for debugging.
- How do I switch from the PHP driver to a native vector database driver?
- Configure the `driver` in the published config file (e.g., `pgvector`, `mysql-heatwave`). The package abstracts the similarity search logic, so switching only requires updating the config and running migrations if needed.
- Does this package work with soft deletes in Eloquent?
- By default, embeddings are hard-deleted when the model is soft-deleted. You can customize this behavior by overriding the `shouldDeleteEmbeddings()` method in your model or adjusting the config.
- What are the performance implications of using the PHP driver for large datasets?
- The PHP driver is flexible but may struggle with datasets exceeding 100K embeddings due to memory constraints. For production-scale use, native drivers like `pgvector` or `mysql-heatwave` are recommended for sub-millisecond searches.
- How do I enable reranking for search results?
- Reranking requires `laravel/ai` and a supported provider (e.g., Cohere, Voyage). Configure the `rerank` section in the published config, then use the `rerank()` method on query results to reorder candidates based on semantic relevance.
- Are there any built-in monitoring or observability features?
- The package integrates with Laravel’s logging system and can be extended with custom metrics. For queue monitoring, use tools like Laravel Horizon or Datadog. The Pulse plugin (if available) may offer additional observability features.
- What alternatives exist for vector embeddings in Laravel?
- Alternatives include standalone libraries like `php-ai/embeddings` or database-specific extensions (e.g., `pgvector` for PostgreSQL). However, this package provides a Laravel-native solution with tight Eloquent integration, queued jobs, and multi-slot support.
Weaver
How can I help you explore Laravel packages today?