Spaces:

lsdf
/

ai-seo-analyzer

Sleeping

{
  "target_text": "string (обязательно)",
  "competitors": ["string"] (обязательно, может быть пустым массивом),
  "keywords": ["string"] (обязательно, может быть пустым массивом),
  "language": "string" (опционально, по умолчанию "en")
}

Параметры:

Параметр	Тип	Обязательный	Описание
`target_text`	string	Да	Текст пользователя для анализа
`competitors`	array[string]	Да	Массив текстов конкурентов
`keywords`	array[string]	Да	Массив ключевых фраз (каждая фраза - отдельный элемент)
`language`	string	Нет	Код языка: `en`, `ru`, `de`, `es`, `it`

Ответ

Статус: 200 OK

Content-Type: application/json

{
  "ngram_stats": {
    "unigrams": [
      {
        "ngram": "string",
        "target_count": 0,
        "competitor_avg": 0.0
      }
    ],
    "bigrams": [...],
    "trigrams": [...],
    "quadgrams": [...]
  },
  "bm25_recommendations": [
    {
      "word": "string",
      "type": "1-gram" | "2-gram" | "3-gram",
      "my_score": 0.0,
      "avg_comp_score": 0.0,
      "action": "ok" | "add" | "remove",
      "count": 0
    }
  ],
  "bert_analysis": {
    "global_scores": [
      {
        "name": "string",
        "score": 0.0,
        "is_me": true
      }
    ],
    "detailed": [
      {
        "phrase": "string",
        "my_max_score": 0.0,
        "comp_max_score": 0.0,
        "status": "ok" | "good" | "warning" | "bad",
        "recommendation": "string",
        "my_top_chunks": [
          {
            "text": "string",
            "score": 0.0
          }
        ],
        "comp_top_chunks": [
          {
            "text": "string",
            "score": 0.0,
            "source": "string"
          }
        ]
      }
    ]
  }
}

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

ngram_stats

Статистика по N-граммам (1-4 слова).

Поля:

ngram - текст N-граммы (лемматизированный)
target_count - количество вхождений в целевом тексте
competitor_avg - среднее количество вхождений у конкурентов

Сортировка: По максимальному значению (target_count или competitor_avg)

bm25_recommendations

Рекомендации по оптимизации частоты слов/фраз с использованием алгоритма BM25.

Особенности алгоритма:

Полная декомпозиция фраз: Каждая ключевая фраза автоматически разбивается на все возможные под-н-граммы длиной от 1 до 3 слов
- Пример: фраза "chicken road casino" анализируется как:
  - Униграммы: "chicken", "road", "casino"
  - Биграммы: "chicken road", "road casino"
  - Триграммы: "chicken road casino"
- Это позволяет находить не только точные совпадения, но и частичные вхождения ключевых фраз
- Дубликаты автоматически удаляются

Поля:

word - слово или фраза (лемматизированная)
type - тип: "1-gram", "2-gram", "3-gram"
my_score - BM25 score в целевом тексте
avg_comp_score - средний BM25 score у конкурентов
action - рекомендуемое действие:
- "ok" - частота в норме
- "add" - нужно добавить (ваш score ниже среднего конкурентов)
- "remove" - нужно убрать (ваш score значительно выше среднего конкурентов)
count - рекомендуемое количество добавлений/удалений (рассчитывается на основе разницы скоров)

Пороги для действий:

Униграммы: порог 0.5
Биграммы: порог 0.25
Триграммы: порог 0.15

Сортировка:

Сначала проблемные рекомендации (add/remove)
Затем по длине фразы (длинные фразы важнее)
Затем алфавитно

bert_analysis

Семантический анализ с использованием BERT.

global_scores:

name - название текста ("Мой текст" или "Конкурент #N")
score - средний максимальный score по всем ключевым фразам (0.0 - 1.0)
is_me - флаг, является ли это целевым текстом

detailed: Для каждой ключевой фразы:

phrase - исходная ключевая фраза
my_max_score - максимальный score в целевом тексте (0.0 - 1.0)
comp_max_score - максимальный score у конкурентов
status - статус:
- "good" - score >= 0.7
- "ok" - 0.5 <= score < 0.7
- "warning" - score < 0.5 или конкуренты лучше на 0.1+
- "bad" - score < 0.5
recommendation - текстовое описание рекомендации
my_top_chunks - топ-5 наиболее релевантных предложений из целевого текста
comp_top_chunks - топ-5 наиболее релевантных предложений у конкурентов (с указанием источника)

Примеры запросов

cURL:

curl -X POST "http://127.0.0.1:8001/analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "target_text": "Это мой текст для анализа SEO.",
    "competitors": ["Текст конкурента номер один.", "Текст конкурента номер два."],
    "keywords": ["SEO анализ", "текст"],
    "language": "ru"
  }'

Python:

import requests

response = requests.post(
    "http://127.0.0.1:8001/analyze",
    json={
        "target_text": "Это мой текст для анализа SEO.",
        "competitors": ["Текст конкурента номер один.", "Текст конкурента номер два."],
        "keywords": ["SEO анализ", "текст"],
        "language": "ru"
    }
)

data = response.json()
print(data)

JavaScript:

fetch('http://127.0.0.1:8001/analyze', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    target_text: "Это мой текст для анализа SEO.",
    competitors: ["Текст конкурента номер один.", "Текст конкурента номер два."],
    keywords: ["SEO анализ", "текст"],
    language: "ru"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Ошибки

400 Bad Request Неверный формат запроса или отсутствуют обязательные поля.

422 Unprocessable Entity Ошибка валидации данных (например, неверный код языка).

500 Internal Server Error Внутренняя ошибка сервера (проблемы с моделями, памятью и т.д.).

Интерактивная документация

После запуска приложения доступны:

Swagger UI: http://127.0.0.1:8001/docs
ReDoc: http://127.0.0.1:8001/redoc

Эти интерфейсы позволяют:

Просматривать все endpoints
Тестировать API прямо в браузере
Видеть схемы данных
Просматривать примеры запросов и ответов

API Документация

Обзор

Базовый URL

Endpoints

GET /

POST /analyze

Запрос