EmbeddingGemma 2 API: 로컬 배포와 멀티모달 활용 사례

EmbeddingGemma 2 API를 찾다 보면 먼저 짚고 넘어가야 할 차이가 있습니다. Google이 호스팅하는 임베딩 API는 Gemini Embedding 2이고, EmbeddingGemma 2는 주로 로컬 및 엣지 추론을 겨냥한 오픈 모델입니다. 덕분에 민감한 데이터를 외부로 보내지 않는 멀티모달 검색을 구축하기 좋지만, 어떤 서빙 계층을 사용할지와 운영 방식은 직접 결정해야 합니다.

EmbeddingGemma 2를 Google API로 사용할 수 있을까?

EmbeddingGemma 2는 공식 출시된 모델이지만, 현재 Google의 관리형 Gemini API 문서에는 embeddinggemma-2가 아니라 gemini-embedding-2가 안내되어 있습니다. EmbeddingGemma 2 모델 카드와 Google 개발자 가이드는 Sentence Transformers 같은 로컬 라이브러리로 내려받아 사용하는 모델로 설명합니다.

로컬에서 /v1/embeddings 엔드포인트를 제공하는 주체는 Google Cloud가 아니라 직접 배포한 런타임입니다. 관리형 서비스를 의미한 것이라면 Gemini Embedding 2 문서에서 클라우드 SDK와 요청 형식을 확인하면 됩니다. 이때 모델 이름은 embeddinggemma-2가 아니라 gemini-embedding-2를 사용해야 합니다.

from google import genai

client = genai.Client()
result = client.models.embed_content(
    model="gemini-embedding-2",
    contents="A private semantic search service",
)
print(result.embeddings)

관리형 호출은 Google이 호스팅하는 API를 사용합니다. 반면 로컬 모델의 인증 정보와 사용량 제한은 배포한 런타임의 정책을 따릅니다.

로컬 모델의 구성과 규모

EmbeddingGemma 2는 7억 4,000만 개의 파라미터로 구성된 멀티모달 임베더입니다. 2억 7,000만 개 파라미터의 텍스트 코어와 선택적으로 불러올 수 있는 비전·오디오 인코더를 분리한 구조라, 필요한 모달리티만 골라 배포할 수 있습니다. Google과 DeepMind는 이 모델을 텍스트 생성용이 아니라 텍스트, 코드, 이미지, 동영상, 오디오 검색용 모델로 소개합니다.

모델 카드에 따르면 서로 다른 모달리티를 비교할 수 있도록 하나의 공유 벡터 공간을 사용합니다. 740M이라는 수치는 전체 모델 기준이며, 개발자 가이드는 필요한 인코더만 선택해 사용하는 방식을 보여줍니다. 따라서 비전과 오디오를 제외한 텍스트 전용 경로에서는 런타임 메모리 사용량과 실제 연산량이 더 낮아질 수 있습니다.

배포 대상에 맞춰 서빙 방식을 고르자

Python 애플리케이션에는 Sentence Transformers

Python 서비스라면 공식 문서에 안내된 Sentence Transformers와 google/embeddinggemma-2 체크포인트 조합이 기본 선택지입니다. 배치 처리, 디바이스 배치, 프롬프트, 정규화, 벡터 차원 축소를 직접 제어할 수 있다는 장점이 있습니다.

검색 파이프라인에서는 질의와 문서에 서로 다른 지시문을 사용해야 합니다. Google 예제는 질의에 검색어용 접두사를 붙이고, 문서에는 title: none | text: ... 같은 형식을 사용합니다. 양쪽을 별도의 일반 호출로 임베딩하기보다, 관련 프롬프트 이름을 지정한 model.encode를 사용하는 편이 안전합니다.

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("google/embeddinggemma-2")

query_vector = model.encode(
    "How do I rotate an API key?",
    prompt_name="query",
    normalize_embeddings=True,
)
document_vectors = model.encode(
    [
        "title: API keys | text: Rotate keys from the security settings page.",
        "title: Billing | text: Download invoices from the billing page.",
    ],
    prompt_name="document",
    normalize_embeddings=True,
)

Python 수준의 세밀한 제어가 필요하다면 이 방식을 선택하고, 여러 서비스가 안정적인 API 규격을 공유해야 한다면 HTTP 서빙 런타임을 사용하는 편이 좋습니다.

빠른 로컬 REST 엔드포인트에는 Ollama

Ollama의 EmbeddingGemma 2 페이지에서는 http://localhost:11434/api/embed 주소의 간단한 로컬 API를 제공합니다.

ollama pull embeddinggemma-2

curl http://localhost:11434/api/embed \\
  -d '{
    "model": "embeddinggemma-2",
    "input": "A private semantic search service"
  }'

Ollama에는 270m, 440m, 570m, 740m 같은 모델 태그가 있으며, 표시된 패키지 크기는 대략 378MB에서 1.3GB까지입니다. 이는 전체 740M 체크포인트를 서로 바꿔 부르는 이름이 아니라 별도로 패키징된 모델 변형으로 봐야 합니다. 운영 환경에 적용하기 전에는 설치된 태그와 지원 입력 모달리티를 확인하세요. 제품군 자체는 멀티모달로 설명되지만, 표시된 각 변형이 모든 모달리티를 동일한 수준으로 명확하게 문서화하고 있지는 않습니다.

또한 작업별 접두사, 모델과 벡터 차원의 일치 여부를 일관되게 관리해야 하며, 모델을 바꾸면 인덱스를 다시 구축해야 합니다.

디바이스 배포에는 엣지 런타임

