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

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

Услуги из объявлений Авито → черновики

По тексту объявления и его микрокатегории находим услуги из других микрокатегорий «Ремонт и отделка» (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.

HTTP API и Swagger

uv sync
uv run uvicorn api.app:app --app-dir src --port 8000

Swagger: 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.json

run.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 8080

OpenAI-совместимый 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 @-

Автозагрузка датасета при старте compose

Сервис 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"

Dev-запуск

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:5173

Vite проксирует /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.

Контрибьюшн

  1. Ветка на каждую фичу: <username>/feature/<slug>. В main — только через PR.
  2. Бэклог локальный: backlog/{TODO,PROCESS,REVIEW,DONE}, задача перемещается по папкам по мере работы.
  3. Новые бенчмарки и папки для них не создаём. Используем существующие сценарии и обновляем их таблицы результатов; набор закреплён в AGENTS.md.
  4. Правки в чужих сервисах — через свою ветку и с согласия автора.
  5. Контракт входа/выхода не меняем без согласования со всей командой.

Подробнее — в AGENTS.md.

CPU и стоимость внешних моделей

Исторический замер на исходных 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, не ноль.

Ручной учёт стоимости токенов.

About

No description, website, or topics provided.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages