3D-pakowanie ładunków: API, Telegram-bot, architektura, Docker

Wysokowydajne pakowanie 3D: Architektura API i implementacja bota Telegram dla logistyki

Współczesna logistyka mierzy się z wyzwaniami optymalizacji transportu towarów, gdzie każdy procent efektywności bezpośrednio przekłada się na korzyści ekonomiczne. Rozwiązanie problemu optymalnego pakowania 3D różnorodnych ładunków o zmiennych gabarytach w ograniczonej przestrzeni kontenera jest jednym z kluczowych zagadnień. Niniejszy artykuł poświęcony jest architekturze i praktycznej implementacji wysokowydajnego API Skewer-v4, zdolnego przetwarzać do 500 000 pozycji na sekundę, oraz jego integracji z interfejsem użytkownika poprzez bota Telegram o nazwie Route Load Bot. Omówimy aspekty techniczne, zastosowane technologie, proces ewolucji projektu, a także kluczowe etapy wdrożenia i zbierania informacji zwrotnych.

Od logiki wektorowej do pakowania 3D: Ewolucja Skewer-v4

Projekt Skewer-v4 stanowi kulminację kilku iteracji rozwojowych, mających na celu stworzenie efektywnego rozwiązania dla złożonych zadań logistycznych. Początkowo skupiono się na optymalizacji tras, co doprowadziło do stworzenia logiki wektorowej do rozwiązywania problemu komiwojażera (TSP), zdolnej przetwarzać 10 000 punktów w 0,4 sekundy. Ten fundament umożliwił przejście do bardziej złożonych zadań.

Kolejnym krokiem było skalowanie na flotę, gdzie z powodzeniem zasymulowano załadunek 100 000 kontenerów na 12 statków. Wykorzystując workerów Celery i FastAPI, system rozdzielił 42 000 kontenerów w zaledwie 2 minuty, uwzględniając ważne ograniczenia, takie jak limity stosu i kolejność rozładunku (LIFO — Last In, First Out). To zademonstrowało potencjał obliczeń rozproszonych dla operacji logistycznych na dużą skalę.

Kulminacją było zagłębienie się w tak zwane „Zadanie Królewskie” — pakowanie ładunków o zmiennych gabarytach. Tutaj algorytm został udoskonalony, aby uwzględniać wagę każdego elementu, obliczać środek ciężkości (COG — Center of Gravity) i zachowywać kolejność rozładunku LIFO. Rezultatem była bezprecedensowa wydajność 500 000 pozycji na sekundę, co czyni Skewer-v4 jednym z liderów w dziedzinie szybkiego pakowania 3D.

Architektura Route Load Bot: Most między algorytmem a użytkownikiem

Aby udostępnić potężny algorytm Skewer-v4 szerokiej publiczności, opracowano bota Telegram o nazwie Route Load Bot. Pełni on rolę wygodnego interfejsu do złożonej logiki, umożliwiając użytkownikom interakcję z systemem za pośrednictwem plików JSON i uzyskiwanie natychmiastowej wizualizacji 3D wyników. Cała ścieżka zapytania od użytkownika do uzyskania wyniku podzielona jest na kilka kluczowych etapów:

• Inicjalizacja i interfejs API: Użytkownik rozpoczyna interakcję z botem komendą /start, otrzymując instrukcje i link do dokumentacji Swagger. Podkreśla to otwartość API dla deweloperów i możliwość integracji z zewnętrznymi systemami logistycznymi.

• Przyjmowanie i walidacja danych: Dane wejściowe do pakowania dostarczane są w formacie JSON (np. order.json). Na tym etapie kluczową rolę odgrywają schematy Pydantic, które zapewniają rygorystyczną walidację danych. Wszelkie nieprawidłowe parametry, takie jak zerowa ilość lub ujemne wymiary, są natychmiast odrzucane, zapobiegając niepotrzebnemu obciążeniu głównego silnika obliczeniowego.

• Rdzeń obliczeniowy: Po walidacji danych uruchamiany jest główny silnik Skewer-v4, który wykonuje pakowanie 3D i oblicza równoważenie środka ciężkości. Dokładne określenie COG jest krytycznie ważne dla bezpieczeństwa transportu, ponieważ niewłaściwe rozłożenie wagi może prowadzić do wypadków. Wyniki obliczeń są tymczasowo buforowane w Redis z TTL 30 minut, co zapewnia szybki dostęp do późniejszej wizualizacji.

• Informacje zwrotne i metryki: Użytkownik otrzymuje kluczowe metryki pakowania: współczynnik wykorzystania przestrzeni (KPI) kontenera i przesunięcie COG. Dodatkowo udostępniany jest interaktywny link do wizualizacji 3D oraz możliwość oceny jakości pakowania w skali od 1 do 5 gwiazdek. Ten system informacji zwrotnej jest ważnym elementem do dalszego uczenia i doskonalenia algorytmu, ponieważ oceny użytkowników pomagają identyfikować scenariusze, w których algorytm może dawać nieoptymalne wyniki w rzeczywistych warunkach.