Google AI Edge는 Universal Embedder 가이드에서 EmbeddingGemma V2를 다루고 있으며, LiteRT-LM 임베딩 모델 문서는 로컬에서 OpenAI 호환 방식의 /v1/embeddings 서빙 패턴을 설명합니다. 일반적인 클라우드 배포의 편리함보다 오프라인 동작과 디바이스 내부의 데이터 보호가 중요하다면 이 경로가 적합합니다.

일반 하드웨어에서 서버를 운영한다면 Sentence Transformers나 Ollama부터 시작하면 됩니다. 오프라인 동작, 개인정보 보호, 초기 메모리 부담, 디바이스 통합이 핵심 요구사항일 때 엣지 전용 런타임으로 옮기는 방식이 현실적입니다.

더 큰 모델이 필요한 멀티모달 활용 사례

EmbeddingGemma 2의 강점은 여러 미디어 유형을 하나의 검색 공간에서 다뤄야 할 때 가장 분명하게 드러납니다.

코드 검색과 개발자용 검색 시스템

공개된 평가 표에 따르면, 인용된 코드 벤치마크에서 EmbeddingGemma 2의 MTEB Code 점수는 78.68로 EmbeddingGemma 1의 68.76보다 높습니다. 저장소 검색, API 문서 검색, 코드 중심 RAG에 시험해볼 만한 근거이지만, 사용 중인 언어 구성이나 코드베이스에서도 같은 결과가 나온다는 보장은 아닙니다.

더 큰 모델로 바꿀 필요가 없는 경우

일반적인 OCR 텍스트만 입력으로 받는 파이프라인이라면 멀티모달 지원이 검색 품질을 높이지 못한 채 복잡성만 키울 수 있습니다. Paperless-ngx 사용자 한 명은 이 trade-off를 다음과 같이 설명했습니다.

“Paperless-ngx가 모델에 보내는 일반 OCR 텍스트에서는 embeddinggemma-2가 기존 embeddinggemma보다 나은지 잘 모르겠습니다. 결과는 같은데 일이 훨씬 많아지는 것 같습니다.” — u/Great-Cow7256, Reddit

이는 벤치마크 결과는 아니지만, 마이그레이션 전에 무엇을 검증해야 하는지는 잘 보여줍니다. 정상적으로 동작하는 텍스트 전용 인덱스를 다시 만들기 전에 실제 데이터셋에서 검색 품질을 비교해보세요.

벡터 차원 선택: 768d, 512d, 256d, 128d

Google의 임베딩 문서는 EmbeddingGemma 2에서 Matryoshka 방식의 차원 축소를 지원한다고 설명합니다. 임베딩을 생성한 뒤 더 작은 표현으로 줄일 수 있다는 뜻입니다. 벡터가 작아지면 인덱스 저장 공간과 전송량을 줄일 수 있지만, 가장 공격적으로 축소했을 때는 품질 저하가 커집니다.

위 수치는 Ollama 모델 페이지에 공개된 평가 표를 옮긴 것입니다. 새 멀티모달 인덱스라면 768d에서 시작하고, 저장 공간이 중요하다면 512d 또는 256d를 고려하세요. 128d는 텍스트 중심 워크로드에서 직접 테스트한 뒤 선택하는 편이 좋습니다.

하나의 벡터 인덱스에 서로 다른 차원의 벡터를 섞어서는 안 됩니다. 기존 데이터베이스에 768차원 벡터가 저장되어 있다면 256d로 바꿀 때 문서를 다시 임베딩하고 인덱스를 재구축해야 합니다. 질의 벡터와 문서 벡터는 동일한 모델, 프롬프트, 정규화 방식, 차원을 사용해야 합니다.

모델 크기보다 워크플로에 맞춰 결정하자

Google 관리형 엔드포인트가 필요하다면 Gemini Embedding 2를 사용하세요. Python 수준의 제어가 필요하면 Sentence Transformers, 빠른 로컬 HTTP 서비스가 목적이면 Ollama, 오프라인 디바이스 배포가 중요하면 AI Edge/LiteRT-LM이 적합합니다.

데이터셋이 일반 OCR 텍스트로만 구성되어 있고 현재 인덱스가 원하는 관련성 기준을 충족한다면 더 작은 텍스트 전용 모델을 유지하는 편이 낫습니다. EmbeddingGemma 2가 멀티모달 아키텍처를 단순화할 수는 있지만, 텍스트 전용 시스템의 품질을 자동으로 개선해주는 것은 아닙니다.

EmbeddingGemma 2 API 자주 묻는 질문

EmbeddingGemma 2를 Gemini API로 사용할 수 있나요?

Google의 관리형 Gemini API 문서에는 현재 gemini-embedding-2가 안내되어 있습니다. EmbeddingGemma 2는 주로 로컬 추론용 오픈 모델로 문서화되어 있지만, 로컬 런타임을 사용하면 API 호환 엔드포인트를 제공할 수 있습니다.

EmbeddingGemma 2를 CPU에서 실행할 수 있나요?

CPU 백엔드를 명시적으로 제공하는 로컬 런타임이라면 CPU 추론을 사용할 수 있습니다. 관련 런타임 문서는 Google의 AI Edge 임베딩 문서를 참고하면 됩니다. 다만 성능은 하드웨어, 양자화, 배치 크기, 모달리티에 따라 달라집니다.

기존 벡터를 다시 만들어야 하나요?

임베딩 모델, 작업별 포맷, 정규화 정책, 벡터 차원 중 하나라도 바꾼다면 일반적으로 그렇습니다. 나중에 마이그레이션을 재현할 수 있도록 인덱스와 함께 모델 식별자, 차원, 전처리 메타데이터를 관리하세요.