Это руководство поможет вам диагностировать и устранять распространенные проблемы, возникающие при вызове 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 также используют режим рассуждения по умолчанию.
Думающие модели генерируют внутренние токены рассуждений, чтобы повысить качество. Этот процесс рассуждения увеличивает задержку ответа и общее потребление токенов.
Если для вас важнее низкая задержка или нужно минимизировать расходы, вы можете снизить уровень рассуждения или отключить его.
Подробные сведения о настройке и примеры кода можно найти в руководстве по размышлению.
Проблемы с безопасностью
Если вы видите, что запрос был заблокирован из-за настроек безопасности в вызове 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) в структурированных выходных данных
|
Если входные данные модели содержат символы Unicode или последовательности экранирования, например
\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.
В этом разделе описывается, как проверить, заблокирован ли ваш ключ Gemini API, и что делать, если это так.
Почему ключи блокируются
Мы обнаружили уязвимость, из-за которой некоторые ключи API могли стать общедоступными. Чтобы защитить ваши данные и предотвратить несанкционированный доступ, мы заранее заблокировали доступ к Gemini API для этих известных скомпрометированных ключей.
Как узнать, затронуты ли ваши ключи
Если произошла утечка ключа, вы больше не сможете использовать его с Gemini API. Вы можете использовать Google AI Studio, чтобы проверить, заблокированы ли какие-либо из ваших ключей API для вызова Gemini API, и создать новые ключи. При попытке использовать эти ключи вы также можете увидеть следующую ошибку:
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 и по умолчанию могут использоваться только в этом сервисе. При этом ключи из других сервисов приниматься не будут. Это поможет предотвратить непреднамеренное использование ключей.
- По умолчанию мы блокируем ключи API, которые были раскрыты и используются с Gemini API, чтобы предотвратить неправомерное использование средств и данных вашего приложения.
- Вы сможете узнать статус своих ключей API в Google AI Studio. Если мы обнаружим утечку ваших ключей API, то сообщим вам об этом, чтобы вы могли принять меры.
Улучшить результат работы модели
Чтобы получать более качественные выходные данные модели, попробуйте составлять более структурированные запросы. На странице Руководство по составлению запросов представлены основные концепции, стратегии и рекомендации, которые помогут вам начать работу.
Ограничения на количество токенов
Прочитайте руководство по токенам, чтобы узнать, как подсчитывать токены и их лимиты.
Известные проблемы
- API поддерживает только некоторые языки. Если отправлять запросы на неподдерживаемых языках, ответы могут быть неожиданными или даже заблокированными. Следите за обновлениями в списке доступных языков.
Сообщить об ошибке
Если у вас есть вопросы, задайте их на форуме для разработчиков Google AI.