Как диагностировать сбои OpenAI API, не раскрывая учетные данные
Практическое руководство по диагностике сбоев OpenAI API: полезные сигналы, защита API-ключей, ограничение разрешений и планирование ротации учетных данных.
Кратко · TL;DR
Если запрос к OpenAI API завершается ошибкой, сохраните достаточно данных для диагностики, не записывая секреты или конфиденциальную информацию. Разделяйте учетные данные по назначению, ограничивайте места их использования и заранее отработайте процедуру ротации.
Главное
- Записывайте результаты запросов и безопасные идентификаторы, но не API-ключи, заголовки авторизации или полные запросы и ответы.
- Используйте отдельные учетные данные для разных задач и предоставляйте рабочей нагрузке только необходимые разрешения.
- Рассматривайте статус, категорию ошибки, время выполнения и идентификаторы запросов как диагностические сигналы, а не как повод раскрывать содержимое запросов.
- Рабочий план ротации включает создание замены, развертывание, проверку и отзыв старых учетных данных.
В этой статье (5)
Диагностировать инцидент OpenAI API проще, если в логах сохраняются рабочие данные, но не учетные данные и лишняя информация о клиентах. Начните с сигнала сбоя — например, статуса, отличного от успешного, тайм-аута или исключения приложения, — а затем сопоставьте его с идентификатором запроса и затронутым развертыванием. Не допускайте, чтобы API-ключ был доступен в среде, где его может прочитать недоверенный или сгенерированный агентом код.
Создайте безопасную запись для диагностики
Для каждой попытки обращения к API фиксируйте только то, что нужно, чтобы ответить на четыре вопроса: когда произошел сбой, какая рабочая нагрузка отправила запрос, какого рода ошибка возникла и можно ли сопоставить событие с данными на стороне провайдера?
Полезная запись может включать временную метку, ваш непрозрачный идентификатор операции, категорию конечной точки, HTTP-статус, время выполнения, число повторных попыток и идентификатор запроса провайдера, если он возвращается. Вместо вывода объекта исключения целиком записывайте его класс или очищенную от чувствительных данных категорию ошибки: некоторые библиотеки включают сведения о запросе в текст исключения. По умолчанию не помещайте в обычные логи запросы, ответы, заголовки авторизации и исходные тела запросов или ответов, если только проверенная процедура не подтверждает конкретную необходимость и не предусматривает надлежащие меры защиты.
Приведенный ниже код на Python — иллюстративный пример, а не проверенная интеграция. Функция получения секрета и обработка ответа зависят от вашего приложения и SDK. В этом примере намеренно не записываются в логи тело запроса и учетные данные.
import logging
import time
import uuid
logger = logging.getLogger(__name__)
def send_request(client, payload):
operation_id = str(uuid.uuid4())
started = time.monotonic()
try:
result = client.responses.create(**payload)
logger.info(
"openai_request_succeeded",
extra={
"operation_id": operation_id,
"elapsed_ms": round((time.monotonic() - started) * 1000),
"provider_request_id": getattr(result, "_request_id", None),
},
)
return result
except Exception as exc:
# Do not log str(exc), request headers, or payload here.
logger.error(
"openai_request_failed",
extra={
"operation_id": operation_id,
"elapsed_ms": round((time.monotonic() - started) * 1000),
"exception_type": type(exc).__name__,
},
)
raise
Прежде чем использовать этот подход, выясните, как ваш клиент предоставляет идентификаторы запросов и могут ли сообщения об исключениях содержать конфиденциальные данные. Применяйте те же правила редактирования в трассировке, отчетах об ошибках, логах прокси и пакетах данных для поддержки: одной очистки логов приложения недостаточно.
Используйте сигналы сбоев, чтобы сузить круг причин
Код статуса или исключение — это подсказка, а не полный диагноз. Резкий рост ошибок аутентификации после развертывания может указывать на отсутствующие, недействительные или неправильно переданные учетные данные. Увеличение числа ответов об ограничении частоты запросов может говорить об изменении их объема или параллельности. Тайм-ауты могут быть связаны с доступом к сети, задержкой на стороне вышестоящего сервиса или слишком коротким тайм-аутом клиента. Если провайдер успешно обработал запрос, но пользовательский запрос завершился ошибкой, причина может быть в разборе данных на стороне приложения или в последующей системе.
Сравните частоту сбоев и задержки до и после развертывания, а также разделите результаты по рабочей нагрузке или среде. Не группируйте данные по значениям секретов и не записывайте их в логи, чтобы «проверить», используют ли две системы один ключ. Если нужно выяснить, какие учетные данные использует сервис, проверьте ссылку на секрет в менеджере секретов и конфигурацию развертывания через авторизованный канал.
Разделяйте учетные данные и ограничивайте их применение
В рекомендациях OpenAI по безопасности песочниц советуют использовать изолированные вычислительные среды, отдельные среды для рабочих нагрузок, которые не должны обмениваться данными, и выделенный проект OpenAI для приложения или рабочей нагрузки. В рекомендациях также различаются ключ API приложения и ключ среды исполнителя: последний предназначен для подключения сред и не дает разрешения на другие действия API. В рекомендациях перечислены отдельные разрешения для сеансов Agents API, инференса и управления хранилищем секретов; предоставляйте рабочей нагрузке только необходимые разрешения. См. рекомендации OpenAI по безопасности песочниц.
Храните ключ приложения вне среды, где его может прочитать сгенерированный агентом код. Не встраивайте ключи в исходный код, образы контейнеров или логи. Для учетных данных сторонних сервисов в рекомендациях советуют хранить секреты вне среды и передавать их с помощью доверенного механизма, например через прокси или хранилище секретов, если это применимо. Секрет, внедренный в среду, по-прежнему доступен выполняющемуся там коду, поэтому само внедрение не делает его недоступным.
Определите процедуру ротации учетных данных
Заранее запишите и отработайте следующие шаги:
- Подготовка: определите владельца учетных данных, их разрешения, использующие их сервисы и расположение в менеджере секретов. Уточните, кто может создавать, развертывать и отзывать учетные данные.
- Замена: создайте новые учетные данные с минимально необходимыми разрешениями. Сохраните их в утвержденном менеджере секретов, а не в задаче, чате или репозитории исходного кода.
- Развертывание: обновите соответствующую рабочую нагрузку в рамках обычного процесса выпуска. Если допустим период параллельного использования, сохраняйте старые учетные данные только на минимальное время, необходимое для проверки.
- Проверка: выполните запрос с низким уровнем риска и проверьте успешность, частоту сбоев и логи. Убедитесь, что ни один сервис больше не зависит от старых учетных данных.
- Отзыв и проверка: отзовите старые учетные данные. Если есть подозрение на утечку, в первую очередь отзовите их и проверьте затронутые рабочие нагрузки и логи, не дожидаясь плановой даты ротации.
Если сразу после ротации запросы начинают завершаться ошибкой, проверьте, получил ли сервис новые секреты, перезапустился ли он или обновил доступ к секретам, а также есть ли у новых учетных данных нужные разрешения. Не устраняйте ошибку с разрешениями, предоставляя широкий доступ, пока не подтвердите, какое именно действие требуется.
Краткий список проверки при инциденте
- Ограничен ли сбой одной рабочей нагрузкой, средой или выпуском?
- Видна ли закономерность по статусам, задержкам, числу повторных попыток и безопасным идентификаторам запросов?
- Не содержат ли логи заголовков авторизации, ключей и лишнего содержимого запросов или ответов?
- Хранятся ли учетные данные и передаются ли они по утвержденному каналу управления секретами?
- Можно ли заменить и отозвать учетные данные, не меняя несвязанные с ними сервисы?
Задача не в том, чтобы записывать всё подряд. Нужно сохранить достаточно безопасных данных, чтобы отличить проблемы с учетными данными, трафиком, сетью и приложением, а при подозрении на утечку быстро выполнить ротацию.
Вопросы
Что записывать в логи, если запрос к OpenAI API завершился ошибкой?
Записывайте временную метку, ваш непрозрачный идентификатор операции, категорию конечной точки, HTTP-статус или очищенную от чувствительных данных категорию ошибки, время выполнения, число повторных попыток и идентификатор запроса провайдера, если он доступен. По умолчанию не записывайте API-ключи, заголовки авторизации и полные тела запросов и ответов.
Должен ли сгенерированный агентом код иметь доступ к API-ключу?
Не предоставляйте ключ API приложения коду, которому он не нужен. В рекомендациях OpenAI по безопасности песочниц говорится, что ключ приложения следует хранить вне среды, а также поясняется, что сгенерированный агентом код может получить доступ к файлам и учетным данным, доступным в его среде.
Когда нужно ротировать или отзывать ключ OpenAI API?
Выполняйте ротацию учетных данных по установленному графику и немедленно отзывайте их при подозрении на утечку. Полная процедура включает создание замены, развертывание, проверку и отзыв старых учетных данных.
Почему запрос может завершиться ошибкой после ротации учетных данных?
Рабочая нагрузка может по-прежнему использовать закэшированный или старый секрет, не обновить конфигурацию либо новые учетные данные могут не иметь нужного разрешения. Проверьте развернутую ссылку на секрет и требуемые разрешения, не записывая сами учетные данные в логи.
Похожие статьи
Guides
Как защитить ключи OpenAI API при сортировке обращений в поддержку
Практическая схема безопасного использования OpenAI для сортировки обращений: защита ключей API, редактирование журналов, ограничение прав, ротация учетных данных и обязательное одобрение действий человеком.
Guides
Как защитить ключи OpenAI API в системе вопросов и ответов по документам
Практический подход к защите ключей OpenAI API в приложении для вопросов и ответов по документам: разделяйте учетные данные, ограничивайте права доступа, маскируйте данные в журналах и безопасно меняйте ключи, сохраняя ссылки на источники.
Guides
Как безопасно диагностировать ошибки аутентификации, лимитов запросов, тайм-аутов и некорректных ответов OpenAI API
Практическое руководство с учетом конфиденциальности: как диагностировать ошибки аутентификации, ограничения частоты запросов, тайм-ауты и некорректные ответы OpenAI API, не раскрывая учетные данные и данные пользователей.
Guides
Стоимость API Claude Fable 5.2 для диагностики инцидентов: воспроизводимый расчёт
Оцените стоимость API Claude Fable 5.2 для диагностики инцидентов с помощью явно заданного объёма токенов, сценариев повторных запросов и наблюдаемых сигналов сбоев.