Vertex AI로 벡터 유사성 검색 수행

Firebase Data Connect의 벡터 유사성 검색에 오신 것을 환영합니다. 벡터 유사성 검색은 Google Vertex AI와 통합되는 시맨틱 검색의 Firebase 구현입니다.

이 기능의 핵심은 텍스트 또는 미디어의 시맨틱 의미를 나타내는 부동 소수점 숫자 배열인 벡터 임베딩입니다. 입력 벡터 임베딩을 사용하여 최근접 이웃 검색을 실행하면 의미상 유사한 콘텐츠를 모두 찾을 수 있습니다. Data Connect는 이 기능을 위해 PostgreSQL의 pgvector 확장 프로그램을 사용합니다.

이 강력한 시맨틱 검색은 추천 엔진 및 검색엔진과 같은 사용 사례를 지원할 수 있습니다. 생성형 AI 흐름에서 검색 증강 생성의 핵심 구성요소이기도 합니다. Vertex AI 문서에서 자세히 알아볼 수 있습니다.

Data Connect의 기본 제공 지원을 사용하여 Vertex AI의 Embeddings API를 통해 벡터 임베딩을 자동으로 생성하거나 해당 API를 사용하여 수동으로 생성할 수 있습니다.

기본 요건

• 프로젝트에 데이터 커넥트 설정

  참고: 설정 흐름을 진행할 때 Data Connect의 Vertex AI 통합은 특정 PostgreSQL용 Cloud SQL 위치에서만 지원됩니다. 위치 목록을 참고하세요.

• Vertex AI API를 사용 설정합니다.

  참고: 별도의 Google Cloud 프로젝트를 만들거나 Google Cloud CLI를 설치할 필요가 없습니다.

설정

웹, Kotlin Android 또는 iOS 개발자인 경우 로컬 개발 흐름을 선택할 수 있고, 웹 개발자인 경우 IDX 흐름을 선택할 수 있습니다. 개발에는 로컬 데이터베이스나 프로덕션 Data Connect 프로젝트 및 해당 PostgreSQL용 Cloud SQL 인스턴스를 사용할 수 있습니다.

참고: 로컬로 작업하든 프로덕션 프로젝트로 작업하든 Vertex AI를 사용하므로 Vertex AI 사용 비용이 발생합니다.

이 안내에서는 빠른 시작 가이드에 따라 Data Connect 프로젝트를 만들었다고 가정합니다.

로컬 PostgreSQL과 통합

1. 로컬 PostgreSQL 인스턴스를 설정합니다.
2. Vertex AI 사용자 IAM 역할을 자신에게 부여합니다.
3. 환경에서 Google Cloud 애플리케이션 기본 사용자 인증 정보를 설정합니다.
4. 로컬 PostgreSQL 인스턴스에 pgvector 확장 프로그램을 설치합니다.
5. pgvector 저장소 안내에 따라 CREATE EXTENSION vector를 사용하여 확장 프로그램을 사용 설정합니다.

IDX와 통합

1. 데이터 커넥트 템플릿을 사용하여 IDX 작업공간을 설정합니다.
2. Vertex AI 사용자 IAM 역할을 자신에게 부여합니다.
3. pgvector 저장소 안내에 따라 CREATE EXTENSION vector를 사용하여 확장 프로그램을 사용 설정합니다.

스키마 설계

벡터 검색을 실행하려면 스키마에 Vector 유형의 새 필드를 추가합니다. 예를 들어 영화 설명을 사용하여 의미 검색을 하려면 영화 설명과 연결된 벡터 임베딩을 저장할 필드를 추가합니다. 이 스키마에서는 description 필드의 벡터 임베딩을 저장하기 위해 descriptionEmbedding가 추가됩니다.

