Руководство оператора: SEO-генератор текстов

Версия: v7.1 | Сервер: pyp.ru (88.99.12.74) | Дата: 2026-03-24

Сервис автоматически генерирует SEO-тексты для категорий (подборок рецептов) на сайте povar.ru. Для каждой категории система создает заголовок, мета-теги и два текстовых блока, оптимизированных под поисковые системы. Каждый текст проходит проверку уникальности через text.ru Antiplagiat.

Batch-тест (2026-03-24): 34 категории обработаны за ~2.5 часа. 34/34 текстов сгенерированы. Uniqueness 100% у всех. 5 текстов прошли все проверки (success/published), 29 текстов с мягкими замечаниями (draft) — пригодны к публикации после быстрого просмотра.

1. Быстрый старт

Убедитесь, что у вас есть SSH-доступ к серверу 88.99.12.74 и API-ключ (см. README.md).

Шаг 1: Проверьте работоспособность сервиса

curl http://localhost:8001/health

Ожидаемый ответ:

{
  "status": "healthy",
  "service": "seo-python-service",
  "version": "1.0.0",
  "environment": "production"
}

Если ответа нет — см. раздел Устранение неполадок.

Шаг 2: Запустите генерацию для одной категории

Отправьте POST-запрос на webhook:

curl -X POST https://n8n.pyp.ru/webhook/seo-category-v1 \
  -H "Content-Type: application/json" \
  -d '{
    "task_index": "test-borsh-001",
    "category_url": "https://povar.ru/list/borsh/",
    "category_name": "Борщ",
    "target_chars_no_spaces": 2000
  }'

Ответ (задача принята):

{
  "status": "accepted",
  "task_index": "test-borsh-001"
}

Важно: Генерация занимает 3-7 минут (включая проверку уникальности text.ru). Результат придет в Telegram и сохранится в NocoDB.

Шаг 3: Проверьте результат

Через 2-5 минут в Telegram-чат поступит уведомление одного из трёх видов:

Иконка	Значение	Что делать
✅	Текст готов, прошёл все проверки	Забрать из NocoDB, опубликовать
⚠️	Текст создан, но есть замечания	Забрать, прочитать, при необходимости подправить
❌	Ошибка генерации	Посмотреть причину в сообщении, перезапустить

Готовый текст находится в NocoDB, таблица generated_content (подробнее — раздел Просмотр результатов).

2. Добавление задач для генерации

Через n8n webhook (одна категория)

Самый быстрый способ — отправить POST-запрос на webhook (см. Шаг 2 в быстром старте). Обязательные поля:

Поле	Тип	Описание
`task_index`	строка	Уникальный идентификатор задачи (любая строка, например `borsh-2026-03-23`)
`category_url`	строка	URL категории на povar.ru (например `https://povar.ru/list/borsh/` или `/list/borsh/`)

Необязательные поля:

Поле	Тип	По умолчанию	Описание
`category_name`	строка	Парсится из страницы	Название категории (например "Борщ")
`category_type`	строка	`list`	Тип категории: `list` или `menu`
`target_chars_no_spaces`	число	2000	Целевой объём основного текста (символов без пробелов, диапазон 1800-2200)

Через NocoDB (пакетная подготовка)

Откройте NocoDB на сервере
Перейдите в таблицу seo_tasks
Добавьте строки с обязательными полями:

Поле	Обязательное	Описание
`task_index`	Да	Уникальный идентификатор
`category_url`	Да	URL категории на povar.ru
`search_query`	Нет	Поисковый запрос (используется как `category_name`, если тот не указан)
`status`	Да	Установите `pending`

Подсказка: Колонка category_url должна содержать полный URL (начинающийся с https://povar.ru/) или путь (начинающийся с /list/ или /menu/). Пустые значения в category_url будут пропущены при пакетной генерации.

Важно: В поле search_query указывайте название категории без слова "рецепты". Правильно: "Борщ", "Салат с семгой без майонеза". Неправильно: "Борщ рецепты". Это поле используется как название категории в генерации текста.

Через CSV-импорт (API)

Отправьте XLSX или CSV файл с задачами:

curl -X POST http://localhost:8001/api/v1/tasks/import-csv \
  -H "X-API-Key: 6dba6e9e4688bcc60c43720d828ee5e5a2e443e7559b83197fa2f77a0510831a" \
  -F "file=@tasks.xlsx"

Если в файле значения символов указаны как дельты от конкурентов (разница, а не абсолютные числа), добавьте параметр ?deltas_mode=true.

Полное описание формата — см. Справочник API.

3. Запуск генерации

Одна категория через webhook

curl -X POST https://n8n.pyp.ru/webhook/seo-category-v1 \
  -H "Content-Type: application/json" \
  -d '{
    "task_index": "my-task-001",
    "category_url": "https://povar.ru/list/grechaniki/",
    "target_chars_no_spaces": 2000
  }'

