Laravel 13.x 中文文档

主题

搜索 ​

简介 ​

几乎每个应用程序都需要搜索功能。无论您的用户是在知识库中搜索相关文章、浏览产品目录，还是对文档集进行自然语言查询，Laravel 都提供了内置工具来处理这些场景——而且通常不需要任何外部服务。

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

全文搜索 ​

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

语义/向量搜索 ​

对于按含义而非精确关键词匹配结果的 AI 驱动语义搜索，whereVectorSimilarTo 查询构建器方法使用存储在 PostgreSQL 中带有 pgvector 扩展的向量嵌入。例如，搜索"Napa Valley 最佳酒庄"可以显示标题为"值得参观的顶级葡萄园"的文章——即使这些词没有重叠。向量搜索需要带有 pgvector 扩展的 PostgreSQL 数据库和 Laravel AI SDK。

重排序 ​

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

Laravel Scout 搜索 ​

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

全文搜索 ​

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

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

WARNING

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

添加全文索引 ​

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

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

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

在 PostgreSQL 上，您可以为索引指定语言配置，这控制词如何进行词干提取：

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

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

执行全文查询 ​

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

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

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

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

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

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

语义/向量搜索 ​

全文搜索依赖于匹配关键词——查询中的词必须（以某种形式）出现在数据中。语义搜索采用根本不同的方法：它使用 AI 生成的向量嵌入将文本的含义表示为数字数组，然后找到含义与查询最相似的结果。例如，搜索"Napa Valley 最佳酒庄"可以显示标题为"值得参观的顶级葡萄园"的文章——即使这些词完全没有重叠。

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

NOTE

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

生成嵌入向量 ​

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

php
use Illuminate\Support\Str;

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

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

php
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（分层可导航小世界）索引，这可以显著加快大型数据集上的相似性搜索：

php
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 数组和数据库向量格式之间的转换：

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

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

按相似度查询 ​

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

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

为方便起见，当给定普通字符串而不是嵌入数组时，Laravel 会使用您配置的嵌入提供程序自动为您生成嵌入。这意味着您可以直接传递用户的搜索查询，而无需先手动将其转换为嵌入：

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

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

重排序结果 ​

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

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

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

php
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 结果变得容易：

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

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

Laravel Scout ​

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

数据库引擎 ​

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

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

php
<?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 上：

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

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

第三方引擎 ​

Scout 还支持第三方搜索引擎，如 Algolia、Meilisearch 和 Typesense。这些专用搜索服务提供高级功能，如容错、分面过滤、地理搜索和自定义排序规则——这些功能在非常大型的规模或需要高度完善的即时搜索体验时变得很重要。

由于 Scout 在所有驱动程序之间提供统一的 API，以后从数据库引擎切换到第三方引擎只需最少的代码更改。您可以从数据库引擎开始，只有在应用程序的需求超出数据库所能提供的功能时才迁移到第三方服务。

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

NOTE

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

组合技术 ​

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

全文检索 + 重排序

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

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

向量搜索 + 传统过滤器

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

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