검색

업데이트됨

번역일: 2026년 6월 26일

이 페이지는 원문이 업데이트되어 번역이 갱신되었습니다.

원문 수정: 2026년 6월 20일
번역 갱신: 2026년 6월 26일

검색

소개
전문 검색 (Full-Text Search)
- 전문 인덱스 추가
- 전문 검색 쿼리 실행
시맨틱 / 벡터 검색
결과 리랭킹
Laravel Scout
- 데이터베이스 엔진
- 서드파티 엔진
기법 조합하기

소개

거의 모든 애플리케이션에는 검색 기능이 필요합니다. 사용자가 지식 베이스에서 관련 글을 찾거나, 상품 목록을 탐색하거나, 문서 모음에 자연어로 질문을 던지는 경우를 모두 Laravel의 기본 도구로 처리할 수 있습니다. 외부 서비스 없이도 충분한 경우가 많습니다.

대부분의 애플리케이션은 Laravel이 제공하는 데이터베이스 기반 검색 옵션만으로도 충분합니다. 오타 허용, 패싯 필터링, 대규모 지리 검색 같은 기능이 필요할 때에만 외부 검색 서비스를 고려하면 됩니다.

전문 검색 (Full-Text Search)

키워드 관련성 순위를 기준으로 — 즉, 데이터베이스가 검색어와 얼마나 잘 일치하는지 점수를 매겨 정렬해야 할 때 — Laravel의 whereFullText 쿼리 빌더 메서드를 사용하면 MariaDB, MySQL, PostgreSQL의 네이티브 전문 인덱스를 활용할 수 있습니다. 전문 검색은 단어 경계와 어간(stemming)을 이해하므로, "running"으로 검색해도 "run"이 포함된 레코드를 찾아줍니다. 외부 서비스는 필요하지 않습니다.

시맨틱 / 벡터 검색

정확한 키워드 일치가 아닌 의미로 결과를 매칭하는 AI 기반 시맨틱 검색이 필요하다면, whereVectorSimilarTo 쿼리 빌더 메서드를 사용하세요. 이 메서드는 pgvector 확장이 설치된 PostgreSQL에 저장된 벡터 임베딩을 활용합니다. 예를 들어 "서울 근교 맛집 추천"으로 검색해도 "수도권 인근 음식점 가이드"라는 제목의 글을 찾아낼 수 있습니다. 단어가 전혀 겹치지 않아도 말이죠. 벡터 검색은 pgvector 확장이 설치된 PostgreSQL과 Laravel AI SDK가 필요합니다.

리랭킹

Laravel의 AI SDK는 AI 모델을 사용해 검색 결과를 쿼리와의 시맨틱 관련성 순서로 재정렬하는 리랭킹 기능을 제공합니다. 리랭킹은 전문 검색처럼 빠른 초기 검색 단계 이후의 두 번째 단계로 특히 강력합니다. 속도와 시맨틱 정확도를 동시에 얻을 수 있습니다.

Laravel Scout 검색 엔진

Searchable 트레이트를 사용해 Eloquent 모델과 검색 인덱스를 자동으로 동기화하고 싶다면 Laravel Scout를 사용하세요. Scout는 내장 데이터베이스 엔진은 물론 Algolia, Meilisearch, Typesense 등 서드파티 서비스용 드라이버도 제공합니다.

전문 검색 (Full-Text Search)

LIKE 쿼리는 단순한 부분 문자열 매칭에는 잘 동작하지만, 언어를 이해하지 못합니다. LIKE로 "running"을 검색하면 "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', '라라벨 개발')->get();

MariaDB와 MySQL에서는 결과가 관련성 점수 순으로 자동 정렬됩니다. PostgreSQL에서는 whereFullText가 일치하는 레코드를 필터링하지만 관련성 순 정렬은 하지 않습니다. PostgreSQL에서 자동 관련성 정렬이 필요하다면 이를 처리해주는 Scout의 데이터베이스 엔진을 고려하세요.

여러 컬럼에 복합 전문 인덱스를 만든 경우, 동일한 컬럼 배열을 whereFullText에 전달해 모든 컬럼을 대상으로 검색할 수 있습니다:

$articles = Article::whereFullText(
    ['title', 'body'], '라라벨 개발'
)->get();

orWhereFullText 메서드를 사용하면 전문 검색 조건을 "or" 조건으로 추가할 수 있습니다. 자세한 내용은 쿼리 빌더 문서를 참고하세요.

시맨틱 / 벡터 검색

전문 검색은 키워드 매칭에 의존하므로, 쿼리의 단어가 데이터에 어떤 형태로든 존재해야 합니다. 시맨틱 검색은 근본적으로 다른 접근 방식을 취합니다. AI가 생성한 벡터 임베딩으로 텍스트의 의미를 숫자 배열로 표현하고, 쿼리와 가장 의미가 유사한 결과를 찾습니다. 예를 들어 "제주도 숙박 추천"으로 검색해도 "한라산 인근 스테이 가이드"라는 제목의 글을 찾아낼 수 있습니다. 단어가 전혀 겹치지 않아도 됩니다.

