Wordstat Semantic Analyzer

Автоматическая очистка семантического ядра из Яндекс.Вордстат с помощью машинного обучения и LLM.

Статус: Спецификация проекта. Код ещё не написан — это детальное ТЗ для разработки.

Содержание

Что это и зачем нужно
Как это работает
Требования
Установка с нуля (для новичков)
Подготовка данных
Настройка конфигурации
Запуск
Результаты
Структура проекта
FAQ и решение проблем

Что это и зачем нужно

Проблема

Когда вы собираете семантическое ядро для SEO или контекстной рекламы через Яндекс.Вордстат, вы получаете тысячи запросов. Например, для ниши «доставка цветов» вы получите:

Релевантные запросы (ваши потенциальные клиенты):

«заказать букет роз с доставкой»
«цветы на день рождения купить»
«доставка цветов круглосуточно москва»

Нерелевантные запросы (мусор):

«как вырастить розы на даче» — это садовод, не покупатель
«цветы из бисера своими руками» — DIY-мастер, не клиент
«цветок женское счастье пересадка» — уход за комнатными растениями

Вручную разбирать 10 000–20 000 запросов — это дни монотонной работы.

Решение

Этот инструмент автоматически классифицирует запросы на три категории:

Релевантные — можно использовать для SEO/рекламы
Нерелевантные — мусор, удалить
Неопределённые — требуют ручной проверки (обычно 5–10%)

Как это работает

Пайплайн состоит из 5 этапов:

Этап 1: Предфильтрация (без AI)

Быстрая очистка очевидного мусора:

Удаление стоп-слов (порно, казино, «скачать бесплатно»)
Удаление запросов с телефонами, email, URL
Удаление слишком коротких запросов
Удаление дубликатов

Этап 2: Векторизация

Преобразование текстовых запросов в числовые векторы (embeddings). Это позволяет измерять «похожесть» запросов математически.

Этап 3: Кластеризация

Группировка похожих запросов в кластеры. Например:

Кластер «цветы + праздник»: день рождения, свадьба, 8 марта
Кластер «цветы + уход»: полив, пересадка, болезни

Этап 4: LLM-классификация

Claude AI анализирует каждый кластер и классифицирует запросы на основе описания вашей ниши.

Этап 5: Ревизия

Повторный анализ неопределённых запросов с дополнительным контекстом.

Требования

Python 3.9 или новее — язык программирования
8 GB RAM — для обработки embeddings (рекомендуется 16 GB для больших выгрузок)
API-ключ Anthropic — для классификации через Claude AI (платный, ~$1-5 за 20K запросов)
Опционально: API-ключ OpenAI — для более качественных embeddings

Установка с нуля (для новичков)

Если вы никогда не работали с Python — не переживайте! Следуйте инструкции шаг за шагом.

Шаг 1: Установка Python

На macOS

Вариант A: Через Homebrew (рекомендуется)

Откройте приложение Terminal (найдите через Spotlight: Cmd + Пробел, введите "Terminal")

Установите Homebrew (менеджер пакетов), если его нет:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Установите Python:
```
brew install python@3.11
```
Проверьте установку:
```
python3 --version
```
Должно показать что-то вроде Python 3.11.x

Вариант B: Через официальный установщик

Перейдите на https://www.python.org/downloads/
Скачайте последнюю версию для macOS
Запустите .pkg файл и следуйте инструкциям
После установки откройте Terminal и проверьте:
```
python3 --version
```

На Windows

Перейдите на https://www.python.org/downloads/
Нажмите «Download Python 3.x.x»
Запустите скачанный .exe файл
ВАЖНО: На первом экране установщика поставьте галочку ☑️ «Add Python to PATH»
Нажмите «Install Now»
После установки откройте PowerShell или Командную строку и проверьте:
```
python --version
```

На Linux (Ubuntu/Debian)

sudo apt update
sudo apt install python3 python3-pip python3-venv
python3 --version

Шаг 2: Скачивание проекта

Вариант A: Через Git (рекомендуется)

Если у вас установлен Git:

# Перейдите в папку, где хотите разместить проект
cd ~/Projects

# Клонируйте репозиторий
git clone https://github.com/vasilievyakov/wordstat-analyzer.git

# Перейдите в папку проекта
cd wordstat-analyzer

Как установить Git, если его нет:

macOS: brew install git или скачайте с https://git-scm.com/download/mac
Windows: скачайте с https://git-scm.com/download/win
Linux: sudo apt install git

Вариант B: Скачать ZIP-архив

Перейдите на страницу репозитория на GitHub
Нажмите зелёную кнопку «Code»
Выберите «Download ZIP»
Распакуйте архив в удобную папку
Откройте терминал и перейдите в эту папку:
```
cd ~/Downloads/wordstat-analyzer-main
```

