Backend Service API

FastAPI бэкенд сервис с интеграцией OpenAI для перевода, аудио-читалки, обучающих карточек и вопросов-ответов.

Возможности

Перевод текста: Перевод абзацев и отдельных слов с помощью ИИ
Аудио-читалка: Озвучка текста с помощью ИИ
Обучающие карточки: Генерация ассоциаций и изображений для изучения слов
Вопросы и ответы: ИИ-помощник для понимания прочитанного контента

Технологии

FastAPI - веб-фреймворк для создания API
SQLAlchemy - ORM для работы с базой данных
PostgreSQL - реляционная база данных
OpenAI - интеграция с ИИ для генерации контента
Alembic - миграции базы данных
uv - менеджер пакетов Python

Установка и запуск

🚀 Быстрый старт с Docker (рекомендуется)

# 1. Клонирование проекта
git clone <repository-url>
cd backend_service

# 2. Запуск с Docker Compose
docker-compose up -d

# 3. Проверка работы
curl http://localhost:8000/health

# 4. Документация API
# Откройте http://localhost:8000/docs в браузере

Предварительные требования

Python 3.11+
PostgreSQL
uv (менеджер пакетов)
API ключ OpenAI
Docker (для Docker развертывания)

1. Клонирование и установка зависимостей

# Установка uv (если не установлен)
pip install uv

# Установка зависимостей
uv sync

2. Настройка базы данных

Создайте базу данных PostgreSQL:

CREATE DATABASE backend_service;

3. Настройка переменных окружения

Скопируйте файл шаблона и настройте переменные:

# Копирование шаблона
cp env.template .env

# Редактирование файла .env
# Укажите ваши реальные значения для переменных

Или создайте файл .env вручную на основе env.template:

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/backend_service

# OpenAI
OPENAI_API_KEY=your_openai_api_key_here

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=True

# OpenAI Model Settings
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_VOICE_MODEL=tts-1
OPENAI_IMAGE_MODEL=dall-e-3

4. Запуск миграций

# Инициализация Alembic (если первый раз)
uv run alembic init alembic

# Создание миграций
uv run alembic revision --autogenerate -m "Initial migration"

# Применение миграций
uv run alembic upgrade head

5. Запуск сервера

# Запуск в режиме разработки
uv run uvicorn main:app --reload --host 0.0.0.0 --port 8000

# Или через Python
uv run python main.py

Сервер будет доступен по адресу: http://localhost:8000

API Документация

После запуска сервера документация API доступна по адресам:

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc

Структура проекта

backend_service/
├── main.py                 # Основное приложение FastAPI
├── config.py               # Конфигурация приложения
├── database.py             # Настройка базы данных
├── models.py               # Модели SQLAlchemy
├── schemas.py              # Схемы Pydantic
├── services/               # Сервисы
│   ├── __init__.py
│   └── openai_service.py   # Сервис для работы с OpenAI
├── routers/                # API роутеры
│   ├── __init__.py
│   ├── users.py            # Управление пользователями
│   ├── translation.py      # Перевод текста
│   ├── audio.py            # Аудио-читалка
│   ├── learning_cards.py   # Обучающие карточки
│   └── qa.py               # Вопросы и ответы
├── tests/                  # Тесты
│   ├── conftest.py         # Конфигурация pytest
│   ├── unit/               # Модульные тесты
│   ├── integration/        # Интеграционные тесты
│   └── fixtures/           # Тестовые данные
├── alembic/                # Миграции базы данных
│   ├── env.py
│   ├── script.py.mako
│   └── versions/
├── audio_files/            # Аудио файлы (создается автоматически)
├── env.template            # Шаблон переменных окружения
├── init_project.py         # Скрипт инициализации проекта
├── run_tests.py            # Скрипт запуска тестов
├── pytest.ini             # Конфигурация pytest
├── Dockerfile              # Контейнеризация
├── docker-compose.yml      # Развертывание с Docker
├── pyproject.toml          # Конфигурация проекта
└── README.md               # Документация

API Endpoints

Пользователи

POST /api/v1/users/ - Создание пользователя
GET /api/v1/users/{user_id} - Получение пользователя
GET /api/v1/users/ - Список пользователей

Перевод

POST /api/v1/translation/translate - Перевод текста
GET /api/v1/translation/user/{user_id} - Переводы пользователя
GET /api/v1/translation/{translation_id} - Конкретный перевод

Аудио

POST /api/v1/audio/generate - Генерация аудио
GET /api/v1/audio/download/{audio_id} - Скачивание аудио
GET /api/v1/audio/user/{user_id} - Аудио запросы пользователя

