README.md

---
title: Russian NER - Извлечение именованных сущностей
emoji: 🏷️
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 6.4.0
app_file: app.py
pinned: false
license: mit
---

# 🏷️ Russian NER — Извлечение именованных сущностей

Веб-приложение для автоматического извлечения именованных сущностей (Named Entity Recognition) из текстов на русском языке.

## 📋 Описание задачи

**Named Entity Recognition (NER)** — это задача извлечения и классификации именованных сущностей в тексте. Приложение распознаёт следующие типы сущностей:

| Тип | Описание | Примеры |
|-----|----------|---------|
| **PER** | Персоны (ФИО) | Владимир Путин, Иван Петров |
| **ORG** | Организации | Яндекс, Сбербанк, МГУ |
| **LOC** | Локации (места) | Москва, Россия, Невский проспект |
| **MISC** | Прочее | Названия событий, продуктов и т.д. |

## 🤖 Выбранные модели

### Модель 1: WikiNEuRal (multilingual)
- **Hugging Face:** [Babelscape/wikineural-multilingual-ner](https://huggingface.co/Babelscape/wikineural-multilingual-ner)
- **Архитектура:** mBERT (multilingual BERT)
- **Почему выбрана:**
  - Поддержка 9 языков, включая русский
  - Распознаёт все 4 типа сущностей (PER, ORG, LOC, MISC)
  - 457K+ загрузок — проверенная сообществом
  - Хорошо работает на текстах общей тематики

### Модель 2: BERT Russian NER
- **Hugging Face:** [Gherman/bert-base-NER-Russian](https://huggingface.co/Gherman/bert-base-NER-Russian)
- **Архитектура:** BERT (multilingual, fine-tuned)
- **Почему выбрана:**
  - Специально обучена для русского языка
  - Высокая точность на русских текстах
  - Альтернатива для сравнения результатов

## ✨ Функциональность

### Базовые функции
- ✅ Ввод текста с ограничением 2000 символов
- ✅ Извлечение сущностей с указанием типа и уверенности
- ✅ Визуальная подсветка сущностей в тексте (цветовая маркировка)
- ✅ Блок примеров для быстрого тестирования
- ✅ Корректная обработка ошибок

### Расширенные функции (на "отлично")
- ✅ **Переключатель моделей** — выбор из 2 моделей через Dropdown
- ✅ **Сравнение моделей** — side-by-side результаты обеих моделей
- ✅ **Измерение latency** — отображение времени обработки в миллисекундах
- ✅ **История запросов** — последние 10 запросов с результатами
- ✅ **Пакетная обработка** — загрузка CSV/TXT и выдача результатов таблицей

## 📊 Примеры работы

### Вход:
```
Владимир Путин встретился с президентом Франции Эммануэлем Макроном в Москве для обсуждения вопросов безопасности.
```

### Выход:
| Текст | Тип | Описание | Уверенность |
|-------|-----|----------|-------------|
| Владимир Путин | PER | Персона (ФИО) | 99.2% |
| Франции | LOC | Локация (место) | 98.7% |
| Эммануэлем Макроном | PER | Персона (ФИО) | 98.9% |
| Москве | LOC | Локация (место) | 99.1% |

### Подсветка в тексте:
- 🔵 **Владимир Путин** — PER
- 🔵 **Эммануэлем Макроном** — PER
- 🟠 **Франции** — LOC
- 🟠 **Москве** — LOC

---

### Вход:
```
Компания Яндекс открыла новый офис в Санкт-Петербурге рядом с Невским проспектом.
```

### Выход:
| Текст | Тип | Описание | Уверенность |
|-------|-----|----------|-------------|
| Яндекс | ORG | Организация | 98.5% |
| Санкт-Петербурге | LOC | Локация (место) | 99.3% |
| Невским проспектом | LOC | Локация (место) | 97.8% |

## ⚠️ Ограничения решения

### Технические ограничения
- **CPU-режим:** Приложение работает без GPU для совместимости с бесплатным Hugging Face Spaces
- **Лимит текста:** Максимум 2000 символов на один запрос
- **Лимит пакетной обработки:** Максимум 100 строк в файле
- **Время загрузки:** Первый запрос может занять 30-60 секунд (загрузка модели)

### Ограничения моделей
- Модели обучены на Wikipedia и новостных текстах — могут хуже работать на сленге, диалектах
- Редкие имена и новые организации могут не распознаваться
- Сложные случаи (омонимия, сокращения) могут давать ошибки
- MISC-категория может быть неточной

### Примеры сложных случаев
| Текст | Проблема |
|-------|----------|
| "Петров выиграл Петрова" | Омонимия: фамилия vs название турнира |
| "ВТБ" | Сокращения могут не распознаваться |
| "пойти в яндекс" | Неформальное написание |

## 🚀 Как использовать

### Локальный запуск
```bash
# Клонировать репозиторий
git clone https://huggingface.co/spaces/YOUR_USERNAME/russian-ner

# Установить зависимости
pip install -r requirements.txt

# Запустить приложение
python app.py
```

### Пакетная обработка
1. Подготовьте CSV-файл с колонкой `text`:
```csv
text
"Иван Петров работает в Яндексе."
"Мария Сидорова живёт в Казани."
```

2. Или TXT-файл (каждая строка — отдельный текст):
```
Иван Петров работает в Яндексе.
Мария Сидорова живёт в Казани.
```

3. Загрузите файл во вкладке "Пакетная обработка"

## 🔒 Правила безопасного использования

⚠️ **ВАЖНО: Не вводите реальные персональные данные!**

- Это демонстрационное приложение
- Данные не сохраняются на сервере, но проходят через модели Hugging Face
- Для обработки конфиденциальных данных используйте локальный запуск
- Не используйте для обработки паспортных данных, медицинских записей и т.п.

## 📁 Структура проекта

```
russian-ner/
├── app.py              # Точка входа приложения
├── config.py           # Константы и настройки
├── processing.py       # Логика NER-обработки
├── ui.py               # Gradio интерфейс
├── requirements.txt    # Зависимости Python
└── README.md           # Документация (этот файл)
```

## 🛠️ Технологии

- **Gradio** — веб-интерфейс
- **Transformers** — работа с моделями NLP
- **PyTorch** — бэкенд для моделей
- **Pandas** — обработка табличных данных

## 📚 Ссылки

- [Hugging Face Transformers](https://huggingface.co/docs/transformers)
- [Gradio Documentation](https://gradio.app/docs/)
- [WikiNEuRal Paper](https://aclanthology.org/2021.findings-emnlp.215/)

## 📝 Лицензия

MIT License