벡터 검색의 기본 흐름은 다음과 같습니다. 각 콘텐츠에 대한 임베딩(숫자 배열)을 생성해 데이터와 함께 저장하고, 검색 시 사용자 쿼리에 대한 임베딩을 생성한 뒤 벡터 공간에서 가장 가까운 저장된 임베딩을 찾습니다.

NOTE

벡터 검색은 Laravel AI SDK가 필요하며, PostgreSQL(pgvector 확장 필요)과 MongoDB(Laravel MongoDB 패키지 필요)에서 지원됩니다. Laravel Cloud의 모든 Postgres 데이터베이스에는 pgvector가 이미 설치되어 있습니다.

임베딩 생성

임베딩은 텍스트의 시맨틱 의미를 나타내는 고차원 숫자 배열(보통 수백~수천 개의 숫자)입니다. Laravel의 Stringable 클래스에서 toEmbeddings 메서드를 사용해 문자열의 임베딩을 생성할 수 있습니다:

use Illuminate\Support\Str;

$embedding = Str::of('제주도 한라산 등반 코스')->toEmbeddings();

여러 입력에 대한 임베딩을 한 번에 생성하려면 — 임베딩 제공자에 대한 API 호출을 한 번만 수행하므로 개별 생성보다 훨씬 효율적입니다 — Embeddings 클래스를 사용하세요:

use Laravel\Ai\Embeddings;

$response = Embeddings::for([
    '제주도 한라산 등반 코스',
    'Laravel은 PHP 프레임워크입니다.',
])->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', '제주도 숙박 추천')
    ->limit(10)
    ->get();

벡터 쿼리를 더 세밀하게 제어하려면 whereVectorDistanceLessThan, selectVectorDistance, orderByVectorDistance 메서드도 사용할 수 있습니다. 이 메서드들은 유사도 점수 대신 거리 값을 직접 다루거나, 계산된 거리를 결과의 컬럼으로 선택하거나, 정렬을 수동으로 제어할 때 유용합니다. 자세한 내용은 쿼리 빌더 문서와 AI SDK 문서를 참고하세요.

결과 리랭킹

리랭킹은 AI 모델이 결과 집합을 주어진 쿼리와의 시맨틱 관련성 순서로 재정렬하는 기법입니다. 벡터 검색과 달리 임베딩을 미리 계산해 저장할 필요가 없으며, 어떤 텍스트 컬렉션에도 적용할 수 있습니다. 원본 콘텐츠와 쿼리를 입력으로 받아 관련성 순으로 정렬된 항목들을 반환합니다.

리랭킹은 빠른 초기 검색 단계 이후의 두 번째 단계로 특히 강력합니다. 예를 들어 전문 검색으로 수천 개의 레코드 중 상위 50개의 후보를 빠르게 추린 다음, 리랭킹으로 가장 관련성 높은 결과를 상위에 배치할 수 있습니다. 이 "검색 후 리랭킹" 패턴은 속도와 시맨틱 정확도를 동시에 제공합니다.

Reranking 클래스를 사용해 문자열 배열을 리랭킹할 수 있습니다:

use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django는 Python 웹 프레임워크입니다.',
    'Laravel은 PHP 웹 애플리케이션 프레임워크입니다.',
    'React는 사용자 인터페이스를 만들기 위한 JavaScript 라이브러리입니다.',
])->rerank('PHP 프레임워크');

$response->first()->document; // "Laravel은 PHP 웹 애플리케이션 프레임워크입니다."

Laravel 컬렉션에도 rerank 매크로가 있어, 필드명(또는 클로저)과 쿼리를 전달해 Eloquent 결과를 손쉽게 리랭킹할 수 있습니다:

$articles = Article::all()
    ->rerank('body', 'Laravel 튜토리얼');

리랭킹 제공자 설정과 사용 가능한 옵션에 대한 자세한 내용은 AI SDK 문서를 참고하세요.

Laravel Scout

앞서 설명한 검색 기법들은 모두 코드에서 직접 호출하는 쿼리 빌더 메서드입니다. Laravel Scout는 다른 접근 방식을 취합니다. Eloquent 모델에 Searchable 트레이트를 추가하면 Scout가 레코드 생성, 수정, 삭제 시 검색 인덱스를 자동으로 동기화해 줍니다. 인덱스 업데이트를 수동으로 관리하지 않아도 모델이 항상 검색 가능한 상태를 유지하려 할 때 특히 편리합니다.

데이터베이스 엔진

Scout의 내장 데이터베이스 엔진은 기존 데이터베이스에서 전문 검색과 LIKE 검색을 수행합니다. 외부 서비스나 추가 인프라가 필요 없습니다. 모델에 Searchable 트레이트를 추가하고 검색 가능하게 할 컬럼을 반환하는 toSearchableArray 메서드를 정의하기만 하면 됩니다.

PHP 속성(attribute)을 사용해 각 컬럼의 검색 전략을 제어할 수 있습니다. 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

컬럼에 전문 검색 쿼리 조건을 지정하기 전에, 해당 컬럼에 전문 인덱스가 설정되어 있는지 확인하세요.

트레이트를 추가하면 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();