Коротко

Простое Flask-приложение принимает запрос на одном эндпоинте, обращается к API и возвращает ответ. Ключ хранится в переменной окружения, а не в коде.

Когда вы освоили простой запрос, логичный шаг это маленькое веб-приложение. Flask хорошо для этого подходит. Здесь мы покажем структуру, один эндпоинт, безопасное хранение ключа и частые ошибки. Если вы ещё не пробовали код, начните с наших примеров на Python.

Структура приложения

Маленькому приложению хватит нескольких файлов. Это главный файл с кодом, файл с зависимостями и файл .env для секретов.

Главное правило: код отдельно, секреты отдельно. Файл .env не должен попадать в репозиторий, поэтому его сразу добавляют в .gitignore.

  • app.py с кодом приложения.
  • requirements.txt со списком библиотек.
  • .env с ключом, вне репозитория.

Один эндпоинт

Достаточно одного маршрута, например /ask. Он принимает текст от пользователя, отправляет его в API и возвращает ответ. Условно это выглядит так как обычный текст:

from flask import Flask, request

app = Flask(_name_)

@app.route("/ask", methods=["POST"])

def ask(): text = request.json.get("text"); return call_model(text)

Точные методы вызова модели смотрите в документации, они могут меняться. Здесь показана только идея маршрута.

  • Маршрут принимает текст вопроса.
  • Функция шлёт запрос в API.
  • Ответ возвращается пользователю.

Что такое эндпоинт

Эндпоинт это адрес внутри приложения, который принимает запросы. Для начала хватит одного, например /ask, и его легко расширить позже.

Безопасность ключа

Ключ читается из окружения. Безопасный пример как обычный текст:

import os

apikey = os.environ.get("OPENAIAPI_KEY")

В коде остаётся только имя переменной, не сам ключ. Это те же правила, что в материале про безопасное хранение ключа. Никогда не печатайте ключ в ответе или в логах.

Защита приложения

Проверяйте входные данные и не доверяйте им слепо. Ограничьте длину текста, чтобы не было лишних расходов, об этом в материале про оценку стоимости запросов.

Если приложение принимает вебхуки, проверяйте подпись каждого входящего сообщения, как описано в материале про основы вебхуков. Общий обзор и связанные материалы есть в разделе про API.

Ограничьте длину текста

Слишком длинный ввод стоит дороже и грузит модель. Поставьте простой предел на число символов, и расходы станут предсказуемее.

Не отдавайте секреты пользователю

Ответ пользователю не должен содержать ключ или внутренние данные. Любой секрет в ответе виден всем, кто шлёт запрос.

Совет. При ошибке возвращайте короткое понятное сообщение без технических деталей. Так вы не покажете секреты случайно.

Шаги запуска

Чтобы приложение заработало, идите по порядку. Сначала окружение и зависимости, потом ключ, потом сам запуск и проверка.

После первого успешного ответа добавьте проверку входных данных и обработку ошибок. Так приложение будет вести себя предсказуемо даже при сбоях сети и не покажет пользователю непонятную ошибку вместо результата.

  1. Создайте файлы app.py, requirements.txt и .env.
  2. Установите зависимости из requirements.txt.
  3. Задайте ключ в переменной окружения.
  4. Запустите приложение и откройте эндпоинт /ask.
  5. Проверьте ответ и добавьте обработку ошибок.

Как не наступить на грабли

Частая ошибка это ключ прямо в app.py, который потом уходит в репозиторий. Опасно и возвращать ключ или секрет в ответе пользователю, ведь так он становится виден всем.

Многие забывают проверять входной текст и ограничивать его длину, из за чего растут расходы. Чтобы этого избежать, держите ключ в окружении, никогда не отдавайте секреты в ответе и всегда проверяйте ввод. Тогда приложение будет и безопаснее, и дешевле в работе.

  • Не храните ключ прямо в app.py.
  • Не возвращайте ключ или секрет в ответе.
  • Не пропускайте проверку входного текста.
  • Не оставляйте длину запроса без ограничения.

Файлы простого приложения

ФайлЗачем нужен
app.py Код приложения и эндпоинт
requirements.txt Список нужных библиотек
.env Секреты, вне репозитория
.gitignore Чтобы .env не попал в git

Доля работы по частям (простая иллюстрация)

Это простая иллюстрация распределения сил, а не реальный замер.

Как работает запрос в приложении

Простой процесс от пользователя до ответа.

Чеклист

  • Создать простую структуру файлов.
  • Сделать один эндпоинт для запроса.
  • Читать ключ из переменной окружения.
  • Проверять входные данные пользователя.
  • Добавить .env в gitignore.
  • Ограничить длину входного текста.
  • Добавить обработку ошибок и сбоев сети.

Частые ошибки

  • Хранить ключ прямо в app.py.
  • Возвращать ключ или секрет в ответе.
  • Не проверять входной текст.
  • Не ограничивать длину запроса.
  • Печатать ключ в логах при отладке.

Частые вопросы

Flask простой и подходит для маленьких приложений. На нём легко сделать один эндпоинт и подключить API.

В переменной окружения или в файле .env вне репозитория. В коде остаётся только имя переменной, не сам ключ.

Да. Проверяйте и ограничивайте текст пользователя, чтобы избежать ошибок и лишних расходов.

Ограничьте длину входного текста и ответа, кэшируйте повторяющиеся запросы и следите за числом обращений.

Да, добавьте отдельный маршрут и проверяйте подпись каждого входящего сообщения, как в материале про вебхуки.

Понятное сообщение без секретов внутри. Никогда не отдавайте пользователю ключ или внутренние данные приложения.

Источники

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