Бэкенд React-клиента: FastAPI-приложение api.app:app (пакет src/api).
Контракт не изменился: вход {"description": "...", "mcId": 101}, выход
{"drafts": [{"mcId": 104, "title": "...", "text": "..."}]}.
docker compose up -d # api внутри контейнера: uvicorn api.app:app
# или локально, без Docker:
uv run uvicorn api.app:app --app-dir src --port 8000Сервер: http://127.0.0.1:8000. Swagger: /docs,
OpenAPI: /openapi.json.
На старте приложение читает .env и config.json (пути — относительно
корня проекта), проверяет выбранные модули и создаёт пул PostgreSQL без
подключения к базе. Отсутствие ключей LLM — не ошибка запуска: сбои видны
только на запросах. Файловый CLI src/main.py --input ... --output ...
использует то же ядро и тот же config.json.
Генератор local_llm общий с CLI и React-бэкендом api.app:app
(POST /api/drafts); оба читают config.json.draft_generation. Это разные
HTTP-приложения: python -m src не обслуживает React /api/*.
Модуль универсального API — src/http_api.py, фабрика — http_api:create_app;
пакет src/api/ предназначен только для веб-бэкенда.
Локальный runtime Qwen3.5-9B и его веса устанавливаются и запускаются отдельно,
не при uv sync и не через Compose. Инструкции — в разделе
«Веб-сервис».
Для CLI/dev endpoint по умолчанию http://127.0.0.1:8080/v1/chat/completions,
для контейнера — http://host.docker.internal:8080/v1/chat/completions.
MLX alias: LOCAL_LLM_MODEL_ID=default_model; таймаут LOCAL_LLM_TIMEOUT=180,
лимит LOCAL_LLM_MAX_TOKENS=4096. Endpoint меняется через LOCAL_LLM_API_URL.
Текст содержит вступление и списки •; исходные эмодзи выбираются вторым
запросом без переписывания слов. Автоматических повторов генерации нет.
Классификатор и генератор выбираются только в config.json
(среди генераторов доступны local_llm и sample_llm):
{
"subcategory_extraction": "decisions.jev",
"draft_generation": "sample_llm"
}Query-параметров extractor/generator у POST /api/drafts нет.
При старте имена сверяются с каталогом модулей (discover_modules):
неизвестный extractor или generator — явная ошибка запуска, запасная
модель молча не подставляется. Добавление нового модуля с существующим
интерфейсом подхватывается после правки config.json и перезапуска сервера;
новые registry-списки в коде не нужны.
В универсальном API src/http_api.py (python -m src, POST /drafts)
дополнительно есть GET /modules (extractors, generators, defaults)
и query-параметры extractor/generator для переопределения модуля одного
запроса. Оба списка строятся одинаково: папки модулей с pipeline.py и
__init__.py, прошедшие проверку имени; импорт и конструкторы моделей не
вызываются.
В app.state живёт один PipelineRuntime: активные экземпляры шагов
кэшируются и переиспользуются между запросами, параллельные запросы
сериализуются замком runtime. Первый запрос к модулю включает его загрузку,
последующие — нет. Наличие модуля в каталоге не означает наличия его
ресурсов, весов или ключа провайдера: это ошибка запроса, а не старта.
Варианты моделей, пороги, таймауты и ключи остаются настройками .env
ядра (SELECTEL_API_KEY, JEV_*, LLM_API_KEY, SAMPLE_LLM_* и другие);
через HTTP они не принимаются.
| Метод и путь | Что делывает |
|---|---|
POST /api/drafts |
Полный пайплайн ядра: извлечение микрокатегорий + генерация черновиков |
POST /api/drafts/batch |
Пакетная обработка: SSE-поток start/result/error/done по мере готовности строк |
POST /api/drafts/stream |
Потоковая генерация одного объявления: SSE-кадры categories/draft/done/error по мере готовности черновиков |
GET /api/microcategories |
Справочник микрокатегорий из БД: [{"mcId": 101, "title": "..."}] |
GET /api/dataset/samples |
Страница объявлений датасета (split, limit, offset) |
GET /api/dataset/random |
Одно случайное объявление сплита |
GET /api/dataset/stats |
Число объявлений по сплитам: {"train": N, "test": M} |
GET /api/health |
Живость API и БД, выбранные модули |
Пример:
curl -X POST 'http://127.0.0.1:8000/api/drafts' \
-H 'Content-Type: application/json' \
-d '{"description":"Устанавливаю розетки и смесители.","mcId":101}'Успешный ответ — {"drafts":[{"mcId":104,"title":"...","text":"..."}]}.
Список пуст, когда дополнительных услуг нет: {"drafts":[]}.
Служебные параметры, usage и selector-значения в результат не добавляются.
Допустимые mcId — 101–106; любое другое значение отклоняется валидацией
входа (422), фронтенд этот контракт не меняет.
GET /api/health возвращает, например:
{"status": "ok", "db": true, "extractor": "decisions.jev", "generator": "sample_llm"}При недоступной базе — status: "degraded", db: false, но не 5xx.
Проверка моделей и облачных API в health не выполняется.
POST /api/drafts/batch принимает массив объявлений (CSV/JSON/JSONL
парсится на клиенте) и необязательный параллелизм:
{"ads": [{"description": "...", "mcId": 101}], "concurrency": 4}Не более 1000 объявлений; concurrency по умолчанию 4, максимум 8
(значение приводится к диапазону [1, 8]). Невалидное тело — mcId вне
101–106, отсутствующий description, больше 1000 строк — 422 до старта
потока. Ответ — text/event-stream, кадры вида
event: <type>\ndata: <json>\n\n:
| Событие | Данные |
|---|---|
start |
{"total": N, "concurrency": K} |
result |
{"index": i, "mcId": <исходный>, "drafts": [{"mcId","title","text"}]} |
error |
{"index": i, "detail": "<безопасное русское сообщение>"} |
done |
{"processed": N, "succeeded": S, "failed": F} |
index — позиция объявления во входном массиве (0-based); события идут по
мере завершения строк и порядок может отличаться от входного. Сбой строки
даёт error (без traceback, ключей и текста провайдера) и не прерывает
поток. Каждая строка выполняется в независимом экземпляре пайплайна
(per-task PipelineRuntime из load_pipeline) под asyncio.Semaphore в
общем threadpool — общий PipelineRuntime одиночного эндпоинта со своим
замком для пакета не используется, mutable-state модулей между строками не
смешивается. При отключении клиента новые строки не запускаются.
Одиночный контракт POST /api/drafts не меняется.
POST /api/drafts/stream — аддитивный потоковый вариант POST /api/drafts:
то же тело {"description": "...", "mcId": 101}, тот же итоговый набор
черновиков, но ответ — text/event-stream, и черновики уходят по мере
готовности (веб-интерфейс использует его для прогресса ручного ввода):
| Событие | Данные |
|---|---|
categories |
{"mcIds": [104, 105]} — цели после классификации (может быть пустым) |
draft |
{"mcId": 104, "title": "...", "text": "..."} — один готовый черновик |
error |
{"detail": "<безопасное русское сообщение>"} — терминальный кадр сбоя |
done |
{} — поток успешно завершён |
Пустой список целей отдаётся кадром categories с [] и сразу done.
Генератор вызывается по одной целевой категории за раз (оба генератора
и так делают по одному обращению на категорию), проверки повторяют
PipelineRuntime.run и DraftsService._checked. Экземпляры модулей
создаются на запрос через load_pipeline, как per-row runtime пакета:
общий замок одиночного PipelineRuntime на время потока не удерживается.
При отключении клиента новые вызовы генератора не запускаются.
GETсправочника микрокатегорий из БД и сверка его сMICROCATEGORIESядра (расхождение — только в лог, работаем с данными из БД).- Вызов синхронного ядра
PipelineRuntime.runв рабочем потоке (starlette.concurrency.run_in_threadpool): urllib не должен блокировать event loop. - На каждый запрос создаётся свой
LLMCostLedgerи включаетсяtrack_llm_costs, чтобы usage не накапливался в переиспользуемых клиентах модулей; ошибка учёта (например, неподходящийLLM_PRICING_FILE) логируется и запрос не роняет. - Runtime сам валидирует результат: допустимые и уникальные целевые категории без исходной и не более одного черновика на подтверждённую цель. Генератор может отказаться от неподтверждённых услуг: допустимы подмножество целей и пустой список. Дубли и категории вне списка целей отклоняются. Неполный результат клиенту не возвращается.
| HTTP | Причина |
|---|---|
| 200 | Полный результат, включая корректный пустой список (отказ от неподтверждённых услуг) |
| 404 | Пустой сплит датасета в /api/dataset/random |
| 422 | Неверное тело, mcId вне таблицы или параметры датасета |
| 502 | Ошибка провайдера или некорректный результат модели: PipelineOutputError, ValueError, URLError, TimeoutError, ConnectionError |
| 503 | Недоступны настройки/зависимости/ключ выбранного модуля (PipelineUnavailableError) либо база данных |
| 500 | Непредвиденная программная ошибка |
Ошибки возвращают detail с безопасным русским сообщением; текст ответа
провайдера, ключи и traceback в HTTP-ответ не попадают.
Контракт проверяется FastAPI TestClient с замоканными PipelineRuntime
и БД: сериализация {"drafts": [...]}, пустой список, валидация mcId,
/api/health с extractor/generator из config.json, 503 при
PipelineUnavailableError и 502 при PipelineOutputError/ValueError.
Паритет CLI ↔ API гарантирован общим ядром: веб вызывает тот же
PipelineRuntime.run и тот же config.json, что и run_pipeline CLI;
без API-ключей паритет воспроизводится на моках/контрольных ответах
(реальные вызовы LLM для этого не требуются).
Известное ограничение: офлайн-проверки HTTP-контракта в
src/draft_generation/benchmarks/full_pipeline_evaluation (run.py --api-check) покрывают оба HTTP-приложения: универсальный API
(python -m src, GET /modules, query-селекторы) и веб-бэкенд
(api.app, /api/*) на контрольных ответах, без API-расходов.