Skip to content

BYOK_DOCUMENTATION.md

Latest commit

 

History

History
261 lines (178 loc) · 9.61 KB

BYOK_DOCUMENTATION.md

File metadata and controls

261 lines (178 loc) · 9.61 KB

🔑 AI Tutor - BYOK (Bring Your Own API Key)

Описание

Полностью автономное Streamlit-приложение с поддержкой BYOK (Bring Your Own API Key) для работы с моделями OpenAI GPT. Пользователь вводит свой собственный API ключ, который хранится только в памяти сессии (без записи в файлы).

Основные возможности

1. 🔐 Безопасное управление API ключом

  • Ввод ключа через защищённое поле (password input)
  • Хранение только в st.session_state (без записи на диск)
  • Кнопка "Сохранить ключ" с уведомлением "✅ Ключ сохранён. Можно работать."
  • Кнопка "Очистить ключ" для удаления из сессии
  • Предупреждение при отсутствии ключа (блокирует работу с моделью)

2. 🎛️ Настройки модели

  • Выбор модели:
    • gpt-4o
    • gpt-4-turbo
    • gpt-4o-mini
    • gpt-3.5-turbo
  • Настройка температуры:
    • Слайдер от 0.0 до 1.0 (шаг 0.1)
    • 0.0 = детерминированные ответы
    • 1.0 = максимальная креативность

3. 💬 Управление чатами

  • Создание новых чатов (кнопка "🆕 Новый чат")
  • Переключение между чатами
  • Удаление чатов с подтверждением
  • Автоматическая нумерация ("Новый чат 1", "Новый чат 2", ...)
  • Счётчик сообщений для каждого чата

4. 🎨 Интерфейс

  • Минималистичный тёмный дизайн
  • Анимированный индикатор "🤖 Печатает..."
  • Временные метки для каждого сообщения
  • Expander "Настройки API" для компактности
  • Адаптивная вёрстка (responsive design)

Структура кода

Основные функции

Инициализация

init_session_state()

Инициализирует переменные состояния сессии:

  • api_key - OpenAI API ключ
  • model - Выбранная модель
  • temperature - Температура генерации
  • chats - Словарь всех чатов
  • current_chat_id - ID активного чата

Управление чатами

create_new_chat() -> str

Создаёт новый чат и возвращает его ID.

switch_chat(chat_id: str)

Переключает активный чат.

delete_chat(chat_id: str)

Удаляет чат по ID. Если удаляется активный чат, автоматически переключается на другой.

get_current_chat() -> Dict

Возвращает данные текущего активного чата.

add_message(role: str, content: str)

Добавляет сообщение в историю текущего чата.

Взаимодействие с API

call_openai_api(messages: List[Dict], api_key: str) -> Optional[str]

Вызывает OpenAI API для получения ответа от модели. Использует:

  • Модель из st.session_state.model
  • Температуру из st.session_state.temperature
  • API ключ, переданный как параметр

Отображение UI

display_message(role: str, content: str, timestamp: datetime)

Отображает сообщение в чате с временной меткой.

show_typing_indicator(placeholder, duration: float = 1.5)

Показывает анимированный индикатор "🤖 Печатает...".

Примерный UX (User Experience)

Шаг 1: Первый запуск

  1. Пользователь открывает приложение
  2. Видит предупреждение: "⚠️ API ключ не введён"
  3. Открывает expander "🔑 Настройки API" в sidebar
  4. Вводит свой OpenAI API ключ в поле (скрыто как пароль)
  5. Нажимает "💾 Сохранить ключ"
  6. Видит уведомление: "✅ Ключ сохранён. Можно работать."

Шаг 2: Настройка модели

  1. В том же expander выбирает модель (например, gpt-4o-mini)
  2. Настраивает температуру (например, 0.7)
  3. Видит текущие настройки: "gpt-4o-mini, температура 0.7"

Шаг 3: Работа с чатом

  1. Вводит запрос в поле "Введите ваше сообщение..."
  2. Видит анимированный индикатор "🤖 Печатает..."
  3. Получает ответ от модели с временной меткой

Шаг 4: Управление чатами

  1. Создаёт новый чат кнопкой "🆕 Новый чат"
  2. Переключается между чатами в sidebar
  3. Удаляет ненужные чаты (с подтверждением)

Шаг 5: Завершение работы

  1. Нажимает "🗑️ Очистить ключ"
  2. API ключ удаляется из памяти
  3. При следующем запуске нужно ввести ключ заново

Безопасность

✅ Реализовано

  • API ключ хранится только в st.session_state
  • Не записывается в файлы, логи или базы данных
  • Поле ввода ключа имеет тип password (символы скрыты)
  • Ключ удаляется при закрытии браузера/вкладки

⚠️ Важные замечания

  • Ключ хранится только в рамках одной сессии браузера
  • При обновлении страницы ключ будет потерян
  • Пользователь должен хранить свой ключ в безопасном месте
  • Не используйте это приложение на общедоступных компьютерах

Запуск приложения

Требования

pip install streamlit openai

Команда запуска

streamlit run app_byok.py

Открытие в браузере

После запуска приложение откроется автоматически:

Комментарии в коде

Весь код содержит подробные комментарии на русском языке, объясняющие:

  • Назначение каждой функции
  • Параметры и возвращаемые значения
  • Логику работы сложных участков
  • Структуру данных

Преимущества BYOK

Для пользователя

✅ Полный контроль над API ключом
✅ Использование собственной квоты OpenAI
✅ Прозрачность расходов (отслеживание в личном кабинете OpenAI)
✅ Безопасность (ключ не хранится на сервере)

Для разработчика

✅ Не нужно платить за API вызовы пользователей
✅ Простота развёртывания (не требуется backend)
✅ Масштабируемость (каждый пользователь использует свой ключ)
✅ Юридическая чистота (пользователь сам отвечает за использование API)

Возможные улучшения

Функциональность

  • Экспорт чата в TXT/JSON
  • Импорт истории чата
  • Переименование чатов
  • Быстрые промпты (шаблоны)
  • Правила общения (system prompt)
  • Счётчик токенов

UI/UX

  • Светлая тема (переключатель)
  • Настройка размера шрифта
  • Подсветка кода в ответах
  • Копирование сообщений в буфер обмена
  • Markdown preview для ввода

Безопасность

  • Валидация формата API ключа
  • Проверка квоты перед запросом
  • Ограничение размера истории
  • Таймаут для длительных запросов

Лицензия

Свободное использование. Код предоставлен "как есть" (AS IS).

Поддержка

При возникновении проблем:

  1. Проверьте корректность API ключа
  2. Убедитесь, что у вас есть доступ к выбранной модели
  3. Проверьте баланс на аккаунте OpenAI
  4. Перезагрузите страницу и введите ключ заново

Версия: 1.0.0
Дата: 5 октября 2025
Автор: AI Tutor Team