Laravel Scout - Knowledge of Laravel

前言

Laravel Scout 是為 Eloquent model 加入全文搜尋功能的簡潔 driver-based 解決方案。透過 model observer 自動同步 Eloquent 記錄與搜尋索引。 Scout 內建 database 引擎，使用 MySQL / PostgreSQL 的全文索引與 LIKE 子句直接搜尋資料庫，無需外部服務。若需要在大型正式環境中容錯拼字、多面向搜尋或地理搜尋，外部引擎會派上用場。

支援的引擎一覽

引擎	特徵	用途
`database`	MySQL / PostgreSQL 的全文索引	大多數應用
`collection`	以 PHP 進行過濾（SQLite 也可）	本機開發、測試
Meilisearch	開源、容錯拼字、高速	正式環境
Algolia	雲端 SaaS、進階功能	正式環境
Typesense	開源、支援向量搜尋	正式環境
Turbopuffer	全文、語意與混合搜尋	正式環境

安裝

以 Composer 安裝套件。

composer require laravel/scout

安裝後執行 vendor:publish 指令發布設定檔。會產生 config/scout.php。

php artisan vendor:publish --provider="Laravel\Scout\ScoutServiceProvider"

最後在欲設為可搜尋的 model 加入 Laravel\Scout\Searchable trait。此 trait 會登記 model observer，並啟用與搜尋 driver 的自動同步。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;
}

Queue 設定

若使用 database 或 collection 以外的引擎，強烈建議在使用 Scout 前先設定 queue driver。啟動 queue worker 可讓索引同步操作在背景執行，大幅提升 Web 介面回應速度。將 config/scout.php 的 queue 選項設為 true。

'queue' => true,

也可指定連線名稱與 queue 名稱。

'queue' => [
    'connection' => 'redis',
    'queue' => 'scout'
],

設定後啟動專用的 queue worker。

php artisan queue:work redis --queue=scout

使用唯一性 Job

在寫入頻繁的應用中，可能想避免同一筆 model 有重複的 queue job 被登記。可在 config/scout.php 註冊 MakeSearchableUniquely 與 RemoveFromSearchUniquely job 類別以使用唯一性索引 job。通常在服務提供者的 boot 方法中設定。

use Laravel\Scout\Jobs\MakeSearchableUniquely;
use Laravel\Scout\Jobs\RemoveFromSearchUniquely;
use Laravel\Scout\Scout;

Scout::makeSearchableUsing(MakeSearchableUniquely::class);
Scout::removeFromSearchUsing(RemoveFromSearchUniquely::class);

這些 job 會使用 Laravel 的唯一性 job lock，避免重複分派針對相同 model 記錄的索引操作。

Driver 前置條件

Algolia

使用 Algolia driver 時，在 config/scout.php 設定 id 與 secret 認證資訊，並安裝 Algolia PHP SDK。

composer require algolia/algoliasearch-client-php

在 .env 檔加入認證資訊。

ALGOLIA_APP_ID=your-app-id
ALGOLIA_SECRET=your-secret-key

索引設定

Algolia 可在 config/scout.php 管理索引設定。

use App\Models\User;

'algolia' => [
    'id' => env('ALGOLIA_APP_ID', ''),
    'secret' => env('ALGOLIA_SECRET', ''),
    'index-settings' => [
        User::class => [
            'searchableAttributes' => ['id', 'name', 'email'],
            'attributesForFaceting' => ['filterOnly(email)'],
        ],
    ],
],

設定後執行 scout:sync-index-settings 指令將設定同步到 Algolia。

php artisan scout:sync-index-settings

Meilisearch

Meilisearch 是高速的開源搜尋引擎。本機開發最簡單的方式是使用 Laravel Sail 的 Docker。

# 使用 Laravel Sail 時
./vendor/bin/sail up -d meilisearch

若不用 Sail，也可用 Docker 直接啟動。

docker run -it --rm \
    -p 7700:7700 \
    getmeili/meilisearch:latest \
    meilisearch --master-key="masterKey"

安裝 Meilisearch PHP SDK。

composer require meilisearch/meilisearch-php http-interop/http-factory-guzzle