Шаг 3: Создание виртуального окружения

Что это такое? Виртуальное окружение — это изолированная «песочница» для проекта. Все библиотеки устанавливаются только для этого проекта и не мешают другим программам на компьютере.

Почему это важно? Разные проекты могут требовать разные версии библиотек. Виртуальное окружение предотвращает конфликты.

# Убедитесь, что вы в папке проекта
cd wordstat-analyzer

# Создайте виртуальное окружение (выполнить один раз)
python3 -m venv venv

# Активируйте его

Активация на macOS/Linux:

source venv/bin/activate

Активация на Windows (PowerShell):

.\venv\Scripts\Activate.ps1

Активация на Windows (Командная строка):

venv\Scripts\activate.bat

После активации в начале строки терминала появится (venv) — это значит, что окружение активно.

Важно: Каждый раз, когда вы открываете новое окно терминала и хотите работать с проектом, нужно снова активировать окружение командой выше.

Шаг 4: Установка зависимостей

После активации виртуального окружения установите необходимые библиотеки:

pip install -r requirements.txt

Это займёт некоторое время — pip скачает и установит все библиотеки из файла requirements.txt.

Возможные проблемы и решения:

Ошибка «pip not found»:

python3 -m pip install -r requirements.txt

Ошибка с hdbscan на Windows: Установите Microsoft Visual C++ Build Tools: https://visualstudio.microsoft.com/visual-cpp-build-tools/
Ошибка с памятью при установке sentence-transformers:
```
pip install --no-cache-dir sentence-transformers
```

Шаг 5: Настройка API-ключей

Для работы классификатора нужен API-ключ Anthropic (Claude AI).

Получение API-ключа Anthropic

Перейдите на https://console.anthropic.com/
Зарегистрируйтесь или войдите
Перейдите в раздел API Keys
Нажмите Create Key
Скопируйте ключ (он показывается только один раз!)

Установка ключа

Вариант A: Через переменную окружения (рекомендуется)

macOS/Linux — добавьте в файл ~/.zshrc или ~/.bashrc:

export ANTHROPIC_API_KEY="sk-ant-ваш-ключ-здесь"

Затем перезапустите терминал или выполните:

source ~/.zshrc

Windows — через PowerShell:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-ваш-ключ-здесь", "User")

Вариант B: Создать файл .env

В папке проекта создайте файл .env:

ANTHROPIC_API_KEY=sk-ant-ваш-ключ-здесь

Важно: Никогда не добавляйте файл .env в Git! Он уже добавлен в .gitignore.

Подготовка данных

Экспорт из Яндекс.Вордстат

Перейдите в Яндекс.Вордстат
Введите базовый запрос вашей ниши
Экспортируйте результаты в CSV/Excel

Формат входного файла

Создайте файл data/input.csv с таким содержимым:

query,frequency
заказать букет роз с доставкой,1200
цветы на день рождения,890
как вырастить розы,450
доставка цветов москва,2100
цветы из бисера своими руками,320

Обязательная колонка:

query — текст поискового запроса

Опциональная колонка:

frequency — частота запроса (если есть, позволяет фильтровать низкочастотные)

Кодировка файла

Файл должен быть в кодировке UTF-8. Если у вас проблемы с русскими буквами:

Откройте файл в Excel
Сохраните как → CSV UTF-8 (разделитель — запятая)

Или в Google Sheets:

Файл → Скачать → CSV

Настройка конфигурации

Создание конфига

Скопируйте пример конфигурации:

cp config.example.yaml config.yaml

Редактирование конфига

Откройте config.yaml в любом текстовом редакторе и заполните:

# ОБЯЗАТЕЛЬНО: Опишите вашу нишу
niche:
  name: "доставка цветов"

  # Подробное описание — чем точнее, тем лучше результат
  description: |
    Интернет-магазин доставки цветов и букетов.
    Целевая аудитория: люди, которые хотят КУПИТЬ и ЗАКАЗАТЬ цветы
    с доставкой на дом, в офис, на мероприятие.

    Релевантно: покупка букетов, заказ доставки, цены на цветы,
    выбор цветов для подарка.

    НЕ релевантно: выращивание цветов, уход за растениями,
    DIY и рукоделие с цветами, ботаника.

  # Примеры релевантных запросов (5-10 штук)
  relevant_examples:
    - "заказать букет роз с доставкой"
    - "цветы на день рождения купить"
    - "доставка цветов круглосуточно"
    - "букет пионов цена москва"
    - "цветы в коробке заказать"

  # Примеры НЕрелевантных запросов (5-10 штук)
  irrelevant_examples:
    - "как вырастить розы на даче"
    - "цветы из бисера своими руками"
    - "комнатные растения уход"
    - "цветок женское счастье пересадка"
    - "розы болезни и вредители"

