Техническая документация: Интеграция Google Gemini API

См. также как оплатить Google Gemini API из России

1. Обзор

Google Gemini — семейство многомодальных моделей ИИ, способных обрабатывать текст, изображения, аудио и видео. API предоставляет программный доступ к этим возможностям.

2. Требования

2.1 Предварительные условия

• Аккаунт Google
• Доступ к Google AI Studio (https://makersuite.google.com/app/apikey)
• Python 3.8+ или Node.js 16+

2.2 Установленные пакеты

Для Python:

pip install google-generativeai python-dotenv

Для Node.js:

npm install @google/generative-ai dotenv

3. Получение API-ключа

3.1 Шаги получения

1. Перейдите на https://makersuite.google.com/app/apikey
2. Войдите в аккаунт Google
3. Нажмите "Create API key"
4. Выберите проект или создайте новый
5. Скопируйте сгенерированный ключ

3.2 Безопасное хранение ключа

# Создайте .env файл
echo "GEMINI_API_KEY=ваш_ключ_здесь" > .env

4. Быстрый старт

4.1 Python пример

import os
import google.generativeai as genai
from dotenv import load_dotenv

# Загрузка переменных окружения
load_dotenv()

# Конфигурация API
genai.configure(api_key=os.getenv("GEMINI_API_KEY"))

# Инициализация модели
model = genai.GenerativeModel('gemini-pro')

# Генерация контента
response = model.generate_content("Привет! Как дела?")
print(response.text)

4.2 JavaScript/Node.js пример

const { GoogleGenerativeAI } = require("@google/generative-ai");
require("dotenv").config();

// Инициализация
const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
const model = genAI.getGenerativeModel({ model: "gemini-pro" });

// Генерация контента
async function generateContent() {
    const result = await model.generateContent("Привет! Как дела?");
    console.log(result.response.text());
}

generateContent();

5. Детальная конфигурация

5.1 Доступные модели

5.2 Конфигурация генерации

from google.generativeai.types import GenerationConfig

generation_config = GenerationConfig(
    temperature=0.7,
    top_p=0.8,
    top_k=40,
    max_output_tokens=2048,
    stop_sequences=["STOP"]
)

model = genai.GenerativeModel(
    'gemini-pro',
    generation_config=generation_config
)

6. Расширенные возможности

6.1 Мультимодальный ввод (изображения + текст)

import PIL.Image

# Загрузка изображения
img = PIL.Image.open('image.jpg')

# Создание промпта с изображением
response = model.generate_content([
    "Опиши что на этом изображении",
    img
])
print(response.text)

6.2 Чат-сессии с историей

# Создание чат-сессии
chat = model.start_chat(history=[])

# Обмен сообщениями
response = chat.send_message("Привет!")
print(response.text)

response = chat.send_message("Как тебя зовут?")
print(response.text)

# Просмотр истории
for message in chat.history:
    print(f"{message.role}: {message.parts[0].text}")

6.3 Потоковая генерация

response = model.generate_content(
    "Расскажи длинную историю",
    stream=True
)

for chunk in response:
    print(chunk.text, end='')

7. Обработка файлов

7.1 Загрузка различных форматов

import google.generativeai as genai

# Загрузка PDF
sample_file = genai.upload_file(path="document.pdf")

# Анализ документа
response = model.generate_content([
    "Проанализируй этот документ и выдели ключевые пункты",
    sample_file
])

7.2 Поддерживаемые форматы:

• Изображения: PNG, JPEG, WebP, HEIC
• Документы: PDF, TXT
• Аудио: WAV, MP3
• Видео: MP4, MOV

8. Управление безопасностью

8.1 Настройки безопасности

import google.generativeai as genai

safety_settings = [
    {
        "category": "HARM_CATEGORY_HARASSMENT",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
    {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "threshold": "BLOCK_ONLY_HIGH"
    },
    {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "threshold": "BLOCK_LOW_AND_ABOVE"
    },
    {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    },
]

model = genai.GenerativeModel(
    'gemini-pro',
    safety_settings=safety_settings
)

8.2 Категории безопасности:

• HARASSMENT
• HATE_SPEECH
• SEXUALLY_EXPLICIT
• DANGEROUS_CONTENT

9. Оптимизация запросов

9.1 Системные инструкции

system_instruction = """
Ты полезный ассистент, который всегда отвечает 
вежливо и профессионально. Твои ответы должны 
быть краткими, но информативными.
"""

model = genai.GenerativeModel(
    'gemini-pro',
    system_instruction=system_instruction
)

9.2 Параметры для тонкой настройки

generation_config = {
    "temperature": 0.2,  # Креативность (0.0-1.0)
    "top_p": 0.95,       # Нуклеус-семплинг
    "top_k": 40,         # Ограничение словаря
    "max_output_tokens": 1000,
    "response_mime_type": "text/plain"
}

10. Обработка ошибок

10.1 Базовый обработчик

import google.api_core.exceptions

try:
    response = model.generate_content(prompt)
    print(response.text)
except google.api_core.exceptions.InvalidArgument as e:
    print(f"Ошибка в промпте: {e}")
except google.api_core.exceptions.PermissionDenied as e:
    print(f"Ошибка доступа: {e}")
except Exception as e:
    print(f"Неизвестная ошибка: {e}")

10.2 Распространенные ошибки:

• 429: Превышен лимит запросов
• 400: Неверный запрос
• 403: Нет доступа к API
• 500: Ошибка сервера

12. Пример полного приложения

12.1 Структура проекта

project/
├── .env
├── requirements.txt
├── config/
│   └── settings.py
├── services/
│   └── gemini_service.py
├── utils/
│   └── file_handler.py
└── main.py

12.2 Сервисный класс

# services/gemini_service.py
import os
import google.generativeai as genai
from typing import Optional, List
from google.generativeai.types import GenerationConfig

class GeminiService:
    def __init__(self, api_key: Optional[str] = None):
        self.api_key = api_key or os.getenv("GEMINI_API_KEY")
        genai.configure(api_key=self.api_key)
        self.model = self._initialize_model()
        
    def _initialize_model(self, model_name: str = "gemini-pro"):
        """Инициализация модели с настройками"""
        generation_config = GenerationConfig(
            temperature=0.7,
            top_p=0.9,
            max_output_tokens=2048,
        )
        
        safety_settings = [
            {
                "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
                "threshold": "BLOCK_MEDIUM_AND_ABOVE"
            }
        ]
        
        return genai.GenerativeModel(
            model_name=model_name,
            generation_config=generation_config,
            safety_settings=safety_settings
        )
    
    async def generate_text(self, prompt: str, **kwargs) -> str:
        """Генерация текста"""
        try:
            response = await self.model.generate_content_async(
                prompt,
                **kwargs
            )
            return response.text
        except Exception as e:
            raise Exception(f"Generation failed: {str(e)}")
    
    def start_chat_session(self, history: List = None):
        """Создание чат-сессии"""
        return self.model.start_chat(history=history or [])
    
    def analyze_image(self, image_path: str, prompt: str) -> str:
        """Анализ изображения"""
        import PIL.Image
        
        img = PIL.Image.open(image_path)
        response = self.model.generate_content([prompt, img])
        return response.text

16. Best Practices

16.1 Рекомендации:

1. Всегда используйте асинхронные методы для продакшена
2. Кэшируйте частые запросы
3. Реализуйте retry логику для сетевых ошибок
4. Валидируйте входные данные
5. Мониторьте использование и стоимость

16.2 Пример с retry логикой:

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=4, max=10)
)
def generate_with_retry(prompt: str):
    return model.generate_content(prompt)

17. Ресурсы и ссылки

• Официальная документация
• Python SDK на GitHub
• Примеры использования
• Сообщество разработчиков