在 .env 檔設定 driver 與 host。

SCOUT_DRIVER=meilisearch
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=masterKey

升級 Scout 時，也務必確認 Meilisearch 服務本身的破壞性變更。

索引設定（Meilisearch）

Meilisearch 需將以 where() 過濾的欄位事先登記在 filterableAttributes，以 orderBy() 排序的欄位登記在 sortableAttributes。

use App\Models\User;

'meilisearch' => [
    'host' => env('MEILISEARCH_HOST', 'http://localhost:7700'),
    'key' => env('MEILISEARCH_KEY', null),
    'index-settings' => [
        User::class => [
            'filterableAttributes' => ['id', 'name', 'email'],
            'sortableAttributes' => ['created_at'],
        ],
    ],
],

請注意數值欄位的資料型別。Meilisearch 只能對型別正確的資料執行過濾操作（如 >、<）。

public function toSearchableArray(): array
{
    return [
        'id' => (int) $this->id,
        'name' => $this->name,
        'price' => (float) $this->price,
    ];
}

設定後執行 scout:sync-index-settings 指令。

php artisan scout:sync-index-settings

語意搜尋與混合搜尋（Meilisearch）

要在 Meilisearch 使用語意搜尋或混合搜尋，需在索引設定中指定 embedder，並在 model 設定中指定嵌入資訊。

'meilisearch' => [
    'index-settings' => [
        Article::class => [
            'embedders' => [
                'default' => [
                    'source' => 'userProvided',
                    'dimensions' => 1536,
                ],
            ],
        ],
    ],
    'model-settings' => [
        Article::class => [
            'embedding' => [
                'embedder' => 'default',
                'dimensions' => 1536,
            ],
        ],
    ],
],

model 的 toSearchableEmbedding 方法回傳供 Laravel AI SDK 產生嵌入的來源文字，或預先計算好的嵌入陣列。設定完成後請執行 scout:sync-index-settings。

Typesense

Typesense 是高速的開源搜尋引擎，支援關鍵字搜尋、語意搜尋、地理搜尋與向量搜尋。

composer require typesense/typesense-php

在 .env 檔設定連線資訊。

SCOUT_DRIVER=typesense
TYPESENSE_API_KEY=masterKey
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PATH=
TYPESENSE_PROTOCOL=http

使用 Typesense 時，需在 toSearchableArray 方法將 model 的主鍵轉為字串、將建立時間轉為 UNIX timestamp。

public function toSearchableArray(): array
{
    return array_merge($this->toArray(), [
        'id' => (string) $this->id,
        'created_at' => $this->created_at->timestamp,
    ]);
}

語意搜尋與混合搜尋（Typesense）

要在 Typesense 啟用語意搜尋與混合搜尋，請在 model 的 Typesense 設定中定義 embedding 設定與向量欄位。預設情況下，Scout 會使用 Laravel AI SDK 產生嵌入。

use App\Models\Article;

'model-settings' => [
    Article::class => [
        'collection-schema' => [
            'fields' => [
                ['name' => 'title', 'type' => 'string'],
                ['name' => 'embedding', 'type' => 'float[]', 'num_dim' => 1536],
            ],
        ],
        'search-parameters' => ['query_by' => 'title'],
        'embedding' => [
            'attribute' => 'embedding',
            'dimensions' => 1536,
        ],
    ],
],

model 的 toSearchableEmbedding 方法可回傳 Scout 用來產生嵌入的原始文字，或事先計算好的嵌入陣列。

public function toSearchableEmbedding(): string|array
{
    return $this->title.' '.$this->body;
}

若使用 Typesense 原生的嵌入功能，即使沒有 Laravel AI SDK 也能產生嵌入。詳情請參閱 Typesense 官方文件。

Turbopuffer

Turbopuffer 是支援全文、語意與混合搜尋的搜尋引擎。要使用 Turbopuffer driver，請設定 SCOUT_DRIVER 與 API 金鑰。

SCOUT_DRIVER=turbopuffer
TURBOPUFFER_API_KEY=tpuf_...
TURBOPUFFER_REGION=gcp-us-central1

TURBOPUFFER_REGION 可省略，預設為 gcp-us-central1。

