FastAPI Boilerplate

Шаблон FastAPI приложения для анализа сентимента текста.

Quick Start

# Установить Just (command runner)
# macOS
brew install just

# vscode plugin https://github.com/nefrob/vscode-just

# Посмотреть доступные команды
just

# Создать venv и установить зависимости
just setup

# Запустить dev сервер
just dev

# Создать релиз
just release 1.0.0

Приложение будет доступно на http://localhost:8787

Команды (Just)

Команда	Описание
just	Показать все команды
just setup	Создать venv + зависимости
just dev	Запустить dev сервер
just check	Проверить код (lint + format)
just fix	Исправить код (lint + format)
just build	Собрать Docker образ
just up	Запустить docker-compose
just down	Остановить docker-compose
just release X.X.X	Создать релиз (тег + push)

CI/CD

При пуше тега вида v*.*.* автоматически:

1. Собирается Docker образ
2. Публикуется в GitHub Container Registry
3. Создаётся GitHub Release с changelog
4. Деплоится на сервер через SSH

Рекомендация: делайте репозиторий публичным — тогда сервер сможет пулить образы из GHCR без авторизации.

Для приватного репозитория на сервере нужно один раз залогиниться:

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Необходимые секреты GitHub

Секрет	Описание
PROD_SSH_HOST	Адрес сервера
PROD_SSH_USER	SSH пользователь
PROD_SSH_KEY	SSH приватный ключ

ML модели

Модели загружаются при старте приложения и кэшируются в persistent volume model_cache.

Добавление модели

1. Отредактируй app/models.py — функция load_model()
2. Добавь зависимости в pyproject.toml

Пример с HuggingFace:

from transformers import pipeline

def load_model():
    return pipeline("text-classification", model="your-model-name")

Gated модели (Llama, Mistral и др.)

Некоторые модели на HuggingFace требуют авторизации:

1. Создай токен на https://huggingface.co/settings/tokens
2. Прими лицензию модели на её странице HF

Локальная разработка:

export HF_TOKEN=hf_xxxxxxxxxxxxx
just up

Production (GitHub Actions):

Добавь секрет HF_TOKEN в Settings → Secrets → Actions.

Секрет	Описание
HF_TOKEN	HuggingFace токен (опционально, для gated моделей)

Использование в роутах

from fastapi import Request

@app.post("/predict")
async def predict(request: Request, text: str):
    model = request.app.state.model
    return model(text)

API Endpoints

• GET /health - Health check
• POST /sentiment?text=your+text - Анализ сентимента

Пример запроса

curl -X POST "http://localhost:8787/sentiment?text=hello world"

Ответ:

{"text": "hello world", "label": "POSITIVE", "score": 0.9998}