Обучающие карточки

POST /api/v1/learning-cards/generate - Генерация карточки с ИИ
POST /api/v1/learning-cards/ - Создание карточки
GET /api/v1/learning-cards/user/{user_id} - Карточки пользователя
PUT /api/v1/learning-cards/{card_id}/learned - Отметить как изученную
GET /api/v1/learning-cards/{card_id} - Конкретная карточка

Вопросы и ответы

POST /api/v1/qa/sessions - Создание сессии Q&A
POST /api/v1/qa/ask - Задать вопрос
GET /api/v1/qa/sessions/user/{user_id} - Сессии пользователя
GET /api/v1/qa/sessions/{session_id}/questions - Вопросы сессии
GET /api/v1/qa/questions/{question_id} - Конкретный вопрос

Примеры использования

Создание пользователя

curl -X POST "http://localhost:8000/api/v1/users/" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com"}'

Перевод текста

curl -X POST "http://localhost:8000/api/v1/translation/translate?user_id=1" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "source_language": "en",
    "target_language": "ru",
    "translation_type": "paragraph"
  }'

Генерация обучающей карточки

curl -X POST "http://localhost:8000/api/v1/learning-cards/generate?user_id=1" \
  -H "Content-Type: application/json" \
  -d '{
    "word": "apple",
    "target_language": "ru"
  }'

🐳 Docker команды

Основные команды

# Сборка образа
docker build -t backend-service .

# Запуск контейнера
docker run -p 8000:8000 backend-service

# Запуск с переменными окружения
docker run --env-file docker.env -p 8000:8000 backend-service

# Docker Compose (рекомендуется)
docker-compose up -d

# Просмотр логов
docker-compose logs -f app

# Остановка
docker-compose down

Отладка

# Подключение к контейнеру
docker exec -it backend_service-app-1 bash

# Просмотр переменных окружения
docker-compose exec app env

# Проверка статуса
docker-compose ps

Разработка

Установка зависимостей для разработки

uv sync --dev

Запуск тестов

Все тесты

uv run pytest

Только unit тесты

uv run pytest tests/unit/ -v -m unit

Только integration тесты

uv run pytest tests/integration/ -v -m integration

Тесты с покрытием

uv run pytest --cov=. --cov-report=html --cov-report=term

Запуск через скрипт

python run_tests.py

Структура тестов

tests/
├── conftest.py                    # Конфигурация pytest
├── unit/                         # Модульные тесты
│   ├── test_models.py            # Тесты моделей
│   ├── test_schemas.py           # Тесты Pydantic схем
│   └── test_services.py          # Тесты сервисов
├── integration/                  # Интеграционные тесты
│   ├── test_users_api.py         # Тесты API пользователей
│   ├── test_translation_api.py   # Тесты API перевода
│   ├── test_audio_api.py         # Тесты API аудио
│   ├── test_learning_cards_api.py # Тесты API карточек
│   └── test_qa_api.py            # Тесты API Q&A
└── fixtures/                     # Тестовые данные

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

uv run black .
uv run isort .

Линтинг

uv run flake8 .

Развертывание

🐳 Docker

Быстрый старт с Docker

# 1. Сборка Docker образа
docker build -t backend-service .

# 2. Запуск контейнера
docker run --env-file docker.env -p 8000:8000 backend-service

Docker Compose (рекомендуется)

# Запуск полной инфраструктуры (приложение + PostgreSQL)
docker-compose up -d

# Просмотр логов
docker-compose logs -f app

# Остановка
docker-compose down

Подробное руководство по Docker

1. Сборка образа

# Сборка с тегом
docker build -t backend-service:latest .

# Сборка с кэшированием
docker build --no-cache -t backend-service:latest .

# Просмотр размера образа
docker images backend-service

2. Запуск контейнера

# Простой запуск
docker run -p 8000:8000 backend-service

# С переменными окружения
docker run --env-file docker.env -p 8000:8000 backend-service

# В фоновом режиме
docker run -d --name backend-app -p 8000:8000 backend-service

# С пробросом volume для аудио файлов
docker run -v $(pwd)/audio_files:/app/audio_files -p 8000:8000 backend-service

3. Управление контейнерами

# Просмотр запущенных контейнеров
docker ps

# Просмотр всех контейнеров
docker ps -a

# Остановка контейнера
docker stop backend-app

# Удаление контейнера
docker rm backend-app

# Просмотр логов
docker logs backend-app

# Подключение к контейнеру
docker exec -it backend-app bash