資料庫／集合引擎

不需外部服務就想加入搜尋時的最佳選項。 資料庫引擎使用 MySQL / PostgreSQL 的全文索引與 LIKE 子句。對多數應用來說已足夠。

SCOUT_DRIVER=database

語意搜尋與混合搜尋

資料庫引擎在啟用 pgvector extension 的 PostgreSQL 上支援語意搜尋與混合搜尋。在 model 的資料表加入 nullable 的向量欄位與全文索引。Scout 會在 model 儲存後才寫入嵌入，因此向量欄位必須為 nullable。

Schema::ensureVectorExtensionExists();

Schema::table('articles', function (Blueprint $table) {
    $table->vector('embedding', dimensions: 1536)->nullable();
    $table->vectorIndex('embedding');
    $table->fullText(['title', 'body']);
});

在 model 定義 toSearchableEmbedding 方法。此方法回傳供 Scout 產生嵌入的來源文字，或預先計算好的嵌入陣列。嵌入預設儲存在 embedding 欄位，可透過 searchableEmbeddingColumn 方法變更。 集合引擎在 PHP 內過濾，能在包括 SQLite 在內的所有 Laravel 支援的資料庫上運作。適合本機開發、測試、小資料集。

SCOUT_DRIVER=collection

資料庫引擎與外部引擎不同，不需手動管理索引。直接搜尋資料庫資料表。

Turbopuffer 的設定

Turbopuffer 需針對每個 model，在 config/scout.php 的 model-settings 中定義可搜尋屬性與 schema。

'turbopuffer' => [
    'model-settings' => [
        Article::class => [
            'searchable-attributes' => [
                'title' => 3,
                'body' => 1,
            ],
            'schema' => [
                'title' => ['type' => 'string', 'full_text_search' => true],
                'body' => ['type' => 'string', 'full_text_search' => true],
                'status' => ['type' => 'string'],
            ],
        ],
    ],
],

searchable-attributes 的數值是 BM25 的相對權重。在此範例中，標題的比對對分數的貢獻是內文的 3 倍。要使用語意搜尋時，請加入 embedding 設定與向量的 schema，並讓 model 的 toSearchableEmbedding 方法回傳來源文字或嵌入陣列。

'embedding' => [
    'attribute' => 'embedding',
    'dimensions' => 1536,
],

'schema' => [
    'embedding' => ['type' => '[1536]f32', 'ann' => true],
],

若使用 Turbopuffer 的原生嵌入，則不需要 Laravel AI SDK 與 toSearchableEmbedding。將嵌入的來源屬性包含在 toSearchableArray 的回傳值中，並如下設定。

'embedding' => [
    'driver' => 'turbopuffer',
    'attribute' => 'embedding_text',
],

Searchable trait

自訂 toSearchableArray()

預設會把 model 的 toArray() 全部資料存入搜尋索引。要自訂同步到索引的資料，覆寫 toSearchableArray 方法。

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Laravel\Scout\Searchable;

class Post extends Model
{
    use Searchable;

    /**
     * 取得 model 可索引的資料陣列。
     *
     * @return array<string, mixed>
     */
    public function toSearchableArray(): array
    {
        $array = $this->toArray();

        // 自訂資料...

        return $array;
    }
}

自訂索引名稱

預設使用 model 的資料表名稱（複數）作為索引名稱。可覆寫 searchableAs 方法自訂。

public function searchableAs(): string
{
    return 'posts_index';
}

資料庫引擎的搜尋策略

資料庫引擎可以用 PHP 屬性為每個欄位指定高效的搜尋策略。

use Laravel\Scout\Attributes\SearchUsingFullText;
use Laravel\Scout\Attributes\SearchUsingPrefix;

#[SearchUsingPrefix(['id', 'email'])]
#[SearchUsingFullText(['bio'])]
public function toSearchableArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
        'email' => $this->email,
        'bio' => $this->bio,
    ];
}

使用 SearchUsingFullText 前，請確認目標欄位已設定全文索引。

條件性設為可搜尋

若只想在特定條件下讓 model 可搜尋，定義 shouldBeSearchable 方法。

