entity-extractor

Сервис для извлечения всех типов сущностей из текста:

• LOC - топонимы (города, страны, реки)
• PER - имена людей
• ORG - организации
• MISC - прочие сущности

API

POST /extract

Запрос:

{
  "text": "Текст для анализа",
  "min_score": 0.5
}

Ответ:

{
  "entities": [...],  // все токены с метками
  "grouped": {         // сгруппировано по типу
    "LOC": [...],
    "PER": [...],
    "ORG": [...],
    "MISC": [...]
  },
  "toponyms": [...],   // обратная совместимость
  "count": 42,
  "time_ms": 123.45
}

Технологии

• XLM-RoBERTa-large NER
• FastAPI
• PyTorch
• Docker + GPU

📋 Техническое описание API сервиса entity-extractor

1. Общая информация

Параметр	Значение
Сервис	entity-extractor
Назначение	Извлечение именованных сущностей (LOC, PER, ORG, MISC) из текста
Базовый URL	http://library-manticore-proxy:1122 (через прокси)
Аутентификация	X-API-Key в заголовке
Формат	JSON

2. Эндпоинты

POST /extract

Извлекает все сущности из переданного текста.

Заголовки:

X-API-Key: <ключ_доступа>
Content-Type: application/json

Тело запроса:

{
    "text": "Текст для анализа",
    "min_score": 0.5,           // опционально, порог уверенности (0.0-1.0)
    "include_positions": false   // опционально, добавлять позиции в тексте
}

3. Формат ответа

{
    "entities": {
        "LOC": [     // топонимы (города, страны, реки и т.д.)
            {
                "text": "Москва",
                "type": "LOC",
                "confidence": 0.999,
                "positions": null  // если include_positions=true
            }
        ],
        "PER": [     // имена людей
            {
                "text": "Иван Петров",
                "type": "PER",
                "confidence": 0.995
            }
        ],
        "ORG": [     // организации
            {
                "text": "ООН",
                "type": "ORG",
                "confidence": 0.998
            }
        ],
        "MISC": [    // прочие сущности
            {
                "text": "Рождество",
                "type": "MISC",
                "confidence": 0.987
            }
        ]
    },
    "total": 42,           // общее количество сущностей
    "time_ms": 156.78      // время обработки в миллисекундах
}

4. Примеры использования

Простой запрос

curl -X POST http://localhost:1122/extract \
  -H "X-API-Key: ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"text": "Москва - столица России. Президент Путин посетил Кремль."}'

Ответ

{
    "entities": {
        "LOC": [
            {"text": "Москва", "type": "LOC", "confidence": 0.999},
            {"text": "России", "type": "LOC", "confidence": 0.999},
            {"text": "Кремль", "type": "LOC", "confidence": 0.998}
        ],
        "PER": [
            {"text": "Путин", "type": "PER", "confidence": 0.999}
        ],
        "ORG": [],
        "MISC": []
    },
    "total": 4,
    "time_ms": 45.67
}

С позициями в тексте

curl -X POST http://localhost:1122/extract \
  -H "X-API-Key: ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"text": "Москва - столица России", "include_positions": true}'

Ответ с позициями

{
    "entities": {
        "LOC": [
            {
                "text": "Москва",
                "type": "LOC",
                "confidence": 0.999,
                "positions": [{"start": 0, "end": 6}]
            },
            {
                "text": "России",
                "type": "LOC",
                "confidence": 0.999,
                "positions": [{"start": 18, "end": 24}]
            }
        ]
    },
    "total": 2,
    "time_ms": 42.34
}

5. Особенности реализации

• Автоматическое разбиение длинных текстов на окна (512 токенов)
• Скользящее окно без перекрытия (OVERLAP_RATIO=0) для предотвращения дублей
• Батчевая обработка окон для оптимальной производительности GPU
• Кэширование модели на диске (первый запрос медленный, далее быстро)

6. Возможные ошибки

// 401 Unauthorized
{
    "error": "Invalid API key"
}

// 500 Internal Server Error
{
    "error": {
        "type": "internal_error",
        "message": "Текст ошибки"
    }
}

7. Рекомендации для UI

• Подсветка в тексте: можно использовать поля positions для выделения сущностей
• Фильтрация по типу: показывать только LOC/PER/ORG по выбору пользователя
• Сортировка по уверенности: наиболее достоверные сущности сверху
• Debouncing: не отправлять запрос на каждое нажатие клавиши
• Индикация загрузки: учитывать время ответа (обычно 20-200ms)