Код ответа	Значение	Что делать
202	Задача принята	Ждать уведомления в Telegram (2-5 мин)
400	Ошибка валидации	Проверить `task_index` и `category_url`
409	Задача уже обрабатывалась	См. раздел Перегенерация

Одна категория через прямой API

curl -X POST http://localhost:8001/api/v1/category-generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 6dba6e9e4688bcc60c43720d828ee5e5a2e443e7559b83197fa2f77a0510831a" \
  -d '{
    "task_index": "my-task-001",
    "category_url": "https://povar.ru/list/grechaniki/"
  }'

Важно: Прямой API-вызов — синхронный. Он вернёт результат через 2-5 минут. Webhook — асинхронный (ответ 202 мгновенно, результат в Telegram и NocoDB).

Пакетная генерация

Три способа запустить пакетную обработку всех задач со статусом pending:

Способ 1: Через n8n UI (кнопка)

Откройте n8n: https://n8n.pyp.ru
Найдите workflow seo-category-batch
Нажмите Execute Workflow

Способ 2: Через форму импорта (кнопка "Запустить генерацию")

После импорта CSV/XLSX через форму (http://localhost:8001/api/v1/tasks/import) появится кнопка "Запустить генерацию". Она автоматически запускает пакетную обработку всех импортированных задач.

Способ 3: Через webhook (curl)

curl -X POST https://n8n.pyp.ru/webhook/seo-category-batch

Ответ (мгновенный, обработка в фоне):

{"message": "Workflow was started"}

Batch workflow автоматически: - Читает из NocoDB таблицы seo_tasks все записи со статусом pending и заполненным category_url (до 50 штук за запуск) - Для каждой задачи вызывает генерацию - Обновляет статус задачи в seo_tasks - Отправляет Telegram-уведомление по каждой задаче

Подсказка: Если нужно обработать более 50 задач, запустите повторно — workflow подхватит следующую порцию задач со статусом pending.

4. Перегенерация текста

Каждая задача защищена от повторной обработки (идемпотентность). Ключ хранится в Redis 24 часа. Если вы хотите перегенерировать текст для той же категории, есть два способа:

Способ 1: Параметр `?force=true` (прямой API)

curl -X POST "http://localhost:8001/api/v1/category-generate?force=true" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: 6dba6e9e4688bcc60c43720d828ee5e5a2e443e7559b83197fa2f77a0510831a" \
  -d '{
    "task_index": "my-task-001",
    "category_url": "https://povar.ru/list/grechaniki/"
  }'

Способ 2: Сброс ключа + повторный webhook

Сначала сбросьте ключ идемпотентности:

curl -X DELETE http://localhost:8001/api/v1/category-generate/idempotency/my-task-001 \
  -H "X-API-Key: 6dba6e9e4688bcc60c43720d828ee5e5a2e443e7559b83197fa2f77a0510831a"

Ответ:

{
  "task_index": "my-task-001",
  "key": "seo:cat:my-task-001",
  "deleted": true
}

Затем отправьте webhook повторно (см. раздел Запуск генерации).

Подсказка: Для пакетной перегенерации сбросьте ключи для нужных задач через DELETE, затем запустите seo-category-batch в n8n.

5. Просмотр результатов

NocoDB: таблица `generated_content`

После генерации текст сохраняется в таблицу generated_content. Ключевые поля:

Поле	Описание	Куда вставлять на сайте
`zone_h1`	Заголовок H1 (до 80 символов)	Заголовок `<h1>` страницы категории
`zone_top`	SEO-текст (~400 символов)	Блок текста над листингом рецептов
`zone_txt`	Основной SEO-текст (~2000 символов)	Блок текста под листингом рецептов
`zone_t`	Meta title (до 70 символов)	Тег `<title>` страницы
`meta_description`	Meta description (100-180 символов)	Тег `<meta name="description">`

Статусы результатов

