Zum Hauptinhalt springen

Einführung

Es gibt mehrere Wege, in einer Anwendung eine Suche anzubieten. Laravel liefert dafür eingebaute Werkzeuge – von der reinen Stichwortsuche bis zur semantischen KI-Suche – ohne dass ein externer Dienst nötig wäre.

Funktionsvergleich

FunktionExterner DienstMerkmale
whereFullTextNeinEingebaute Volltextindizes in MariaDB/MySQL/PostgreSQL
whereVectorSimilarToNein (PostgreSQL + pgvector)Ähnlichkeitssuche über Bedeutung; benötigt AI SDK
RerankingKI-ProviderBeliebige Ergebnismengen per KI nach Relevanz sortieren
Laravel ScoutNein (database-Engine) / optionalAutomatische Indexsynchronisation von Eloquent-Modellen

Volltextsuche

LIKE-Abfragen sind praktisch für einfache Teilzeichenketten, verstehen aber keine Sprache. Volltextsuche nutzt spezialisierte Indizes, um Worten, Wortgrenzen und Relevanz zu berücksichtigen. MariaDB, MySQL und PostgreSQL unterstützen Volltextsuche eingebaut – ganz ohne externe Dienste.
Volltextsuche wird von MariaDB, MySQL und PostgreSQL unterstützt.

Volltextindex anlegen

Bevor Sie eine Volltextsuche verwenden, legen Sie einen Volltextindex auf den betroffenen Spalten an.
Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->timestamps();

    $table->fullText(['title', 'body']); // Zusammengesetzter Index
});
In PostgreSQL können Sie die Sprache angeben. Für andere Sprachen als Englisch ändert sich die Wortbeugung.
$table->fullText('body')->language('english');
Details finden Sie unter Migrationen.
Volltextsuche für Deutsch (bzw. nicht-lateinische Sprachen)
Die Unterstützung von MySQL variiert; auf AWS RDS ist z. B. nur der N-gram-Parser verfügbar, MeCab u. Ä. lässt sich nicht ergänzen. Auch PostgreSQL bietet für manche Sprachen nur eingeschränkte Wortformen. Wenn die Suchqualität kritisch ist, prüfen Sie spezialisierte Engines wie Meilisearch oder Typesense.

Volltextabfragen ausführen

Nach dem Anlegen des Indexes suchen Sie mit whereFullText. Laravel erzeugt je nach Datenbank passendes SQL (in MariaDB/MySQL MATCH(...) AGAINST(...), in PostgreSQL to_tsvector(...) @@ plainto_tsquery(...)).
$articles = Article::whereFullText('body', 'web developer')->get();
Für zusammengesetzte Indizes übergeben Sie dasselbe Spalten-Array.
$articles = Article::whereFullText(
    ['title', 'body'], 'web developer'
)->get();
In MariaDB/MySQL werden Treffer automatisch nach Relevanz sortiert. In PostgreSQL filtert whereFullText nur; für automatische Relevanzsortierung eignet sich die Datenbank-Engine von Scout.
Mit orWhereFullText fügen Sie eine Volltextsuche als OR-Bedingung an. Details im Query-Builder.

Semantische bzw. Vektorsuche

Volltextsuche basiert auf Wortgleichheit. Die Vektorsuche wählt einen grundlegend anderen Ansatz: KI erzeugt Vektor-Embeddings, mit denen die Bedeutung eines Textes als Zahlenarray repräsentiert wird – so lassen sich semantisch nahe Ergebnisse finden. Beispiel: Eine Suche nach „best wineries in Napa Valley“ findet einen Artikel „Top Vineyards to Visit“, obwohl kein Wort exakt übereinstimmt.
Für die Vektorsuche wird das Laravel AI SDK benötigt. Unterstützt werden PostgreSQL (mit pgvector) und MongoDB (mit dem Paket Laravel MongoDB). In allen Postgres-Datenbanken von Laravel Cloud ist pgvector vorinstalliert.

Embeddings erzeugen

Ein Embedding ist ein hochdimensionales Zahlenarray, das die Bedeutung eines Textes darstellt (oft mehrere hundert bis mehrere tausend Dimensionen). Sie erzeugen es mit der Methode toEmbeddings der Klasse Stringable.
use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();
Für mehrere Texte ist die Klasse Embeddings effizient – ein API-Aufruf für alles.
use Laravel\Ai\Embeddings;

$response = Embeddings::for([
    'Napa Valley has great wine.',
    'Laravel is a PHP framework.',
])->generate();

$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]
Konfiguration des Embedding-Providers und Dimensionen siehe AI-SDK-Dokumentation.

Vektoren speichern und indexieren

In der Migration definieren Sie eine vector-Spalte. dimensions muss zur Ausgabe des Providers passen (z. B. text-embedding-3-small von OpenAI: 1536). Mit index() legen Sie einen HNSW-Index an, der Ähnlichkeitssuchen bei großen Datenmengen erheblich beschleunigt.
Schema::ensureVectorExtensionExists(); // pgvector-Erweiterung aktivieren

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});
Casten Sie im Eloquent-Modell die Spalte embedding als array; PHP-Array und Datenbank-Vektorformat werden automatisch konvertiert.
protected function casts(): array
{
    return [
        'embedding' => 'array',
    ];
}
Details zu Vektorspalten und Indizes siehe Migrationen.

