Совместимость задаёт форму, контракт — поведение
Общий формат запроса и ответа уменьшает объём изменений в приложении и облегчает смену модели или поставщика. Доступ можно собрать за одним интерфейсом. Но совпадение полей не отвечает на вопросы: был ли принят запрос, кто его исполнил, когда допустим повтор, как оценивать неполный ответ и как сверять итоговое потребление. Как только люди полагаются на систему, эти вопросы становятся частью её контракта.
Шлюзу нужны явные границы проверки входа, допуска и правил, выбора маршрута, выполнения, классификации результата и подтверждения потребления. Это обязанности архитектуры, а не утверждение, что все шлюзы реализуют их одинаково. Успешный обмен HTTP не доказывает завершение работы. И наоборот, клиент может потерять ответ после того, как поставщик уже выполнил запрос. Общая метка «ошибка» скрывает выбор, который предстоит сделать оператору.
Поток — последовательность свидетельств, а не единый ответ
Потоковая передача позволяет показывать текст до окончания генерации. Например, документированный HTTP-поток OpenAI использует серверные события и отделяет фрагменты вывода от события завершения. Приложение может показать полезное начало, ещё не зная, готов ли ответ. Если после двух абзацев соединение прервалось по тайм-ауту, видимый текст не доказывает, что операция завершилась. [2]
Шлюз должен сохранить известные факты: идентификатор запроса, выбранный маршрут, факт приёма поставщиком, наблюдавшиеся события и подтверждение завершения либо его отсутствие. Видимый фрагмент нужно отличать от окончательного результата. Это архитектурная рекомендация, а не обещание, что каждый поставщик умеет возобновлять поток. Система может показать неполный ответ, предложить новое решение о попытке или проверить запись у поставщика, если такая возможность есть. Неопределённость следует назвать, а не незаметно превратить в успех или неудачу.
Перед повтором нужно учесть риск двойной работы
Рассмотрим исключительно условный запрос на подготовку текста. Поставщик начал поток, приложение получило два абзаца, затем соединение оборвалось. Поставщик мог продолжить генерацию и начислить плату за уже сделанное. Немедленный повтор того же запроса способен породить вторую генерацию и вторые расходы, даже если пользователю покажут только один ответ. Тайм-аут не доказывает, что первой попытки не было. Документация OpenAI по Chat Completions также предупреждает: при обрыве потока заключительный блок с полным потреблением может не прийти. [3]
Семантика HTTP уточняет правило: клиент не должен автоматически повторять неидемпотентный запрос, если не знает, что операция фактически идемпотентна, или что первый запрос не был применён; прокси не должен повторять такие запросы. Генерация обычно вызывается через POST, поэтому знакомая форма API не делает повтор безопасным. [1] Политика может разрешать повтор до отправки, применять поддерживаемый поставщиком механизм идемпотентности либо требовать явной новой попытки после неоднозначного потока. Компромисс — скорость и удобство против дублирования и неопределённых затрат.
Сначала решить, допустимо ли выполнение, затем — где
Маршрутизация выбирает место выполнения допустимого запроса. Правила определяют, можно ли выполнять запрос и при каких ограничениях. Задача может задавать тип данных, длину контекста, регион, список разрешённых поставщиков, доступ к инструментам или предел расходов. Если основной поставщик недоступен, запасной маршрут полезен лишь при соблюдении тех же условий. Незаметный переход на неподходящий маршрут меняет договорённость с приложением.
Условная последовательность такова: проверить запрос → оценить правила и бюджет → выбрать допустимый маршрут → выполнить в пределах срока → определить исход → записать наблюдаемое потребление → передать событие расчётов в собственную систему соответствующего продукта. Это схема архитектуры, а не описание выпущенных внутренних функций RouterShift. Выбор маршрута, обработка отказа и расчёты должны объясняться отдельно. Детерминированные правила проще проверить; адаптивный выбор полезен при надёжной обратной связи, но требует объяснения конкретного решения.
Сначала измерить известное, потом рассчитывать деньги
Запрос, попытка выполнения и окончательная запись поставщика о потреблении — разные факты. При обрыве потока итоговое значение может быть неизвестно; оценку по видимому тексту нельзя выдавать за окончательную сумму. Следует хранить исходную запись, идентификатор попытки и основание оценки. Когда поступит авторитетная информация, её можно сверить; исправления должны оставлять след. [3]
Действующие соглашения OpenTelemetry для генеративного ИИ задают названия для входных и выходных токенов, модели, поставщика и класса ошибки. Это словарь для телеметрии, а не система расчётов и не гарантия одинаковых единиц у всех поставщиков. Документ также предупреждает о чувствительных данных в содержимом сообщений. [4] Цена и движение средств следуют после измерения и требуют валюты, версии тарифа и следа проверки. Для изображений, аудио и видео одних токенов может быть недостаточно.
Сделать контракт видимым в обычной эксплуатации
При инциденте команде нужно узнать: какой запрос затронут, какой маршрут выбран и почему, принял ли поставщик работу, полон ли вывод, какие данные о потреблении подтверждены, оценены или неизвестны, какие версии правил и цен действовали. Идентификаторы запроса и попытки, состояния результата и ссылки на трассировки помогают отвечать без записи текста запросов по умолчанию. Интерфейс должен быть понятен эксплуатирующей команде, а не только разработчикам.
Эти вопросы позволяют проверять обещания шлюза. При отказе до отправки возможен другой допустимый маршрут. Если поток оборвался после начала работы, система должна назвать результат неполным либо неопределённым и объяснить дальнейший выбор. Если нет данных о потреблении, их следует дождаться или сверить. Совместимость снижает порог подключения; рабочий контракт делает поведение предсказуемым вне идеального сценария. RouterShift — действующий продукт SlateMoth для доступа к моделям. Здесь изложена задача проектирования, а не утверждение, что каждый описанный механизм уже реализован в RouterShift.