시작하기
애플리케이션에 검색 기능을 추가하는 방법은 용도에 따라 여러 가지가 있습니다. Laravel은 키워드 일치부터 AI를 사용한 시맨틱 검색까지, 외부 서비스 불필요로 대응할 수 있는 조립된 도구를 제공하고 있습니다.기능 비교
| 기능 | 외부 서비스 | 특징 |
|---|---|---|
whereFullText | 불필요 | MariaDB / MySQL / PostgreSQL 조립된 전문 인덱스 |
whereVectorSimilarTo | 불필요 (PostgreSQL + pgvector) | 의미적인 유사도로 검색. AI SDK가 필요 |
Reranking | AI 프로바이더 | 임의의 결과 세트를 AI로 관련도 순으로 재정렬 |
| Laravel Scout | 불필요 (database 엔진) / 임의 | Eloquent 모델의 자동 인덱스 동기 |
전문 검색
LIKE 쿼리는 심플한 부분 일치에는 편리하지만, 언어를 이해하지 않습니다. 전문 검색은 전용 인덱스를 사용해 단어의 경계·어형 변화·관련도 스코어를 고려한 검색을 수행합니다.
MariaDB·MySQL·PostgreSQL은 전문 검색을 조립되어 지원하고 있어, 외부 서비스는 불필요합니다.
전문 인덱스의 추가
전문 검색을 사용하려면, 우선 대상 컬럼에 전문 인덱스를 추가합니다.한국어 전문 검색의 주의 사항
MySQL에서의 한국어 전문 검색은 약간 사용하기 어려운 면이 있습니다. AWS RDS에서는 N-gram 파서만 이용 가능하며, 형태소 분석 플러그인을 추가할 수 없기 때문에 제한됩니다. Laravel Cloud의 MySQL도 마찬가지라고 생각됩니다. PostgreSQL에서도 한국어의 어형 변화 대응은 한정적입니다. 한국어 검색의 정확도가 중요한 경우는 Meilisearch나 Typesense 등의 전용 엔진의 이용을 검토해 주세요.
전문 쿼리의 실행
인덱스를 추가하면whereFullText 메서드로 검색합니다. Laravel은 사용하고 있는 데이터베이스 드라이버에 맞춰 적절한 SQL을 생성합니다 (MariaDB / MySQL에서는 MATCH(...) AGAINST(...), PostgreSQL에서는 to_tsvector(...) @@ plainto_tsquery(...)).
MariaDB·MySQL에서는 결과가 자동적으로 관련도 스코어 순으로 늘어섭니다. PostgreSQL에서는
whereFullText는 매치하는 레코드를 필터링할 뿐이며 관련도 순이 되지 않습니다. PostgreSQL에서 자동적인 관련도 순이 필요한 경우는 Scout의 데이터베이스 엔진이 유효합니다.orWhereFullText 메서드로 OR 조건으로서 전문 검색을 추가할 수도 있습니다. 상세는 쿼리 빌더 문서를 참조해 주세요.
시맨틱 / 벡터 검색
전문 검색은 키워드의 일치에 의존하고 있습니다. 벡터 검색은 근본적으로 다른 접근 방법으로, AI가 생성한 벡터 임베딩을 사용해 텍스트의 의미를 수치 배열로서 표현하고, 의미적으로 가까운 결과를 검색합니다. 예를 들어 “best wineries in Napa Valley”라는 검색으로 “Top Vineyards to Visit”라는 타이틀의 기사가 히트합니다. 단어가 일치하지 않아도 의미가 가깝기 때문입니다.벡터 검색에는 Laravel AI SDK가 필요하며, PostgreSQL(
pgvector 확장이 필요)과 MongoDB(Laravel MongoDB 패키지가 필요)를 지원합니다. Laravel Cloud의 모든 Postgres 데이터베이스에는 pgvector가 사전 설치되어 있습니다.임베딩의 생성
임베딩은 텍스트의 의미를 나타내는 고차원의 수치 배열(통상 수백~수천 차원)입니다. Laravel의Stringable 클래스의 toEmbeddings 메서드로 생성할 수 있습니다.
Embeddings 클래스를 사용하면 효율적입니다(API 호출이 1회로 끝납니다).
벡터의 보존과 인덱스 작성
벡터 임베딩을 보존하려면, 마이그레이션으로vector 컬럼을 정의합니다. 임베딩 프로바이더의 출력 차원 수에 맞춰 dimensions를 지정해 주세요(예: OpenAI의 text-embedding-3-small은 1536 차원). index()를 호출해 HNSW 인덱스를 작성하면, 대규모 데이터셋에서의 유사 검색이 대폭 고속화됩니다.
embedding 컬럼을 array로 캐스트해, PHP 배열과 데이터베이스의 벡터 형식의 변환을 자동화합니다.
유사도에 의한 검색
임베딩을 보존하면,whereVectorSimilarTo 메서드로 유사 레코드를 검색할 수 있습니다. 코사인 유사도로 벡터를 비교하고, minSimilarity 임계값 이하의 결과를 필터링해, 관련성이 높은 순으로 자동 정렬합니다. 임계값은 0.0~1.0의 값으로, 1.0은 완전 일치를 의미합니다.
whereVectorDistanceLessThan·selectVectorDistance·orderByVectorDistance도 이용할 수 있습니다. 상세는 쿼리 빌더 문서와 AI SDK 문서를 참조해 주세요.
리랭킹
리랭킹은, AI 모델이 결과 세트를 쿼리와의 관련도 순으로 재정렬하는 수법입니다. 벡터 검색과 달리, 사전에 임베딩을 계산·보존할 필요는 없고, 임의의 텍스트 컬렉션에 적용할 수 있습니다. 전문 검색으로 대량의 레코드를 빠르게 좁힌 후에 리랭킹을 적용하는 “검색→리랭크” 패턴이 특히 효과적입니다. 데이터베이스의 속도와 AI의 정확도를 양립할 수 있습니다.rerank 매크로가 있어, 필드명(또는 클로저)과 쿼리를 전달하는 것만으로 Eloquent의 결과를 리랭크할 수 있습니다.
Laravel Scout
여기까지 설명한 검색 수법은 모두 쿼리 빌더의 메서드를 직접 호출하는 것이었습니다. Laravel Scout는 다른 접근 방법을 취합니다. Eloquent 모델에Searchable 트레이트를 추가하면, Scout가 레코드의 작성·업데이트·삭제에 맞춰 검색 인덱스를 자동 동기합니다.
데이터베이스 엔진
Scout 조립된 데이터베이스 엔진은 기존의 데이터베이스에 대해 전문 검색과LIKE 검색을 수행합니다. 외부 서비스도 인프라도 추가 불필요합니다.
toSearchableArray 메서드로 검색 대상의 컬럼을 정의합니다. PHP 애트리뷰트로 컬럼별로 검색 전략을 지정할 수 있습니다.
| 애트리뷰트 | 검색 전략 |
|---|---|
SearchUsingFullText | 전문 인덱스를 사용 (MATCH...AGAINST / to_tsvector) |
SearchUsingPrefix | 전방 일치 (example%) |
| 없음 | 전후 와일드카드 (%example%) |
search 메서드로 모델을 검색할 수 있습니다. Scout의 데이터베이스 엔진은 PostgreSQL에서도 자동적으로 관련도 순으로 결과를 반환합니다.
서드파티 엔진
Scout는 Algolia·Meilisearch·Typesense 등의 서드파티 검색 엔진도 지원합니다. 이들은 오타 허용·패싯 검색·지오 서치·커스텀 랭킹 등 고도의 기능을 제공합니다. Scout는 통일 API를 제공하기 때문에, 나중에 데이터베이스 엔진에서 서드파티 엔진으로 이행할 때의 코드 변경은 최소한으로 끝납니다.대부분의 애플리케이션은 외부 검색 엔진을 필요로 하지 않습니다. 이 페이지에서 설명한 조립된 수법이 대다수의 유스 케이스를 커버합니다.
기술의 조합
여기까지 소개한 검색 수법은 상호 배타적이지 않습니다. 조합함으로써 최량의 결과를 얻을 수 있습니다.전문 검색 + 리랭킹
전문 검색으로 후보를 빠르게 좁혀, 리랭킹으로 시맨틱한 관련도 순으로 재정렬합니다. 데이터베이스 속도와 AI 정확도를 양립하는 패턴입니다.벡터 검색 + 통상의 필터
벡터 유사 검색과 통상의where 절을 조합하여, 특정한 서브셋으로 좁힌 시맨틱 검색을 실현합니다. 팀이나 카테고리로 좁히면서 의미적인 검색을 하고 싶은 경우에 편리합니다.
관련 페이지
Laravel Scout
Searchable 트레이트로 모델을 자동 인덱스 동기하는 완전 가이드.
Laravel AI SDK
벡터 임베딩과 리랭킹에 필요한 AI SDK의 설정 방법.
쿼리 빌더
whereFullText·whereVectorSimilarTo 등의 쿼리 빌더 메서드의 상세.
마이그레이션
전문 인덱스와 벡터 컬럼의 작성 방법.