搜索

简介

几乎每个应用都需要搜索。无论你的用户是在知识库中搜索相关文章、浏览产品目录，还是针对文档语料库提出自然语言问题，Laravel 都提供了内置工具来处理这些场景——而且你通常不需要任何外部服务就能实现。

大多数应用会发现 Laravel 提供的内置数据库驱动选项已经足够了——只有当你需要大规模的拼写容错、分面过滤或地理搜索等功能时，才需要外部搜索服务。

全文搜索

当你需要关键词相关性排名——数据库根据结果与搜索词的匹配程度进行评分和排序时——Laravel 的 whereFullText 查询构建器方法利用了 MariaDB、MySQL 和 PostgreSQL 上的原生全文索引。全文搜索理解词边界和词干提取，因此搜索 "running" 可以匹配包含 "run" 的记录。不需要外部服务。

语义/向量搜索

对于按含义而非精确关键词匹配结果的 AI 驱动语义搜索，whereVectorSimilarTo 查询构建器方法使用存储在带有 pgvector 扩展的 PostgreSQL 中的向量嵌入。例如，搜索 "best wineries in Napa Valley" 可以呈现标题为 "Top Vineyards to Visit" 的文章——即使词语完全不重叠。向量搜索需要带有 pgvector 扩展的 PostgreSQL 和 Laravel AI SDK。

重排序

Laravel 的 AI SDK 提供了重排序功能，使用 AI 模型根据查询的语义相关性对任何结果集进行重新排序。重排序作为快速初始检索步骤（如全文搜索）之后的第二阶段特别强大——为你提供速度和语义准确性。

Laravel Scout 搜索

对于希望使用 Searchable trait 自动保持搜索索引与 Eloquent 模型同步的应用，Laravel Scout 提供了内置数据库引擎和第三方服务（如 Algolia、Meilisearch 和 Typesense）的驱动。

全文搜索

虽然 LIKE 查询对于简单的子字符串匹配效果很好，但它们不理解语言。对 "running" 的 LIKE 搜索不会找到包含 "run" 的记录，结果也不会按相关性排名——它们只是以数据库找到它们的任何顺序返回。全文搜索通过使用理解词边界、词干提取和相关性评分的专用索引来解决这两个问题，允许数据库首先返回最相关的结果。

快速全文搜索内置于 MariaDB、MySQL 和 PostgreSQL 中——不需要外部搜索服务。你只需要向要搜索的列添加全文索引，然后使用 whereFullText 查询构建器方法对其进行搜索。

WARNING

全文搜索目前由 MariaDB、MySQL 和 PostgreSQL 支持。

添加全文索引

要使用全文搜索，首先向要搜索的列添加全文索引。你可以将索引添加到单个列，或传递列数组以创建跨多个字段同时搜索的复合索引：

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

    $table->fullText(['title', 'body']);
});

在 PostgreSQL 上，你可以为索引指定语言配置，用于控制词干提取方式：

$table->fullText('body')->language('english');

有关创建索引的更多信息，请参阅迁移文档。

运行全文查询

索引就位后，使用 whereFullText 查询构建器方法对其进行搜索。Laravel 将为你的数据库驱动生成适当的 SQL——例如，在 MariaDB 和 MySQL 上为 MATCH(...) AGAINST(...)，在 PostgreSQL 上为 to_tsvector(...) @@ plainto_tsquery(...)：

$articles = Article::whereFullText('body', 'web developer')->get();

使用 MariaDB 和 MySQL 时，结果会自动按相关性分数排序。在 PostgreSQL 上，whereFullText 过滤匹配的记录但不按相关性排序——如果你需要在 PostgreSQL 上自动按相关性排序，请考虑使用 Scout 的数据库引擎，它会为你处理此事。

如果你创建了跨多个列的复合全文索引，可以通过将相同的列数组传递给 whereFullText 来搜索所有列：

