2026-10-20

Трассировка каждой попытки запроса AI API

Руководство для production: Трассировка каждой попытки запроса AI API. Включает детерминированный артефакт, границы отказа, контроль rollout и проверенные источники.

Сначала решение

Трассировка каждой попытки запроса AI API — явный production-контракт, а не отдельное изменение. До переноса трафика задайте успех, конечный отказ и rollback; артефакт отделяет доказательства от предположений.

Начните с request, детерминированно докажите attempt и сделайте privacy обязательным release-gate.

Повторно используемый артефакт

Строка считается пройденной, только если доказательство относится к тому же запросу, окну теста или версии конфигурации.

Контрольная точка	Доказательство	Условие прохождения
`request`	`request_id,tenant_pseudonym,operation,accepted_at`	Запись связывает логический запрос и конкретную попытку.
`attempt`	`attempt_number,route_version,model,channel_pseudonym`	Запись связывает логический запрос и конкретную попытку.
`timing`	`connect,headers,first_event,first_output,idle,total`	Значение точно сохраняется и сравнивается на wire-границе.
`terminal`	`HTTP,provider_class,cancellation_source,retry_decision`	Owner, источник, дата и ограничение записаны.
`usage`	`normalized_input/output/cache_categories_and_provenance`	Резерв, наблюдение и итог сходятся в долговечном ledger.
`privacy`	`allowlisted_attributes_only;no_prompt,secret,or_raw_arguments`	Предел явный, превышение закрывает операцию.

Разобранный пример

Пример синтетический и детерминированный. Подставьте проверенные параметры своей нагрузки; не используйте секреты или данные клиентов.

trace_id: 7f3a...synthetic
request_id: req_demo_001
operation: responses
attempts:
  - attempt: 1
    route_version: rv_42
    model: model_alias
    timings_ms: { headers: 812, first_output: 1240, total: 3100 }
    terminal: upstream_503
  - attempt: 2
    timings_ms: { headers: 620, first_output: 980, total: 2400 }
    terminal: success
usage: { input: 1800, output: 220, source: provider_normalized }

Порядок внедрения

Зафиксировать текущие запрос, ответ, конфигурацию и наблюдаемую базовую линию.
Выполнить детерминированный положительный сценарий и сохранить полный результат.
Выполнить парный отрицательный или предельный сценарий.
Связать попытки одним логическим request ID и записать время, конечное состояние и usage без чувствительного содержимого.
Раскатывать на ограниченную когорту с условиями остановки.
Повторно прочитать долговечное состояние и публичное поведение; при нарушении инварианта выполнить rollback.

Режимы отказа

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

Промпты, ключи или чувствительные аргументы попадают в телеметрию.
Фрагменты связываются по позиции, а не стабильному ID.
Читается одно удобное поле, а типизированные outputs, tools, отказы или частичные результаты теряются.
Процентили публикуются без нагрузки, параллелизма, ошибок, региона и окна.

Граница Modelflare

Modelflare централизует OpenAI-совместимый routing, ключи, группы, usage и ошибки, но настроенный маршрут не доказывает опциональные возможности провайдера. Проверяйте модель и канал нативным протоколом, сохраняйте явные нули и считайте истиной billing только долговечный расчет.

Общая граница решения описана в родительском руководстве, текущая настройка — в документации.

Проверка перед публикацией

Сначала ответить на главный вопрос.
Назначить owner каждому полю, состоянию, метрике и формуле.
Использовать только синтетические идентификаторы.
Сохранить структуру, код, лимиты и предупреждения во всех языках.
На T-1 перепроверить контракты, поддержку и цены; при изменении перенести дату.
До срока исключить страницу из public API, маршрутов и sitemap.

Источники и дата проверки

Источники проверены 2026-08-07; они не доказывают непроверенный маршрут.