# Настройки входных данных
input:
  file: "data/input.csv"
  query_column: "query"
  frequency_column: "frequency"  # Закомментируйте, если нет частоты

# Настройки фильтрации
processing:
  min_frequency: 10      # Убрать запросы с частотой < 10
  min_words: 2           # Убрать запросы короче 2 слов
  batch_size: 300        # Размер батча для LLM

# Embeddings (векторизация)
embeddings:
  provider: "local"      # "local" = бесплатно, "openai" = лучше качество

# Кластеризация
clustering:
  min_cluster_size: 10   # Минимум запросов в кластере

# Выходные данные
output:
  dir: "data/output"

Советы по описанию ниши

Плохо:

description: "продажа цветов"

Хорошо:

description: |
  Интернет-магазин доставки цветов в Москве и МО.
  Продаём: букеты, композиции, цветы в горшках, подарочные наборы.
  Наши клиенты: люди, которые хотят купить цветы с доставкой
  на праздник, день рождения, без повода.

  Включаем: запросы о покупке, заказе, доставке, ценах на цветы.
  Исключаем: выращивание, уход за растениями, садоводство,
  DIY, поделки, ботаника, болезни растений.

Запуск

Примечание: Код ещё не написан. Ниже — планируемый интерфейс.

# Полный прогон
python run.py --config config.yaml

# Только предфильтрация и кластеризация (без LLM, бесплатно)
python run.py --config config.yaml --until clustering

# Продолжить с классификации (если уже есть embeddings)
python run.py --config config.yaml --from classifier

# Посмотреть статистику
python run.py --stats

Результаты

После запуска в папке data/output/ появятся:

Файл	Описание
`relevant.csv`	Релевантные запросы — можно использовать
`irrelevant.csv`	Мусор — удалить
`uncertain.csv`	Неопределённые — проверить вручную

Формат выходных файлов

query,frequency,category,reason,cluster_id
заказать букет роз,1200,relevant,"покупка цветов с доставкой",12
как вырастить розы,450,irrelevant,"садоводство, не покупка",34
цветы подарок,890,relevant,"подарочные цветы",12

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

wordstat-analyzer/
├── README.md              # Этот файл
├── CLAUDE.md              # Техническая спецификация для разработки
├── requirements.txt       # Зависимости Python
├── config.example.yaml    # Пример конфигурации
├── config.yaml            # Ваша конфигурация (создать самостоятельно)
│
├── config/
│   ├── stopwords.txt      # Список стоп-слов для фильтрации
│   └── garbage_patterns.txt # Regex-паттерны для фильтрации
│
├── src/                   # Исходный код (будет добавлен)
│   ├── pipeline.py        # Главный оркестратор
│   ├── prefilter.py       # Этап 1: предфильтрация
│   ├── embeddings.py      # Этап 2: векторизация
│   ├── clustering.py      # Этап 3: кластеризация
│   ├── classifier.py      # Этап 4: LLM-классификация
│   └── revision.py        # Этап 5: ревизия
│
├── data/
│   ├── input.csv          # Входные данные (добавить самостоятельно)
│   └── output/            # Результаты
│
└── logs/                  # Логи выполнения

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

Общие вопросы

Q: Сколько стоит использование?

A: Embeddings через local — бесплатно. Классификация через Claude AI — примерно $1–5 за 20 000 запросов (зависит от длины запросов и описания ниши).

Q: Можно без API-ключа?

A: Можно запустить этапы 1–3 (предфильтрация, embeddings, кластеризация) — они бесплатны. Но финальная классификация требует LLM.

Q: Какой компьютер нужен?

A: Минимум 8 GB RAM. Для 20K+ запросов рекомендуется 16 GB. Процессор и видеокарта не критичны.

Ошибки и их решения

Ошибка: ModuleNotFoundError: No module named 'xxx'

Причина: Не активировано виртуальное окружение или не установлены зависимости.

Решение:

source venv/bin/activate  # или .\venv\Scripts\activate на Windows
pip install -r requirements.txt

Ошибка: ANTHROPIC_API_KEY not found

Причина: Не настроен API-ключ.

Решение: См. раздел Настройка API-ключей.

Ошибка: UnicodeDecodeError при чтении CSV

Причина: Файл не в UTF-8.

Решение: Пересохраните файл в UTF-8 (см. раздел Кодировка файла).

Ошибка: MemoryError при создании embeddings

Причина: Недостаточно RAM для обработки всех запросов.