4. Docker Compose команды

# Запуск в фоновом режиме
docker-compose up -d

# Запуск с пересборкой
docker-compose up --build

# Просмотр статуса
docker-compose ps

# Просмотр логов
docker-compose logs app
docker-compose logs db

# Остановка
docker-compose down

# Остановка с удалением volumes
docker-compose down -v

# Перезапуск сервисов
docker-compose restart app

5. Переменные окружения

Создайте файл docker.env:

# Database
DATABASE_URL=postgresql://postgres:password@db:5432/backend_service

# OpenAI
OPENAI_API_KEY=your_openai_api_key_here

# Server
HOST=0.0.0.0
PORT=8000
DEBUG=False

# OpenAI Model Settings
OPENAI_MODEL=gpt-3.5-turbo
OPENAI_VOICE_MODEL=tts-1
OPENAI_IMAGE_MODEL=dall-e-3

6. Тестирование Docker

# Проверка здоровья приложения
curl http://localhost:8000/health

# Создание пользователя
curl -X POST "http://localhost:8000/api/v1/users/" \
  -H "Content-Type: application/json" \
  -d '{"username": "testuser", "email": "test@example.com"}'

# Просмотр документации API
# Откройте http://localhost:8000/docs в браузере

7. Отладка Docker

# Просмотр логов приложения
docker-compose logs -f app

# Подключение к контейнеру приложения
docker-compose exec app bash

# Подключение к базе данных
docker-compose exec db psql -U postgres -d backend_service

# Проверка переменных окружения
docker-compose exec app env

8. Продакшен настройки

# Сборка для продакшена
docker build -t backend-service:prod .

# Запуск с продакшен настройками
docker run -d \
  --name backend-prod \
  --restart unless-stopped \
  -e DATABASE_URL=postgresql://user:pass@db:5432/backend_service \
  -e OPENAI_API_KEY=your_prod_key \
  -e DEBUG=False \
  -p 8000:8000 \
  backend-service:prod

Структура Docker файлов

backend_service/
├── Dockerfile              # Основной Docker образ
├── docker-compose.yml      # Оркестрация сервисов
├── .dockerignore           # Исключения для Docker
├── docker.env              # Переменные окружения
└── alembic/                # Миграции БД
    ├── env.py
    └── versions/

Troubleshooting

Проблема: Контейнер не запускается

# Решение: Проверьте логи
docker-compose logs app

Проблема: База данных недоступна

# Решение: Проверьте статус БД
docker-compose ps
docker-compose logs db

Проблема: Порты заняты

# Решение: Измените порты в docker-compose.yml
ports:
  - "8001:8000"  # Внешний:Внутренний

Переменные окружения для продакшена

DATABASE_URL=postgresql://user:password@db_host:5432/backend_service
OPENAI_API_KEY=your_production_openai_key
HOST=0.0.0.0
PORT=8000
DEBUG=False

Лицензия

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
alembic		alembic
routers		routers
services		services
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.python-version		.python-version
Dockerfile		Dockerfile
README.md		README.md
alembic.ini		alembic.ini
config.py		config.py
database.py		database.py
docker-compose.yml		docker-compose.yml
docker.env		docker.env
env.template		env.template
init_project.py		init_project.py
main.py		main.py
models.py		models.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
run_tests.py		run_tests.py
schemas.py		schemas.py
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Backend Service API

Возможности

Технологии

Установка и запуск

🚀 Быстрый старт с Docker (рекомендуется)

Предварительные требования

1. Клонирование и установка зависимостей

2. Настройка базы данных

3. Настройка переменных окружения

4. Запуск миграций

5. Запуск сервера

API Документация

Структура проекта

API Endpoints

Пользователи

Перевод

Аудио

Обучающие карточки

Вопросы и ответы

Примеры использования

Создание пользователя

Перевод текста

Генерация обучающей карточки

🐳 Docker команды

Основные команды

Отладка

Разработка

Установка зависимостей для разработки

Запуск тестов

Все тесты

Только unit тесты

Только integration тесты

Тесты с покрытием

Запуск через скрипт

Структура тестов

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

Линтинг

Развертывание

🐳 Docker

Быстрый старт с Docker

Docker Compose (рекомендуется)

Подробное руководство по Docker

1. Сборка образа

2. Запуск контейнера

3. Управление контейнерами

4. Docker Compose команды

5. Переменные окружения

6. Тестирование Docker

7. Отладка Docker

8. Продакшен настройки

Структура Docker файлов

Troubleshooting

Переменные окружения для продакшена

Лицензия

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages