mawo-natasha

NER и семантический анализ для русского языка с Navec embeddings и интеграцией SlovNet.

Возможности

• Named Entity Recognition: Извлечение персон, мест и организаций
• Navec Embeddings: 250K слов, 300 измерений, ~50МБ
• Семантический анализ: Векторные представления для русских слов
• Работа офлайн: После первой установки не требует интернета
• Интеграция с SlovNet: Опциональная интеграция с mawo-slovnet
• Качество: +30% точности семантического анализа

Установка

pip install mawo-natasha

С дополнительными зависимостями

# С интеграцией SlovNet
pip install mawo-natasha[slovnet]

# Всё вместе
pip install mawo-natasha[all]

Быстрый старт

Извлечение именованных сущностей

from mawo_natasha import MAWODoc

# Создаём документ
doc = MAWODoc("Александр Пушкин родился в Москве.")

# Сегментируем на предложения и токены
doc.segment()

# Извлекаем именованные сущности
print(f"Токены: {doc.tokens}")
print(f"Предложения: {doc.sents}")

Семантические векторы (Navec)

from mawo_natasha import RealRussianEmbedding

# Создаём embedding с Navec
embedding = RealRussianEmbedding(use_navec=True)

# Получаем векторное представление текста
doc = embedding("Привет, как дела?")

# Работаем с векторами
for token, emb in zip(doc.tokens, doc.embeddings):
    print(f"{token}: вектор размерностью {emb.shape}")
    # Привет: вектор размерностью (300,)
    # как: вектор размерностью (300,)
    # дела: вектор размерностью (300,)

Семантическая близость

from mawo_natasha import RealRussianEmbedding
import numpy as np

embedding = RealRussianEmbedding(use_navec=True)

# Получаем векторы для слов
vec1 = embedding("кот").embeddings[0]
vec2 = embedding("кошка").embeddings[0]
vec3 = embedding("собака").embeddings[0]

# Вычисляем косинусное сходство
def cosine_sim(v1, v2):
    return np.dot(v1, v2) / (np.linalg.norm(v1) * np.linalg.norm(v2))

print(f"кот ↔ кошка: {cosine_sim(vec1, vec2):.3f}")   # ~0.85 (высокое)
print(f"кот ↔ собака: {cosine_sim(vec1, vec3):.3f}")  # ~0.65 (среднее)

Продвинутое использование

Интеграция с SlovNet

from mawo_natasha import MAWODoc
from mawo_slovnet import NewsNERTagger

# Создаём документ
doc = MAWODoc("Владимир Путин встретился с министром обороны.")

# Используем SlovNet для NER
ner = NewsNERTagger()
markup = ner(doc.text)

# Добавляем NER-метки в документ
doc.spans = markup.spans

# Выводим найденные сущности
for span in doc.spans:
    print(f"{span.text} -> {span.type}")
    # Владимир Путин -> PER
    # министром -> (морфология)

Навигация по документу

from mawo_natasha import MAWODoc

text = """
Александр Сергеевич Пушкин родился в Москве.
Он написал "Евгений Онегин" в 1833 году.
"""

doc = MAWODoc(text)
doc.segment()

# Проходим по предложениям
for i, sent in enumerate(doc.sents):
    print(f"Предложение {i+1}: {sent}")

# Работаем с токенами
print(f"Всего токенов: {len(doc.tokens)}")
print(f"Первые 5 токенов: {doc.tokens[:5]}")

Кастомная обработка

from mawo_natasha import MAWODoc

class CustomDoc(MAWODoc):
    def custom_analysis(self):
        """Свой метод анализа."""
        # Подсчёт слов
        word_count = len([t for t in self.tokens if t.isalpha()])

        # Подсчёт предложений
        sent_count = len(self.sents)

        return {
            "words": word_count,
            "sentences": sent_count,
            "avg_words_per_sent": word_count / sent_count if sent_count > 0 else 0
        }

doc = CustomDoc("Это первое предложение. Это второе. Третье здесь.")
doc.segment()
stats = doc.custom_analysis()
print(stats)
# {'words': 7, 'sentences': 3, 'avg_words_per_sent': 2.33}

Navec Embeddings

Характеристики

• Словарь: 250,000 русских слов
• Размерность: 300 измерений
• Размер: ~50МБ
• Источник: Обучен на новостных корпусах
• Качество: Оптимизировано для русского языка