Nach Ähnlichkeit suchen

Nach dem Speichern der Embeddings finden Sie ähnliche Datensätze mit whereVectorSimilarTo. Verglichen wird per Kosinus-Ähnlichkeit; Ergebnisse unterhalb von minSimilarity werden verworfen und die verbleibenden nach Ähnlichkeit sortiert. Der Schwellenwert liegt zwischen 0.0 und 1.0; 1.0 bedeutet exakte Übereinstimmung.
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();
Statt einem Embedding-Array können Sie auch einen String übergeben – Laravel erzeugt das Embedding automatisch. Sehr praktisch, um Benutzeranfragen direkt zu verwenden.
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();
Für feinere Kontrolle stehen whereVectorDistanceLessThan, selectVectorDistance und orderByVectorDistance bereit. Details siehe Query Builder und AI SDK.

Reranking

Beim Reranking bringt ein KI-Modell eine bestehende Ergebnismenge in eine an der Query orientierte Reihenfolge. Anders als bei Vektorsuche müssen Sie keine Embeddings vorab berechnen und speichern; es lässt sich auf beliebige Textmengen anwenden. Sehr effektiv ist das Muster „Suchen → Reranken“: Zuerst grenzen Sie mit einer Volltextsuche viele Datensätze schnell ein und lassen sie anschließend per KI umsortieren. So kombinieren Sie die Geschwindigkeit der Datenbank mit der Präzision einer KI.
use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
Laravel-Collections bieten das Makro rerank; damit rerankieren Sie Eloquent-Ergebnisse mit Feldname (oder Closure) und Query.
$articles = Article::all()
    ->rerank('body', 'Laravel tutorials');
Konfiguration und Optionen des Reranking-Providers siehe AI SDK.

Laravel Scout

Die bisher gezeigten Ansätze rufen Query-Builder-Methoden direkt auf. Laravel Scout geht einen anderen Weg: Ergänzen Sie am Eloquent-Modell das Trait Searchable, synchronisiert Scout Neuanlagen, Aktualisierungen und Löschungen automatisch mit einem Suchindex.

Datenbank-Engine

Die eingebaute Datenbank-Engine sucht in der vorhandenen DB per Volltextsuche und LIKE – ohne zusätzliche Infrastruktur. In toSearchableArray definieren Sie die durchsuchbaren Spalten. Über PHP-Attribute legen Sie pro Spalte die Suchstrategie fest.
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;
use Laravel\Scout\Searchable;

class Article extends Model
{
    use Searchable;

    #[SearchUsingPrefix(['id'])]
    #[SearchUsingFullText(['title', 'body'])]
    public function toSearchableArray(): array
    {
        return [
            'id' => $this->id,
            'title' => $this->title,
            'body' => $this->body,
        ];
    }
}
AttributSuchstrategie
SearchUsingFullTextVolltextindex (MATCH...AGAINST / to_tsvector)
SearchUsingPrefixPräfix-Suche (example%)
ohneWildcards davor und dahinter (%example%)
Spalten mit SearchUsingFullText benötigen im Vorfeld einen Volltextindex.
Sobald das Trait gesetzt ist, verwenden Sie search. Die Datenbank-Engine von Scout liefert die Ergebnisse auch in PostgreSQL automatisch nach Relevanz sortiert.
$articles = Article::search('Laravel')->get();

Externe Engines

Scout unterstützt auch Algolia, Meilisearch und Typesense. Diese bieten fortgeschrittene Features wie Tippfehler-Toleranz, Facetten-, Geo-Suche und individuelle Ranking-Regeln. Da Scout eine einheitliche API bereitstellt, ist der Umstieg von der Datenbank-Engine auf eine externe Engine mit minimalen Codeänderungen möglich.
Die meisten Anwendungen benötigen keine externe Such-Engine. Die hier vorgestellten integrierten Methoden decken die überwiegende Zahl der Anwendungsfälle ab.
Details finden Sie im Leitfaden zu Laravel Scout.

Techniken kombinieren

Die gezeigten Ansätze schließen sich nicht aus. Kombinationen liefern häufig die besten Resultate.

Volltextsuche + Reranking

Volltextsuche filtert Kandidaten schnell heraus, Reranking sortiert danach semantisch. Das kombiniert Datenbank-Geschwindigkeit mit KI-Präzision.
$articles = Article::query()
    ->whereFullText('body', $request->input('query'))
    ->limit(50)
    ->get()
    ->rerank('body', $request->input('query'), limit: 10);

Vektorsuche + reguläre Filter

Kombinieren Sie Vektorsuche mit gewöhnlichen where-Klauseln, um semantische Suche auf einer bestimmten Teilmenge auszuführen. Praktisch, wenn Sie z. B. innerhalb eines Teams oder einer Kategorie semantisch suchen wollen.
$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $request->input('query'))
    ->limit(10)
    ->get();

Verwandte Seiten

Laravel Scout

Vollständige Anleitung, wie das Trait Searchable Modelle automatisch indiziert.

Laravel AI SDK

Konfiguration des AI SDK für Embeddings und Reranking.

Query Builder

Details zu whereFullText, whereVectorSimilarTo und mehr.

Migrationen

Anlegen von Volltextindizes und Vektorspalten.
Zuletzt geändert am 13. Juli 2026