텍스트 임베딩 생성

텍스트 임베딩 생성 (Get text embeddings)

텍스트 임베딩(text embedding)은 문장이나 단락을 벡터로 바꿔서, 검색과 추천을 할 때 '단어가 같은지'가 아니라 '의미가 가까운지'로 찾게 해 주는 기술이에요. 이 글에서는 Vertex AI의 텍스트 임베딩 API를 호출하는 방법을 실제 코드와 함께 살펴볼게요. 요청 한도와 지원 모델, REST 엔드포인트까지 한 번에 정리해 드릴게요.

출처: Get text embeddings — Gemini Enterprise Agent Platform | Google Cloud Documentation

임베딩이란 무엇인가요

Vertex AI의 텍스트 임베딩 API는 밀집 벡터(dense vector) 표현을 만들어요. 예를 들어 gemini-embedding-001 모델은 3,072차원 벡터를 만들어 내죠. 밀집 벡터 임베딩 모델은 대규모 언어 모델과 비슷한 딥러닝 방식을 쓰는데, 스파스 벡터(sparse vector)가 단어를 숫자에 직접 매핑하는 것과 달리 밀집 벡터는 텍스트의 의미를 더 잘 나타내도록 설계돼요. 그래서 생성형 AI에서 검색할 때 같은 언어가 아니어도 질문의 의미와 맞닿는 구절을 찾아낼 수 있는 거예요.

생성된 벡터는 정규화되어 있기 때문에 코사인 유사도(cosine similarity), 내적(dot product), 유클리드 거리(Euclidean distance) 어느 것으로 비교해도 같은 유사도 순위를 얻을 수 있어요.

시작하기 전에

호출하려면 먼저 Google Cloud 프로젝트를 준비하고 Agent Platform API를 사용 설정해야 해요. 임베딩 작업에는 task type을 먼저 골라야 하는데, 이 값은 임베딩을 어떤 용도로 쓸지(예: 검색, 분류 등) API에 알려 주는 역할을 해요.

API 한도

• 요청당 250개의 입력 텍스트까지 보낼 수 있어요.
• 입력 토큰 최대치는 20,000이에요. 이 한도를 넘으면 400 에러가 나요.
• 개별 입력 텍스트 하나는 2,048 토큰으로 제한되고, 초과분은 조용히 잘려 나가요. 잘림을 끄려면 autoTruncate를 false로 설정하면 돼요.

전화 코드로 임베딩 만들기

먼저 google-genai 패키지를 설치해요.

pip install --upgrade google-genai

그다음 환경 변수를 설정해 Vertex AI에서 Gen AI SDK를 쓰도록 해요.

export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

텍스트 임베딩 코드

모델 기본값은 전체 길이의 임베딩 벡터를 만들고, gemini-embedding-001은 3,072차원, 나머지 모델은 768차원이에요. output_dimensionality 파라미터로 출력 벡터 크기를 조절할 수 있는데, 크기를 줄이면 저장 공간이 아껴지고 후속 작업 연산이 빨라져요. 품질 손실은 아주 작아요.

REST 엔드포인트

HTTP 메서드와 URL은 다음과 같아요.

POST https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict

요청 JSON 본문:

{
  "instances": [
    { "content": "TEXT" }
  ],
  "parameters": {
    "autoTruncate": AUTO_TRUNCATE
  }
}

curl로 보낼 때는 다음과 같이 요청 본문을 request.json 파일에 저장하고 호출해요.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-embedding-001:predict"

지원 모델

Google 모델

오픈 모델

임베딩을 생성한 뒤에는 Vector Search 같은 벡터 데이터베이스에 넣어 저지연 검색에 활용할 수 있어요.

더 알아보기

• 임베딩 API 개요 — Gemini Enterprise Agent Platform
• 배치 텍스트 임베딩 추론 생성
• 멀티모달 임베딩 생성
• Vector Search 개요