Skip to content
This repository was archived by the owner on Nov 19, 2026. It is now read-only.

Latest commit

 

History

History
210 lines (172 loc) · 14.6 KB

http-api.md

File metadata and controls

210 lines (172 loc) · 14.6 KB

HTTP API веб-сервиса черновиков

Бэкенд 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 не выполняется.

Пакетная обработка (SSE)

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 не меняется.

Потоковая генерация одного объявления (SSE)

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 на время потока не удерживается. При отключении клиента новые вызовы генератора не запускаются.

Как выполняется запрос

  1. GET справочника микрокатегорий из БД и сверка его с MICROCATEGORIES ядра (расхождение — только в лог, работаем с данными из БД).
  2. Вызов синхронного ядра PipelineRuntime.run в рабочем потоке (starlette.concurrency.run_in_threadpool): urllib не должен блокировать event loop.
  3. На каждый запрос создаётся свой LLMCostLedger и включается track_llm_costs, чтобы usage не накапливался в переиспользуемых клиентах модулей; ошибка учёта (например, неподходящий LLM_PRICING_FILE) логируется и запрос не роняет.
  4. Runtime сам валидирует результат: допустимые и уникальные целевые категории без исходной и не более одного черновика на подтверждённую цель. Генератор может отказаться от неподтверждённых услуг: допустимы подмножество целей и пустой список. Дубли и категории вне списка целей отклоняются. Неполный результат клиенту не возвращается.

Ошибки

HTTP Причина
200 Полный результат, включая корректный пустой список (отказ от неподтверждённых услуг)
404 Пустой сплит датасета в /api/dataset/random
422 Неверное тело, mcId вне таблицы или параметры датасета
502 Ошибка провайдера или некорректный результат модели: PipelineOutputError, ValueError, URLError, TimeoutError, ConnectionError
503 Недоступны настройки/зависимости/ключ выбранного модуля (PipelineUnavailableError) либо база данных
500 Непредвиденная программная ошибка

Ошибки возвращают detail с безопасным русским сообщением; текст ответа провайдера, ключи и traceback в HTTP-ответ не попадают.

Проверка без Docker и без API-расходов

Контракт проверяется 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-расходов.