이 페이지에서는 PostgreSQL용 Cloud SQL을 사용하여 다음 작업을 수행하는 방법을 보여줍니다.
모델을 기반으로 벡터 임베딩을 생성하고 저장합니다.
pgvector
확장 프로그램을 사용하여 임베딩 색인을 생성하고 임베딩을 쿼리합니다.
자세한 내용은 Cloud SQL을 사용하여 생성형 AI 애플리케이션 빌드를 참조하세요.
Cloud SQL을 사용하면 Vertex AI에서 호스팅하는 임베딩 모델을 사용하여 텍스트 문자열을 임베딩으로 변환할 수 있습니다. 임베딩은 지정된 텍스트의 의미론적 의미를 숫자 벡터로 나타내는 모델 표현입니다.
Cloud SQL은 임베딩을 real
값 배열로 구현합니다. 이를 통해 생성된 임베딩을 pgvector
확장 함수 입력으로 사용할 수 있습니다.
시작하기 전에
일부 요구사항은 Cloud SQL을 사용하여 임베딩을 생성할지 또는 다른 소스의 데이터베이스에 저장된 임베딩으로만 작업해야 하는지 여부에 따라 달라집니다.
리전별 제한사항
Cloud SQL로 Vertex AI 임베딩을 생성하려면 인스턴스가 generative AI foundational models are supported
가 있는 리전에 있어야 합니다.
Cloud SQL이 임베딩에 사용할 수 있는 Vertex AI 모델인 text-embedding
및 textembedding-gecko
는 이 리전에 있습니다.
필수 데이터베이스 확장 프로그램
임베딩을 사용하려면 Cloud SQL 인스턴스에 google_ml_integration
확장 프로그램을 설치합니다. Vertex AI 모델의 경우 버전 1.2
이상을 설치합니다. 서드 파티 또는 맞춤 모델의 경우 버전 1.4.2
이상을 설치합니다.
원하는 경우 이러한 임베딩을 저장하고 임베딩과 함께 벡터 함수와 연산자를 사용하려면 pgvector
확장 프로그램도 필요합니다.
Cloud SQL에는 이러한 두 가지 확장 프로그램이 모두 있습니다. 인스턴스의 모든 데이터베이스에 설치할 수 있습니다. 자세한 내용은 PostgreSQL 확장 프로그램 구성을 참조하세요.
모델 액세스 설정
Cloud SQL 인스턴스에서 임베딩을 생성하려면 먼저 텍스트 임베딩 모델을 사용하도록 Cloud SQL을 구성해야 합니다.
클라우드 기반 text-embedding
또는 textembedding-gecko
모델을 사용하려면 Cloud SQL을 Vertex AI와 통합해야 합니다.
데이터베이스 사용자에게 임베딩을 생성할 수 있는 액세스 권한 부여
데이터베이스 사용자에게 embedding
함수를 사용하여 예측을 실행할 수 있는 권한을 부여합니다.
psql 클라이언트를 사용하여 연결의 설명대로
psql
클라이언트를 기본 인스턴스에 연결합니다.psql
명령 프롬프트에서 데이터베이스에 연결하고 권한을 부여합니다.\c
DB_NAME GRANT EXECUTE ON FUNCTION embedding TOUSER_NAME ;다음을 바꿉니다.
DB_NAME: 권한을 부여할 데이터베이스의 이름
USER_NAME: 권한을 부여할 사용자의 이름
임베딩 생성
Cloud SQL은 텍스트를 벡터 임베딩으로 변환할 수 있는 함수를 제공합니다. 그런 다음 임베딩을 벡터 데이터로 데이터베이스에 저장하고 선택적으로 pgvector
함수를 사용하여 쿼리를 실행할 수 있습니다.
임베딩 생성
Cloud SQL을 사용하여 임베딩을 생성하려면 google_ml_integration
확장 프로그램에서 제공하는 embedding()
함수를 사용합니다.
SELECT embedding( 'MODEL_ID VERSION_TAG ', 'TEXT ');
다음을 바꿉니다.
MODEL_ID: 쿼리할 모델의 ID입니다.
Vertex AI Model Garden을 사용하는 경우
text-embedding-004
또는text-multilingual-embedding-002
을 지정합니다. Cloud SQL에서 텍스트 임베딩에 사용할 수 있는 클라우드 기반 모델입니다. 자세한 내용은 텍스트 임베딩을 참조하세요.VERSION_TAG(선택사항): 쿼리할 모델의 버전 태그입니다.
text-embedding-004
또는text-multilingual-embedding-002
이전 버전의textembedding-gecko
의 경우Prepend the tag with
@`를 수행합니다.Vertex AI에서
textembedding-gecko
모델 중 하나를 사용하는 경우 모델 버전에 나열된 버전 태그 중 하나를 지정합니다.TEXT: 벡터 임베딩으로 변환할 텍스트입니다.
다음 예시에서는 text-embedding-004
모델을 사용하여 제공된 리터럴 문자열을 기반으로 임베딩을 생성합니다.
SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');
생성된 임베딩 저장
embedding()
함수의 반환 값은 real
값 배열입니다.
이 값을 테이블에 저장하려면 real[]
열을 추가합니다.
ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS ];
다음을 바꿉니다.
TABLE: 테이블 이름
EMBEDDING_COLUMN: 새 임베딩 열의 이름
DIMENSIONS: 모델에서 지원하는 차원 수
Vertex AI에서
text-embedding
또는textembedding-gecko
모델 중 하나를 사용하는 경우768
을 지정합니다.
원하는 경우 pgvector
확장 프로그램을 설치했으면 임베딩을 vector
값으로 저장할 수 있습니다.
ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS );
임베딩을 저장할 열을 만든 후 같은 테이블의 다른 열에 이미 저장된 값을 기준으로 열을 채울 수 있습니다.
UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_ID VERSION_TAG ', SOURCE_TEXT_COLUMN );
다음을 바꿉니다.
TABLE: 테이블 이름입니다.
EMBEDDING_COLUMN: 임베딩 열 이름입니다.
MODEL_ID: 쿼리할 모델의 ID입니다.
Vertex AI Model Garden을 사용하는 경우
text-embedding-004
또는text-multilingual-embedding-002
을 지정합니다. Cloud SQL에서 텍스트 임베딩에 사용할 수 있는 클라우드 기반 모델입니다. 자세한 내용은 텍스트 임베딩을 참조하세요.VERSION_TAG(선택사항): 쿼리할 모델의 버전 태그입니다.
text-embedding-004
또는text-multilingual-embedding-002
이전 버전의textembedding-gecko
의 경우Prepend the tag with
@`를 수행합니다.Vertex AI에서
textembedding-gecko
모델 중 하나를 사용하는 경우 모델 버전에 나열된 버전 태그 중 하나를 지정합니다.SOURCE_TEXT_COLUMN: 텍스트를 저장하는 열의 이름입니다. 이 텍스트를 임베딩으로 변환합니다.
위 명령어는 real[]
및 vector
임베딩 열 모두에서 작동합니다. 임베딩 열이 vector
유형이면 Cloud SQL에서 암시적으로 real
배열의 embedding()
반환 값을 vector
값으로 변환합니다.
다음 예시에서는 text-embedding-004
모델을 사용하여 messages.message
열의 콘텐츠에 따라 messages.message_vector
열을 임베딩으로 채웁니다.
UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);
pgvector
을 사용하여 임베딩 쿼리 및 색인 생성
pgvector
PostgreSQL 확장 프로그램을 사용하면 데이터베이스에서 텍스트 임베딩을 저장, 색인 생성, 쿼리할 때 벡터별 연산자와 함수를 사용할 수 있습니다. Cloud SQL는 pgvector
를 사용할 수 있도록 자체적으로 최적화되므로 임베딩을 포함하는 쿼리를 가속화할 수 있는 색인을 만들 수 있습니다.
최근접 이웃 색인 만들기
pgvector
는 색인 생성을 통한 근사 최근접 이웃 검색을 지원합니다.
hnsw
를 색인 메서드로 사용하여 pgvector
기반 색인을 만들려면 다음 예를 사용하세요.
CREATE INDEX ON TABLE
USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION )
WITH (m = M , ef_construction = EF_CONSTRUCTION );
다음을 바꿉니다.
TABLE: 색인을 추가할 테이블입니다.
EMBEDDING_COLUMN:
vector
데이터를 저장하는 열입니다.DISTANCE_FUNCTION: 이 색인과 함께 사용할 거리 함수입니다. 다음 중 하나를 선택합니다.
L2 거리:
vector_l2_ops
내부 제품:
vector_ip_ops
코사인 거리:
vector_cosine_ops
M (선택사항): 그래프에서 인접한 데이터 포인트와의 최대 연결 수입니다.
pgvector
의 기본값은 16이므로 5~48 범위를 사용하는 것이 좋습니다.EF_CONSTRUCTION (선택사항): 색인을 빌드할 때 그래프를 탐색하는 동안 가장 가까운 후보를 보유하는 목록의 크기입니다. 값이 클수록 알고리즘이 더 많은 후보를 고려하여 더 나은 색인을 만들 수 있습니다. 기본 크기는 64입니다.
vector
대신 real[]
데이터 유형을 사용하는 임베딩 열에 이 색인을 만들려면 열을 vector
데이터 유형으로 변환합니다.
CREATE INDEX ON TABLE
USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS ))) DISTANCE_FUNCTION )
WITH (m = M , ef_construction = EF_CONSTRUCTION );
DIMENSIONS를 임베딩 열의 차원 너비로 바꿉니다.
다음 섹션에서는 이러한 종류의 색인 예시를 보여줍니다.
지정된 텍스트로 최근접 이웃 쿼리 작성
데이터베이스에 임베딩을 저장하고 색인을 생성하면 pgvector
쿼리 기능의 모든 범위를 사용할 수 있습니다.
텍스트에서 의미론적으로 최근접 이웃을 찾으려면 embedding()
함수를 사용하여 텍스트를 벡터로 변환합니다. 같은 쿼리에서 이 벡터를 pgvector
최근접 이웃 연산자인 <->
에 적용하여 의미상 가장 유사한 임베딩이 있는 데이터베이스 행을 찾습니다.
embedding()
에서 real
배열을 반환하므로 pgvector
연산자와 함께 이러한 값을 사용하려면 embedding()
호출을 vector
으로 변환해야 합니다.
SELECT RESULT_COLUMNS FROM TABLE
ORDER BY EMBEDDING_COLUMN
<-> embedding('MODEL_ID VERSION_TAG ', 'TEXT ')::vector
LIMIT ROW_COUNT
다음을 바꿉니다.
RESULT_COLUMNS: 의미론적으로 유사한 행에서 표시할 열입니다.
TABLE: 텍스트를 비교할 임베딩이 포함된 테이블입니다.
EMBEDDING_COLUMN: 저장된 임베딩이 포함된 열입니다.
MODEL_ID: 쿼리할 모델의 ID입니다.
Vertex AI Model Garden을 사용하는 경우
text-embedding-004
또는text-embedding-multilingual-002
을 지정합니다. Cloud SQL에서 텍스트 임베딩에 사용할 수 있는 클라우드 기반 모델입니다. 자세한 내용은 텍스트 임베딩을 참조하세요.VERSION_TAG(선택사항): 쿼리할 모델의 버전 태그입니다. 태그 앞에
@
를 추가합니다.Vertex AI에서
textembedding-gecko
모델 중 하나를 사용하는 경우 모델 버전에 나열된 버전 태그 중 하나를 지정합니다.TEXT: 의미론적으로 최근접으로 저장된 이웃을 찾을 수 있는 텍스트입니다.
ROW_COUNT: 반환할 행의 개수입니다. 가장 일치하는 값을 하나만 원하는 경우 이 매개변수의 값으로
1
을 지정합니다.
real[]
데이터 유형을 사용하는 저장된 임베딩 열로 이 쿼리를 실행하려면 vector
대신 열을 vector
데이터 유형으로 변환합니다.
SELECT RESULT_COLUMNS FROM TABLE
ORDER BY EMBEDDING_COLUMN ::vector
<-> embedding('MODEL_ID VERSION_TAG ', 'TEXT ')::vector
LIMIT ROW_COUNT
모델 버전 태그를 사용하여 오류 방지
항상 선택한 임베딩 모델의 안정화 버전을 사용하는 것이 좋습니다. 즉, 대부분의 모델에서 버전 태그를 명시적으로 설정합니다.
모델의 버전 태그를 지정하지 않고 embedding()
함수 호출하면 구문적으로는 유효하지만 오류가 발생하기 쉽습니다.
Vertex AI Model Garden에서 모델을 사용할 때 버전 태그를 생략하면 Vertex AI에서 모델 최신 버전을 사용합니다. 이 버전은 최신 안정화 버전이 아닐 수 있습니다. 사용 가능한 Vertex AI 모델 버전에 대한 자세한 내용은 모델 버전을 참조하세요.
지정된 Vertex AI 모델 버전은 동일한 embedding()
응답을 항상 지정된 텍스트 입력에 반환합니다. embedding()
호출 시 모델 버전을 지정하지 않으면 새로 게시된 모델 버전에서 지정된 입력에 반환된 벡터를 갑자기 변경할 수 있습니다. 이로 인해 애플리케이션에서 오류나 기타 예상치 못한 동작이 발생할 수 있습니다.
이러한 문제를 방지하려면 항상 모델 버전을 지정합니다.