EmbeddingGemma

EmbeddingGemma

이 문서는 SGLang으로 Google의 EmbeddingGemma 텍스트 임베딩 모델을 서빙하는 방법을 설명해요. EmbeddingGemma는 OpenAI 호환 /v1/embeddings 엔드포인트를 통해 임베딩을 제공하며, 양방향 Gemma 3 인코더와 정규화된 평균 풀링을 자동으로 처리해요.

출처: 문서

본문

개요

EmbeddingGemma는 Google의 3억(300M) 파라미터 텍스트 임베딩 모델이에요. SGLang은 이 모델의 양방향(bidirectional) Gemma 3 인코더를 감지해서 정규화된 평균 풀링(normalized mean pooling)을 적용하고, OpenAI 호환 /v1/embeddings 엔드포인트로 임베딩을 서빙해요.

NVIDIA CUDA에서는 SGLang이 기본적으로 전체 prefill에 breakable CUDA graph(BCG)를 사용해요. 또한 이 양방향 인코더와 호환되지 않는 prefix caching과 chunked prefill은 자동으로 비활성화해요.

사전 요구 사항

  • NVIDIA CUDA GPU.
  • EmbeddingGemma 라이선스에 동의한 Hugging Face 계정.
  • Hugging Face 액세스 토큰. 서버를 시작하기 전에 내보내서 gated 체크포인트를 내려받을 수 있게 하세요:
export HF_TOKEN=<your-hugging-face-token>

EmbeddingGemma 지원이 포함된 SGLang 빌드를 설치하세요:

pip install 'git+https://github.com/sgl-project/sglang.git#subdirectory=python'

서버 시작하기

표준 설정은 EmbeddingGemma를 감지해서 embedding 모드, BCG, 그리고 체크포인트의 BF16 dtype을 자동으로 활성화해요:

sglang serve \
  --model-path google/embeddinggemma-300m \
  --host 0.0.0.0

Hopper 성능 기본값

H100과 H200에서 SGLang은 자동으로 FA3를 선택하고 16,384 토큰까지 BCG를 캡처해요. 이는 8개의 2K 임베딩 요청이 한 번의 replay로 처리된다는 의미예요. 이 작업 부하에는 추가 성능 플래그가 필요 없어요.

더 큰 집계 prefill을 캡처하려면 BCG tier를 명시적으로 올리세요:

sglang serve \
  --model-path google/embeddinggemma-300m \
  --cuda-graph-max-bs-prefill 32768 \
  --host 0.0.0.0

EmbeddingGemma는 list 값의 embedding 요청에 대해 배치 토큰화(batch tokenization)를 자동으로 활성화하므로, 별도의 토크나이저 배치 플래그를 추가하지 마세요.

임베딩 만들기

OpenAI 호환 엔드포인트에 문자열 하나 또는 문자열 배치를 보내세요:

curl http://127.0.0.1:30000/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "google/embeddinggemma-300m",
    "input": [
      "A short guide to serving text embeddings.",
      "Vector search retrieves semantically similar documents."
    ],
    "encoding_format": "float"
  }'

Python 및 OpenAI 클라이언트 예시는 OpenAI-compatible embedding APIs를 참고하세요.

배포 동작

EmbeddingGemma는 전체 입력에 대해 양방향 어텐션을 수행하므로, prefix KV cache를 재사용하거나 입력을 chunked prefill로 나누면 잘못된 어텐션 상태가 생겨요. SGLang은 필요한 설정을 자동으로 적용해요:

  • RadixAttention prefix caching 비활성화;
  • chunked prefill 비활성화;
  • embedding 전용 모델이므로 decode CUDA graph 비활성화;
  • CUDA prefill에 BCG 사용;
  • 지원되는 Hopper 및 Blackwell CUDA GPU에서 prefill backend가 FA3 또는 FA4일 때 FlashAttention의 raw-K/V 경로 사용.

이 레시피에는 prefill CUDA-graph override가 필요 없어요. 최적화된 EmbeddingGemma 경로를 사용하려면 BCG를 계속 활성화해 두세요.