EmbeddingGemma 2 API: локальное развертывание и мультимодальные сценарии

Запрос EmbeddingGemma 2 API легко приводит к путанице. Облачный API Google для эмбеддингов использует модель Gemini Embedding 2, тогда как EmbeddingGemma 2 — открытая модель, рассчитанная прежде всего на локальный запуск и edge-устройства. Это хороший вариант для приватного мультимодального поиска, но серверную часть придётся выбрать и обслуживать самостоятельно.

Есть ли у EmbeddingGemma 2 официальный API Google?

EmbeddingGemma 2 официально выпущена, однако в актуальной документации управляемого Gemini API от Google указана модель gemini-embedding-2, а не embeddinggemma-2. В карточке модели EmbeddingGemma 2 и руководстве Google для разработчиков описан скачиваемый вариант, который запускается через локальные библиотеки вроде Sentence Transformers.

Локальный endpoint /v1/embeddings предоставляет выбранный вами runtime, а не Google Cloud. Если вам нужен именно управляемый сервис, обратитесь к документации Gemini Embedding 2 — там приведены облачный SDK и форматы запросов. Используйте gemini-embedding-2, а не embeddinggemma-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)

В первом случае запрос уходит в облачный API Google, а при локальном запуске ограничения и учётные данные определяются выбранным вами runtime.

Что входит в локальную модель

EmbeddingGemma 2 — мультимодальная модель для построения эмбеддингов на 740 миллионах параметров. В её основе лежит текстовый блок на 270M параметров, а энкодеры изображений и аудио подключаются отдельно. Поэтому можно загружать только нужные модальности. Google и DeepMind позиционируют модель для поиска по тексту, коду, изображениям, видео и аудио, а не для генерации текста.

В карточке модели описано общее векторное пространство для сравнения разных модальностей. Число 740M относится ко всей модели, но в руководстве Google для разработчиков показано, как использовать энкодеры выборочно. Поэтому для сценариев только с текстом, где не нужны изображения и аудио, потребление памяти и вычислительная нагрузка могут быть ниже.

Выбирайте способ запуска под задачу

Sentence Transformers для Python-приложения

Для Python-сервиса официальный документированный путь — использовать чекпойнт google/embeddinggemma-2 через Sentence Transformers. Такой вариант даёт полный контроль над батчингом, размещением на устройстве, промптами, нормализацией и усечением векторов.

В поисковом сценарии для запроса и документа нужно использовать разные инструкции. В примерах 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. Если один endpoint должны использовать несколько сервисов, удобнее поднять runtime с HTTP-интерфейсом.

Ollama для быстрого локального REST endpoint

Страница EmbeddingGemma 2 в Ollama предлагает простой локальный API по адресу http://localhost:11434/api/embed:

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; размер доступных пакетов составляет примерно от 378 МБ до 1,3 ГБ. Считайте их отдельными вариантами упаковки модели, а не взаимозаменяемыми обозначениями полного чекпойнта на 740M параметров. Перед созданием production-контракта проверьте установленный тег и поддерживаемые модальности: семейство заявлено как мультимодальное, но в описаниях отдельных вариантов не все модальности раскрыты одинаково подробно.

Кроме того, нужно обеспечить единообразные префиксы задач, совпадение модели и размерности, а при смене модели — перестроить индекс.

Edge-runtime для запуска на устройствах

Google AI Edge описывает EmbeddingGemma V2 в руководстве Universal Embedder, а в документации LiteRT-LM для embedding-моделей приведён локальный паттерн сервинга с OpenAI-совместимым endpoint /v1/embeddings. Этот путь имеет смысл, когда автономная работа и приватность на устройстве важнее удобства обычного облачного развертывания.

Для сервера на обычном железе начните с Sentence Transformers или Ollama. На специализированный edge-runtime стоит переходить, когда автономность, приватность, время запуска, занимаемое место или интеграция с устройством становятся ключевыми требованиями.

Когда мультимодальность действительно оправдывает размер модели

EmbeddingGemma 2 особенно интересна проектам, которым нужно единое поисковое пространство для разных типов данных.

Поиск по коду и данные для разработчиков

В опубликованной таблице оценки для EmbeddingGemma 2 указан результат 78.68 MTEB Code против 68.76 у EmbeddingGemma 1 на приведённом бенчмарке кода. Это весомая причина протестировать модель для поиска по репозиторию, документации API и RAG-сценариев, связанных с кодом. Но результат на бенчмарке не гарантирует такого же эффекта для вашего набора языков и кодовой базы.

Когда переход на более крупную модель не оправдан

Если pipeline получает только обычный текст после OCR, мультимодальная поддержка может усложнить систему, не улучшив качество поиска. Один из пользователей Paperless-ngx описал компромисс так:

«Не уверен, что embeddinggemma-2 лучше обычной embeddinggemma для простого OCR, который Paperless-ngx отправляет модели. Похоже, работы гораздо больше, а результат тот же». — u/Great-Cow7256, Reddit

Это не результат бенчмарка, но для миграции вывод правильный: сначала сравните качество поиска на реальном корпусе, а уже потом перестраивайте работающий текстовый индекс.

Какую размерность выбрать: 768d, 512d, 256d или 128d

Документация Google по эмбеддингам описывает для EmbeddingGemma 2 усечение в стиле Matryoshka: после кодирования можно выбрать более компактное представление. Маленькие векторы экономят место в индексе и уменьшают объём передачи данных, но при самом агрессивном сокращении качество снижается.

Эти значения взяты из опубликованной таблицы оценки на странице модели в Ollama. Для нового мультимодального индекса начните с 768d; если важна экономия места, рассмотрите 512d или 256d. Вариант 128d используйте только после проверки на рабочей нагрузке с преобладанием текста.

Не смешивайте векторы разной размерности в одном индексе. Если существующая база хранит векторы размерностью 768, переход на 256d потребует заново закодировать документы и перестроить индекс. Векторы запросов должны быть получены с той же моделью, промптами, нормализацией и размерностью, что и векторы документов.

Выбирайте по рабочему процессу, а не по размеру модели

Используйте Gemini Embedding 2, если нужен управляемый endpoint Google. Для контроля на уровне Python подойдёт Sentence Transformers, для быстрого локального HTTP-сервиса — Ollama, а для автономного запуска на устройстве — AI Edge/LiteRT-LM.

Если корпус состоит из обычного OCR-текста и текущий индекс уже обеспечивает нужную релевантность, сохраняйте компактную текстовую модель. EmbeddingGemma 2 способна упростить мультимодальную архитектуру, но сама по себе не улучшает текстовый поиск.

EmbeddingGemma 2 API: часто задаваемые вопросы

Доступна ли EmbeddingGemma 2 через Gemini API?

В актуальной документации управляемого Gemini API Google указана модель gemini-embedding-2. EmbeddingGemma 2 описывается прежде всего как открытая модель для локального инференса, хотя локальные runtime могут предоставлять совместимые с API endpoint.

Можно ли запустить EmbeddingGemma 2 на CPU?

Инференс на CPU возможен в локальных runtime, которые явно поддерживают CPU-бэкенд; соответствующая документация приведена в материалах Google AI Edge по эмбеддингам. Производительность по-прежнему зависит от оборудования, квантования, размера батча и используемой модальности.

Нужно ли перестраивать существующие векторы?

Как правило, да — если вы меняете модель эмбеддингов, форматирование задач, политику нормализации или размерность векторов. Храните вместе с индексом идентификатор модели, размерность и метаданные предобработки, чтобы миграцию можно было воспроизвести.