Конфигурация¶

Принцип работы¶

Все настройки серверной части считываются из переменных окружения при запуске приложения. Для этого используется библиотека Pydantic Settings, которая автоматически находит переменные по имени и приводит их к нужному типу.

Если переменная не задана, используется значение по умолчанию. Все имена переменных нечувствительны к регистру (можно писать как MONGODB_URL, так и mongodb_url).

Дополнительно настройки можно указать в файле .env в корневом каталоге серверной части --- он будет прочитан автоматически.

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

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

Подключение к MongoDB¶

Переменная	Тип	По умолчанию	Описание
`MONGODB_URL`	строка	`mongodb://localhost:27017`	Адрес подключения к серверу MongoDB
`MONGODB_DATABASE`	строка	`smart_doc_matcher`	Имя базы данных

Подключение к MinIO¶

Переменная	Тип	По умолчанию	Описание
`MINIO_ENDPOINT`	строка	`localhost:9000`	Внутренний адрес MinIO (для операций загрузки и скачивания)
`MINIO_PUBLIC_ENDPOINT`	строка	`localhost:9000`	Публичный адрес MinIO (для формирования временных ссылок на скачивание)
`MINIO_ACCESS_KEY`	строка	`minioadmin`	Ключ доступа к MinIO
`MINIO_SECRET_KEY`	строка	`minioadmin`	Секретный ключ MinIO
`MINIO_SECURE`	логическое	`false`	Использовать ли защищённое соединение (HTTPS) при обращении к MinIO

Имена хранилищ MinIO¶

Переменная	Тип	По умолчанию	Описание
`BUCKET_UPLOADS`	строка	`uploads`	Хранилище для исходных загруженных файлов
`BUCKET_DOCUMENTS`	строка	`documents`	Хранилище для изображений страниц после обработки
`BUCKET_PREVIEWS`	строка	`previews`	Хранилище для миниатюр страниц

Помимо этих трёх, при запуске автоматически создаётся хранилище originals --- оно используется для архива оригиналов файлов.

Распознавание через Claude¶

Переменная	Тип	По умолчанию	Описание
`ANTHROPIC_API_KEY`	строка	(пустая)	Ключ доступа к Anthropic для обращений к Claude
`CLAUDE_MODEL`	строка	`claude-haiku-4-5-20251001`	Идентификатор модели Claude, используемой для распознавания

Режим и параметры обработки¶

Переменная	Тип	По умолчанию	Описание
`PROCESSING_MODE`	строка	`batch`	Режим обработки: `sync` (немедленная отправка каждого документа) или `batch` (накопление и пакетная отправка)
`OCR_WORKERS`	целое число	`1`	Количество параллельных операций распознавания текста. Рекомендуется устанавливать на единицу меньше числа доступных процессорных ядер
`BATCH_SIZE`	целое число	`30`	Количество заданий в одном пакете при пакетной обработке
`POLL_INTERVAL`	целое число	`10`	Интервал (в секундах) между проверками готовности результатов пакетной обработки
`RESULT_WORKERS`	целое число	`3`	Количество параллельных заданий при обработке результатов пакета
`MAX_CONCURRENT_MB`	целое число	`300`	Ограничение суммарного размера PDF-файлов, одновременно находящихся в оперативной памяти (в мегабайтах). Предотвращает исчерпание памяти при обработке большого количества крупных файлов

Рекомендации по масштабированию:

Число процессорных ядер	`OCR_WORKERS`	`BATCH_SIZE`
2	1	30
4	2--3	50
8	4--6	100

Распознавание текста через GCP Vision¶

Переменная	Тип	По умолчанию	Описание
`GCP_VISION_ENABLED`	логическое	`false`	Включить ли распознавание текста через Google Cloud Vision (резервный вариант)
`GCP_CREDENTIALS_PATH`	строка	(пустая)	Путь к файлу учётных данных Google Cloud

Очередь задач (Redis и Celery)¶

Переменная	Тип	По умолчанию	Описание
`REDIS_URL`	строка	`redis://localhost:6379/0`	Адрес подключения к Redis. Используется и как брокер задач Celery, и как хранилище результатов

Сетевые параметры серверной части¶

Переменная	Тип	По умолчанию	Описание
`BACKEND_HOST`	строка	`0.0.0.0`	Адрес, на котором серверная часть принимает входящие соединения
`BACKEND_PORT`	целое число	`8000`	Порт серверной части

Настройки Celery¶

Помимо переменных окружения, фоновый обработчик Celery использует фиксированные параметры, заданные в celery_app.py:

Параметр	Значение	Описание
Формат данных	JSON	Все задачи и результаты передаются в формате JSON
Мягкий предел времени	35 минут	По истечении этого срока задача получает сигнал на завершение
Жёсткий предел времени	40 минут	По истечении этого срока задача принудительно останавливается
Время хранения результатов	1 час	После этого результат удаляется из Redis
Количество задач наперёд	1	Обработчик берёт ровно одну задачу за раз (важно для тяжёлых операций)
Подтверждение выполнения	После завершения	Задача считается полученной только после успешного выполнения; при сбое она будет повторена

Где задаются переменные на боевом сервере¶

На боевом сервере переменные окружения указываются в файле docker-compose.yml в секции environment соответствующего сервиса.

Пример:

backend:
  environment:
    - MONGODB_URL=mongodb://mongodb:27017
    - MONGODB_DATABASE=smart_doc_matcher
    - MINIO_ENDPOINT=minio:9000
    - MINIO_PUBLIC_ENDPOINT=alfainft-minio.monroe-tech.ru
    - MINIO_SECURE=true
    - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    - PROCESSING_MODE=batch
    - OCR_WORKERS=1
    - BATCH_SIZE=30
    - POLL_INTERVAL=10

Секретные значения (ключи доступа) рекомендуется выносить в отдельный файл .env, который не попадает в систему управления версиями.