diff --git a/docs/uk/concepts/model-failover.md b/docs/uk/concepts/model-failover.md index 10f19a978..220edb488 100644 --- a/docs/uk/concepts/model-failover.md +++ b/docs/uk/concepts/model-failover.md @@ -1,16 +1,16 @@ --- read_when: - - Діагностика чергування профілів автентифікації, періодів охолодження або поведінки переходу на резервний варіант моделі - - Оновлення правил переходу на резервний варіант для профілів автентифікації або моделей - - Розуміння того, як перевизначення моделі сеансу взаємодіють із повторними спробами резервного переходу + - Діагностика чергування профілів автентифікації, періодів охолодження або поведінки резервного перемикання моделей + - Оновлення правил резервного перемикання для профілів автентифікації або моделей + - Розуміння того, як перевизначення моделі сеансу взаємодіють із повторними спробами резервного перемикання sidebarTitle: Model failover -summary: Як OpenClaw чергує профілі автентифікації та виконує перехід на резервний варіант між моделями -title: Перехід на резервний варіант моделі +summary: Як OpenClaw чергує профілі автентифікації та перемикається на резервні варіанти між моделями +title: Резервне перемикання моделей x-i18n: - generated_at: "2026-04-26T11:07:53Z" + generated_at: "2026-04-26T21:48:19Z" model: gpt-5.4 provider: openai - source_hash: 0e681a456f75073bb34e7af94234efeee57c6c25e9414da19eb9527ccba5444a + source_hash: 3127f0b0ad76f8654685ae4446f2c7d82be8367bcd631e2f4ed160fc3457cfe7 source_path: concepts/model-failover.md workflow: 15 --- @@ -18,11 +18,11 @@ x-i18n: OpenClaw обробляє збої у два етапи: 1. **Чергування профілів автентифікації** в межах поточного провайдера. -2. **Резервний перехід моделі** до наступної моделі в `agents.defaults.model.fallbacks`. +2. **Резервне перемикання моделей** на наступну модель у `agents.defaults.model.fallbacks`. -У цьому документі пояснюються правила виконання під час роботи та дані, на яких вони базуються. +У цьому документі пояснюються правила виконання та дані, на яких вони ґрунтуються. -## Потік виконання +## Логіка виконання Для звичайного текстового запуску OpenClaw оцінює кандидатів у такому порядку: @@ -31,26 +31,26 @@ OpenClaw обробляє збої у два етапи: Визначте активну модель сеансу та налаштування профілю автентифікації. - Побудуйте ланцюжок моделей-кандидатів на основі поточної вибраної моделі сеансу, потім `agents.defaults.model.fallbacks` у вказаному порядку, завершуючи налаштованою основною моделлю, якщо запуск почався з перевизначення. + Побудуйте ланцюжок кандидатів моделей із поточно вибраної моделі сеансу, потім `agents.defaults.model.fallbacks` у заданому порядку, завершуючи налаштованою основною моделлю, якщо запуск почався з перевизначення. Спробуйте поточного провайдера з правилами чергування/охолодження профілів автентифікації. - - Якщо можливості цього провайдера вичерпані через помилку, що допускає резервний перехід, перейдіть до наступної моделі-кандидата. + + Якщо цей провайдер вичерпано через помилку, що допускає резервне перемикання, перейдіть до наступного кандидата моделі. - - Збережіть вибране перевизначення резервного переходу перед початком повторної спроби, щоб інші читачі сеансу бачили того самого провайдера/модель, яких виконавець зараз збирається використати. + + Збережіть вибране перевизначення резервного варіанта до початку повторної спроби, щоб інші читачі сеансу бачили того самого провайдера/модель, яких виконавець збирається використати. - - Якщо кандидат резервного переходу завершується помилкою, відкотіть лише ті поля перевизначення сеансу, які належать резервному переходу, якщо вони все ще відповідають цьому невдалому кандидату. + + Якщо кандидат резервного варіанта зазнає збою, відкочуйте лише поля перевизначення сеансу, що належать резервному варіанту, коли вони все ще відповідають цьому невдалому кандидату. - - Якщо всі кандидати завершилися невдачею, викиньте `FallbackSummaryError` із деталями для кожної спроби та найближчим часом завершення охолодження, якщо він відомий. + + Якщо всі кандидати зазнали збою, викиньте `FallbackSummaryError` із деталями для кожної спроби та найближчим часом завершення охолодження, якщо його відомо. -Це навмисно вужче, ніж «зберегти та відновити весь сеанс». Виконавець відповіді зберігає для резервного переходу лише поля вибору моделі, якими він володіє: +Це навмисно вужче, ніж «зберегти й відновити весь сеанс». Виконавець відповіді зберігає лише поля вибору моделі, якими він володіє для резервного перемикання: - `providerOverride` - `modelOverride` @@ -58,16 +58,16 @@ OpenClaw обробляє збої у два етапи: - `authProfileOverrideSource` - `authProfileOverrideCompactionCount` -Це запобігає ситуації, коли невдала повторна спроба резервного переходу перезаписує новіші, не пов’язані зі збоями зміни сеансу, як-от ручні зміни `/model` або оновлення ротації сеансу, що сталися під час виконання спроби. +Це запобігає тому, щоб невдала повторна спроба резервного перемикання перезаписала новіші, не пов’язані із цим зміни сеансу, як-от ручні зміни `/model` або оновлення чергування сеансу, що сталися під час виконання спроби. ## Сховище автентифікації (ключі + OAuth) -OpenClaw використовує **профілі автентифікації** як для API-ключів, так і для OAuth-токенів. +OpenClaw використовує **профілі автентифікації** як для API-ключів, так і для токенів OAuth. - Секрети зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (застарілий шлях: `~/.openclaw/agent/auth-profiles.json`). - Стан маршрутизації автентифікації під час виконання зберігається в `~/.openclaw/agents//agent/auth-state.json`. -- Конфігурація `auth.profiles` / `auth.order` — це **лише метадані та маршрутизація** (без секретів). -- Застарілий OAuth-файл лише для імпорту: `~/.openclaw/credentials/oauth.json` (імпортується до `auth-profiles.json` під час першого використання). +- Конфігурація `auth.profiles` / `auth.order` — це **лише метадані + маршрутизація** (без секретів). +- Застарілий файл OAuth лише для імпорту: `~/.openclaw/credentials/oauth.json` (імпортується в `auth-profiles.json` під час першого використання). Докладніше: [OAuth](/uk/concepts/oauth) @@ -78,16 +78,16 @@ OpenClaw використовує **профілі автентифікації* ## Ідентифікатори профілів -OAuth-входи створюють окремі профілі, щоб могли співіснувати кілька облікових записів. +Входи через OAuth створюють окремі профілі, щоб кілька облікових записів могли співіснувати. -- Типово: `provider:default`, якщо електронна адреса недоступна. -- OAuth з електронною адресою: `provider:` (наприклад, `google-antigravity:user@gmail.com`). +- Типово: `provider:default`, коли email недоступний. +- OAuth з email: `provider:` (наприклад, `google-antigravity:user@gmail.com`). Профілі зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` у розділі `profiles`. ## Порядок чергування -Коли провайдер має кілька профілів, OpenClaw обирає порядок так: +Коли провайдер має кілька профілів, OpenClaw вибирає порядок так: @@ -104,59 +104,59 @@ OAuth-входи створюють окремі профілі, щоб могл Якщо явний порядок не налаштовано, OpenClaw використовує порядок round-robin: - **Основний ключ:** тип профілю (**OAuth перед API-ключами**). -- **Другорядний ключ:** `usageStats.lastUsed` (найдавніші першими в межах кожного типу). +- **Другорядний ключ:** `usageStats.lastUsed` (найстаріші спочатку в межах кожного типу). - **Профілі в охолодженні/вимкнені профілі** переміщуються в кінець, упорядковані за найближчим завершенням строку дії. -### Прив’язка до сеансу (cache-friendly) +### Закріплення за сеансом (дружнє до кешу) -OpenClaw **закріплює вибраний профіль автентифікації за кожним сеансом**, щоб кеші провайдера залишалися теплими. Він **не** виконує чергування для кожного запиту. Закріплений профіль використовується повторно, доки: +OpenClaw **закріплює вибраний профіль автентифікації за кожним сеансом**, щоб кеші провайдера залишалися «теплими». Він **не** чергує профілі для кожного запиту. Закріплений профіль використовується повторно, доки: - сеанс не буде скинуто (`/new` / `/reset`) - не завершиться Compaction (лічильник Compaction збільшиться) - профіль не перейде в стан охолодження/не буде вимкнений -Ручний вибір через `/model …@` задає **перевизначення користувача** для цього сеансу й не чергується автоматично, доки не почнеться новий сеанс. +Ручний вибір через `/model …@` задає **перевизначення користувача** для цього сеансу та не чергується автоматично, доки не почнеться новий сеанс. -Автоматично закріплені профілі (вибрані маршрутизатором сеансу) розглядаються як **побажання**: їх пробують першими, але OpenClaw може перейти до іншого профілю у разі обмежень швидкості/тайм-аутів. Профілі, закріплені користувачем, залишаються прив’язаними саме до цього профілю; якщо він завершується помилкою і налаштовано резервні переходи між моделями, OpenClaw переходить до наступної моделі замість перемикання профілів. +Автоматично закріплені профілі (вибрані маршрутизатором сеансу) розглядаються як **перевага**: їх пробують першими, але OpenClaw може перейти на інший профіль у разі обмежень швидкості/тайм-аутів. Профілі, закріплені користувачем, залишаються прив’язаними до цього профілю; якщо він зазнає збою і налаштовано резервні моделі, OpenClaw переходить до наступної моделі замість перемикання профілів. ### Чому OAuth може «здаватися втраченим» -Якщо для одного провайдера у вас є і OAuth-профіль, і профіль API-ключа, round-robin може перемикатися між ними між повідомленнями, якщо профіль не закріплений. Щоб примусово використовувати один профіль: +Якщо у вас є і профіль OAuth, і профіль API-ключа для одного провайдера, round-robin може перемикатися між ними між повідомленнями, якщо вони не закріплені. Щоб примусово використовувати один профіль: -- Закріпіть його через `auth.order[provider] = ["provider:profileId"]`, або -- Використовуйте перевизначення для конкретного сеансу через `/model …` з перевизначенням профілю (якщо це підтримується вашим UI/поверхнею чату). +- Закріпіть через `auth.order[provider] = ["provider:profileId"]`, або +- Використайте перевизначення для конкретного сеансу через `/model …` із перевизначенням профілю (коли це підтримується вашим UI/поверхнею чату). -## Періоди охолодження +## Охолодження -Коли профіль завершується помилкою через автентифікацію/обмеження швидкості (або тайм-аутом, що схожий на обмеження швидкості), OpenClaw переводить його в стан охолодження та переходить до наступного профілю. +Коли профіль зазнає збою через помилки автентифікації/обмеження швидкості (або тайм-аут, схожий на обмеження швидкості), OpenClaw переводить його в стан охолодження та переходить до наступного профілю. - Ця категорія обмежень швидкості ширша за простий `429`: до неї також входять повідомлення провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` і періодичні обмеження вікна використання, як-от `weekly/monthly limit reached`. + Ця категорія обмеження швидкості ширша за звичайний `429`: вона також включає повідомлення провайдерів, як-от `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `throttled`, `resource exhausted` і періодичні обмеження вікна використання, як-от `weekly/monthly limit reached`. - Помилки формату/некоректного запиту (наприклад, помилки валідації ID виклику інструмента Cloud Code Assist) вважаються такими, що допускають резервний перехід, і використовують ті самі періоди охолодження. Помилки stop-reason у стилі OpenAI-compatible, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали тайм-ауту/резервного переходу. + Помилки формату/некоректного запиту (наприклад, помилки перевірки ID виклику інструмента Cloud Code Assist) вважаються придатними для резервного перемикання та використовують ті самі механізми охолодження. Помилки сумісних з OpenAI причин зупинки, як-от `Unhandled stop reason: error`, `stop reason: error` і `reason: error`, класифікуються як сигнали тайм-ауту/резервного перемикання. - Загальний текст серверних помилок також може потрапити до цієї категорії тайм-аутів, коли джерело відповідає відомому шаблону тимчасового збою. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається таким, що допускає резервний перехід, для кожного провайдера, оскільки pi-ai повертає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних деталей. JSON-повідомлення `api_error` із тимчасовим серверним текстом, таким як `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також вважаються тайм-аутами, що допускають резервний перехід. + Загальний текст серверних помилок також може потрапляти до цієї категорії тайм-аутів, коли джерело відповідає відомому тимчасовому шаблону. Наприклад, просте повідомлення обгортки потоку pi-ai `An unknown error occurred` вважається придатним для резервного перемикання для кожного провайдера, оскільки pi-ai повертає його, коли потоки провайдера завершуються з `stopReason: "aborted"` або `stopReason: "error"` без конкретних подробиць. JSON-повідомлення `api_error` із тимчасовим серверним текстом, як-от `internal server error`, `unknown error, 520`, `upstream error` або `backend error`, також розглядаються як тайм-аути, придатні для резервного перемикання. - Загальний текст вищестоящої помилки, специфічний для OpenRouter, як-от просте `Provider returned error`, вважається тайм-аутом лише тоді, коли контекст провайдера справді OpenRouter. Загальний внутрішній текст резервного переходу, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервний перехід. + Загальний upstream-текст, специфічний для OpenRouter, як-от просте `Provider returned error`, вважається тайм-аутом лише тоді, коли контекстом провайдера справді є OpenRouter. Загальний внутрішній резервний текст, як-от `LLM request failed with an unknown error.`, залишається консервативним і сам по собі не запускає резервне перемикання. - Деякі SDK провайдерів можуть інакше спати протягом довгого вікна `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на основі Stainless, таких як Anthropic і OpenAI, OpenClaw типово обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60 секунд і негайно показує довші відповіді з можливістю повтору, щоб міг спрацювати цей шлях резервного переходу. Налаштуйте або вимкніть це обмеження через `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry). + Деякі SDK провайдерів інакше можуть «спати» протягом довгого вікна `Retry-After`, перш ніж повернути керування OpenClaw. Для SDK на базі Stainless, таких як Anthropic і OpenAI, OpenClaw типово обмежує внутрішні очікування SDK `retry-after-ms` / `retry-after` до 60 секунд і негайно показує довші відповіді, придатні для повторної спроби, щоб цей шлях резервного перемикання міг спрацювати. Налаштуйте або вимкніть це обмеження через `OPENCLAW_SDK_RETRY_MAX_WAIT_SECONDS`; див. [Поведінка повторних спроб](/uk/concepts/retry). - - Періоди охолодження через обмеження швидкості також можуть бути прив’язані до моделі: + + Охолодження через обмеження швидкості також може бути прив’язане до моделі: - - OpenClaw записує `cooldownModel` для збоїв через обмеження швидкості, коли ідентифікатор моделі, що завершилася помилкою, відомий. - - Сусідню модель у того самого провайдера все ще можна спробувати, коли період охолодження прив’язаний до іншої моделі. + - OpenClaw записує `cooldownModel` для збоїв через обмеження швидкості, коли відомий ідентифікатор моделі, що зазнала збою. + - Дочірню модель того самого провайдера все ще можна спробувати, якщо охолодження прив’язане до іншої моделі. - Вікна білінгу/вимкнення все одно блокують увесь профіль для всіх моделей. -Періоди охолодження використовують експоненційне збільшення затримки: +Для охолодження використовується експоненційне збільшення інтервалу: - 1 хвилина - 5 хвилин @@ -179,12 +179,12 @@ OpenClaw **закріплює вибраний профіль автентифі ## Вимкнення через білінг -Збої через білінг/кредит (наприклад, «недостатньо кредитів» / «занадто низький кредитний баланс») вважаються такими, що допускають резервний перехід, але зазвичай вони не є тимчасовими. Замість короткого періоду охолодження OpenClaw позначає профіль як **вимкнений** (із довшим збільшенням затримки) і переходить до наступного профілю/провайдера. +Збої білінгу/кредитів (наприклад, «недостатньо кредитів» / «занадто низький баланс кредитів») вважаються придатними для резервного перемикання, але зазвичай не є тимчасовими. Замість короткого охолодження OpenClaw позначає профіль як **вимкнений** (із довшим інтервалом відкладення) і переходить до наступного профілю/провайдера. -Не кожна відповідь, схожа на білінгову проблему, має код `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний текст про білінг у білінговій категорії, навіть коли провайдер натомість повертає `401` або `403`, але специфічні для провайдера зіставлення залишаються прив’язаними до провайдера, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`). +Не кожна відповідь, схожа на білінгову, є `402`, і не кожен HTTP `402` потрапляє сюди. OpenClaw зберігає явний білінговий текст у категорії білінгу, навіть коли провайдер натомість повертає `401` або `403`, але специфічні для провайдера відповідності залишаються обмеженими тим провайдером, якому вони належать (наприклад, OpenRouter `403 Key limit exceeded`). -Тим часом тимчасові помилки `402`, пов’язані з вікном використання та лімітами витрат організації/робочого простору, класифікуються як `rate_limit`, коли повідомлення виглядає придатним для повторної спроби (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на шляху короткого охолодження/резервного переходу, а не на шляху тривалого вимкнення через білінг. +Тимчасові помилки `402` вікна використання та лімітів витрат організації/робочого простору класифікуються як `rate_limit`, коли повідомлення виглядає придатним для повторної спроби (наприклад, `weekly usage limit exhausted`, `daily limit reached, resets tomorrow` або `organization spending limit exceeded`). Вони залишаються на шляху короткого охолодження/резервного перемикання, а не довгого вимкнення через білінг. Стан зберігається в `auth-state.json`: @@ -202,18 +202,18 @@ OpenClaw **закріплює вибраний профіль автентифі Типові значення: -- Затримка для білінгу починається з **5 годин**, подвоюється після кожного білінгового збою та обмежується **24 годинами**. -- Лічильники затримки скидаються, якщо профіль не мав збоїв протягом **24 годин** (можна налаштувати). -- Повторні спроби для стану overloaded дозволяють **1 ротацію профілю того самого провайдера** перед резервним переходом моделі. -- Для повторних спроб у стані overloaded типово використовується затримка **0 мс**. +- Відкладення через білінг починається з **5 годин**, подвоюється з кожним збоєм білінгу та обмежується **24 годинами**. +- Лічильники відкладення скидаються, якщо профіль не зазнавав збоїв протягом **24 годин** (можна налаштувати). +- Для перевантажених повторних спроб дозволено **1 чергування профілю того самого провайдера** перед резервним перемиканням моделі. +- Для перевантажених повторних спроб типово використовується відкладення **0 мс**. -## Резервний перехід моделі +## Резервне перемикання моделей -Якщо всі профілі для провайдера завершуються помилкою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це застосовується до помилок автентифікації, обмежень швидкості та тайм-аутів, які вичерпали чергування профілів (інші помилки не переводять до резервного переходу). +Якщо всі профілі для провайдера зазнають збою, OpenClaw переходить до наступної моделі в `agents.defaults.model.fallbacks`. Це застосовується до збоїв автентифікації, обмежень швидкості та тайм-аутів, які вичерпали чергування профілів (інші помилки не просувають резервне перемикання). -Помилки overloaded і rate-limit обробляються агресивніше, ніж періоди охолодження через білінг. Типово OpenClaw дозволяє одну повторну спробу профілю автентифікації того самого провайдера, а потім без очікування перемикається на наступну налаштовану резервну модель. Сигнали зайнятості провайдера, такі як `ModelNotReadyException`, потрапляють до цієї категорії overloaded. Налаштовуйте це через `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`. +Помилки перевантаження та обмеження швидкості обробляються агресивніше, ніж охолодження через білінг. Типово OpenClaw дозволяє одну повторну спробу з профілем автентифікації того самого провайдера, а потім без очікування перемикається на наступну налаштовану резервну модель. Сигнали зайнятості провайдера, як-от `ModelNotReadyException`, потрапляють до цієї категорії перевантаження. Налаштуйте це через `auth.cooldowns.overloadedProfileRotations`, `auth.cooldowns.overloadedBackoffMs` і `auth.cooldowns.rateLimitedProfileRotations`. -Коли запуск починається з перевизначення моделі (hooks або CLI), резервні переходи все одно завершуються на `agents.defaults.model.primary` після спроби будь-яких налаштованих резервних варіантів. +Коли запуск починається з перевизначення моделі (хуки або CLI), резервні варіанти все одно завершуються на `agents.defaults.model.primary` після спроб усіх налаштованих резервних моделей. ### Правила ланцюжка кандидатів @@ -222,95 +222,96 @@ OpenClaw будує список кандидатів із поточного з - Запитана модель завжди стоїть першою. - - Явно налаштовані резервні варіанти проходять дедуплікацію, але не фільтруються списком дозволених моделей. Вони розглядаються як явний намір оператора. - - Якщо поточний запуск уже працює на налаштованому резервному варіанті в тій самій родині провайдерів, OpenClaw продовжує використовувати повний налаштований ланцюжок. - - Якщо поточний запуск використовує іншого провайдера, ніж у конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервних варіантів, OpenClaw не додає не пов’язані налаштовані резервні варіанти від іншого провайдера. - - Коли запуск почався з перевизначення, налаштована основна модель додається в кінець, щоб ланцюжок міг знову повернутися до звичайного типового варіанта після вичерпання попередніх кандидатів. + - Явно налаштовані резервні варіанти дедуплікуються, але не фільтруються за allowlist моделей. Вони розглядаються як явний намір оператора. + - Якщо поточний запуск уже виконується на налаштованій резервній моделі в тій самій сім’ї провайдерів, OpenClaw продовжує використовувати весь налаштований ланцюжок. + - Якщо поточний запуск виконується на іншому провайдері, ніж у конфігурації, і ця поточна модель ще не є частиною налаштованого ланцюжка резервних варіантів, OpenClaw не додає не пов’язані налаштовані резервні варіанти від іншого провайдера. + - Коли запуск почався з перевизначення, налаштована основна модель додається в кінець, щоб ланцюжок міг повернутися до звичайного типового стану після вичерпання попередніх кандидатів. -### Які помилки переводять до резервного переходу +### Які помилки просувають резервне перемикання - + - збоїв автентифікації - - обмежень швидкості та вичерпання періоду охолодження - - помилок overloaded / зайнятості провайдера - - помилок резервного переходу, схожих на тайм-аут - - вимкнень через білінг - - `LiveSessionModelSwitchError`, яка нормалізується до шляху резервного переходу, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб + - обмежень швидкості та вичерпання охолодження + - помилок перевантаження/зайнятості провайдера + - помилок резервного перемикання, схожих на тайм-аут + - вимкнення через білінг + - `LiveSessionModelSwitchError`, яка нормалізується в шлях резервного перемикання, щоб застаріла збережена модель не створювала зовнішній цикл повторних спроб - інших нерозпізнаних помилок, коли ще залишаються кандидати - - - явних переривань, які не схожі на тайм-аут/резервний перехід - - помилок переповнення контексту, які мають залишатися в межах логіки Compaction/повторної спроби (наприклад, `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `The input is too long for the model` або `ollama error: context length exceeded`) - - остаточної невідомої помилки, коли кандидатів більше не залишилося + + - явних переривань, які не схожі на тайм-аут/резервне перемикання + - помилок переповнення контексту, які мають залишатися в межах логіки Compaction/повторних спроб (наприклад, `request_too_large`, `INVALID_ARGUMENT: input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `The input is too long for the model` або `ollama error: context length exceeded`) + - фінальної невідомої помилки, коли кандидатів більше не залишилося -### Пропуск через охолодження проти пробної спроби +### Поведінка пропуску охолодження та пробних спроб Коли всі профілі автентифікації для провайдера вже перебувають у стані охолодження, OpenClaw не пропускає цього провайдера автоматично назавжди. Він ухвалює рішення окремо для кожного кандидата: - - Стійкі збої автентифікації одразу пропускають усього провайдера. - - Вимкнення через білінг зазвичай пропускаються, але основного кандидата все ще можна пробно перевірити з обмеженням, щоб відновлення було можливим без перезапуску. - - Основного кандидата можна пробно перевірити поблизу завершення періоду охолодження, із обмеженням частоти для кожного провайдера. - - Сусідні резервні моделі того самого провайдера можна пробувати попри охолодження, якщо збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо важливо, коли обмеження швидкості прив’язане до моделі, а сусідня модель може відновитися негайно. - - Тимчасові пробні спроби під час охолодження обмежуються однією на провайдера для кожного запуску резервного переходу, щоб один провайдер не затримував резервний перехід між провайдерами. + - Стійкі збої автентифікації негайно пропускають усього провайдера. + - Вимкнення через білінг зазвичай призводять до пропуску, але основного кандидата все ще можна пробувати з тротлінгом, щоб відновлення було можливим без перезапуску. + - Основного кандидата можна пробувати поблизу завершення охолодження з окремим тротлінгом для кожного провайдера. + - Дочірні резервні варіанти того самого провайдера можна пробувати попри охолодження, коли збій виглядає тимчасовим (`rate_limit`, `overloaded` або невідомий). Це особливо актуально, коли обмеження швидкості прив’язане до моделі, а дочірня модель може відновитися негайно. + - Тимчасові пробні спроби під час охолодження обмежуються однією на провайдера за один запуск резервного перемикання, щоб один провайдер не затримував резервне перемикання між провайдерами. -## Перевизначення сеансу та живе перемикання моделі +## Перевизначення сеансу та перемикання моделі в реальному часі -Зміни моделі сеансу — це спільний стан. Активний виконавець, команда `/model`, оновлення Compaction/сеансу та узгодження живого сеансу читають або записують частини одного й того самого запису сеансу. +Зміни моделі сеансу є спільним станом. Активний виконавець, команда `/model`, оновлення Compaction/сеансу та узгодження live-сеансу читають або записують частини того самого запису сеансу. -Це означає, що повторні спроби резервного переходу мають координуватися з живим перемиканням моделі: +Це означає, що повторні спроби резервного перемикання мають узгоджуватися з перемиканням моделі в реальному часі: -- Лише явні зміни моделі, ініційовані користувачем, позначають очікуване живе перемикання. Це включає `/model`, `session_status(model=...)` і `sessions.patch`. -- Зміни моделі, ініційовані системою, як-от чергування резервного переходу, перевизначення Heartbeat або Compaction, ніколи самі по собі не позначають очікуване живе перемикання. -- Перед початком повторної спроби резервного переходу виконавець відповіді зберігає в записі сеансу вибрані поля перевизначення резервного переходу. -- Узгодження живого сеансу надає перевагу збереженим перевизначенням сеансу над застарілими полями моделі в середовищі виконання. -- Якщо спроба резервного переходу завершується помилкою, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату. +- Лише явні зміни моделі, ініційовані користувачем, позначають очікуване live-перемикання. Це включає `/model`, `session_status(model=...)` і `sessions.patch`. +- Зміни моделі, ініційовані системою, як-от чергування резервних варіантів, перевизначення Heartbeat або Compaction, самі по собі ніколи не позначають очікуване live-перемикання. +- Перед початком повторної спроби резервного перемикання виконавець відповіді зберігає в записі сеансу вибрані поля перевизначення резервного варіанта. +- Узгодження live-сеансу віддає перевагу збереженим перевизначенням сеансу над застарілими полями моделі під час виконання. +- Якщо помилка live-перемикання вказує на пізнішого кандидата в активному ланцюжку резервного перемикання, OpenClaw одразу переходить до цієї вибраної моделі замість проходження непов’язаних кандидатів спочатку. +- Якщо спроба резервного перемикання зазнає збою, виконавець відкочує лише ті поля перевизначення, які він записав, і лише якщо вони все ще відповідають цьому невдалому кандидату. -Це запобігає класичній гонці: +Це запобігає типовій гонці станів: - Вибрана основна модель завершується помилкою. + Вибрана основна модель зазнає збою. - - Резервного кандидата вибрано в пам’яті. + + Кандидата резервного варіанта вибрано в пам’яті. Сховище сеансу все ще відображає стару основну модель. - - Узгодження живого сеансу читає застарілий стан сеансу. + + Узгодження live-сеансу читає застарілий стан сеансу. - Повторну спробу повертає до старої моделі ще до початку спроби резервного переходу. + Повторну спробу повертає до старої моделі ще до початку спроби резервного перемикання. -Збережене перевизначення резервного переходу закриває це вікно, а точковий відкат зберігає новіші ручні або робочі зміни сеансу. +Збережене перевизначення резервного варіанта закриває це вікно, а вузький відкат зберігає новіші ручні або runtime-зміни сеансу без змін. ## Спостережуваність і підсумки збоїв -`runWithModelFallback(...)` записує деталі для кожної спроби, які використовуються в журналах і повідомленнях для користувача про охолодження: +`runWithModelFallback(...)` записує деталі кожної спроби, які використовуються в логах і повідомленнях для користувача про охолодження: - провайдер/модель, які було спробовано -- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та подібні причини резервного переходу) +- причина (`rate_limit`, `overloaded`, `billing`, `auth`, `model_not_found` та інші подібні причини резервного перемикання) - необов’язковий статус/код -- зрозумілий людині підсумок помилки +- зрозумілий для людини підсумок помилки -Коли всі кандидати завершуються невдачею, OpenClaw викидає `FallbackSummaryError`. Зовнішній виконавець відповіді може використати це, щоб побудувати конкретніше повідомлення, наприклад «усі моделі тимчасово обмежені за швидкістю», і включити найближчий час завершення охолодження, якщо він відомий. +Коли всі кандидати зазнають збою, OpenClaw викидає `FallbackSummaryError`. Зовнішній виконавець відповіді може використати це, щоб побудувати точніше повідомлення, наприклад «усі моделі тимчасово обмежені за швидкістю», і додати найближчий час завершення охолодження, якщо він відомий. Цей підсумок охолодження враховує модель: -- не пов’язані обмеження швидкості на рівні моделі ігноруються для ланцюжка спроб провайдер/модель -- якщо блокування, що залишилося, — це відповідне обмеження швидкості на рівні моделі, OpenClaw повідомляє останній відповідний час завершення, який усе ще блокує цю модель +- непов’язані обмеження швидкості, прив’язані до інших моделей, ігноруються для ланцюжка спробуваних провайдера/моделі +- якщо блокування, що залишилося, є відповідним обмеженням швидкості, прив’язаним до моделі, OpenClaw повідомляє про останній відповідний час завершення, який усе ще блокує цю модель ## Пов’язана конфігурація @@ -324,4 +325,4 @@ OpenClaw будує список кандидатів із поточного з - `agents.defaults.model.primary` / `agents.defaults.model.fallbacks` - маршрутизації `agents.defaults.imageModel` -Див. [Моделі](/uk/concepts/models) для ширшого огляду вибору моделі та резервного переходу. +Див. [Моделі](/uk/concepts/models), щоб переглянути ширший огляд вибору моделей і резервного перемикання.