VMK 360 Data Collector — Техническое задание

1. Общее описание

Сервис приёма, нормализации и ИИ-обогащения данных об объектах недвижимости.

Парсеры отправляют полусырые данные через REST API. Сервис валидирует их с помощью локальной LLM (Ollama), приводит к единому формату, анализирует изображения, обогащает текст ИИ и сохраняет в PostgreSQL. При повторном приёме объявления (по source_id + external_id) создаётся снапшот старой версии и обновляется текущая.

2. Домен: объекты недвижимости

2.1 Типы объектов (property_types)

• Квартира
• Дом
• Таунхаус
• Коммерческая
• Земельный участок
• Гараж
• Офис
• Склад
• Торговая площадь
• Коттедж
• Комната
• Новостройка

2.2 Типы сделок (deal_types)

• sale — продажа
• rent_long — долгосрочная аренда
• rent_short — посуточная аренда

3. Модель данных

3.1 Справочники

3.2 Основные сущности

raw_parsing_data

Приёмник всех данных от парсеров.

Уникальность: UNIQUE(source_id, external_id)

property_listings

Нормализованное объявление. Максимум типичных полей для недвижимости.

Уникальность: UNIQUE(source_id, external_id)

property_images

Картинки объявления.

property_custom_fields

Универсальные кастомные атрибуты. Всё, что не вошло в типичные поля property_listings.

Уникальность: UNIQUE(property_id, field_name)

property_snapshots

История обновлений объявлений.

ai_enrichments

Результат ИИ-анализа.

3.3 Связи

raw_parsing_data 1:1 property_listings
property_listings 1:N property_images
property_listings 1:N property_custom_fields
property_listings 1:N property_snapshots
property_listings 1:1 ai_enrichments
property_listings N:1 property_types
property_listings N:1 data_sources

4. AI-слой (Ollama)

4.1 Конфигурация

OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_TEXT_MODEL=llama3.2
OLLAMA_VISION_MODEL=llava
OLLAMA_TIMEOUT=120
OLLAMA_MOCK=false
IMAGE_STORAGE_PATH=/var/lib/vmk/images

4.2 AiNormalizer (валидация + структуризация)

Задача: определить, является ли payload объявлением о недвижимости. Если нет — вернуть is_real_estate: false. Если да — вернуть нормализованную структуру.

Границы валидации:

• Reject: автомобили, телефоны, вакансии, мебель, бытовая техника, животные.
• Accept: квартиры, дома, гаражи, земля, офисы, склады, торговые площади.
• Uncertain: стройматериалы, услуги ремонта — требуют внимания, но пока accept.

Поведение при reject:

• raw_parsing_data.status = invalid
• validation_result = invalid
• Ответ API: 202 { job_id, status: "invalid", reason: "..." }
• НИЧЕГО не создаётся в property_listings.

Структурированный выход (JSON schema в prompt):

{
  "is_real_estate": true,
  "property_type": "apartment",
  "deal_type": "sale",
  "title": "...",
  "description": "...",
  "price": 12200000,
  "currency": "RUB",
  "total_area": 78.5,
  "rooms_count": 3,
  "floor": 12,
  "floors_total": 16,
  "building_year": 2019,
  "address": "г. Москва, ул. Ленина, 15",
  "city": "Москва",
  "metro_station": "Таганская",
  "metro_distance_min": 8,
  "contact_phone": "+7...",
  "contact_name": "...",
  "is_agent": false,
  "images": ["https://..."],
  "custom_fields": {
    "balcony_type": "лоджия",
    "ceiling_height": 2.85
  }
}

4.3 AiImageAnalyzer

Задача: анализ каждого изображения объекта.

Вход: base64 картинка. Выход:

{
  "overall_condition": "хороший ремонт, современный стиль",
  "rooms_observed": 3,
  "issues_found": ["пятно на потолке"],
  "positive_highlights": ["панорамные окна", "встроенная кухня"],
  "view_from_window": "двор, детская площадка",
  "furniture_included": true,
  "appliances_included": ["холодильник", "стиральная машина"]
}

Процесс:

1. Скачивание картинок по URL (asyncio.gather).
2. Сохранение в IMAGE_STORAGE_PATH / {property_id} / {hash}.ext.
3. Дедупликация по SHA-256.
4. Извлечение width/height (Pillow).
5. Vision-анализ через Ollama (llava / llama3.2-vision).

4.4 AiEnricher (финальное обогащение)

Задача: анализ текста + результатов image_analysis.

Вход:

• Нормализованный текст (title, description, custom_fields)
• Агрегированные image_analysis_results

Выход:

{
  "extracted_features": {
    "property_complex": "ЖК Солнечный",
    "developer": "Группа Самолет",
    "material": "монолит",
    "additional_params": { "кондиционер": true }
  },
  "price_assessment": {
    "market_estimate": 12500000,
    "deviation_percent": -3.5,
    "confidence": 0.82,
    "comment": "Цена соответствует рынку"
  },
  "listing_quality_score": 8,
  "reliability_rating": 4,
  "sentiment_score": 0.6,
  "classification": "secondary_sale_apartment",
  "generated_description": "Продаётся уютная 3-комнатная квартира...",
  "summary": "3-комнатная квартира, 78 м², ЖК Солнечный, цена 12.2 млн",
  "language": "ru"
}

4.5 Ollama клиент

