hotels/NATASHA_API_USAGE.md

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

## 🚀 **ЗАПУСК API:**

```bash
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 /** - Информация о сервисе
```bash
curl http://localhost:8004/
```

### **2. GET /health** - Проверка здоровья
```bash
curl http://localhost:8004/health
```

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

**Ответ:**
```json
{
  "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)
```bash
curl -X POST http://localhost:8004/extract_simple \
  -H "Content-Type: application/json" \
  -d '{"text": "ООО Гостиница Певек, ИНН 1234567890"}'
```

**Ответ:**
```json
{
  "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:**
```json
{
  "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 (ИНН/ОГРН):**
```json
{
  "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 (Адрес):**
```json
{
  "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

---

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

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

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

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