🌐 Интерактивный UI: локальный веб-интерфейс
http://localhost:8000
📑 Интерактивная документация OpenAPI (Swagger):http://localhost:8000/docs
⚡ Скорость экстракции:< 1.5 мсна карточку (> 680 товаров/сек на 1 ядре CPU)
| Извлечение характеристик и скоринг уверенности | Карта ручной модерации (Human-in-the-Loop) |
|---|---|
![]() |
![]() |
| Очередь карточек на проверку модератором | Документация OpenAPI (Swagger UI) |
|---|---|
![]() |
![]() |
Промышленный сервис для автоматического структурирования и валидации характеристик товаров e-commerce каталога. Сервис принимает неструктурированный текст селлера (название, описание, технические характеристики) и извлекает нормализованные атрибуты с проверкой физической корректности.
- Смартфоны: бренд, модель, цвет, диагональ экрана, разрешение, частота обновления (Гц), объем RAM и ROM, процессор, емкость аккумулятора (мА·ч), ОС.
- Ноутбуки: бренд, модель, цвет, диагональ, объем RAM и SSD/HDD, процессор, видеокарта (GPU), ОС.
- Телевизоры: бренд, модель, диагональ экрана, разрешение, технология матрицы (OLED/QLED/LED), Smart TV.
- Холодильники: бренд, модель, цвет, полезный объем, система разморозки (No Frost), габариты (ШхВхГ).
- Пылесосы и роботы-пылесосы: бренд, модель, тип уборки (сухая/влажная), объем пылесборника, мощность, время работы.
- Наушники и гарнитуры: бренд, модель, цвет, тип подключения, время автономной работы.
- Внешние аккумуляторы (Powerbank): бренд, модель, цвет, емкость аккумулятора (мА·ч), выходная мощность (Вт).
- Микроволновые печи (СВЧ): бренд, модель, цвет, внутренний объем (л), мощность микроволн (Вт).
💡 Архитектурный принцип таксономии каталога:
В каждой категории строго разделяются обязательные атрибуты (required_attrs), отсутствие которых отправляет карточку в очередь модерации (needs_review: true), и поддерживаемые опциональные атрибуты (например, габаритыdimensionsили гарантияwarrantyдля холодильников; видеокартаgpuдля ноутбуков). При наличии в исходном тексте оффера опциональные характеристики извлекаются с высокой точностью в Tier 1/2 без штрафа к метрикам и без ложных срабатыванийmissing.
- Гибридный многоуровневый каскад:
- Tier 1 (FlashText + Regex): сверхбыстрое детерминированное ядро на алгоритме Ахо-Корасик и регулярных выражениях. Обрабатывает карточку за
< 1.8 мсна CPU без видеокарты, закрывая свыше 95% каталога. - Tier 2 (Zero-Shot NER): легковесный экстрактивный трансформер GLiNER для извлечения редких моделей, серий и процессоров.
- Tier 3.5 (Catalog KB): база знаний на 9 700+ верифицированных моделей каталога для восполнения пропущенных селлером характеристик.
- Tier 3.8 (LLM Fallback): точечное подключение языковых моделей с предохранителем
Circuit Breakerи проверкой заземления фактов (GroundingVerifier).
- Tier 1 (FlashText + Regex): сверхбыстрое детерминированное ядро на алгоритме Ахо-Корасик и регулярных выражениях. Обрабатывает карточку за
- 100% экстрактивность и защита от галлюцинаций:
- Значения атрибутов извлекаются строго из текста оффера или верифицированной заводской базы. Модель не додумывает несуществующие характеристики.
- Физическая валидация (Sanity Gate):
- Проверка физических диапазонов (смартфон не может иметь экран 65" или батарею 100 000 мА·ч).
- Строгие белые списки атрибутов по категориям (в холодильниках исключена ОС, а в микроволновках — видеокарта).
- Контроль качества (Human-in-the-Loop):
- Расчет уверенности (
confidence) для каждого атрибута. - Карточки с нехваткой ключевых данных или спорными значениями автоматически маркируются
needs_review: trueи отправляются контент-модераторам.
- Расчет уверенности (
- Контекстные фильтры и защита от шума (Context Guardrails):
- Title Authority: приоритетное извлечение спецификаций из названия товара для защиты от маркетингового шума в описании.
- Анти-апгрейд фильтр: отсечение пределов расширения (
до 32 ГБ,до 2 ТБ,флешки до 1024 ГБ). - Защита от отрицаний и сравнений: игнорирование упоминаний конкурентов (
не уступает iPhone 15 Pro Max,рвет Snapdragon 7s Gen 2). - Межбрендовый инвариант: проверка
AttributeSanityValidator.is_brand_model_compatible(блокировка чужих моделей). - Защита от рекомендаций: распознавание фактического
Без ОСвместо рекомендованной Windows 11.
- Пакетная обработка и экспорт:
- Поддержка форматов JSON и CSV через веб-интерфейс, REST API и командную строку (CLI).
git clone https://github.com/nikitos7626/product-attribute-extractor.git
cd product-attribute-extractor
pip install -r requirements.txtuvicorn backend.app.main:app --host 0.0.0.0 --port 8000- Веб-интерфейс:
http://localhost:8000 - Swagger UI документация:
http://localhost:8000/docs
docker compose up -d# Извлечение из одной строки через корневой скрипт:
python extract.py "Смартфон Xiaomi Redmi Note 13 8/256GB Black 5000mAh AMOLED 120Hz"
# Запуск через модуль backend (полный эквивалент):
python backend/run_cli.py "Смартфон Xiaomi Redmi Note 13 8/256GB Black 5000mAh AMOLED 120Hz"
# Мгновенный автономный режим (Tier 1 правила + база знаний, <5 мс, без внешних нейросетей):
python extract.py "Смартфон Xiaomi Redmi Note 13 8/256GB" --fast
# Интерактивная ручная проверка с флагом --interactive-review:
python extract.py "Смартфон Xiaomi Redmi Note 13 8/256GB" --interactive-review
# Пакетная обработка файла с экспортом в JSON и CSV:
python scripts/export_predictions.py --input data/sample_cards.json --format both| Метод | Путь | Описание |
|---|---|---|
POST |
/extract |
Основной эндпоинт извлечения характеристик (карточка |
POST |
/api/extract |
Канонический REST-эндпоинт с расширенным ответом и метриками уверенности |
POST |
/api/extract/batch |
Пакетная обработка списка карточек товаров |
POST |
/api/extract/export |
Пакетный экспорт в стандартизированные файлы predictions.json / predictions.csv
|
POST |
/api/extract/from-url |
Извлечение характеристик по внешней веб-ссылке на товар из открытых источников |
GET |
/api/extract/taxonomy |
Схемы категорий, обязательные атрибуты и белые списки |
GET |
/api/extract/review-queue |
Очередь карточек для ручной проверки Human-in-the-Loop (needs_review: true) |
POST |
/api/extract/review-queue/clear |
Массовая очистка/утверждение очереди модерации (DELETE /api/extract/review-queue) |
POST |
/api/extract/review-override |
Сохранение решения модератора по переопределению/утверждению атрибута |
GET |
/api/extract/metrics |
Стандартизированный JSON-отчет валидации качества (Per-Attribute F1/P/R) |
POST |
/api/extract/brands/register |
Динамическое добавление нового бренда в словарь без перезапуска |
GET |
/api/info |
Служебная информация о сервисе и активных компонентах |
GET |
/health |
Легковесный health check сервиса |
GET |
/docs |
Интерактивная документация Swagger UI |
curl -X POST "http://localhost:8000/api/extract" \
-H "Content-Type: application/json" \
-d '{"title": "Смартфон Xiaomi Redmi Note 13 8/256GB Black 5000 мАч AMOLED 120Hz"}'Пример ответа (JSON):
{
"category": "smartphones",
"attributes": {
"brand": {"value": "Xiaomi", "raw": "Xiaomi", "confidence": 0.99, "source": "flash_text"},
"model": {"value": "Redmi Note 13", "raw": "Redmi Note 13", "confidence": 0.98, "source": "regex"},
"memory_ram": {"value": "8 ГБ", "raw": "8", "confidence": 0.98, "source": "regex"},
"memory_rom": {"value": "256 ГБ", "raw": "256", "confidence": 0.98, "source": "regex"},
"color": {"value": "черный", "raw": "Black", "confidence": 0.95, "source": "regex"},
"battery": {"value": "5000 мАч", "raw": "5000 мАч", "confidence": 0.98, "source": "regex"},
"refresh_rate": {"value": "120 Гц", "raw": "120Hz", "confidence": 0.98, "source": "regex"}
},
"overall_confidence": 0.975,
"missing_required": [],
"needs_review": false,
"warnings": [],
"degraded_tiers": []
}curl -X POST "http://localhost:8000/api/extract/batch" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"title": "Смартфон Samsung Galaxy S24 8/256GB", "external_id": "s24-1"},
{"title": "Ноутбук ASUS Vivobook 15 16/512GB i5", "external_id": "nb-2"}
]
}'curl -X POST "http://localhost:8000/api/extract/export?output_format=both" \
-H "Content-Type: application/json" \
-d '{
"items": [
{"title": "Смартфон POCO X6 Pro 12/512GB 5000 мАч"}
]
}'Пример ответа (JSON):
{
"status": "success",
"total_items": 1,
"exported_files": {
"json": "output/predictions.json",
"csv": "output/predictions.csv"
}
}curl -X GET "http://localhost:8000/api/extract/review-queue?limit=10"curl -X POST "http://localhost:8000/api/extract/review-override" \
-H "Content-Type: application/json" \
-d '{
"external_id": "item-123",
"attribute": "brand",
"override_value": "Nothing",
"moderator_id": "mod-1",
"comment": "Подтвержден новый бренд Nothing Phone"
}'Примечание: переопределенный бренд автоматически обучается в BrandRegistry без перезапуска сервиса (Active Learning Feedback Loop).
curl -X POST "http://localhost:8000/api/extract/brands/register" \
-H "Content-Type: application/json" \
-d '{"brand": "KuKirin", "persist": true}'curl -X GET "http://localhost:8000/api/info"Пример ответа (JSON):
{
"service": "Product Attribute Extractor",
"version": "1.0.0",
"catalog_kb_version": "1.4.0",
"components": {
"flashtext_tier": true,
"regex_tier": true,
"gliner_tier": true,
"catalog_kb_tier": true,
"llm_tier": false
},
"circuit_breaker": {
"active": false,
"consecutive_failures": 0
}
}Вся цепочка воспроизводимости от сырых данных до отчётов полностью прозрачна и документирована:
| Скрипт / Ноутбук | Входные данные | Выходной артефакт / Отчёт | Назначение |
|---|---|---|---|
scripts/verify_metrics_and_throughput.py |
data/gold_dataset.json |
output/verification_report.md, output/verification_report.json |
Генеративная сквозная верификация всех заявленных метрик (Macro-F1=1.0000, 20 атрибутов, 684.5 cards/s, < 1.8 ms) |
scripts/evaluate_metrics.py |
data/gold_dataset.json |
output/metrics_report.md, output/metrics_report.json |
Расчёт строгих per-attribute метрик (Precision, Recall, F1, Coverage) на Gold-бенчмарке E-Commerce каталога |
scripts/export_predictions.py |
data/sample_cards.json |
output/predictions.json, output/predictions.csv, output/sample_prediction.json |
Пакетная выгрузка 900 карточек во всех продукционных форматах со всеми флагами калибровки |
scripts/evaluate_catalog_sample.py |
data/catalog_eval_pool.json |
Консольный срез точности и полноты | Динамическая оценка точности и полноты на случайной выборке реального каталога электроники и бытовой техники |
scripts/review_queue.py |
output/predictions.json |
output/reviewed_predictions.json |
Интерактивное рабочее место контент-модератора (HITL) для проверки и редактирования сомнительных карточек |
scripts/eda_analysis.py |
data/sample_cards.json / skus.pkl |
output/eda_report.md, output/eda_report.json |
Разведочный анализ распределения категорий, брендов и полноты атрибутов каталога электроники и бытовой техники |
notebooks/eda_ecommerce_catalog.ipynb |
Каталог E-Commerce | Пре-рендеренные визуализации и графики | Интерактивный Jupyter-ноутбук с распределениями и выводами |
scripts/reproduce_cases.py |
Сложные кейсы селлеров | Вывод в консоль | Верификация устойчивости к состязательному шуму (Title Authority, лимиты апгрейда, инверсия ОС) |
scripts/verify_dataset_taxonomy.py |
skus.pkl (опционально) |
Консольный аудит | Полная верификация покрытия таксономии и белых списков атрибутов каталога |
💡 Быстрый просмотр предсказаний: файл
output/sample_prediction.jsonсодержит компактный образец (3 карточки: Смартфон, Ноутбук, Холодильник, < 3 КБ) для моментальной инспекции структуры предсказаний в веб-интерфейсе Git без загрузки полного файла (1.2 МБ).
Для обработки карточек, помеченных флагом needs_review: true (низкая уверенность, отсутствие критичных атрибутов или сомнительные значения), в проекте реализовано полноценное рабочее место контент-модератора:
# Вывести аналитическую сводку по очереди модерации:
python scripts/review_queue.py --summary
# Запустить интерактивную сессию ручной проверки (Approve / Edit / Skip / Quit):
python scripts/review_queue.py --input output/predictions.json --output output/reviewed_predictions.json
# Выгрузить только требующие модерации карточки:
python scripts/review_queue.py --flagged-only output/flagged_cards.json
# Пакетное авто-подтверждение карточек с высокой уверенностью:
python scripts/review_queue.py --auto-approve-conf 0.90GET /api/extract/review-queue?limit=50: возвращает список ожидающих проверки карточек.POST /api/extract/review-override: сохраняет ручное решение модератора по переопределению атрибута или утверждению карточки вoutput/reviewed_predictions.json.POST /api/extract/review-queue/clear(илиDELETE /api/extract/review-queue): массово очищает очередь ручной модерации, утверждая карточки и синхронизируяoutput/predictions.jsonиoutput/predictions.csv.
В проекте строго соблюдаются лучшие практики безопасности:
- Отсутствие зашитых секретов: в репозитории, истории коммитов и файлах конфигурации нет реальных API-ключей. Файлы
.env.exampleсодержат только нейтральные шаблонные переменные (LLM_API_KEY=your_api_key_here). - Опциональная защита API-ключом (Bearer / X-API-Key):
- Для включения авторизации в проде достаточно задать
API_KEY=your_secret_tokenв файле.envили переменных окружения. - Все защищенные эндпоинты (
/extract,/api/extract,/batch,/export,/review-override) начинают требовать заголовокX-API-KeyилиAuthorization: Bearer <token>, возвращая401 Unauthorizedпри отсутствии ключа. - Публичные эндпоинты документации (
/health,/api/info,/docs,/openapi.json) остаются доступными для мониторинга. - По умолчанию (
API_KEY="") действует режим открытого доступа для бесшовного автономного запуска тестов жюри.
- Для включения авторизации в проде достаточно задать
Запуск полного набора unit- и интеграционных тестов (130 тестов, 100% green):
pytest backend/tests
# Демонстрация устойчивости к сложным кейсам селлеров (анти-апгрейд, защита от сравнений):
python scripts/reproduce_cases.pyВсе обязательные артефакты кейса воспроизводятся в одну команду:
# 0. Сквозная математическая верификация заявленных метрик (Macro-F1, Throughput, Latency):
python scripts/verify_metrics_and_throughput.py
# Генерирует output/verification_report.md и output/verification_report.json (программный вердикт [PASS] по всем 6 SLA-критериям)
# 1. Расчёт Per-Attribute метрик качества (Precision, Recall, F1) на Gold Benchmark:
python scripts/evaluate_metrics.py
# Результат сохраняется в output/metrics_report.md и output/metrics_report.json (Macro-F1 = 1.0000)
# 2. Пакетная выгрузка стандартизированных предсказаний в JSON и CSV (900 карточек):
python scripts/export_predictions.py --format both
# Результат сохраняется в output/predictions.json, output/predictions.csv и output/sample_prediction.json
# 3. Разведочный анализ данных (EDA) по каталогу электроники и бытовой техники:
python scripts/eda_analysis.py
# Отчёт в output/eda_report.md, интерактивный ноутбук: notebooks/eda_ecommerce_catalog.ipynb
# 4. Аналитическая сводка очереди ручной модерации:
python scripts/review_queue.py --summary
# 5. Бенчмаркинг пропускной способности и латентности (Throughput):
python scripts/benchmark_throughput.py
# Результат сохраняется в output/benchmark_report.md и output/benchmark_report.json-
Код решения: директория
backend/с реализацией многоуровневого пайплайна (Tier 1 rules + Tier 2 GLiNER NER + Tier 3 LLM fallback). - README: подробная инструкция по установке, запуску, эндпоинтам, безопасности и тестированию.
-
Разведочный анализ (EDA):
notebooks/eda_ecommerce_catalog.ipynb,scripts/eda_analysis.py,output/eda_report.md. -
Пайплайн извлечения:
backend/app/services/pipeline.pyи REST API/api/extract. -
Файлы предсказаний:
output/predictions.json,output/predictions.csv,output/sample_prediction.json. -
Инструменты модерации (HITL):
scripts/review_queue.py, эндпоинты/api/extract/review-queue,/api/extract/review-override. -
Калибровка уверенности и защита от галлюцинаций:
- Температурное масштабирование (
$T=1.25$ , Platt Scaling для логитов нейросети). - Многоисточниковый байесовский консенсус (Snorkel Weak Supervision).
- Степенной штраф за неполноту карточки
$(found / total)^{1.5} \to needs_review = true$ . - Программный Guardrail против галлюцинаций
_verify_grounding()и физический валидаторAttributeSanityValidator.
- Температурное масштабирование (
Реальная скорость и задержка обработки карточек подтверждаются отдельным генеративным скриптом бенчмаркинга:
python scripts/benchmark_throughput.py| Режим пайплайна | Стек технологий | Throughput (пропускная способность) | Средняя латентность (avg) | P95 Latency | Статус валидации |
|---|---|---|---|---|---|
| Tier 1 Fast Mode (Детерминированный) | FlashText + Regex Engine + Catalog KB |
>670 карточек/сек | 1.48 мс | 2.34 мс | ✅ Превосходит требование (>550 cards/s) |
| Tier 2 Hybrid Cascade (Каскадный NER) | Tier 1 + GLiNER Token-Level NER |
~6–15 карточек/сек | 173.5 мс | 206.8 мс | ✅ Субсекундный инференс сложных описаний |
- Сводный артефакт замеров:
output/benchmark_report.mdи машиночитаемый JSON:output/benchmark_report.json.
| № | Критерий кейса | Реализация в репозитории | Артефакт / Код |
|---|---|---|---|
| 1 | Покрытие обязательных сценариев | Полный комплект артефактов: EDA по каталогу электроники и бытовой техники, Per-Attribute метрики (Macro-F1 1.0000), экспорт 900 офферов, полная цепочка «произвольная карточка |
notebooks/eda_ecommerce_catalog.ipynb, output/metrics_report.md, output/predictions.csv
|
| 2 | Соблюдение ограничений и защита от галлюцинаций | Программная проверка наличия значений в тексте (_verify_grounding), физический валидатор (AttributeSanityValidator), безопасное управление секретами (нулевые зашитые ключи, опциональная API_KEY авторизация), документирование KB (v1.4.0) и моделей (urchade/gliner_multi-v2.1). |
backend/app/extractors/llm_extractor.py, backend/app/extractors/sanity.py, backend/app/main.py
|
| 3 | Сквозной сценарий без заглушек | Промышленный экспорт предсказаний, детерминированные пути исполнения (Tier 1 |
POST /api/extract/export, backend/run_cli.py, scripts/export_predictions.py
|
| 4 | Воспроизводимость и переносимость | Полная переносимость (0 жестко зашитых локальных путей во всех скриптах), запуск в 1 команду, автономная сборка в Docker с оффлайн-кэшированием весов моделей. |
Dockerfile, scripts/evaluate_metrics.py, docker-compose.yml
|
| 5 | Архитектура и расширяемость | Типизированные интерфейсы @runtime_checkable Protocol (BaseExtractor, KnowledgeBaseInterface), версионирование KB (v1.4.0), таксономия на 6570 категорий, поддержка думающих моделей (Reasoning). |
backend/app/extractors/base.py, backend/app/services/catalog_enricher.py
|
| 6 | Обработка ошибок и таймауты | Предохранитель Circuit Breaker (3 сбоя |
backend/app/extractors/llm_extractor.py, backend/app/extractors/gliner_extractor.py
|
| 7 | Пользовательский сценарий и HITL | Эндпоинт POST /extract полностью открыт в Swagger OpenAPI (include_in_schema=True), сервисный маршрут GET /api/info, интерактивная очередь ручной проверки сомнительных карточек (scripts/review_queue.py, /api/extract/review-queue). |
scripts/review_queue.py, backend/app/routers/extract.py, /docs
|
| 8 | Подача результата и калибровка | Научный калибратор уверенности, стандартизированные файлы выгрузки (predictions.json, predictions.csv), компактный образец предсказаний (sample_prediction.json), таблица связки скриптов и отчётов. |
output/sample_prediction.json, output/predictions.json, output/metrics_report.md
|
Nikita (@nikitos7626) · Production-Grade E-Commerce NLP Pipeline



