При обращении к API Developer Knowledge или серверу Developer Knowledge MCP в производственных приложениях и агентах ИИ необходимо обеспечить обработку ошибок и управление квотами для достижения высокой производительности.
В этом руководстве вы узнаете, как:
- Реализуйте усеченную экспоненциальную задержку с учетом дрожания для ответов HTTP 429.
- Обработка канонических кодов ошибок gRPC (
INVALID_ARGUMENT,PERMISSION_DENIED,RESOURCE_EXHAUSTED). - Управление таймаутами подключения MCP и логикой повторных попыток.
- Применяйте лучшие практики управления квотами и кэширования.
HTTP 429: ограничение скорости и экспоненциальная задержка
Когда количество запросов превышает стандартную квоту API, сервис возвращает ошибку HTTP 429 Too Many Requests . Приложениям необходимо реализовать логику повторных попыток с использованием усеченной экспоненциальной задержки с учетом дрожания, чтобы избежать перегрузки сервиса.
Усеченная экспоненциальная задержка
Рассчитайте задержку повторной попытки, используя следующую формулу:
retry_delay = min(max_delay, initial_delay * (2 ^ attempt) + jitter)
Для расчета задержек повторной попытки используйте следующие параметры:
-
initial_delay: начальная задержка повторной попытки (например, 1,0 секунда). -
max_delay: максимальное ограничение задержки (например, 32,0 секунды). -
attempt: текущее количество повторных попыток (0, 1, 2, ...). -
jitter: случайное значение от 0 до 1,0 секунды для предотвращения скачков синхронизации потоков (проблема "громового стада").
обработка ошибок gRPC
Приложения, обращающиеся к сервису через gRPC, должны проверять канонические значения grpc.StatusCode .
Стандартные коды состояния gRPC
В таблице ниже перечислены канонические коды состояния gRPC, возвращаемые службой, и рекомендуемые способы обработки клиентом:
| код состояния gRPC | HTTP-статус | Первопричина | Рекомендуемые действия |
|---|---|---|---|
INVALID_ARGUMENT | 400 Bad Request | Некорректная строка запроса, недопустимый формат параметра или недопустимая маска поля. | Повторная попытка не требуется . Перед повторным запросом необходимо исправить параметры запроса. |
UNAUTHENTICATED | 401 Unauthorized | Отсутствует, истек срок действия или некорректно сформирован ключ API или токен OAuth Bearer. | Повторять попытку не нужно . Обновите учетные данные или сгенерируйте действительный ключ API. |
PERMISSION_DENIED | 403 Forbidden | Ключ API не имеет необходимых разрешений, или API базы знаний разработчика отключен в проекте. | Повторять попытку не нужно . Проверьте включение API в консоли Google Cloud. |
NOT_FOUND | 404 Not Found | Указанный путь к parent документу не существует. Функция BatchGetDocuments завершается с ошибкой, если какой-либо из запрошенных документов не найден. | Повторять попытку не следует . Проверьте имя ресурса документа. |
RESOURCE_EXHAUSTED | 429 Too Many Requests | Превышен лимит ставок или лимит квоты проекта. | Попробуйте еще раз, используя экспоненциальную задержку с дрожанием. |
UNAVAILABLE | 503 Service Unavailable | Временное отключение сети или перезагрузка сервера. | Повторите попытку с экспоненциальной задержкой. |
DEADLINE_EXCEEDED | 504 Gateway Timeout | Запрос превысил установленный крайний срок выполнения RPC-запроса до завершения. | Повторите попытку , увеличив время ожидания RPC-вызова клиента. |
Управление таймаутами подключения и ошибками MCP
Сервер Developer Knowledge MCP — это удалённый сервис, размещённый по адресу https://developerknowledge.googleapis.com/mcp и доступный по протоколу HTTPS (с использованием HTTP POST или Server-Sent Events). Хосты и агенты ИИ должны корректно обрабатывать таймауты подключения и ошибки инструментов.
Таймауты выполнения инструментов
Когда агент вызывает search_documents , get_documents или answer_query , время ожидания вызова инструмента может превышать установленные значения (например, 30 секунд), если сетевое соединение работает с задержкой.
Для обработки таймаутов выполнения инструментов:
- Настройка тайм-аутов клиента : установите тайм-ауты выполнения инструментов на 30–60 секунд в конфигурации клиента MCP.
- Обработка сетевых сбоев : повторная попытка выполнения неудачных HTTP-запросов с экспоненциальной задержкой при возникновении временных обрывов связи или ответов HTTP 503.
- Анализ сообщений об ошибках : разбор стандартных сообщений об ошибках JSON-RPC или кодов состояния ошибок HTTP для различения недопустимых аргументов от исчерпания квоты.
Передовые методы управления квотами
Следуйте этим рекомендациям, чтобы обеспечить оптимальное использование API и избежать неожиданных ограничений скорости запросов:
- Кэширование содержимого полученных документов : хранение полученных документов Markdown локально или в кэше (например, Redis) при разработке приложений, которые часто обращаются к одним и тем же страницам.
- Используйте пакетную обработку : используйте
documents.batchGetвместо выполнения нескольких последовательных запросовdocuments.get. - Оптимизация полей запроса : запрашивайте только необходимые поля ответа, используя маски выборочных полей (
fields=results(parent,content)). - Отслеживание потребления квот : мониторинг частоты запросов к API на панели мониторинга API в консоли Google Cloud .