$articles = Article::whereFullText(
    ['title', 'body'], 'web developer'
)->get();

orWhereFullText 方法可用于将全文搜索子句作为 "or" 条件添加。有关完整详细信息，请参阅查询构建器文档。

语义/向量搜索

全文搜索依赖于匹配关键词——查询中的词必须以某种形式出现在数据中。语义搜索采用了根本不同的方法：它使用 AI 生成的向量嵌入将文本的含义表示为数字数组，然后找到含义与查询最相似的结果。例如，搜索 "best wineries in Napa Valley" 可以呈现标题为 "Top Vineyards to Visit" 的文章——即使词语完全不重叠。

向量搜索的基本工作流程是：为每段内容生成嵌入（数字数组）并将其与数据一起存储，然后在搜索时为用户的查询生成嵌入，并在向量空间中找到与之最接近的已存储嵌入。

NOTE

向量搜索需要带有 pgvector 扩展的 PostgreSQL 数据库和 Laravel AI SDK。所有 Laravel Cloud Serverless Postgres 数据库已包含 pgvector。

生成嵌入

嵌入是一个高维数字数组（通常包含数百或数千个数字），表示一段文本的语义含义。你可以使用 Laravel 的 Stringable 类上可用的 toEmbeddings 方法为字符串生成嵌入：

use Illuminate\Support\Str;

$embedding = Str::of('Napa Valley has great wine.')->toEmbeddings();

要一次为多个输入生成嵌入——这比逐个生成更高效，因为只需要对嵌入提供者进行一次 API 调用——请使用 Embeddings 类：

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, ...]]

有关配置嵌入提供者、自定义维度和缓存的更多详细信息，请参阅 AI SDK 文档。

存储和索引向量

要存储向量嵌入，请在迁移中定义一个 vector 列，指定与嵌入提供者输出匹配的维度数（例如，OpenAI 的 text-embedding-3-small 模型为 1536）。你还应该在列上调用 index 以创建 HNSW（Hierarchical Navigable Small World）索引，这会显著加速大型数据集上的相似性搜索：

Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536)->index();
    $table->timestamps();
});

Schema::ensureVectorExtensionExists 方法确保在创建表之前在 PostgreSQL 数据库上启用了 pgvector 扩展。

在 Eloquent 模型上，将向量列转换为 array，以便 Laravel 自动处理 PHP 数组和数据库向量格式之间的转换：

protected function casts(): array
{
    return [
        'embedding' => 'array',
    ];
}

有关向量列和索引的更多详细信息，请参阅迁移文档。

按相似度查询

存储内容的嵌入后，你可以使用 whereVectorSimilarTo 方法搜索相似记录。此方法使用余弦相似度将给定的嵌入与存储的向量进行比较，过滤掉低于 minSimilarity 阈值的结果，并自动按相关性排序结果——最相似的记录排在最前面。阈值应为 0.0 到 1.0 之间的值，其中 1.0 表示向量完全相同：

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

为了方便，当给出纯字符串而不是嵌入数组时，Laravel 将使用你配置的嵌入提供者自动为你生成嵌入。这意味着你可以直接传递用户的搜索查询，而无需先手动将其转换为嵌入：

$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();

对于向量查询的更低级别控制，还提供了 whereVectorDistanceLessThan、selectVectorDistance 和 orderByVectorDistance 方法。这些方法让你可以直接使用距离值而不是相似度分数，将计算的距离作为结果中的列选择，或手动控制排序。有关完整详细信息，请参阅查询构建器文档和 AI SDK 文档。

重排序结果

重排序是一种技术，AI 模型根据每条结果与给定查询的语义相关性对一组结果进行重新排序。与向量搜索不同（需要预先计算和存储嵌入），重排序适用于任何文本集合——它将原始内容和查询作为输入，并返回按相关性排序的条目。