/**
 * 決定是否要將此 model 設為可搜尋。
 */
public function shouldBeSearchable(): bool
{
    return $this->isPublished();
}

shouldBeSearchable 在資料庫引擎下無效。若要在資料庫引擎下達到相同行為，請使用where 子句。

索引管理

本節指令主要適用於使用 Algolia、Meilisearch、Typesense 等第三方引擎時。資料庫引擎不需管理索引。

匯入既有記錄

在既有專案導入 Scout 時，可用 scout:import 指令將既有記錄匯入索引。

php artisan scout:import "App\Models\Post"

也可用 queue 在背景匯入。

php artisan scout:queue-import "App\Models\Post" --chunk=500

清空索引

要從搜尋索引移除 model 的所有記錄，使用 scout:flush。

php artisan scout:flush "App\Models\Post"

暫停索引

在 Eloquent 操作中若想暫時停止與搜尋索引的同步，使用 withoutSyncingToSearch。

use App\Models\Order;

Order::withoutSyncingToSearch(function () {
    // 此區塊內的 model 操作不會同步到搜尋索引
});

手動新增、移除記錄

可用查詢將 model 集合加到索引。

// 加入查詢結果
Order::where('price', '>', 100)->searchable();

// 透過 relation 加入
$user->orders()->searchable();

要從索引移除記錄，使用 unsearchable。

Order::where('price', '>', 100)->unsearchable();

delete model 時會自動從索引中移除。

搜尋

用 search 方法搜尋 model。連結 get 取得 Eloquent model 的 collection。

use App\Models\Order;

$orders = Order::search('Star Trek')->get();

直接從控制器或路由回傳會自動轉為 JSON。

use Illuminate\Http\Request;

Route::get('/search', function (Request $request) {
    return Order::search($request->search)->get();
});

若需要原始搜尋結果，可用 raw 方法。

$orders = Order::search('Star Trek')->raw();

語意搜尋

在已設定嵌入的 database、Meilisearch、Typesense、Turbopuffer 引擎中，可依查詢的語意搜尋記錄。在搜尋查詢加上 semantic 方法。若由 Scout 產生嵌入，語意搜尋與混合搜尋需要 Laravel AI SDK。若使用 Typesense 原生嵌入、Turbopuffer 原生嵌入，或事先計算好的查詢向量，則不需要 Laravel AI SDK。

$articles = Article::search('如何在沒有電力的情況下讓住家保持舒適')
    ->semantic()
    ->get();

在支援的引擎上，也可以指定最小相似度門檻。

$articles = Article::search('再生能源的儲能')
    ->semantic(minSimilarity: 0.6)
    ->get();

要結合全文搜尋與語意搜尋，可使用 hybrid 方法。透過引數可指定文字搜尋與語意搜尋的相對權重。

$articles = Article::search('再生能源的儲能')
    ->hybrid(textWeight: 1, semanticWeight: 2)
    ->get();

分頁

可用 paginate 方法對搜尋結果分頁。與一般 Eloquent 查詢的分頁機制相同。

$orders = Order::search('Star Trek')->paginate();

// 指定每頁筆數
$orders = Order::search('Star Trek')->paginate(15);

資料庫引擎也可使用 simplePaginate。由於不取得總筆數，適合大型資料集。

$orders = Order::search('Star Trek')->simplePaginate(15);

Blade 樣板顯示範例：

<div class="container">
    @foreach ($orders as $order)
        {{ $order->price }}
    @endforeach
</div>

{{ $orders->links() }}

過濾與排序

用 where 方法可在搜尋查詢加入過濾條件。

use App\Models\Order;

// 等值過濾
$orders = Order::search('Star Trek')->where('user_id', 1)->get();

// 陣列中任一相符
$orders = Order::search('Star Trek')->whereIn('status', ['open', 'paid'])->get();

// 陣列中皆不相符
$orders = Order::search('Star Trek')->whereNotIn('status', ['closed'])->get();

使用 Meilisearch 時，使用 where 前需先設定可過濾屬性。

也能用 query 方法自訂 Eloquent 查詢。

use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with('invoices'))
    ->get();

Eager Loading