type Movie @table {
 id: ID! @col(name: "movie_id") @default(id: ID! @col(name: "movie_id") @default(expr: "uuidV4()")
 title: String!
 description: String
 descriptionEmbedding: Vector! @col(size:768)
 // ...
}

참고: 벡터 임베딩 검색은 동일한 차원의 벡터만 비교할 수 있으므로 @col(size: X) 스키마 지시어를 사용하여 벡터 임베딩 차원을 제공해야 합니다. Vertex AI를 사용하여 생성된 벡터 임베딩의 크기는 768입니다.

임베딩 생성 및 검색

Data Connect는 _embed 서버 값을 사용하여 벡터 임베딩을 통합 지원합니다. 이렇게 하면 Data Connect가 Vertex AI의 임베딩 API를 내부적으로 호출하여 벡터 임베딩을 생성합니다. _embed 서버 값은 변이와 쿼리 모두에서 사용할 수 있습니다.

참고: 서로 다른 모델 버전에서 생성된 벡터 임베딩은 일반적으로 호환되지 않는 것으로 간주됩니다. 따라서 필드에 대한 모든 작업 (쿼리 또는 변형)의 경우 동일한 모델을 사용하여 생성된 벡터 임베딩을 사용하는 것이 좋습니다. 지원되는 Vertex AI 모델 목록은 문서에서 확인할 수 있습니다.

변형

Data Connect를 통해 임베딩 생성 및 저장

벡터 검색 앱에서는 데이터베이스에 레코드를 추가하는 즉시 임베딩이 생성되도록 요청하는 것이 좋습니다. 다음은 createMovie 변이로, Movie 테이블에 영화 레코드를 추가하고 지정된 삽입 model로 영화 설명을 전달합니다.

mutation createMovie($title: String!, $description: String!) {
  movie_insert(data: {
    title: $title,
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

경우에 따라 영화 설명과 삽입을 업데이트해야 할 수도 있습니다.

mutation updateDescription($id: String!, $description: String!) {
  movie_update(id: $id, data: {
    description: $description,
    descriptionEmbedding_embed: {model: "textembedding-gecko@003", text: $description}
  })
}

클라이언트에서 후자 변이를 호출하려면 다음을 실행합니다.

import { updateMovieDescription } from 'lib/dataconnect-sdk/';

await updateMovieDescription({ id: movieId, description: description});

// Use the response

쿼리

다음과 같은 쿼리를 사용하여 벡터 임베딩을 가져옵니다. 쿼리에서 반환되는 descriptionEmbedding는 부동 소수점 배열이며 일반적으로 사람이 읽을 수 없습니다. 따라서 Data Connect 생성 SDK는 직접 반환을 지원하지 않습니다.

반환된 벡터 임베딩을 사용하여 다음 섹션에 설명된 대로 유사성 검색을 실행할 수 있습니다.

query getMovieDescription($id: String!) @auth(level: PUBLIC) {
 movie(id: $id)
   id
   description
   descriptionEmbedding
}

유사성 검색 실행

이제 유사성 검색을 실행할 수 있습니다.

각 Vector 필드에 대해 Data Connect는 유사성 검색을 구현하는 GraphQL 함수를 생성합니다. 생성된 이 함수의 이름은 ${pluralType}_${vectorFieldName}_similarity입니다. 다음 예와 참조 목록에 표시된 대로 몇 가지 매개변수를 지원합니다.

유사성 검색을 호출하는 GraphQL 함수를 정의할 수 있습니다. 위에서 언급한 것처럼 _embed 서버 값은 Data Connect이 Vertex AI의 임베딩 API를 사용하여 벡터 임베딩을 생성하도록 지시합니다. 이 경우 영화 설명 임베딩과의 비교에 사용되는 검색 문자열의 임베딩을 생성합니다.

이 예에서 유사성 검색은 설명이 입력 쿼리와 시맨틱으로 가장 유사한 영화를 최대 5개까지 반환합니다. 결과 집합은 거리의 오름차순(가장 가까운 순서부터 가장 먼 순서)으로 정렬됩니다.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
      }
  }

유사성 쿼리 조정

method 및 within과 같은 검색 매개변수의 기본값은 대부분의 사용 사례에서 성능이 우수합니다. 하지만 쿼리에서 너무 다른 결과가 반환되거나 포함하고 싶은 결과가 누락되는 경우 이러한 매개변수를 조정해 보세요.

within의 적절한 값을 찾기 위해 선택한 필드에 _metadata.distance을 추가하여 각 결과가 쿼리 벡터에서 얼마나 떨어져 있는지 확인할 수 있습니다. 반환된 distance 값을 기반으로 within 매개변수를 설정할 수 있습니다. within 값보다 거리가 짧은 결과만 포함됩니다.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: 2,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

method 매개변수를 설정하여 다양한 거리 함수를 실험할 수도 있습니다.

query searchMovieDescriptionUsingL2Similarity ($query: String!) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare_embed: {model: "textembedding-gecko@003", text: $query},
      within: .5,
      method: COSINE,
      where: {content: {ne: "No info available for this movie."}}, limit: 5)
      {
        id
        title
        description
        _metadata {
          distance
        }
      }
  }