重排序作为快速初始检索步骤之后的第二阶段特别强大。例如，你可以使用全文搜索快速将数千条记录缩减到前 50 个候选结果，然后使用重排序将最相关的结果放在最前面。这种「检索然后重排序」模式为你提供了速度和语义准确性。

你可以使用 Reranking 类对字符串数组进行重排序：

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 集合还有一个 rerank 宏，接受字段名（或闭包）和查询，使重排序 Eloquent 结果变得简单：

$articles = Article::all()
    ->rerank('body', 'Laravel tutorials');

有关配置重排序提供者和可用选项的完整详细信息，请参阅 AI SDK 文档。

Laravel Scout

上面描述的搜索技术都是你在代码中直接调用的查询构建器方法。Laravel Scout 采用了不同的方法：它提供了一个 Searchable trait，你可以将其添加到 Eloquent 模型中，Scout 会在记录创建、更新和删除时自动保持搜索索引同步。当你希望模型始终可搜索而无需手动管理索引更新时，这特别方便。

数据库引擎

Scout 的内置数据库引擎对你现有的数据库执行全文和 LIKE 搜索——不需要外部服务或额外基础设施。只需将 Searchable trait 添加到你的模型并定义一个 toSearchableArray 方法，返回你希望可搜索的列。

你可以使用 PHP 属性来控制每列的搜索策略。SearchUsingFullText 将使用数据库的全文索引，SearchUsingPrefix 只会从字符串开头匹配（example%），任何没有属性的列使用默认的 LIKE 策略，两侧都有通配符（%example%）：

<?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,
        ];
    }
}

WARNING

在指定列应使用全文查询约束之前，请确保该列已分配了全文索引。

添加 trait 后，你可以使用 Scout 的 search 方法搜索你的模型。Scout 的数据库引擎会自动按相关性排序结果，即使在 PostgreSQL 上也是如此：

$articles = Article::search('Laravel')->get();

当你的搜索需求适中并且希望利用 Scout 的自动索引同步便利性而无需部署外部服务时，数据库引擎是一个很好的选择。它能很好地处理最常见的搜索用例，包括过滤、分页和软删除记录处理。有关完整详细信息，请参阅 Scout 文档。

第三方引擎

Scout 还支持第三方搜索引擎，如 Algolia、Meilisearch 和 Typesense。这些专用搜索服务提供了高级功能，如拼写容错、分面过滤、地理搜索和自定义排名规则——这些功能在非常大的规模下或当你需要高度精致的边输入边搜索体验时变得重要。

由于 Scout 在其所有驱动中提供了统一的 API，因此从数据库引擎切换到第三方引擎只需要最少的代码更改。你可以从数据库引擎开始，只有在应用的需求超出数据库所能提供的范围时才迁移到第三方服务。

有关配置第三方引擎的完整详细信息，请参阅 Scout 文档。

NOTE

许多应用永远不需要外部搜索引擎。本页描述的内置技术涵盖了绝大多数用例。

组合技术

本页描述的搜索技术并不互斥——组合使用它们通常会产生最佳结果。以下是两种常见模式，展示了这些工具如何协同工作。

全文检索 + 重排序

使用全文搜索快速将大型数据集缩减到候选集，然后应用重排序按语义相关性对这些候选结果进行排序。这为你提供了数据库原生全文搜索的速度和 AI 驱动的相关性评分的准确性：

$articles = Article::query()
    ->whereFullText('body', $request->input('query'))
    ->limit(50)
    ->get()
    ->rerank('body', $request->input('query'), limit: 10);

向量搜索 + 传统过滤

将向量相似度与标准 where 子句结合使用，将语义搜索限定在记录的子集中。当你需要基于含义的搜索但又需要按所有权、类别或任何其他属性限制结果时，这非常有用：

$documents = Document::query()
    ->where('team_id', $user->team_id)
    ->whereVectorSimilarTo('embedding', $request->input('query'))
    ->limit(10)
    ->get();