README.md

metadata

title: Layout Viewer
emoji: 📚
colorFrom: red
colorTo: blue
sdk: docker
pinned: false

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

🏪 ИИ-Мерчандайзер 3D (Text-to-3D Store Layout)

ИИ-Мерчандайзер 3D — это интеллектуальный генератор физически корректных 3D-планировок торговых залов, работающий на базе текстовых запросов (Text-to-3D).

Система позволяет пользователю описать желаемую расстановку простым языком (например: "Поставь молоко в холодильник, а пиво на стеллаж напротив"), после чего оркестратор подключает LLM для формирования абстрактного графа, а затем использует физический движок (Space Syntax + Tensor Fields) для точного позиционирования объектов без коллизий.

✨ Ключевые возможности

• 🗣️ Text-to-3D: Превращение естественного языка в готовые трехмерные сцены.
• 🧠 Гибридная генерация (LLM + Физика): Языковая модель (Qwen) формирует черновой граф (Draft AABB), а алгоритмы тензорных полей и спирального поиска разрешают коллизии оборудования в непрерывном пространстве.
• 🛒 Умная планограмма: Автоматический подбор 3D-моделей товаров (SKU) под запрошенные категории и динамический расчет их размещения на полках.
• 🗜️ Оптимизация для Web: Экспорт готовых сцен в формате .glb с применением высокоэффективной Draco-компрессии.
• 📊 Богатые артефакты: Генерация не только 3D, но и векторных 2D-планов (SVG), а также сырых JSON-данных с точными координатами для интеграции с ERP-системами.
• 🛠️ Отказоустойчивость: Интеграция json-repair для "лечения" синтаксических ошибок в ответах LLM при генерации графов.

---

🏗 Как это работает (Пайплайн)

Генерация проходит через 6 автоматизированных шагов (src/layout_generator/pipeline.py):

1. LLM-Оркестрация (llm/client.py): Запрос отправляется в локальный инстанс vLLM. Модель возвращает JSON-граф, где узлы — это оборудование с товарами, а ребра — пространственные связи (рядом, напротив).
2. Загрузка ассетов (assets.py): Быстрый разогрев кэша ОЗУ — загрузка геометрии оборудования и SKU.
3. Расчет планограммы (planner.py): Сопоставление абстрактных сущностей от LLM с конкретными 3D-моделями, расчет вместимости полок с учетом габаритов (AABB) каждого товара.
4. Генерация топологии (topology.py): Разрешение физических коллизий между стеллажами. Используются черновые координаты LLM и направляющие тензорные поля.
5. Сборка 3D-сцены (assembler.py): Финальный рендер объектов в единой сцене, генерация процедурного пола по размерам помещения.
6. Экспорт и визуализация (exporter.py, visualizer.py): Сжатие .glb файла, отрисовка векторных 2D-планов (до и после физики) и сохранение логов.

---

🚀 Установка и запуск

1. Системные требования

• Python 3.10+
• GPU с поддержкой CUDA (рекомендуется от 16GB VRAM для локального запуска vLLM)

2. Установка зависимостей

Выполните клонирование репозитория и установку пакетов: pip install -r requirements.txt

3. Запуск локального сервера vLLM

Сервер поднимается в фоновом режиме. Настройки модели и API задаются не хардкодом, а через конфигурационный файл configs/main_config.yaml. python scripts/launch_llm_server.py

4. Запуск веб-интерфейса (Gradio)

Как только сервер LLM готов, запускайте UI: python scripts/launch_ui.py

Интерфейс будет доступен по адресу: http://localhost:7860

(Примечание: Проект полностью совместим с развертыванием в Hugging Face Spaces через предоставленный Dockerfile и app.py).

---

📂 Структура проекта

layout-viewer/

├── app.py # Точка входа для Hugging Face Spaces

├── Dockerfile # Конфигурация окружения для облака

├── configs/ # Настройки Hydra/OmegaConf

│ ├── main_config.yaml # Основные настройки проекта и LLM

│ ├── llm_prompt.txt # Системный промпт для LLM

│ └── asset_config.yaml # Иерархия 3D-ассетов

├── scripts/ # Утилиты запуска и дебага

│ ├── launch_llm_server.py # Поднятие vLLM бэкенда

│ ├── launch_ui.py # Старт Gradio UI

│ └── check_gpu.py # Диагностика CUDA окружения

├── src/ # Исходный код приложения

│ ├── dsynth/ # Ядро генерации (Space Syntax, Tensor Fields)

│ ├── layout_generator/ # Пайплайн (Planogram, Topology, Assembler)

│ ├── llm/ # Клиент для связи с vLLM сервером

│ └── ui/ # Логика и компоненты Gradio

├── data/ # Исходные данные и экспортированные 3D-модели

├── notebooks/ # Jupyter тетрадки для экспериментов

├── reports/ # Директория для отчетов генерации

└── logs/ # Сгенерированные артефакты (создается автоматически)

---

📥 Артефакты генерации

Веб-интерфейс позволяет не только вращать 3D-сцену, но и скачивать результаты работы пайплайна (сохраняются в директории logs/):

• 📄 Draft JSON / Final JSON: Машиночитаемые координаты мебели до и после физического движка.
• 🗺️ Draft SVG / Final SVG: Черновой и финальный векторные 2D-планы (вид сверху).
• 📝 History JSONL: Полный лог взаимодействия с LLM (сырой промпт, ответ сети, парсинг) для дебага галлюцинаций.
• 🎮 GLB: Финальная скомпрессированная 3D-модель.