hotels/NATASHA_API_USAGE.md

🤖 NATASHA NER API - ИСПОЛЬЗОВАНИЕ В n8n

🚀 ЗАПУСК API:

cd /root/engine/public_oversight/hotels
python3 -m uvicorn natasha_ner_api:app --host 0.0.0.0 --port 8004 --reload

API будет доступен на: http://localhost:8004

---

📡 ENDPOINTS:

1. GET / - Информация о сервисе

curl http://localhost:8004/

2. GET /health - Проверка здоровья

curl http://localhost:8004/health

3. POST /extract - Полное извлечение сущностей

curl -X POST http://localhost:8004/extract \
  -H "Content-Type: application/json" \
  -d '{"text": "ИП Фролов С.А. находится по адресу г. Петропавловск-Камчатский"}'

Ответ:

{
  "organizations": ["ИП"],
  "persons": ["Фролов С.А."],
  "locations": ["Петропавловск-Камчатский"],
  "entities": [
    {
      "type": "ORG",
      "text": "ИП",
      "start": 0,
      "end": 2
    },
    {
      "type": "PER",
      "text": "Фролов С.А.",
      "start": 3,
      "end": 14
    },
    {
      "type": "LOC",
      "text": "Петропавловск-Камчатский",
      "start": 35,
      "end": 59
    }
  ],
  "total_entities": 3
}

4. POST /extract_simple - Упрощённое извлечение (для n8n)

curl -X POST http://localhost:8004/extract_simple \
  -H "Content-Type: application/json" \
  -d '{"text": "ООО Гостиница Певек, ИНН 1234567890"}'

Ответ:

{
  "organizations": ["ООО", "Гостиница Певек"],
  "persons": [],
  "locations": [],
  "has_organizations": true,
  "has_persons": false,
  "has_locations": false,
  "total": 2
}

---

🔗 ИСПОЛЬЗОВАНИЕ В n8n:

HTTP REQUEST NODE:

Настройки:

• Method: POST
• URL: http://localhost:8004/extract_simple
• Body:

{
  "text": "{{ $json.quote }}",
  "max_length": 5000
}

Headers:

• Content-Type: application/json

---

💻 CODE NODE для обработки NER результатов:

Используй готовый файл: n8n_code_natasha_ner.js

Он:

1. ✅ Проверяет критерии 1 и 2 (ИНН/ОГРН и Адрес)
2. ✅ Вызывает Natasha API
3. ✅ Комбинирует с результатами регулярок
4. ✅ Возвращает улучшенную оценку

---

🎯 WORKFLOW В n8n:

┌─────────────────────────────┐
│ 1. Generate 17 Criteria     │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│ 2. Loop Over Items          │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│ 3. PostgreSQL: Regex Search │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│ 4. Code: Process Results    │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│ 5. Code: Natasha NER Check  │  ← 🆕 Вызывает Natasha API
│    (n8n_code_natasha_ner.js)│
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│ 6. Aggregate Results        │
└──────────────┬──────────────┘
               ↓
┌─────────────────────────────┐
│ 7. Calculate Final Score    │
└─────────────────────────────┘

---

📊 ПРИМЕР РЕЗУЛЬТАТА:

Критерий 1 (ИНН/ОГРН):

{
  "criterion_id": 1,
  "criterion_name": "Юридическая идентификация",
  "score": 0.0,           // Регулярки не нашли
  "ner_score": 1.0,       // Natasha нашла!
  "ner_entities": ["ООО Гостиница Певек", "ИП Фролов С.А."],
  "final_score": 1.0,     // MAX(0.0, 1.0) = 1.0
  "method": "Natasha NER"
}

Критерий 2 (Адрес):

{
  "criterion_id": 2,
  "criterion_name": "Адрес",
  "score": 1.0,           // Регулярки нашли
  "ner_score": 1.0,       // Natasha тоже нашла!
  "ner_entities": ["Петропавловск-Камчатский", "ул. Пограничная"],
  "final_score": 1.0,     // MAX(1.0, 1.0) = 1.0
  "method": "Гибрид (Regex + NER)"
}

---

⚡ ПРЕИМУЩЕСТВА:

✅ Natasha находит организации, даже если нет ИНН/ОГРН
✅ Natasha находит адреса, даже если формат нестандартный
✅ Работает через HTTP - легко интегрировать в n8n
✅ Быстрая - обрабатывает текст за ~100-200ms
✅ Локальная - не нужен интернет

---

🔧 НАСТРОЙКА В n8n:

Вариант 1: Используй готовый Code Node

Вставь код из n8n_code_natasha_ner.js - он всё сделает автоматически!

Вариант 2: HTTP Request Node

1. Добавь HTTP Request Node
2. URL: http://localhost:8004/extract_simple
3. Method: POST
4. Body: {"text": "{{ $json.quote }}"}
5. Обработай ответ в следующей Code Node

---

📞 ПРОВЕРКА РАБОТЫ:

# Проверка здоровья
curl http://localhost:8004/health

# Тест на русском тексте
curl -X POST http://localhost:8004/extract_simple \
  -H "Content-Type: application/json" \
  -d '{"text": "Гостиница Певек находится по адресу г. Певек, ул. Ленина, 10"}'

Готово! Natasha API запущен на порту 8004! 🚀