• Текст: POST /api/chat с JSON mode (system prompt: «Ответь ТОЛЬКО JSON»).
• Vision: /api/chat с images: [base64...].
• Retries: exponential backoff (2^n сек), max 5 попыток.
• Timeout: 60–120 секунд.
• Circuit breaker: при 5 ошибок подряд — fallback на mock или queue.
• Mock режим: при OLLAMA_MOCK=true возвращается фиксированный JSON без реального вызова.

5. Пайплайн обработки (PropertyPipeline)

Parser JSON
    │
    ▼
POST /api/v1/properties/ingest
    │
    ▼
Save raw_parsing_data (status = pending)
    │
    ▼
AiNormalizer (Ollama text model)
    │
    ├──► "Это не недвижимость"
    │       └──► raw_data.status = invalid
    │           Response: 202 { job_id, status: invalid }
    │
    └──► "Это недвижимость"
            │
            ▼
        Structured JSON от Ollama
            │
            ▼
        Check: source_id + external_id exists?
            │
            ├──► Нет → CREATE property_listings
            │
            └──► Да  → UPDATE
                    │
                    ├──► Копируем текущее → property_snapshots
                    ├──► Обновляем property_listings
                    └──► Удаляем старые custom_fields, пересоздаём
            │
            ▼
        Download images (asyncio.gather)
        URL → local dir (IMAGE_STORAGE_PATH) → SHA-256 → property_images
            │
            ▼
        AiImageAnalyzer (Ollama vision model)
        Каждое фото → описание, ремонт, комнаты, проблемы
            │
            ▼
        AiEnricher (Ollama text model)
        Текст + image_analysis → summary, price_assessment,
        quality_score, reliability_rating, generated_description
            │
            ▼
        Commit всё в одной транзакции
        raw_data.status = completed
            │
            ▼
        Response 202 { job_id, property_id, status: completed }

5.1 Повторные объявления (Upsert)

При совпадении source_id + external_id:

1. Создаём снапшот текущей версии в property_snapshots.
2. Обновляем property_listings.
3. Удаляем старые property_custom_fields, создаём новые.
4. Обрабатываем изображения: новые добавляем, существующие по hash пропускаем.
5. Пересоздаём ai_enrichments.
6. Обновляем raw_parsing_data.status = completed.

6. API

POST /api/v1/properties/ingest

Гибкий формат входа (парсеры гарантированно шлют):

{
  "source_slug": "olx_parser",
  "external_id": "olx_987654",
  "payload": {
    "title": "Продам 2-комнатную квартиру",
    "url": "https://olx.ua/...",
    "images": ["https://..."],
    "published_at": "2024-06-01T10:00:00Z"
  }
}

Опционально могут шлют:

• payload.description — текст с кашей параметров
• payload.price + payload.currency
• payload.contacts — phone, name
• payload.address — строка
• payload.params — разнобой ключей от парсера

Response (invalid / rejected):

{
  "job_id": 1,
  "property_id": null,
  "status": "invalid",
  "reason": "Payload appears to be a car listing, not real estate",
  "message": "Data rejected: not a real estate listing"
}

Response (new listing created):

{
  "job_id": 1,
  "property_id": 42,
  "status": "completed",
  "message": "New property listing created and enriched"
}

Response (existing listing updated):

{
  "job_id": 1,
  "property_id": 42,
  "status": "completed",
  "message": "Existing property listing updated, snapshot saved",
  "snapshot_id": 15
}

7. Тесты

Unit-тесты

• test_ai_normalizer.py — валидный reject (авто), валидный accept (квартира), распознавание из каши.
• test_ai_image_analyzer.py — мок Ollama vision.
• test_ai_enricher.py — мок Ollama text.
• test_upsert_pipeline.py — snapshot создан при обновлении.
• test_image_downloader.py — скачивание, hash, дедупликация.

Integration-тесты

• test_api_ingest.py — FastAPI TestClient.
• test_end_to_end.py — минимальный payload → проверка создания raw + listing + images + custom_fields + enrichment.
• test_invalid_reject.py — payload про авто → только raw со статусом invalid.
• test_upsert_integration.py — duplicate external_id → snapshot + update.

Фикстуры

• async_engine — test DB engine.
• db_session — async session с rollback.
• client — FastAPI TestClient.
• mock_ollama_client — фиксированные JSON-ответы.
• sample_payloads — примеры от разных парсеров (olx, avito, domria).

8. Переменные окружения (.env)

# Database
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/vmk_data
DATABASE_POOL_SIZE=20
DATABASE_MAX_OVERFLOW=10
DATABASE_ECHO=false

# Application
APP_HOST=0.0.0.0
APP_PORT=8000
LOG_LEVEL=info
DEBUG=false

# Ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_TEXT_MODEL=llama3.2
OLLAMA_VISION_MODEL=llava
OLLAMA_TIMEOUT=120
OLLAMA_MOCK=false

# Storage
IMAGE_STORAGE_PATH=/var/lib/vmk/images

# Feature flags
ENABLE_IMAGE_ANALYSIS=true
ENABLE_PRICE_ESTIMATION=true

9. Технологический стек

• Python 3.12+
• FastAPI — REST API
• PostgreSQL + asyncpg — БД
• SQLAlchemy 2.x (async) + Alembic — ORM и миграции
• Pydantic — валидация и Settings
• httpx — HTTP клиент (Ollama API + скачивание картинок)
• Pillow — обработка изображений (width/height)
• tenacity — retries
• structlog — логирование
• pytest + pytest-asyncio — тестирование
• Docker Compose — PostgreSQL и Ollama

10. Порядок реализации