Перейти к основному содержимому

Пулы API-ключей

Пулы API-ключей позволяют настроить несколько API-ключей для одного и того же провайдера. Запросы распределяются с помощью weighted round-robin, а система автоматически переключается на другой доступный ключ при достижении лимитов скорости или возникновении сбоев.

Когда использовать​

  • Сценарии с высокой параллельностью: лимита скорости одного ключа недостаточно; несколько ключей делят между собой нагрузку трафика
  • Совместное использование в команде: каждый участник команды использует квоту своего ключа, чтобы распределить расходы
  • Объединение бесплатных тарифов: ключи от нескольких бесплатных аккаунтов используются по очереди
  • Высокая доступность: когда один ключ выходит из строя, система автоматически переключается на другой, чтобы избежать прерываний
  • Разделение теста и production: используйте разные веса, чтобы управлять долей запросов, уходящих на production-ключи и тестовые ключи

Практическое руководство​

Добавление API-ключа​

  1. Откройте Settings → Provider Management
  2. Выберите целевого провайдера (например, OpenAI)
  3. Найдите раздел API Key Pool
  1. Нажмите кнопку Add Key
  2. Заполните информацию:
ПолеОбязательноОписание
API KeyДаЗначение ключа или ссылка на переменную окружения (с префиксом $)
LabelНетНазвание для удобной идентификации, например "Production Key #1" или "Test Key"
WeightНет1–100, по умолчанию 1; более высокие значения увеличивают вероятность выбора
  1. Нажмите Confirm, чтобы добавить

Настройка веса​

  1. Найдите целевой ключ в списке API-ключей
  2. Измените значение Weight (1–100)
  3. Вес определяет относительную вероятность выбора этого ключа

Включение / отключение отдельного ключа​

  1. Найдите целевой ключ в списке API-ключей
  2. Переключите тумблер Enabled
  3. Отключенные ключи исключаются из ротации, но их конфигурация сохраняется

Удаление ключа​

  1. Найдите целевой ключ в списке API-ключей
  2. Нажмите кнопку Delete
  3. Подтвердите удаление (это действие нельзя отменить)

Справочник конфигурации​

НастройкаТипПо умолчаниюДиапазонОписание
API KeyString(empty)--Значение ключа или ссылка $ENV_VAR
LabelString(empty)--Имя примечания для различения ключей
WeightInteger11–100Вес для weighted round-robin
EnabledBooleantrue--Участвует ли этот ключ в ротации
OrderInteger0--Порядок отображения в списке

Примечания о поведении​

Weighted Round-Robin​

Каждый ключ в пуле занимает количество "слотов", пропорциональное его весу. Elftia проходит эти слоты в фиксированной последовательности, распределяя запросы согласно соотношению весов.

Пример распределения весов:

Предположим, есть 3 ключа с весами 3, 2 и 1 (общий вес = 6):

КлючВесДоляВыборов на 6 запросов
Key A350%3
Key B233%2
Key C117%1

Порядок ротации: A → A → A → B → B → C → A → A → A → B → ...

Пример с равными весами:

3 ключа, каждый с весом 1 (общий вес = 3), поэтому они чередуются строго: A → B → C → A → B → C → ...

Привязка к сессии​

Все запросы в рамках одной чат-сессии привязаны к одному и тому же API-ключу. У этого решения есть две важные причины:

  1. Кэширование prompt: некоторые провайдеры (например, Anthropic) поддерживают кэширование prompt — последовательные запросы с одним и тем же ключом могут попадать в кэш, значительно снижая задержку и стоимость
  2. Согласованность: предотвращает сбросы счетчиков лимитов скорости, вызванные частыми переключениями ключей в рамках одного разговора

Привязка сессии переназначается в следующих ситуациях:

  • Текущий привязанный ключ отключен или удален
  • Текущий привязанный ключ переходит в период cooldown из-за ошибок
  • Сессия завершается (закрыта или удалена)

Автоматическое переключение при сбое​

Когда запрос сталкивается с ошибкой, пул ключей применяет разные стратегии в зависимости от типа ошибки:

