Это руководство поможет вам диагностировать и устранять распространенные проблемы, возникающие при вызове Gemini API. Вы можете столкнуться с проблемами, связанными с бэкенд-службой Gemini API или клиентскими SDK. Наши клиентские SDK размещены в следующих репозиториях с открытым исходным кодом:
Если у вас возникли проблемы с ключом API, убедитесь, что вы настроили его правильно, следуя руководству по настройке ключа API.
Коды ошибок
Полный список кодов ошибок, включая коды статуса HTTP, коды блокировки генерации и коды ошибок контента, приведен на странице Ошибки API.
Стратегия повторных попыток
Если вы получили ошибку, указывающую на то, что запрос нужно повторить (например, 429 RESOURCE_EXHAUSTED или 503 UNAVAILABLE), рекомендуем использовать экспоненциальную выдержку. Это означает, что перед первой повторной попыткой вы ждете короткое время, а затем постепенно увеличиваете время ожидания между последующими повторными попытками.
Официальные клиентские SDK для Gemini API, например Python SDK, по умолчанию включают логику автоматического повтора с экспоненциальной выдержкой для обработки временных ошибок, таких как тайм-ауты, проблемы с сетью и ограничения частоты запросов (коды статуса 429 и 5xx). Например, Python SDK автоматически повторяет попытку при временных ошибках до четырех раз с начальной задержкой около 1 секунды и максимальной задержкой 60 секунд.
Если вы отправляете прямые запросы к REST API или настраиваете логику повторных попыток, следуйте приведенным ниже рекомендациям, чтобы повысить вероятность успешного выполнения запроса к API и предотвратить перегрузку сервиса.
- Используйте экспоненциальную выдержку. Подождите немного перед первой повторной попыткой (например, 1 секунду), а затем увеличивайте задержку экспоненциально (например, 2, 4, 8 секунд).
- Добавьте джиттер. Добавьте случайный джиттер к задержке, чтобы клиенты не пытались повторить попытку одновременно.
- Повторяйте попытки только при определенных ошибках. Повторяйте попытки только при временных ошибках (например,
429,408или5xx). Не повторяйте попытки при ошибках клиента (например,400,402или403), так как они указывают на такие проблемы, как недействительные ключи API, исчерпанные средства предоплаты или неправильный синтаксис. - Задайте максимальное количество повторных попыток. Это позволит избежать бесконечных циклов.
Проверьте вызовы API на наличие ошибок в параметрах модели
Убедитесь, что параметры модели находятся в следующих пределах:
| Параметр модели | Значения (диапазон) |
| Количество кандидатов | 1–8 (целое число) |
| Температура | 0.0–1.0 |
| Макс. число выходных токенов | Максимальное количество токенов для используемой модели можно узнать на странице моделей. |
| TopP | 0.0–1.0 |
Помимо проверки значений параметров, убедитесь, что вы используете правильную версию API (например, /v1 или /v1beta) и модель, которая поддерживает нужные вам функции. Например, если функция находится на стадии бета-тестирования, она будет доступна только в версии API /v1beta.
Как проверить модель устройства
Убедитесь, что вы используете поддерживаемую модель, указанную на странице моделей.
Более высокая задержка или использование токенов с думающими моделями
Более высокая задержка или использование токенов часто происходит из-за того, что в моделях Gemini 3.x по умолчанию включено мышление. Устаревшие модели Gemini 2.5 также используют режим Thinking по умолчанию.
Думающие модели генерируют внутренние токены рассуждений, чтобы повысить качество ответов. Этот процесс рассуждения увеличивает как задержку ответа, так и общее потребление токенов.
Если для вас важнее низкая задержка или вы хотите снизить расходы, вы можете уменьшить уровень рассуждения или отключить его.
Подробные сведения о настройке и примеры кода можно найти в руководстве по размышлению.
Проблемы с безопасностью
Если вы видите, что запрос был заблокирован из-за настроек безопасности в вызове API, проверьте запрос с учетом фильтров, заданных в вызове API.
Если вы видите BlockedReason.OTHER, запрос или ответ может нарушать Условия использования или не поддерживаться по другой причине.
Проблема с декламацией
Если модель прекращает генерировать выходные данные по причине RECITATION, это означает, что выходные данные модели могут напоминать определенные данные. Чтобы исправить это, попробуйте сделать запрос или контекст как можно более уникальными и использовать более высокую температуру.
Проблема с повторяющимися токенами
Если вы видите повторяющиеся выходные токены, попробуйте воспользоваться следующими советами, чтобы уменьшить или устранить их.
| Описание | Причина | Рекомендуемое временное решение |
|---|---|---|
| Повторяющиеся дефисы в таблицах Markdown | Это может произойти, если содержимое таблицы длинное, поскольку модель пытается создать визуально выровненную таблицу Markdown. Однако выравнивание в Markdown не требуется для правильного отображения. |
Добавьте в запрос инструкции, чтобы дать модели конкретные указания по созданию таблиц Markdown. Приведите примеры, соответствующие этим рекомендациям. Вы также можете попробовать изменить температуру. Для генерации кода или структурированных данных, например таблиц Markdown, лучше подходит высокая температура (>= 0,8). Ниже приведен пример инструкций, которые можно добавить в запрос, чтобы избежать этой проблемы.
# Markdown Table Format
* Separator line: Markdown tables must include a separator line below
the header row. The separator line must use only 3 hyphens per
column, for example: |---|---|---|. Using more hypens like
----, -----, ------ can result in errors. Always
use |:---|, |---:|, or |---| in these separator strings.
For example:
| Date | Description | Attendees |
|---|---|---|
| 2024-10-26 | Annual Conference | 500 |
| 2025-01-15 | Q1 Planning Session | 25 |
* Alignment: Do not align columns. Always use |---|.
For three columns, use |---|---|---| as the separator line.
For four columns use |---|---|---|---| and so on.
* Conciseness: Keep cell content brief and to the point.
* Never pad column headers or other cells with lots of spaces to
match with width of other content. Only a single space on each side
is needed. For example, always do "| column name |" instead of
"| column name |". Extra spaces are wasteful.
A markdown renderer will automatically take care displaying
the content in a visually appealing form.
|
| Повторяющиеся токены в таблицах Markdown | Как и в случае с повторяющимися дефисами, это происходит, когда модель пытается визуально выровнять содержимое таблицы. Выравнивание в Markdown не требуется для правильного отображения. |
|
Повторяющиеся символы новой строки (\n) в структурированных выходных данных
|
Если входные данные модели содержат символы Юникода или escape-последовательности, такие как \u или \t, это может привести к повторным переносам строк.
|
|
| Повторяющийся текст в структурированных описаниях | Если порядок полей в выходных данных модели отличается от заданной структурированной схемы, это может привести к повторению текста. |
|
| Повторяющиеся вызовы инструментов | Это может произойти, если модель теряет контекст предыдущих рассуждений и/или вызывает недоступную конечную точку, к которой она вынуждена обращаться. |
Укажите модели поддерживать состояние в процессе мышления.
Добавьте в конец системных инструкций следующее:
When thinking silently: ALWAYS start the thought with a brief
(one sentence) recap of the current progress on the task. In
particular, consider whether the task is already done.
|
| Повторяющийся текст, который не является частью структурированных выходных данных. | Это может произойти, если модель застрянет на запросе, который не может решить. |
|
Проект недоступен или доступ к нему ограничен
Если в ответ на запросы к API вы получаете ошибку 403 PERMISSION_DENIED ("Доступ для вашего проекта запрещен") или в Google AI Studio у проекта статус Ограничено, Бесплатный план недоступен, Требуется оплата или Недоступно, ознакомьтесь с информацией ниже.
Недоступность бесплатного плана Gemini API
Бесплатный план Gemini API доступен не для всех облачных проектов и аккаунтов Google Cloud. Если в вашем проекте нельзя использовать бесплатный план:
- Создание нового ключа API в том же проекте не устранит ошибку. Google оценивает соответствие требованиям на уровне проекта Google Cloud.
- Чтобы использовать Gemini API в этом проекте, вам нужно перейти на платный тариф, связав активный платежный аккаунт Cloud.
- Примечание. Переход на платный тариф не разблокирует квоту бесплатного тарифа. Google выставляет счета за использование платного уровня в соответствии с ценами на Gemini API или вычитает сумму из бонусов Google Cloud.
Требуется платеж в платежном аккаунте Cloud
Если проект уже связан с платежным аккаунтом Cloud и вы видите сообщение Требуется оплата (или возвращается ошибка 403 PERMISSION_DENIED с указанием задолженности):
- Чтобы погасить задолженность или изменить способ оплаты, перейдите на страницу оплаты AI Studio или в консоль Cloud Billing в Google Cloud.
- После того как вы восстановите хорошую репутацию платежного аккаунта, доступ к API для проекта будет восстановлен автоматически.
Раскрытые или заблокированные ключи API
Если в состоянии ошибки 403 PERMISSION_DENIED говорится, что ключ API был заблокирован или произошла его утечка:
- Перейдите на страницу ключей Studio API в AI Studio, чтобы сгенерировать новый ключ API и обновить учетные данные приложения.
- Никогда не встраивайте ключи API непосредственно в клиентский код или в общедоступные репозитории.
Блокировка проекта или платежного аккаунта за нарушение правил
Если Google приостановит ваш облачный проект Google Cloud или платежный аккаунт Cloud за нарушение правил, проверьте связанный адрес электронной почты. Перейдите в консоль Google Cloud, чтобы ознакомиться с уведомлениями о блокировке, и следуйте рекомендациям по устранению блокировки проекта.
Заблокированные или неработающие ключи API.
В этом разделе описывается, как проверить, заблокирован ли ваш ключ Gemini API, и что делать, если это так.
Почему ключи блокируются
Мы обнаружили уязвимость, из-за которой некоторые ключи API могли стать общедоступными. Чтобы защитить ваши данные и предотвратить несанкционированный доступ, мы заблокировали доступ к Gemini API для всех ключей, которые были раскрыты.
Как проверить, затронуты ли ваши ключи
Если произошла утечка ключа, вы больше не сможете использовать его с Gemini API. Проверить, заблокированы ли какие-либо из ваших ключей API для вызова Gemini API, и сгенерировать новые ключи можно в Google AI Studio. При попытке использовать эти ключи вы также можете увидеть следующую ошибку:
Your API key was reported as leaked. Please use another API key.
Действие для заблокированных ключей API
Вам нужно сгенерировать новые ключи API для интеграций Gemini API с помощью Google AI Studio. Мы настоятельно рекомендуем пересмотреть методы управления ключами API, чтобы обеспечить безопасность новых ключей и не допустить их раскрытия.
Неожиданные списания из-за уязвимости
Отправьте запрос в службу поддержки по вопросам оплаты. Наши специалисты по платежам работают над этим, и мы сообщим вам, как только у нас появится новая информация.
Меры безопасности Google в отношении утекших ключей
Как Google поможет защитить мой аккаунт от перерасхода средств и злоупотреблений, если произойдет утечка ключей API?
- Мы планируем перейти на выдачу ключей API, которые по умолчанию будут ограничены только Google AI Studio и не будут принимать ключи из других сервисов. Это будет происходить, когда вы запрашиваете новый ключ с помощью Google AI Studio. Это поможет предотвратить непреднамеренное использование ключей.
- По умолчанию мы блокируем ключи API, которые были раскрыты и использовались с Gemini API. Это помогает предотвратить неправомерное использование данных приложения и избежать лишних расходов.
- Вы сможете узнать статус своих ключей API в Google AI Studio. Если мы обнаружим утечку ваших ключей API, то сообщим вам об этом, чтобы вы могли принять меры.
Улучшить результат работы модели
Чтобы получать более качественные выходные данные модели, попробуйте писать более структурированные запросы. На странице Руководство по составлению запросов представлены основные концепции, стратегии и рекомендации, которые помогут вам начать работу.
Ограничения на количество токенов
Прочитайте руководство по токенам, чтобы узнать, как подсчитывать токены и их лимиты.
Известные проблемы
- API поддерживает только некоторые языки. Если вы отправите запрос на неподдерживаемом языке, то можете получить неожиданный ответ или он будет заблокирован. Следите за обновлениями в списке доступных языков.
Сообщить об ошибке
Если у вас есть вопросы, задайте их на форуме для разработчиков Google AI.