Статус в NocoDB	Как отображается	Что значит	Что делать
`published`	✅	Текст прошёл все 16 проверок	Можно публиковать как есть
`draft`	⚠️	Текст создан, но не прошёл мягкие проверки	Прочитать текст; обычно нужна минимальная правка или можно публиковать
`failed`	❌	Ошибка генерации или критический дефект	Посмотреть таблицу `dlq_errors`, исправить причину, перегенерировать

Дополнительные поля

Поле	Описание
`category_url`	URL категории, для которой сгенерирован текст
`chars_no_spaces`	Количество символов без пробелов в основном тексте
`recipe_count`	Количество рецептов, найденных на странице
`iterations`	Сколько итераций потребовалось (1-4)
`output_type`	Тип результата: `success`, `forward_phase6`, `dlq`
`warnings`	JSON-массив предупреждений (если есть)
`uniqueness_pct`	Уникальность текста в % по text.ru Antiplagiat (обычно 100%)
`textru_status`	Статус проверки text.ru: `passed` (≥95%), `marginal` (85-95%), `failed` (<85%), `skipped`

6. Мониторинг

Telegram-уведомления

Каждая генерация автоматически отправляет уведомление в Telegram-чат. Формат сообщений:

Успех (✅):

✅ Category SEO

📌 test-borsh-001
📊 1920 chars
🍳 49 recipes
🔄 2 iters

Черновик (⚠️):

⚠️ Category SEO (draft)

📌 test-borsh-001
📊 1850 chars
⚠️ ["burstiness: 0.09 < 0.10"]

Ошибка (❌):

❌ Category SEO DLQ

📌 test-borsh-001
📝 https://povar.ru/list/borsh/
❌ QUALITY_HARD_FAIL: stop_words found

Проверка здоровья системы

curl http://localhost:8001/health

Если сервис не отвечает — см. раздел Устранение неполадок.

n8n: просмотр выполнений

Откройте https://n8n.pyp.ru
Перейдите в нужный workflow (seo-category-v1 или seo-category-batch)
Нажмите вкладку Executions
Каждое выполнение показывает: статус (success/error), время, данные на каждом шаге

7. n8n: управление воркфлоу

Доступные воркфлоу

Workflow	Назначение	Триггер	Статус
`seo-category-v1`	Генерация одной категории	Webhook (`POST /webhook/seo-category-v1`)	Active
`seo-category-batch`	Пакетная генерация из NocoDB	Manual (кнопка Execute) + Webhook (`POST /webhook/seo-category-batch`)	Active

Активация / деактивация

Откройте https://n8n.pyp.ru
Найдите workflow в списке
Переключите тумблер Active/Inactive

Важно: Если seo-category-v1 деактивирован, webhook перестанет принимать запросы и вернёт 404.

Логи выполнений

Все выполнения сохраняются в n8n. Для просмотра: откройте workflow → вкладка Executions. Для каждого шага видны входные и выходные данные.

8. Устранение неполадок

Симптом	Причина	Решение
`curl /health` не отвечает	Контейнер Python-сервиса остановлен	`cd /opt/seo-python-service && docker compose -f docker-compose.seo.yml up -d`
Webhook возвращает 409	Задача уже обрабатывалась (идемпотентность, TTL 24 часа)	Сбросить ключ: `curl -X DELETE http://localhost:8001/api/v1/category-generate/idempotency/{task_index} -H "X-API-Key: API_KEY"`
Webhook возвращает 404	Workflow `seo-category-v1` деактивирован	Активировать в n8n UI
Текст в статусе `draft`	Мягкие проверки не пройдены (стиль, буквы ё, леммы)	Прочитать текст, при необходимости отредактировать. Обычно пригоден к публикации.
Текст в статусе `failed`	Критическая ошибка генерации	Посмотреть таблицу `dlq_errors` в NocoDB. Типичные причины: API timeout, стоп-слова, ошибка LLM. Перегенерировать через `?force=true`
Telegram не присылает уведомления	Бот заблокирован или сервис не запущен	Проверить `/health`. Если OK — проверить логи: `docker logs seo-python-service --tail 50`
Batch workflow не обрабатывает задачи	Нет задач с `status=pending` и заполненным `category_url`	Проверить в NocoDB: таблица `seo_tasks`, фильтр `status = pending`
Все запросы возвращают ошибки	Circuit breaker открыт (5 ошибок подряд)	Подождать 5 минут. Сервис автоматически попробует восстановиться

Просмотр логов

# Последние 50 строк логов Python-сервиса
docker logs seo-python-service --tail 50

# Логи в реальном времени
docker logs seo-python-service -f