Ограничение скорости (429/529)​

При получении ответа HTTP 429 (rate limit) или 529 (service overloaded):

  1. Текущий ключ переходит в период cooldown
  2. Система автоматически переключается на следующий доступный ключ в пуле
  3. Запрос повторяется с новым ключом

Механизм cooldown:

Последовательные сбоиДлительность cooldownФормула
1-й60 секунд60s × 2^0
2-й120 секунд60s × 2^1
3-й240 секунд60s × 2^2
4-й480 секунд60s × 2^3
5-й и далее900 секунд (предел)min(60s × 2^(n-1), 900s)

Ключ исключается из ротации на период cooldown и автоматически снова становится доступным после его истечения. Успешный запрос сбрасывает счетчик последовательных сбоев для этого ключа.

Ошибка аутентификации (401/403)​

При получении ответа HTTP 401 (Unauthorized) или 403 (Forbidden):

  1. Ключ навсегда отключается (помечается как отключенный в базе данных)
  2. Система автоматически переключается на следующий доступный ключ
  3. В UI настроек ключ отображается как отключенный

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

Блок-схема переключения при сбое​

Request sent
    |
    v
Use session-bound key
    |
    +---> Success ---> Reset cooldown counter ---> Return response
    |
    +---> 429/529 (rate limited)
    |         |
    |         v
    |     Current key enters cooldown
    |     (starts at 60s, exponential backoff, cap at 15 minutes)
    |         |
    |         v
    |     Any other available keys in the pool?
    |         |           |
    |        Yes          No
    |         |           |
    |         v           v
    |     Switch to new key    Request fails, return error
    |     Rebind session        (all keys unavailable)
    |         |
    |         v
    |     Retry with new key
    |
    +---> 401/403 (authentication failure)
              |
              v
          Permanently disable this key
              |
              v
          Any other available keys in the pool?
              |           |
             Yes          No
              |           |
              v           v
          Switch to new key    Request fails, return error
          Rebind session

Связь между пулом ключей и API-ключом уровня провайдера​

  • Когда для провайдера настроены и API-ключ уровня провайдера (поле api_key в конфигурации Provider), и пул ключей, приоритет имеет пул ключей
  • Если пул ключей пуст (нет записей), используется API-ключ уровня провайдера
  • Для возможностей балансировки нагрузки и переключения при сбоях рекомендуется использовать пул ключей вместо API-ключа уровня провайдера

Устранение неполадок​

ПроблемаВозможная причинаРешение
Все ключи находятся в cooldown; запросы завершаются ошибкойВсе ключи одновременно достигли лимитов скоростиДождитесь окончания cooldown (до 15 минут) или добавьте больше ключей, чтобы расширить емкость пула
Ключ никогда не выбираетсяВес равен 0 или у других ключей намного более высокие весаПроверьте настройки веса; убедитесь, что вес не меньше 1
Ключ автоматически отключенБыла получена ошибка аутентификации 401/403Проверьте, не истек ли ключ и не был ли он отозван; проверьте статус ключа на сайте провайдера, затем вручную включите его после устранения проблемы
Пул настроен правильно, но запросы все равно используют старый ключПривязка сессии закреплена за старым ключомНачните новую чат-сессию или дождитесь, пока старый ключ перейдет в cooldown, чтобы система автоматически выполнила перепривязку
Добавленный ключ не начинает действовать сразуКэш ключей не обновленСохраните конфигурацию и повторите попытку; система обновляет кэш автоматически
Ключ из переменной окружения не удается разрешитьИмя переменной неверно или не заданоУбедитесь, что имя переменной после $ точно совпадает с заданным в системе, включая регистр
Cooldown слишком долгийЭкспоненциальная задержка после нескольких последовательных попаданий в rate limitСнизьте частоту запросов или добавьте больше ключей, чтобы распределить нагрузку. Максимальный cooldown — 15 минут
Ключ переключился внутри той же сессииИсходный привязанный ключ перешел в cooldown или был отключенЭто ожидаемое поведение; система автоматически выбирает лучший доступный ключ

Связанные страницы​