Как защитить ключи OpenAI API в системе вопросов и ответов по документам
Практический подход к защите ключей OpenAI API в приложении для вопросов и ответов по документам: разделяйте учетные данные, ограничивайте права доступа, маскируйте данные в журналах и безопасно меняйте ключи, сохраняя ссылки на источники.
Кратко · TL;DR
В приложении для вопросов и ответов по документам храните учетные данные OpenAI на стороне доверенного сервера — в защищенном хранилище секретов, а не в браузере, песочнице, исходном файле или журнале. Предоставляйте каждой рабочей нагрузке только необходимые ей права, маскируйте чувствительные данные в журналах и меняйте учетные данные по документированной процедуре с периодом перекрытия и последующим отзывом старого ключа. Добавляйте к каждому ответу ссылки на источники, чтобы пользователи могли сверить утверждения с найденными документами.
Главное
- Храните ключ OpenAI для приложения вне кода, созданного агентом, и других недоверенных сред выполнения.
- Используйте отдельный проект или границу рабочей нагрузки и предоставляйте приложению только необходимые разрешения API.
- Записывайте в журналы идентификаторы запросов, время выполнения и идентификаторы источников, а не учетные данные, фрагменты документов или полные запросы.
- Добавляйте к ответам идентификаторы документов и ссылки на страницы или разделы; не считайте беглый, хорошо сформулированный ответ доказательством.
- При ротации разверните новый ключ, проверьте трафик, а затем отзовите старый. Если есть подозрение на утечку, отзовите его немедленно.
В этой статье (6)
Система вопросов и ответов по документам должна хорошо справляться с двумя задачами: отвечать на основе нужных материалов и не допускать попадания учетных данных в процесс обработки этих материалов. Самый безопасный вариант по умолчанию — отправлять запросы в OpenAI с доверенного сервера приложения, а поиск документов и обработку ссылок на источники явно включить в собственный рабочий процесс. Не размещайте ключ приложения в браузере, документе, запросе, репозитории с исходным кодом или песочнице, доступной агенту.
Начните с определения границ доверия
Типовой процесс выглядит так: пользователь задает вопрос; приложение находит подходящие фрагменты в авторизованном хранилище документов; сервер отправляет вопрос и выбранные фрагменты в OpenAI; приложение возвращает ответ со ссылками на эти фрагменты. Ключ должен храниться на стороне сервера — в управляемом хранилище секретов или другой защищенной конфигурации, — а не в коде, который передается пользователю, или в рабочей нагрузке, способной просматривать свою среду выполнения.
В рекомендациях OpenAI по безопасности песочниц отмечается, что код, созданный агентом, может получить доступ к файлам, учетным данным и сетевым ресурсам, доступным в его среде. В рекомендациях предлагается изолировать рабочие нагрузки, использовать отдельные среды, если данные не должны передаваться между ними, выделять отдельные проекты OpenAI для приложений или рабочих нагрузок и хранить ключ API приложения за пределами среды. Также рекомендуется не встраивать ключи в образы, исходный код или журналы. См. рекомендации OpenAI по безопасности песочниц.
В системе вопросов и ответов по документам это означает, что загруженные документы и код, созданный моделью, нужно считать недоверенными данными. Рабочая нагрузка для поиска должна получать только те документы и инструменты, которые необходимы для ее задачи. Не предоставляйте ей неограниченный ключ приложения лишь потому, что ей нужно отправить вопрос на обработку.
Ограничивайте разрешения и разделяйте учетные данные
Создайте для этого приложения отдельный проект или выделенную границу учетных данных вместо того, чтобы использовать общий ключ с широкими правами для разных рабочих нагрузок. Установите минимально необходимые разрешения для операций API, которые действительно использует ваша реализация. В упомянутых рекомендациях OpenAI для работы с сессиями указаны api.agents.read и api.agents.write, для обработки запросов — api.responses.write, а для управления хранилищами — api.vaults.read и api.vaults.write. Это примеры для описанных сценариев использования Agents API; не предоставляйте все разрешения по умолчанию. Проверьте, какие разрешения нужны для API, которые вы используете на самом деле.
Если среде выполнения нужно подключаться к OpenAI, в руководстве описывается использование для этого отдельного ключа среды. В нем говорится, что такой ключ позволяет подключать среды, но не дает права выполнять другие действия через API. Храните его отдельно от ключа приложения. Учетные данные сторонних сервисов храните в приложении или у доверенного прокси; не передавайте долгосрочные секреты в среду, где их может прочитать сгенерированный код.
Маскируйте данные в журналах, сохраняя их полезность для работы
Журналы помогают выявлять пустые результаты поиска, неудачные запросы и отсутствие ссылок на источники. Однако полные запросы и документы могут содержать персональную, конфиденциальную или коммерчески чувствительную информацию. Записывайте только то, что необходимо команде для работы сервиса, например:
- Идентификатор запроса, метку времени, статус и задержку.
- Модель и версию приложения, если они нужны для отладки.
- Внутренние идентификаторы документов и ссылки на страницы или разделы вместо полного текста найденных фрагментов.
- Категорию ошибки без чувствительных данных — не заголовки запроса и не значения секретов.
По умолчанию никогда не записывайте заголовки авторизации, ключи API, полные запросы пользователей или целые фрагменты документов. Если для отладки временно нужны сами данные, используйте контролируемый процесс с ограниченным сроком, ограничьте доступ и установите четкую дату удаления. Проверьте также приложение, прокси, системы трассировки и отправки отчетов об ошибках: маскирование в основном журнале приложения не очищает данные автоматически в других точках сбора.
Примерный шаблон журналирования:
log_event(
request_id="generated-request-id",
outcome="success",
retrieved_sources=["policy-17:p4", "handbook-03:section-2"],
credential="[never include]",
prompt="[omit or redact]",
passage_text="[omit or redact]"
)
Это псевдокод, а не проверенный пример для OpenAI SDK. Адаптируйте его к своей системе журналирования и убедитесь, что секреты удаляются до того, как события покинут процесс приложения.
Сделайте ссылки на источники обязательной частью ответа
Не просите модель придумывать ссылки на источники постфактум. Сохраняйте метаданные источников при поиске, связывайте каждый фрагмент с идентификатором документа и страницей, разделом или URL и передавайте эти метаданные на этап генерации ответа. Задайте ожидаемый приложением формат ответа: текст ответа и ссылки только на найденные источники. Затем проверяйте ссылки в коде приложения перед отображением.
Если поиск не вернул подходящих фрагментов, сообщите, что доступные документы не дают ответа, или попросите пользователя уточнить вопрос. Если утверждение в ответе нельзя связать с найденным источником, пометьте его как неподтвержденное или опустите. Ссылка полезна только тогда, когда указанное место существует и содержит подтверждение утверждения. Конкретная реализация поиска и формата ответа зависит от выбранных API; упомянутые здесь рекомендации по безопасности не предписывают конкретную реализацию вопросов и ответов по документам или цитирования.
Определите процедуру ротации учетных данных
Задокументируйте порядок действий до возникновения инцидента. Практическая процедура:
- Определите приложение, проект, запись в хранилище секретов и сервисы, использующие текущие учетные данные.
- Создайте замену с теми же минимально необходимыми правами и сохраните ее в утвержденном хранилище секретов.
- Разверните замену в рамках контролируемого изменения конфигурации. Не выводите ее в журнал при развертывании и не помещайте в артефакты сборки.
- Отправьте тестовый вопрос через обычный рабочий процесс. Убедитесь, что обработка запроса проходит успешно, ссылки на источники по-прежнему открываются, а журналы не содержат секретов или текста документов.
- Следите за ошибками, а после подтверждения, что используется новая учетная запись, отзовите старую. Удалите устаревшие копии из систем развертывания и локальных сред разработки.
- Если есть подозрение на утечку, немедленно отзовите затронутые учетные данные, проверьте доступ и журналы, а затем выпустите замену. Не ждите плановой ротации.
В рекомендациях OpenAI говорится, что ключи следует менять или отзывать при необходимости, а при подозрении на утечку учетные данные нужно отозвать немедленно. Организация должна установить собственный интервал ротации с учетом рисков, внутренних правил и эксплуатационных ограничений; в упомянутом источнике универсальный график не приводится.
Контрольный список перед запуском
- Ключ приложения хранится на сервере и недоступен браузерам и коду, созданному агентом.
- Рабочая нагрузка надлежащим образом изолирована; при необходимости используется отдельный проект или среда.
- Разрешения ограничены операциями, необходимыми приложению.
- В журналах нет ключей, заголовков авторизации, исходных запросов и полных найденных фрагментов.
- Ответы содержат проверенные ссылки на найденные документы.
- Назначен ответственный, который может развернуть новый ключ и отозвать старый.
Основной принцип прост: храните учетные данные за пределами среды обработки документов и обеспечивайте возможность отследить ссылки на найденные источники. Это снижает последствия компрометации рабочей нагрузки и позволяет пользователям проверить, на чем основан ответ.
Вопросы
Можно ли поместить ключ OpenAI API в браузерное приложение для вопросов и ответов по документам?
Не раскрывайте ключ приложения в коде браузера. Отправляйте запросы в OpenAI с доверенного серверного компонента, который получает ключ из защищенной конфигурации или менеджера секретов.
Нужно ли записывать запросы и найденные фрагменты документов в журнал, чтобы отлаживать ответы?
По умолчанию этого делать не следует. Вместо этого записывайте идентификаторы запросов, статусы, время выполнения и идентификаторы источников. Если для отладки временно необходимы сами данные, ограничьте доступ, установите срок удаления и убедитесь, что учетные данные не попадут в журнал.
Как часто нужно менять ключи OpenAI API?
В упомянутых рекомендациях OpenAI по безопасности говорится, что ключи следует менять или отзывать при необходимости, но универсальный интервал не указан. Установите график с учетом рисков и правил организации и немедленно отзывайте ключ при подозрении на утечку.
Как сделать ссылки на источники в ответах по документам надежными?
Передавайте идентификаторы документов и метаданные страниц, разделов или URL через этап поиска, разрешайте ссылки только на найденные источники и проверяйте каждую ссылку перед отображением. Не полагайтесь на то, что модель самостоятельно придумает ссылки на источники.
Похожие статьи
Guides
Как диагностировать сбои OpenAI API при ответах на вопросы по документам
Практическое руководство по устранению ошибок аутентификации, ограничений частоты запросов, тайм-аутов и некорректных ответов со ссылками на источники.
Guides
Расчёт стоимости Kimi K3.1 Pro Highspeed для вопросов по документам
Воспроизводимый расчёт стоимости ответов на вопросы по документам с Kimi K3.1 Pro Highspeed: официальные цены и цены OneMux, допущения по кэшированию и арифметика расчёта нагрузки.
Guides
Как защитить ключи OpenAI API при сортировке обращений в поддержку
Практическая схема безопасного использования OpenAI для сортировки обращений: защита ключей API, редактирование журналов, ограничение прав, ротация учетных данных и обязательное одобрение действий человеком.
Guides
Оценка стоимости API Qwen3.8 Flash для ответов на вопросы по документам
Воспроизводимый способ оценить стоимость Qwen3.8 Flash для ответов на вопросы по документам с указанием источников: явные допущения по токенам и опубликованные цены OneMux.