Автоматическая загрузка

from mawo_natasha import download_navec

# Загрузить Navec embeddings (если ещё не скачаны)
download_navec()

Fallback режим

Если Navec недоступен, используются случайные векторы:

from mawo_natasha import RealRussianEmbedding

# Попытка использовать Navec
embedding = RealRussianEmbedding(use_navec=True)

# Если Navec не найден, автоматически fallback на random embeddings
doc = embedding("тест")
# Работает, но качество ниже

Файлы данных

Embeddings хранятся в:

~/.cache/mawo_natasha/embeddings/
└── navec_news_v1/          # Navec embeddings (~50МБ)

Или в пакете:

mawo_natasha/
├── embeddings/
│   └── navec_news_v1_1B_250K_300d_100q.tar  # Navec
├── dictionaries/           # Служебные словари
└── models/                 # Дополнительные модели

Производительность

Скорость обработки

Использование памяти

Типы сущностей

При интеграции с SlovNet распознаются:

• PER (Персона): Имена, фамилии, отчества
• LOC (Место): Города, страны, улицы
• ORG (Организация): Компании, учреждения

Интеграция с другими MAWO библиотеками

С mawo-pymorphy3

from mawo_natasha import MAWODoc
from mawo_pymorphy3 import create_analyzer

doc = MAWODoc("Мама мыла раму.")
doc.segment()

# Морфологический анализ токенов
morph = create_analyzer()
for token in doc.tokens:
    parses = morph.parse(token)
    if parses:
        print(f"{token}: {parses[0].tag}")

С mawo-razdel

from mawo_natasha import MAWODoc
from mawo_razdel import sentenize

text = "Первое предложение. Второе предложение."

# Natasha сегментация
doc = MAWODoc(text)
doc.segment()
natasha_sents = doc.sents

# Razdel сегментация
razdel_sents = [s.text for s in sentenize(text)]

print(f"Natasha: {natasha_sents}")
print(f"Razdel: {razdel_sents}")

Источники

Основано на:

• Natasha от Alexander Kukushkin (github.com/natasha/natasha)
• Navec от Alexander Kukushkin (github.com/natasha/navec)
• Обучение: Новостные корпуса (RIA, Lenta, etc.)

Решение проблем

Navec не загружается

# Попробуйте загрузить вручную
from mawo_natasha import download_navec
download_navec(force=True)

Ошибка импорта

pip install --upgrade mawo-natasha

Медленная первая загрузка

Это нормально - Navec скачивается один раз (~50МБ). Последующие запуски моментальны.

Разработка

Настройка окружения

git clone https://github.com/mawo-ru/mawo-natasha.git
cd mawo-natasha
pip install -e ".[dev]"

Запуск тестов

pytest tests/

Благодарности и Upstream-проект

mawo-natasha является форком оригинального проекта Natasha, разработанного Александром Кукушкиным (@kuk).

Оригинальный проект

• Репозиторий: https://github.com/natasha/natasha
• Автор: Alexander Kukushkin
• Лицензия: MIT
• Copyright: (c) 2016 Alexander Kukushkin

Связанные проекты Natasha

Этот проект также использует другие компоненты экосистемы Natasha:

• Navec (embeddings): Copyright (c) 2017 Alexander Kukushkin
• SlovNet (модели): Copyright (c) 2017 Alexander Kukushkin
• Razdel (токенизация): Copyright (c) 2017 Alexander Kukushkin

Улучшения MAWO

• Интеграция с Navec embeddings: Автоматическая загрузка и работа
• Offline-first архитектура: Полная автономность после первой загрузки
• Интеграция с mawo-slovnet: Seamless работа с другими библиотеками MAWO
• Оптимизация памяти: Эффективное использование ресурсов (~50МБ)

Полная информация об авторстве: см. ATTRIBUTION.md

Лицензия

MIT License - см. LICENSE файл.

Этот проект полностью соответствует MIT лицензии оригинального проекта natasha и сохраняет все оригинальные copyright notices.

Ссылки

• GitHub: https://github.com/mawo-ru/mawo-natasha
• PyPI: https://pypi.org/project/mawo-natasha/
• Проблемы: https://github.com/mawo-ru/mawo-natasha/issues
• Оригинальная Natasha: https://github.com/natasha/natasha
• Navec: https://github.com/natasha/navec

Сделано с ❤️ командой MAWO