Laravel AI SDK on MariaDB
The laravel/ai package generates the embeddings; MariaDB stores and searches them.
Nothing connects the two beyond what the framework already does — see
mariadb-laravel-vector for the column, the index and the cast. Requires MariaDB 11.7+
(11.8 LTS recommended) on the mariadb driver.
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
Generating embeddings
use Illuminate\Support\Str;
use Laravel\Ai\Embeddings;
// One string...
$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();
// Many at once, with an explicit provider and dimensions...
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])
->dimensions(1536)
->generate(Lab::OpenAI, 'text-embedding-3-small');
$response->embeddings; // [[0.12, 0.45, ...], [0.78, 0.01, ...]]
The dimension count is a contract with the schema. vector('embedding', 1536) accepts
vectors of exactly that length; MariaDB rejects any other length at insert time. Pick the
model first, then size the column.
Storing them
Document::create([
'title' => $title,
'content' => $content,
'embedding' => Str::of($content)->toEmbeddings(),
]);
With 'embedding' => AsVector::class in the model's casts, the array is written as
vec_fromtext('[...]') and read back as an array of floats. Nothing else is needed.
Searching
$documents = Document::query()
->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
->limit(10)
->get();
Passing a string rather than a vector is what ties the two halves together: the query
builder calls Str::of($query)->toEmbeddings(cache: true) — a macro that only exists once
laravel/ai is installed and a provider is configured. Without the package, pass an array
of floats.
Cache the query embedding (cache: true is the default on that path): the same question
asked twice should not be billed twice.
Giving an agent the search as a tool
use App\Models\Document;
use Laravel\Ai\Tools\SimilaritySearch;
public function tools(): iterable
{
return [
SimilaritySearch::usingModel(
model: Document::class,
column: 'embedding',
minSimilarity: 0.7,
limit: 10,
query: fn ($query) => $query->where('published', true),
)->withDescription('Search the knowledge base for relevant articles.'),
];
}
This runs whereVectorSimilarTo against MariaDB on every tool call — the constraints of
mariadb-laravel-vector all apply, in particular that the vector index is only used when
the query's distance function matches the index's DISTANCE.
For a closure-based tool scoped to the current user, the same rule holds:
new SimilaritySearch(using: fn (string $query) => Document::query()
->where('user_id', $this->user->id)
->whereVectorSimilarTo('embedding', $query)
->limit(10)
->get());
Reranking
Laravel\Ai\Reranking reorders an already-retrieved list. The usual shape is a wide vector
search on MariaDB (cheap, the index does the work) followed by a rerank of the top 50 — not
a rerank of the whole table.
Pitfalls
Laravel\Ai\Storesis not MariaDB. Vector stores in the AI SDK are collections of files hosted by the AI provider; they are not a driver layer over your database, and no configuration points them at MariaDB. To keep the data in MariaDB, use a vector column and the query builder as above. Mixing both means two copies of the corpus.- Changing embedding model means re-embedding everything. Distances between vectors from different models are meaningless. Store the model name next to the vector, and if the new model has a different dimension count the column has to be altered too.
minSimilarityis a cosine notion. It becomesvec_distance_cosine(...) <= 1 - s. A value tuned for one embedding model does not transfer to another.- Do not call
Schema::ensureVectorExtensionExists()— it throws on MariaDB. Seemariadb-laravel-vector. - Embedding generation is a network call. Generating embeddings inside a request that also writes to the database holds a transaction open for the duration; queue the ingestion instead.
Related skills
mariadb-laravel-vector— the column, the index, the cast, the query methods.mariadb-laravel-connector— driver and version setup.