• Wizualizacja 3D: Najbardziej obrazowa część procesu. Przejście pod link aktywuje endpoint FastAPI (@app.get("/visualize/{task_id}")), który pobiera zapisane obliczenia z Redis i renderuje szablon HTML visualize.html za pomocą Jinja2. W rezultacie użytkownik otrzymuje pełnowartościowy, interaktywny model 3D załadowanego kontenera, który można obracać i skalować w celu szczegółowej analizy.

Aspekty techniczne i narzędzia deweloperskie

Rozwój i wdrożenie Route Load Bot opierają się na nowoczesnym stosie technologicznym, zapewniającym wysoką wydajność, niezawodność i skalowalność:

• Python: Główny język programowania.
• FastAPI: Wysokowydajny asynchroniczny framework webowy do tworzenia API.
• Pydantic: Biblioteka do walidacji danych i zarządzania ustawieniami z wykorzystaniem adnotacji typów Pythona.
• Celery: Rozproszony system kolejek zadań, używany do operacji asynchronicznych, takich jak skalowanie na flotę.
• Redis: Wysokowydajna baza danych in-memory, używana do buforowania wyników pośrednich i sesji.
• PostgreSQL: Relacyjna baza danych do trwałego przechowywania danych użytkowników, historii zapytań i informacji zwrotnych.
• Alembic: Narzędzie do migracji baz danych, zapewniające zarządzanie zmianami schematu PostgreSQL.
• Jinja2: Silnik szablonów do renderowania stron HTML wizualizacji 3D.
• Docker i Docker Compose: Narzędzia do konteneryzacji i orkiestracji aplikacji, zapewniające przenośność i uproszczone wdrożenie.
• Nginx: Serwer webowy, używany do proxyfikacji zapytań i serwowania plików statycznych.

Wyzwania i iteracje w procesie rozwoju

Projekt nie jest pozbawiony typowych dla rozwoju oprogramowania złożoności i wymaga ciągłych iteracji. Deweloperzy napotkali szereg problemów, które zostały pomyślnie rozwiązane:

• Optymalizacja algorytmu pakowania: Początkowo algorytm kładł większy nacisk na wagę, ale w wyniku informacji zwrotnych priorytety zostały zmienione: LIFO -> Maksymalna Szerokość -> Maksymalna Długość -> Waga. Złagodzono również rygorystyczne wymagania dotyczące podparcia ładunków.
• Problemy z wizualizacją i COG: Wykrywano i poprawiano błędy w wizualizacji ładunków oraz obliczaniu środka ciężkości, co wymagało szybkiej interwencji i testowania.
• Interakcja z użytkownikami: Niska aktywność użytkowników na początku projektu (pomimo dużej liczby wyświetleń) skłoniła do stworzenia trybu DEMO. Tryb ten umożliwia generowanie losowych pojazdów i ładunków, natychmiastowe ich pakowanie oraz udostępnianie linków do wizualizacji 3D i wejściowego pliku JSON. Znacząco obniżyło to próg wejścia do testowania i uzyskiwania informacji zwrotnych.
• Problemy z kopiowaniem JSON: W Telegramie napotkano trudności z kopiowaniem struktur JSON z powodu automatycznej zamiany cudzysłowów na „inteligentne” cudzysłowy, co prowadziło do błędów. Rozwiązaniem było zalecenie używania kopiowania jednym kliknięciem zamiast ręcznego zaznaczania.
• Monitoring i analityka: Dla lepszego zrozumienia zachowań użytkowników dodano pola total_requests i last_action do modelu użytkownika, co pozwala śledzić aktywność i efektywność korzystania z bota.
• Problemy z wdrożeniem (deploy): Podczas wdrażania w Dockerze na serwerze produkcyjnym napotkano na takie „pułapki” jak limity Docker Hub dla anonimowego pobierania obrazów.

Przykład wykonania migracji i wdrożenia:

rsync -avz --delete --exclude '.venv' --exclude 'venv' --exclude '**pycache**' --exclude '.git' --exclude '.env' --exclude '.pytest_cache' --exclude '.vscode' --exclude 'backup' --exclude '*.json' --exclude 'pytest.ini' --exclude 'instruction.md' /home/andreymazo/Projects/skewer_api/ root@mój_numer_serwera:/root/mój_katalog_główny/
docker exec -it skewer_engine_v4 alembic upgrade head
docker compose up -d --build nazwa_kontenera_aplikacji
docker logs -f skewer_engine_v4

Co ważne

• Wysokowydajny algorytm: Skewer-v4 zapewnia pakowanie 3D do 500 000 pozycji/sek z uwzględnieniem wagi, COG i LIFO.
• Kompletna architektura: Projekt obejmuje API na FastAPI, buforowanie w Redis, przechowywanie danych w PostgreSQL, walidację Pydantic i wizualizację 3D Jinja2.
• Dostępność przez Telegram: Route Load Bot zapewnia wygodny interfejs do interakcji z algorytmem, w tym tryb DEMO i wizualizację 3D.
• Iteracyjny rozwój: Ciągłe doskonalenie na podstawie informacji zwrotnych od użytkowników i rozwiązywanie wyzwań technicznych podczas wdrażania.
• Potencjał ekonomiczny: Optymalizacja transportu towarów za pomocą takich systemów może przynieść znaczne oszczędności dla dużych firm logistycznych.

— Editorial Team