Перезапуск сервиса

cd /opt/seo-python-service
docker compose -f docker-compose.seo.yml up -d --force-recreate

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

Конвейер генерации

Система обрабатывает каждую категорию в четыре этапа:

Генератор — создает черновик SEO-текста на основе названия категории, списка рецептов и SEO-фраз
Редактор — улучшает текст: делает его живым, добавляет разнообразие в длину предложений, убирает канцеляризмы
Автоматические проверки — 16 программных проверок качества (без участия LLM): объем текста, покрытие SEO-фраз, отсутствие AI-маркеров, отсутствие первого лица и другие
Проверка уникальности (text.ru) — текст проверяется через Antiplagiat API (уникальность ≥95% для публикации)

Если проверки на этапе 3 выявляют критические проблемы, текст возвращается Редактору на доработку (до 4 итераций). Проверка text.ru выполняется один раз на финальном тексте.

Статусы результатов

output_type	Статус в NocoDB	Описание
success	`generated` (seo_tasks) / `published` (generated_content)	Текст прошел все 16 проверок и проверку уникальности text.ru (≥95%). Готов к публикации
forward_phase6	`draft`	Текст создан, но не прошел некоторые мягкие проверки (SEO-покрытие, длина zone_top) или уникальность 85-95%. Обычно пригоден к публикации после быстрого просмотра
dlq	`failed`	Текст не удалось создать, не прошел критические проверки, или уникальность <85%. Требует перегенерации

Примечание (v7.1): В batch-тесте 34 категорий типичное распределение: ~15% success, ~85% draft. Draft-тексты — полноценные тексты с мелкими замечаниями (например, SEO-покрытие zone_top 67% вместо 70%). Все тексты проходят text.ru с uniqueness=100%.

Идемпотентность

Каждый task_index может быть обработан только один раз в течение 24 часов. Это защита от случайного дублирования. Для повторной обработки используйте ?force=true или сбросьте ключ через DELETE-запрос (см. раздел Перегенерация).

10. Глоссарий

Термин	Описание
`zone_h1`	Заголовок H1 страницы категории
`zone_top`	SEO-текст над листингом рецептов (~400 символов)
`zone_txt`	Основной SEO-текст под листингом рецептов (~2000 символов)
`zone_t`	Meta title страницы (тег `<title>`)
`meta_description`	Meta description (тег `<meta name="description">`)
DLQ	Dead Letter Queue — очередь ошибок. Задачи, которые не удалось обработать
`forward_phase6`	Результат генерации, требующий ручной проверки (статус `draft` в NocoDB)
Идемпотентность	Защита от повторной обработки одной и той же задачи
Circuit breaker	Автоматическая защита: после 5 ошибок подряд система приостанавливает запросы к внешнему API на 5 минут
Webhook	URL, на который можно отправить POST-запрос для запуска обработки
Batch	Пакетная обработка — генерация нескольких категорий за один запуск
LLM	Large Language Model — языковая модель (Claude Sonnet 4.5), используемая для генерации текста
text.ru	Сервис проверки уникальности текста (Antiplagiat) и AI-детекции. Порог уникальности: ≥95% для публикации
n8n	Платформа автоматизации, управляющая воркфлоу генерации
NocoDB	База данных (аналог Airtable) для хранения задач и результатов

Руководство оператора: SEO-генератор текстов

1. Быстрый старт

Шаг 1: Проверьте работоспособность сервиса

Шаг 2: Запустите генерацию для одной категории

Шаг 3: Проверьте результат

2. Добавление задач для генерации

Через n8n webhook (одна категория)

Через NocoDB (пакетная подготовка)

Через CSV-импорт (API)

3. Запуск генерации

Одна категория через webhook

Одна категория через прямой API

Пакетная генерация

4. Перегенерация текста

Способ 1: Параметр ?force=true (прямой API)

Способ 2: Сброс ключа + повторный webhook

5. Просмотр результатов

NocoDB: таблица generated_content

Статусы результатов

Дополнительные поля

6. Мониторинг

Telegram-уведомления

Проверка здоровья системы

n8n: просмотр выполнений

7. n8n: управление воркфлоу

Доступные воркфлоу

Активация / деактивация

Логи выполнений

8. Устранение неполадок

Просмотр логов

Перезапуск сервиса

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

Конвейер генерации

Статусы результатов

Идемпотентность

10. Глоссарий

Способ 1: Параметр `?force=true` (прямой API)

NocoDB: таблица `generated_content`