Vai al contenuto principale

Introduzione

Ci sono più modi per aggiungere la ricerca a un’applicazione. Laravel fornisce strumenti integrati che vanno dal match per keyword alla ricerca semantica con AI, senza servizi esterni obbligatori.

Confronto

FunzioneServizio esternoCaratteristiche
whereFullTextNessunoIndici full-text integrati di MariaDB/MySQL/PostgreSQL
whereVectorSimilarToNessuno (PostgreSQL + pgvector)Similarità semantica. Richiede AI SDK
RerankingProvider AIRiordina qualsiasi set per rilevanza tramite AI
Laravel ScoutNessuno (database engine) / opzionaleSincronizzazione automatica dell’indice

Ricerca full-text

Le query LIKE non capiscono la lingua. La ricerca full-text usa indici dedicati e tiene conto di parole, forme, punteggio di rilevanza. MariaDB, MySQL e PostgreSQL la supportano nativamente.
Supportata su MariaDB, MySQL, PostgreSQL.

Indici full-text

Schema::create('articles', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('body');
    $table->timestamps();

    $table->fullText(['title', 'body']);
});
PostgreSQL può indicare la lingua:
$table->fullText('body')->language('english');
Nota sulla ricerca full-text in giapponese / italiano non-standard
In MySQL la ricerca full-text non anglofona ha limiti (es. AWS RDS supporta solo N-gram parser). Anche PostgreSQL è limitato per lingue con morfologia complessa. Considera motori dedicati come Meilisearch o Typesense.

Esecuzione

$articles = Article::whereFullText('body', 'web developer')->get();
Con indice composito:
$articles = Article::whereFullText(
    ['title', 'body'], 'web developer'
)->get();
MariaDB/MySQL ordinano per rilevanza. In PostgreSQL whereFullText filtra soltanto: per l’ordinamento automatico usa il database engine di Scout.
Anche orWhereFullText per OR. Vedi il query builder.

Ricerca semantica / vettoriale

Il full-text si basa su match di keyword. La vector search usa embedding generati da AI per rappresentare il significato come array numerici e trovare risultati semanticamente vicini. Esempio: “best wineries in Napa Valley” corrisponde a “Top Vineyards to Visit” pur senza keyword condivise.
Richiede Laravel AI SDK. Supporta PostgreSQL (con l’estensione pgvector) e MongoDB (con laravel-mongodb). Laravel Cloud ha pgvector preinstallato su tutti i database Postgres.

Generare gli embedding

Con Stringable::toEmbeddings:
use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();
Batch con Embeddings:
use Laravel\Ai\Embeddings;

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

$response->embeddings;
Vedi la documentazione dell’AI SDK per configurazione e dimensioni.

Salvataggio e indicizzazione

Colonna vector in migration:
Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});
Cast in array:
protected function casts(): array
{
    return [
        'embedding' => 'array',
    ];
}
Vedi Migration.

Ricerca per similarità

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();
Passando una stringa, Laravel calcola l’embedding.
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();
Anche whereVectorDistanceLessThan, selectVectorDistance, orderByVectorDistance.

Reranking

L’AI riordina un set di risultati per rilevanza rispetto alla query. Diversa dalla vector search: non richiede embedding preesistenti e si applica a qualsiasi collezione di testo. Pattern efficace: filtra veloce + rerank.
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;
Le Collection Laravel hanno la macro rerank.
$articles = Article::all()
    ->rerank('body', 'Laravel tutorials');
Vedi la documentazione dell’AI SDK.

Laravel Scout

Fin qui abbiamo usato metodi del query builder. Laravel Scout è diverso: aggiungi il trait Searchable e Scout sincronizza automaticamente gli indici.

Database engine

Full-text + LIKE sul DB esistente. Senza servizi esterni.
<?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,
        ];
    }
}
AttributoStrategia
SearchUsingFullTextFull-text (MATCH...AGAINST / to_tsvector)
SearchUsingPrefixPrefisso (example%)
NessunoWildcard davanti/dietro (%example%)
$articles = Article::search('Laravel')->get();
Il database engine di Scout ordina per rilevanza anche in PostgreSQL.

Motori di terze parti

Scout supporta Algolia, Meilisearch, Typesense. API unificata: puoi migrare cambiando poco.
Non serve a tutti. I metodi integrati coprono la maggior parte dei casi.
Vedi la guida a Laravel Scout.

Combinazioni

Full-text + Reranking

Filtra veloce con full-text, poi rerank con AI.
$articles = Article::query()
    ->whereFullText('body', $request->input('query'))
    ->limit(50)
    ->get()
    ->rerank('body', $request->input('query'), limit: 10);

Vector + filtri classici

Restringi a un tenant e cerca per similarità.
$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $request->input('query'))
    ->limit(10)
    ->get();

Pagine correlate

Laravel Scout

Guida completa alla sincronizzazione automatica degli indici.

Laravel AI SDK

Configurazione dell’AI SDK per embedding e reranking.

Query Builder

Dettagli su whereFullText, whereVectorSimilarTo, ecc.

Migration

Creazione di indici full-text e colonne vector.
Ultima modifica il 13 luglio 2026