使用 Scout 時，會先從搜尋引擎取得 ID 清單，再以 Eloquent 取得 model。為避免 N+1 問題，可在 query 方法中用 with() 指定 eager loading。

use App\Models\Order;
use Illuminate\Database\Eloquent\Builder;

$orders = Order::search('Star Trek')
    ->query(fn (Builder $query) => $query->with(['invoices', 'user']))
    ->get();

批次匯入時要 eager load 關聯，可定義 makeAllSearchableUsing 方法。

use Illuminate\Database\Eloquent\Builder;

protected function makeAllSearchableUsing(Builder $query): Builder
{
    return $query->with('author');
}

makeAllSearchableUsing 有時無法用於使用 queue 的批次匯入。當 queue job 處理 model collection 時，關聯不會被還原。

軟刪除

若被索引的 model 使用軟刪除，且想同時搜尋已刪除的 model，將 config/scout.php 的 soft_delete 選項設為 true。

'soft_delete' => true,

啟用後可用 withTrashed 或 onlyTrashed 搜尋已刪除記錄。

// 包含已刪除
$orders = Order::search('Star Trek')->withTrashed()->get();

// 只搜尋已刪除
$orders = Order::search('Star Trek')->onlyTrashed()->get();

自訂引擎

若內建搜尋引擎不符需求，可實作自訂引擎。自訂引擎需繼承 Laravel\Scout\Engines\Engine 抽象類別，並實作以下 8 個方法。

use Laravel\Scout\Builder;

abstract public function update($models);
abstract public function delete($models);
abstract public function search(Builder $builder);
abstract public function paginate(Builder $builder, $perPage, $page);
abstract public function mapIds($results);
abstract public function map(Builder $builder, $results, $model);
abstract public function getTotalCount($results);
abstract public function flush($model);

可參考 Laravel\Scout\Engines\AlgoliaEngine 類別作為實作參考。建立好的自訂引擎，在 App\Providers\AppServiceProvider 的 boot 方法中註冊到 Scout。

use App\ScoutExtensions\MySqlSearchEngine;
use Laravel\Scout\EngineManager;

public function boot(): void
{
    resolve(EngineManager::class)->extend('mysql', function () {
        return new MySqlSearchEngine;
    });
}

註冊後，在 config/scout.php 指定為 driver。

'driver' => 'mysql',

Eloquent ORM

複習 Eloquent model 的基本用法。

Eloquent Relationships

確認 relationship 的定義與 eager loading。

Queue

Scout 可搭配 queue 在背景更新索引。

​前言

​支援的引擎一覽

​安裝

​Queue 設定

​使用唯一性 Job

​Driver 前置條件

​Algolia

​索引設定

​Meilisearch

​索引設定（Meilisearch）

​語意搜尋與混合搜尋（Meilisearch）

​Typesense

​語意搜尋與混合搜尋（Typesense）

​Turbopuffer

​資料庫／集合引擎

​語意搜尋與混合搜尋

​Turbopuffer 的設定

​Searchable trait

​自訂 toSearchableArray()

​自訂索引名稱

​資料庫引擎的搜尋策略

​條件性設為可搜尋

​索引管理

​匯入既有記錄

​清空索引

​暫停索引

​手動新增、移除記錄

​搜尋

​語意搜尋

​分頁

​過濾與排序

​Eager Loading

​軟刪除

​自訂引擎

​相關頁面

Eloquent ORM

Eloquent Relationships

Queue

前言

支援的引擎一覽

安裝

Queue 設定

使用唯一性 Job

Driver 前置條件

Algolia

索引設定

Meilisearch

索引設定（Meilisearch）

語意搜尋與混合搜尋（Meilisearch）

Typesense

語意搜尋與混合搜尋（Typesense）

Turbopuffer

資料庫／集合引擎

語意搜尋與混合搜尋

Turbopuffer 的設定

Searchable trait

自訂 toSearchableArray()

自訂索引名稱

資料庫引擎的搜尋策略

條件性設為可搜尋

索引管理

匯入既有記錄

清空索引

暫停索引

手動新增、移除記錄

搜尋

語意搜尋

分頁

過濾與排序

Eager Loading

軟刪除

自訂引擎

相關頁面