Универсальный анализатор релевантности видео YouTube

Этот скрипт представляет собой гибкий инструмент для анализа данных, который вычисляет релевантность видео YouTube к поисковым запросам. Он считывает данные из Google Sheets, применяет настраиваемые NLP-модели для оценки семантической близости и записывает вычисленные скоры обратно в таблицу. Про этот скрипт я написал статью, почитать можно тут - Как проверить релевантность видео с Ютуб.

Основное преимущество скрипта — его универсальность. Вся бизнес-логика (правила фильтрации спама, контекстуальная адаптация ключевых слов) вынесена в конфигурационный файл .env, что позволяет адаптировать его под любую задачу без изменения кода.

🚀 Ключевые возможности

• Оценка релевантности: Использует TF-IDF и косинусное сходство для вычисления базового балла релевантности (Relevance).
• Конфигурируемый спам-фильтр: Позволяет задать любой список стоп-слов в .env для исключения нерелевантных видео.
• Гибкая контекстуальная оценка: Вычисляет второй, альтернативный скор релевантности (RelevanceContextual) на основе настраиваемых правил, которые модифицируют поисковый запрос в зависимости от данных в определенном столбце (например, страна, категория, город).
• Анализ полного контента: Работает с заголовком, описанием и полным текстом субтитров видео для максимальной точности.
• Прямая интеграция с Google Sheets: Читает исходные данные и записывает результаты в новые столбцы той же таблицы, автоматически расширяя ее при необходимости.

⚙️ Как работает алгоритм

1. Загрузка конфигурации: Скрипт считывает все настройки из файла .env, включая ID таблицы, пути, списки спам-слов и правила для контекстуальной оценки.
2. Анализ и нормализация: Данные из Google Sheets загружаются в DataFrame. Весь текст проходит нормализацию (приведение к нижнему регистру, удаление диакритики).
3. Фильтрация спама: Видео помечаются как спам, если:
   • Их заголовок или описание содержат слова из списка SPAM_KEYWORDS в .env.
   • Их субтитры похожи на текст песни (состоят из коротких строк или музыкальных тегов).
4. Вычисление базовой релевантности (Relevance):
   • Для каждой группы видео, найденной по одному ключевому слову, создается текстовый корпус.
   • Текст (заголовок + первое предложение описания + субтитры) векторизуется и взвешивается через TF-IDF.
   • Вычисляется косинусное сходство между вектором ключевого слова и вектором каждого видео.
5. Вычисление контекстной релевантности (RelevanceContextual):
   • Этот шаг выполняется, только если в .env настроены контекстные правила.
   • Алгоритм повторяется, но поисковый запрос для каждого видео модифицируется согласно правилам из .env. Например, если в ключевом слове есть "триггерное слово", оно заменяется на "контекстное", иначе "контекстное" слово добавляется в конец запроса.
6. Запись результатов: Новые столбцы Relevance и RelevanceContextual создаются в Google Sheets (если их нет), и вычисленные значения записываются в соответствующие ячейки.

🛠️ Подготовка и Установка

Шаг 1: Клонирование репозитория и установка

git clone https://github.com/ВАШ_НИК/youtube-relevance-analyzer.git
cd youtube-relevance-analyzer
python -m venv venv
# Активация: venv\Scripts\activate (Windows) или source venv/bin/activate (macOS/Linux)
pip install -r requirements.txt

Шаг 2: Настройка Google API

• Следуйте инструкциям по созданию Сервисного аккаунта в Google Cloud Console. Вам нужно будет включить Google Sheets API и Google Drive API.
• Скачайте JSON-ключ для вашего сервисного аккаунта. Поместите его в корень проекта.

Шаг 3: Конфигурация .env

1. Создайте копию файла .env.example и переименуйте ее в .env.
2. Откройте .env и заполните все поля вашими данными:
   • Укажите SHEET_ID, WORKSHEET_NAME и CREDENTIALS_JSON_PATH.
   • Настройте SPAM_KEYWORDS под вашу задачу.
   • При необходимости настройте правила для контекстуальной оценки, следуя комментариям в файле.

Шаг 4: Подготовка данных в Google Sheets

• Убедитесь, что ваша таблица содержит столбцы: Title, Description, Keywords, Captions.
• Если вы используете контекстуальную оценку, убедитесь, что в таблице есть столбец, имя которого указано в CONTEXT_COLUMN_NAME.

▶️ Запуск скрипта

python relevance_analyzer.py

Скрипт выведет в консоль информацию о процессе работы. После завершения откройте вашу Google Таблицу, чтобы увидеть новые столбцы с результатами.