within를 설정한 경우 method를 변경한 후 해당 값을 다시 조정해야 합니다.

유사성 쿼리 호출

클라이언트 코드에서 유사성 검색을 호출하려면 다음 단계를 따르세요.

import { searchMovieDescriptionUsingL2similarity} from 'lib/dataconnect-sdk';

const response = await searchMovieDescriptionUsingL2similarity({ query });

// Use the response

커스텀 임베딩 사용

또한 Data Connect를 사용하면 _embed 서버 값을 사용하여 임베딩을 생성하는 대신 임베딩을 Vector로 직접 사용할 수 있습니다.

맞춤 임베딩 저장

Vertex Embeddings API를 사용하여 일치 모델을 지정하고 올바른 차원의 임베딩 결과를 요청합니다.

그런 다음 반환된 부동 소수점 배열을 Vector로 변환하여 스토리지의 업데이트 작업에 전달합니다.

mutation updateDescription($id: String!, $description: String!, $descriptionEmbedding: Vector!) {
  movie_update(id: $id, data: {
    // title, genre...
    description: $description,
    descriptionEmbedding: $descriptionEmbedding
  })
}

맞춤 임베딩을 사용하여 유사성 검색 실행

동일한 작업을 실행하여 검색어의 임베딩을 가져오고 이를 Vectors로 변환합니다.

그런 다음 _similarity 쿼리를 호출하여 각 검색을 실행합니다.

query searchMovieDescriptionUsingL2Similarity($compare: Vector!, $within: Float, $excludesContent: String, $limit: Int) @auth(level: PUBLIC) {
    movies_descriptionEmbedding_similarity(
      compare: $compare,
      method: L2,
      within: $within,
      where: {content: {ne: $excludesContent}}, limit: $limit)
      {
        id
        title
        description
      }
  }

프로덕션에 배포

스키마 및 커넥터 배포

일반적인 Data Connect 반복의 마지막 단계는 애셋을 프로덕션에 배포하는 것입니다.

firebase deploy 명령어를 사용하여 Vector 유형이 포함된 스키마를 CloudSQL에 배포하면 Firebase CLI에서 CloudSQL 인스턴스에서 Vertex AI 기반 임베딩 생성을 사용 설정하는 데 필요한 단계를 수행합니다.

firebase deploy --only dataconnect

CloudSQL 인스턴스에서 수동으로 삽입 지원을 사용 설정하거나 CLI 오류가 발생하는 경우 이 안내를 따르세요.

벡터 검색 구문

스키마 확장

Data Connect의 Vector 데이터 유형은 pgvector 확장 프로그램에 정의된 대로 PostgreSQL의 vector 유형에 매핑됩니다. pgvector의 vector 유형은 PostgreSQL에 단정밀도 부동 소수점 숫자의 배열로 저장됩니다.

Data Connect에서 Vector 유형은 JSON 숫자의 배열로 표현됩니다. 입력은 float32 값의 배열로 강제 변환됩니다. 강제 변환이 실패하면 오류가 발생합니다.

참고: JavaScript 숫자는 float 강제 변환과 호환됩니다.

@col 지시문의 크기 매개변수를 사용하여 벡터의 차원을 설정합니다.

type Question @table {
    text: String!
    category: String!
    textEmbedding: Vector! @col(size: 768)
}

size는 Vector 유형에만 지원됩니다. 유사성 검색과 같은 Vector 작업에는 모든 Vector의 차원 수가 동일해야 합니다.

directive @col(
  # … existing args
  """
  Defines a fixed column size for certain scalar types.

  - For Vector, size is required.
  - For all other types, size is currently unsupported and hence supplying it will result in a schema error.
  """
  size: Int
) on FIELD_DEFINITION

쿼리 및 변형의 _embed 서버 값

_embed

이 서버 값은 Data Connect 서비스가 Vertex AI의 임베딩 API를 사용하여 임베딩을 생성하고 저장하도록 안내합니다. 이 서버 값은 쿼리와 변형 모두에서 사용할 수 있습니다.

유사성 검색을 위한 파라미터

method: COSINE|INNER_PRODUCT|L2

근처 이웃을 검색하는 데 사용되는 거리 함수입니다. 현재 지원되는 알고리즘은 pgvector 검색 알고리즘의 하위 집합입니다.

within: float

최근접 이웃 검색이 실행되는 거리의 제약 조건입니다.

where: FDC filter condition

스키마, 쿼리, 변형 가이드를 참고하세요.

limit: int

반환할 결과 수입니다.