По тексту объявления и его микрокатегории находим услуги из других микрокатегорий «Ремонт и отделка» (101–106) и генерируем черновики объявлений.
| Путь | Что это |
|---|---|
src/main.py |
CLI + всё общее: контракт, микрокатегории, BasePipeline, LLMClient |
src/http_api.py |
HTTP API полного пайплайна и селекторы модулей в Swagger |
config.json |
выбор реализации каждого шага |
src/subcategory_extraction/ |
шаг 1: выделение подкатегорий услуг |
src/draft_generation/ |
шаг 2: генерация черновиков |
data/ |
пример входа |
docs/ |
кейс, критерии, справочник, датасеты |
backlog/ |
локальный бэклог (в .gitignore) |
src/api/ |
веб-сервис: FastAPI-бэкенд, клиенты LLM, промпты |
src/web/ |
веб-клиент: Vite + React + Mantine |
docker-compose.yml, deploy/ |
инфраструктура веб-сервиса: db + api + web |
В каждом разделе — несколько вариантов: <module>/pipeline.py и, при
необходимости, <module>/prompts/. Общие benchmarks/<name>/ с run.py,
README.md и результатами остаются в корне раздела. Экспериментальные решения тоже оформляем
как модули, без отдельной папки experiments/.
Обученные модели храним внутри своего решения:
src/subcategory_extraction/<group>/<module>/ # остальные сервисы: src/<service>/<module>/
├── __init__.py
├── pipeline.py
├── prompts/ # обязательно для decisions, иначе при необходимости
├── PROMPTS.md # анализ различий промптов для каждого decision-модуля
└── artifacts/ # обученные веса, токенизатор, метаданные и калибровка
artifacts/ включаем в Git и загружаем на GitHub вместе с решением;
для файлов сверх лимита обычного GitHub Git используем Git LFS.
Итоговые веса обучения и путь загрузки модуля по умолчанию должны указывать
сюда; способ загрузки и воспроизведения весов описываем в README модуля.
semantic_encoder_f1 по умолчанию загружает модель из своей папки artifacts/.
Временные checkpoint и отчёты полного обучения остаются в out/;
выбранная итоговая модель копируется в модуль.
Корневой config.json задаёт модуль каждого шага; для extraction — <group>.<module>:
{
"subcategory_extraction": "decisions.jev",
"draft_generation": "sample_llm"
}Модули выделения сгруппированы по подходам. Внутри каждой группы — папки модулей:
src/subcategory_extraction/
├── lexical/ # regex/, tfidf/, learned_keywords/, snippet_logistic_regression/
├── semantic/ # semantic_encoder/, semantic_encoder_calibrated/, semantic_encoder_f1/, semantic_evidence/
├── decisions/ # google_decision/, qwen_decision/, jev/, local_jev/, jev_calibrated/, jev_boundaries/, jev_retrieval/
├── hybrid/ # jev_tfidf/, evidence_jev/, jev_arbiter/
└── benchmarks/ # четыре общих сценария для всех подходов
TinyBERT исключён из поддерживаемых модулей.
Указывайте полный путь, например lexical.tfidf или decisions.jev.
Список методов,
веса и подготовленные ресурсы.
Доступен генератор draft_generation/sample_llm. null означает, что модуль
не выбран. CLI выдаёт явную ошибку.
Текущий Jev использует Selectel Decisions: JEV_PROVIDER=selectel,
JEV_MODEL=typesafe/jev-1.13,
JEV_ENDPOINT=https://api.selectel.ru/aig/v1/decisions.
Задайте отдельный SELECTEL_API_KEY в .env; детали — в
README Jev.
Доступен экспериментальный jev_calibrated:
минимальный промпт и порог 0.635 выбраны по train-группам; control micro-F1
0.926829 → 0.939759. На официальном test: 0.842415 → 0.844376,
на диагностическом: 0.816754 → 0.775068. Из-за этого компромисса по умолчанию
сохранён прежний jev; эксперимент включается явно через config.json.
Новый Selectel-прогон: micro-F1 0.842415 на исходных 208 строках и
0.816754 на 119 диагностических; среднее время run() на 10 входах — 1.026307 с.
Данные и ограничения — в бенчмарках ниже.
Варианты (например, jev, embeddings или llm) добавляются в
src/<service>/<module>/; затем в конфиге указывается имя папки вместо null.
Каждый вариант содержит __init__.py и pipeline.py с классом и интерфейсом
своего раздела (см. AGENTS.md). В CLI выбор задаётся конфигом,
в HTTP — query-параметрами extractor/generator с defaults из конфига.
Несуществующий модуль вызывает ошибку.
Для сравнения вариантов используем общие бенчмарки раздела и фиксируем модуль в результатах. Скрипты переноса и обучения описаны в subcategory_extraction/README.md; исторические результаты с внешним SplitShift сохранены в истории Git; невоспроизводимые старые скрипты доступны в Git.
Ровно четыре проверки: ручная стоимость токенов, F1 improved_dataset, F1 InnoGlobalHack и время работы. Новые бенчмарки и папки не создаём.
uv run python src/subcategory_extraction/benchmarks/improved_dataset/run.py --replay
uv run python src/subcategory_extraction/benchmarks/classifier_methods/run.py --replayЭти команды проверяют сохранённые ответы без API и обучения. Для оценки
текущих весов передайте --methods <модуль>. Исторический F1 модуля
semantic_encoder_f1 на 119 диагностических строках — 0.857143;
это предварительная разметка, не независимый ручной эталон.
Опубликованные веса Leo включены в модуль через Git LFS (git lfs pull).
Загрузка и повторное обучение описаны в
инструкции модуля.
Для dataset_annotation — только время применения сохранённых решений и шесть примеров с mcId.
uv sync
uv run uvicorn api.app:app --app-dir src --port 8000Swagger: http://127.0.0.1:8000/docs. POST /api/drafts принимает
{"description": "...", "mcId": 101} и возвращает {"drafts": [...]};
выбор extractor и generator — только в config.json, query-параметров нет.
GET /api/health — состояние сервера, базы и выбранные модули.
curl -X POST 'http://127.0.0.1:8000/api/drafts' \
-H 'Content-Type: application/json' \
-d '{"description":"Устанавливаю розетки и смесители.","mcId":101}'Пакетная обработка — POST /api/drafts/batch: массив объявлений обрабатывается
параллельно, результат стримится по SSE (события start/result/error/done).
Потоковая генерация одного объявления — POST /api/drafts/stream: тот же вход,
но цели приходят кадром categories, а каждый черновик — отдельным кадром
draft по мере готовности (done/error в конце).
Тело и результат соответствуют контракту кейса. Сервер выполняет inference
последовательно в одиночном запросе и переиспользует активные экземпляры
модулей; пакетный эндпоинт создаёт независимый пайплайн на каждую строку.
Пустой список целей возвращает drafts: [] без генерации.
API-ключи и веса нужны только при использовании соответствующего модуля.
Подробности, ошибки и офлайн-проверка: docs/http-api.md.
description + mcId
│
▼
subcategory_extraction список mcId найденных услуг (101–106)
│
▼
draft_generation черновик на каждую целевую категорию
│
▼
{"drafts": [{"mcId": 104, "title": "...", "text": "..."}]}
Запуск:
uv sync
cp -n .env.example .env # заполнить SELECTEL_API_KEY и LLM_API_KEY
uv run python src/main.py --input data/input.json --output out/output.jsonДля полного запуска выберите реализации обоих шагов и настройте .env
(для генератора см. src/draft_generation/README.md).
Общий LLMClient — абстрактный интерфейс для конкретных клиентов.
uv sync
uv run python src/run.py --config run.config.jsonrun.config.json задаёт датасет (.parquet или официальный .jsonl),
путь к конфигу модулей, исходную категорию (101 для официальных данных),
путь отчёта, необязательный лимит строк и частоту логирования.
Все относительные пути считаются от файла конфигурации.
pipeline_config ссылается на обычный config.json: необходимо выбрать
оба рабочих модуля, включая генератор. При null оценка завершается
ошибкой, без подмены полного решения классификатором. Параметры моделей
и секреты выбранных модулей по-прежнему берутся из .env.
Метрика — sklearn.metrics.f1_score(average="micro", zero_division=0)
по множествам mcId из итоговых drafts, баллы за классификацию —
60 × micro-F1 (не итоговый балл за все критерии хакатона).
Повторы не учитываются, ошибочный вывод исходной категории считается FP.
Если все эталоны и ответы пусты, micro-F1 равен 0.
Отчёт out/evaluation.json содержит метрику, TP/FP/FN, конфигурацию,
время, эталоны и полные ответы для каждой строки. Ошибка обработки
не превращается в пустой ответ: прогон прекращается без новой метрики.
training_dataset включает проверку нормализованных точных совпадений
описаний с train; пересечения отражаются в отчёте и предупреждении,
но не удаляются из оценки. Это не поиск всех близких дубликатов
и не гарантия отсутствия утечки. null отключает проверку.
Официальный test следует использовать для итоговой оценки после
фиксации модели и порогов, не для их подбора.
Кроме CLI, проект поднимает веб-сервис черновиков: FastAPI-бэкенд
(src/api/), одностраничный клиент (src/web/, подробнее —
src/web/README.md) и справочник микрокатегорий
в PostgreSQL. Инфраструктура — docker-compose.yml и deploy/.
CLI, универсальный HTTP POST /drafts (python -m src) и React
POST /api/drafts используют один генератор из config.json.draft_generation:
local_llm. Веб-классификатор остаётся Selectel Jev Decisions API.
Генератор возвращает вступление и тематические пункты •, затем при необходимости
дополнительные сведения; исходные эмодзи выбираются отдельным запросом без
переписывания сгенерированных слов. Ошибка генерации даёт 502, не пустой черновик.
До запуска отдельно установите runtime и веса Qwen3.5-9B.
Docker Compose не устанавливает и не запускает модель. Например, на Apple Silicon
в отдельном окружении с mlx-lm и скачанными MLX-весами:
mlx_lm.server --model /absolute/path/to/Qwen3.5-9B-MLX --host 0.0.0.0 --port 8080OpenAI-совместимый endpoint для CLI/dev по умолчанию —
http://127.0.0.1:8080/v1/chat/completions, идентификатор MLX — default_model.
Compose обращается к хосту через
http://host.docker.internal:8080/v1/chat/completions; runtime должен быть доступен
контейнеру (не только на loopback). Не открывайте этот неаутентифицированный порт
в публичную сеть. URL и alias другой локальной службы задаются через
LOCAL_LLM_API_URL и LOCAL_LLM_MODEL_ID.
cp .env.example .env # заполнить SELECTEL_API_KEY
docker compose up -d --buildВеб-клиент: http://localhost:8081, API напрямую: http://localhost:8000.
nginx внутри контейнера web раздаёт статику и проксирует /api/ в
сервис api. Хост-порт клиента задаётся переменной WEB_PORT (.env
или окружение compose) и по умолчанию равен 8081: порт 8080 на этой
машине занят другим сервисом.
| Эндпоинт | Что делает |
|---|---|
POST /api/drafts |
контракт кейса: вход {"description": "…", "mcId": 101}, выход {"drafts": [{"mcId": 104, "title": "…", "text": "…"}]} |
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/health |
статус API и БД (ok/degraded) и модель классификатора |
GET /api/dataset/samples |
страница объявлений датасета: `?split=train |
GET /api/dataset/random |
один случайный сэмпл: `?split=train |
GET /api/dataset/stats |
число объявлений по сплитам: {"train": 10000, "test": 208} |
Сбой шлюза LLM отвечает 502, недоступная база — 503; detail — русское
сообщение, его показывает интерфейс.
Официальные данные InnoGlobalHack × Avito (public-train-annotated.jsonl
— 10 000 объявлений с разметкой, public-test-dataset.parquet — 208
объявлений с названиями категорий) загружаются в таблицу case_ads
PostgreSQL и доступны через эндпоинты /api/dataset/*. Исходная категория
всех объявлений — 101; для train хранится foundMcIds (массив mcId из
found_microcategories), для test — categories (массив названий).
Схема создаётся автоматически (CREATE TABLE IF NOT EXISTS в лоадере и
в deploy/db/init.sql), загрузка идемпотентна: UNIQUE-ключ row_key и
ON CONFLICT DO NOTHING, повторный запуск не дублирует строки
(в test есть полные дубликаты текстов, поэтому ключ test-строк —
test:{номер}:{хэш текста}, а ключ train-строк — train:{item_id}).
Локально (БД из compose, код из репозитория):
docker compose up -d db
PYTHONPATH=src uv run python -m api.dataset_loader # или: uv run python src/api/dataset_loader.py
# флаги: --data-dir (по умолчанию data/innoglobalhack_avito/innoglobalhack_avito)
# --database-url (по умолчанию DATABASE_URL из окружения/.env)Внутри compose (каталог ./data смонтирован в контейнер api на read-only):
docker compose up -d --build # пересоздать api с монтированием data/
docker compose exec api uv run --no-dev python src/api/dataset_loader.pyПосле загрузки — сэмпл из датасета можно прогнать через основной контракт
POST /api/drafts:
curl -s "http://localhost:8000/api/dataset/random?split=train" \
| jq -c '{description, mcId: .sourceMcId}' \
| curl -s -X POST http://localhost:8000/api/drafts \
-H 'Content-Type: application/json' -d @-Сервис db-load при каждом docker compose up исполняет
src/api/dataset_loader.py (см. «Датасет кейса в БД») и завершается:
restart: "no", depends_on: db: service_healthy, каталог
docs/innoglobalhack_avito смонтирован в лоадер только на чтение.
Повторный запуск идемпотентен (UNIQUE row_key + ON CONFLICT DO NOTHING), на api и web сервис не влияет. Образ лоадера — отдельный
лёгкий deploy/db-load.Dockerfile без torch/CUDA: полный
uv sync --frozen для одноразовой загрузки не нужен. Повтор вручную:
docker compose run --rm db-load
docker compose exec db psql -U avito -d avito \
-c "SELECT split, count(*) FROM case_ads GROUP BY split"docker compose up -d db
uv run uvicorn api.app:app --app-dir src --port 8000
cd src/web && npm install && npm run dev # http://localhost:5173Vite проксирует /api/* на http://localhost:8000 (см.
src/web/vite.config.ts).
Шаблон — .env.example, сервис читает корневой .env:
| Переменная | Назначение |
|---|---|
DATABASE_URL |
подключение к PostgreSQL (compose переопределяет на db:5432) |
SELECTEL_API_KEY |
ключ Selectel: классификатор decisions.jev (endpoint, модель и порог — JEV_*) и генератор sample_llm (Qwen через AI Router, настройки — SAMPLE_LLM_*) |
LLM_API_KEY, LLM_MODEL_ID |
ключ и модель классификаторов Google (GOOGLE_DECISION_*) |
BESTAPI_API_KEY |
ключ BestAPI для структурного LLM (STRUCTURED_LLM_*) |
LOCAL_LLM_API_URL, LOCAL_LLM_MODEL_ID |
endpoint локальной генерации local_llm и alias модели (default_model) |
LOCAL_LLM_TIMEOUT, LOCAL_LLM_MAX_TOKENS |
таймаут 180 с и лимит 4096 токенов на запрос; скрытых повторов нет |
LLM_PRICING_FILE |
JSON-тарифы USD для учёта расходов; без файла стоимость неизвестна |
API_PORT, WEB_PORT |
хост-порты API и веб-клиента |
Примечание. Модели, пороги, таймауты и повторы — настройки выбранных модулей в
.envядра (шаблон —.env.example); через HTTP они не принимаются, выбор модулей — только вconfig.json. Текущая пара модулей видна вGET /api/healthв поляхextractorиgenerator.
- Ветка на каждую фичу:
<username>/feature/<slug>. Вmain— только через PR. - Бэклог локальный:
backlog/{TODO,PROCESS,REVIEW,DONE}, задача перемещается по папкам по мере работы. - Новые бенчмарки и папки для них не создаём. Используем существующие сценарии и обновляем их таблицы результатов; набор закреплён в AGENTS.md.
- Правки в чужих сервисах — через свою ветку и с согласия автора.
- Контракт входа/выхода не меняем без согласования со всей командой.
Подробнее — в AGENTS.md.
Исторический замер на исходных 208 строках: RuBERT-tiny2 на CPU дал micro-F1
0.786704, медиану 3.58 мс на уникальный вход на Apple M4 Pro. Это дообученная
компактная модель, не TinyBERT. Замер не относится к новым весам improved_dataset.
Все API-клиенты теперь учитывают usage, повторы и локальный/provider cache.
Обычный CLI дополнительно сохраняет <output>.costs.json, включая ошибки;
run.py сохраняет расходы; в бенчмарках стоимость токенов вносится вручную. Тарифы задаются через
LLM_PRICING_FILE по точному endpoint/model; неизвестная цена — null, не ноль.