3D 화물 적재: API, Telegram 봇, 아키텍처, Docker

고성능 3D 적재: 물류를 위한 API 아키텍처 및 텔레그램 봇 구현

현대 물류는 화물 최적화에 있어 상당한 어려움에 직면해 있으며, 효율성 1%가 경제적 수익성에 직접적인 영향을 미칩니다. 제한된 컨테이너 공간 내에서 다양한 화물 크기에 대한 최적의 3D 적재 문제를 해결하는 것은 매우 중요한 과제입니다. 이 글에서는 초당 최대 50만 개의 품목을 처리할 수 있는 고성능 Skewer-v4 API의 아키텍처와 실제 구현, 그리고 Route Load Bot 텔레그램 봇을 통한 사용자 인터페이스 통합에 대해 자세히 다룹니다. 기술적 측면, 사용된 기술, 프로젝트의 발전 과정, 그리고 주요 배포 및 피드백 단계를 살펴보겠습니다.

벡터 논리에서 3D 적재까지: Skewer-v4의 진화

Skewer-v4 프로젝트는 복잡한 물류 문제를 위한 효율적인 솔루션을 만들기 위한 여러 개발 반복의 정점입니다. 초기에는 경로 최적화에 중점을 두었으며, 이는 0.4초 만에 10,000개의 지점을 처리할 수 있는 Traveling Salesperson Problem (TSP) 해결을 위한 벡터 논리 개발로 이어졌습니다. 이 기반은 더 복잡한 작업으로의 전환을 가능하게 했습니다.

다음 단계는 전체 차량 규모의 확장이었습니다. 12척의 선박에 10만 개의 컨테이너를 적재하는 시뮬레이션이 성공적으로 이루어졌습니다. Celery 워커와 FastAPI를 활용하여 시스템은 스택 제한 및 LIFO(Last In, First Out) 하역 순서와 같은 중요한 제약 조건을 고려하여 단 2분 만에 42,000개의 컨테이너를 분배했습니다. 이는 대규모 물류 운영을 위한 분산 컴퓨팅의 잠재력을 보여주었습니다.

그 정점은 이른바 '궁극적인 도전'인 불규칙한 크기의 화물 적재에 뛰어드는 것이었습니다. 여기에서 알고리즘은 각 품목의 무게를 고려하고, 무게 중심(COG)을 계산하며, LIFO 하역 순서를 유지하도록 개선되었습니다. 그 결과 초당 50만 개의 품목을 처리하는 전례 없는 성능을 달성하여 Skewer-v4를 고속 3D 적재 분야의 선두 주자로 자리매김했습니다.

Route Load Bot 아키텍처: 알고리즘과 사용자 연결하기

강력한 Skewer-v4 알고리즘을 더 많은 사람들이 사용할 수 있도록 Route Load Bot 텔레그램 봇이 개발되었습니다. 이 봇은 복잡한 로직에 대한 편리한 인터페이스 역할을 하여 사용자가 JSON 파일을 통해 시스템과 상호 작용하고 결과에 대한 즉각적인 3D 시각화를 받을 수 있도록 합니다. 사용자 입력부터 결과 전달까지 전체 요청 과정은 몇 가지 주요 단계로 나뉩니다.

초기화 및 API 인터페이스: 사용자는 /start 명령어를 사용하여 봇과 상호 작용을 시작하며, 지침과 Swagger 문서 링크를 받습니다. 이는 개발자를 위한 API의 개방성과 타사 물류 시스템과의 통합 가능성을 강조합니다.

데이터 수신 및 유효성 검사: 적재를 위한 입력 데이터는 JSON 형식(예: order.json)으로 제공됩니다. 이 단계에서 Pydantic 스키마는 엄격한 데이터 유효성 검사를 보장하는 데 중요한 역할을 합니다. 수량 0 또는 음수 치수와 같은 잘못된 매개변수는 즉시 거부되어, 주요 계산 엔진에 불필요한 부하가 걸리는 것을 방지합니다.

계산 코어: 데이터 유효성 검사 후, 주요 Skewer-v4 엔진이 실행되어 3D 적재 및 무게 중심(COG) 균형 계산을 수행합니다. 정확한 COG 결정은 운송 안전에 매우 중요합니다. 잘못된 무게 분배는 사고로 이어질 수 있기 때문입니다. 계산 결과는 30분 TTL(Time-To-Live)로 Redis에 임시 캐시되어, 이후 시각화를 위한 빠른 접근을 보장합니다.

피드백 및 지표: 사용자는 주요 적재 지표인 컨테이너 활용 효율성 및 COG 오프셋을 받습니다. 또한, 3D 시각화에 대한 인터랙티브 링크와 함께 1점부터 5점까지의 별점으로 적재 품질을 평가할 수 있는 옵션이 제공됩니다. 이 피드백 시스템은 알고리즘의 추가 학습 및 개선을 위한 중요한 요소입니다. 사용자 평가는 알고리즘이 실제 환경에서 최적의 결과를 내지 못할 수 있는 시나리오를 식별하는 데 도움이 됩니다.

3D 시각화: 이 과정에서 가장 직관적인 부분입니다. 링크를 따라가면 FastAPI 라우트(@app.get("/visualize/{task_id}"))가 활성화되어 Redis에서 저장된 계산 결과를 검색하고 Jinja2를 사용하여 visualize.html HTML 템플릿을 렌더링합니다. 결과적으로 사용자는 적재된 컨테이너의 완전한 인터랙티브 3D 모델을 받게 되며, 이를 회전하고 확대/축소하여 상세하게 분석할 수 있습니다.

기술적 측면 및 개발 도구

Route Load Bot의 개발 및 배포는 고성능, 신뢰성 및 확장성을 보장하는 최신 기술 스택에 의존합니다.

Python: 주 개발 언어.
FastAPI: API 구축을 위한 고성능 비동기 웹 프레임워크.
Pydantic: Python 타입 어노테이션을 사용한 데이터 유효성 검사 및 설정 관리 라이브러리.
Celery: 전체 차량 규모 확장과 같은 비동기 작업을 위한 분산 태스크 큐 시스템.
Redis: 중간 결과 및 세션 캐싱에 사용되는 고성능 인메모리 데이터 저장소.
PostgreSQL: 사용자 데이터, 요청 기록 및 피드백의 영구 저장을 위한 관계형 데이터베이스.
Alembic: PostgreSQL 스키마 변경 관리를 위한 데이터베이스 마이그레이션 도구.
Jinja2: 3D 시각화를 위한 HTML 페이지 렌더링용 템플릿 엔진.
Docker and Docker Compose: 컨테이너화 및 애플리케이션 오케스트레이션 도구로, 이식성과 간편한 배포를 보장합니다.
Nginx: 요청 프록시 및 정적 파일 제공에 사용되는 웹 서버.

개발 과정에서의 도전 과제 및 반복

이 프로젝트는 일반적인 개발 복잡성에서 벗어나지 않았으며 지속적인 반복이 필요했습니다. 개발자들은 성공적으로 해결된 몇 가지 문제에 직면했습니다.

적재 알고리즘 최적화: 초기에는 알고리즘이 무게에 더 중점을 두었지만, 피드백 결과 우선순위가 LIFO -> 최대 너비 -> 최대 길이 -> 무게로 변경되었습니다. 화물 지지 요건의 엄격성도 완화되었습니다.
시각화 및 COG 문제: 화물 시각화 및 무게 중심 계산 오류가 식별 및 수정되었으며, 즉각적인 개입과 테스트가 필요했습니다.
사용자 상호 작용: 프로젝트 초기 낮은 사용자 활동(높은 조회수에도 불구하고)은 데모 모드 생성을 촉발했습니다. 이 모드는 무작위 차량과 화물을 생성하고, 즉시 적재하며, 3D 시각화 및 입력 JSON 링크를 제공합니다. 이는 테스트 및 피드백을 위한 진입 장벽을 크게 낮추었습니다.
JSON 복사 문제: 텔레그램에서 JSON 구조를 복사할 때 표준 따옴표가 "스마트" 따옴표로 자동 교체되어 오류가 발생하는 어려움이 관찰되었습니다. 해결책은 수동 선택 대신 클릭하여 복사하는 것을 권장하는 것이었습니다.
모니터링 및 분석: 사용자 행동을 더 잘 이해하기 위해 사용자 모델에 total_requests 및 last_action 필드가 추가되어 봇 활동 및 사용 효율성을 추적할 수 있게 되었습니다.
배포 문제: 프로덕션 서버에 Docker 배포 중, 익명 이미지 다운로드에 대한 Docker Hub 제한과 같은 일반적인 "함정"이 발생했습니다.

예시 마이그레이션 및 배포 실행:

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@your_server_ip:/root/your_root_directory/
docker exec -it skewer_engine_v4 alembic upgrade head
docker compose up -d --build app_container_name
docker logs -f skewer_engine_v4

주요 시사점

고성능 알고리즘: Skewer-v4는 무게, COG, LIFO를 고려하여 초당 최대 50만 개의 품목을 3D 적재합니다.
포괄적인 아키텍처: 이 프로젝트는 FastAPI API, Redis 캐싱, PostgreSQL 데이터 저장소, Pydantic 유효성 검사 및 Jinja2 3D 시각화를 특징으로 합니다.
텔레그램 접근성: Route Load Bot은 데모 모드 및 3D 시각화를 포함하여 알고리즘과 상호 작용하기 위한 사용자 친화적인 인터페이스를 제공합니다.
반복적인 개발: 사용자 피드백 및 기술 배포 문제 해결을 기반으로 한 지속적인 개선.
경제적 잠재력: 이러한 시스템을 사용한 화물 최적화는 대규모 물류 회사에 상당한 비용 절감을 가져올 수 있습니다.

— Editorial Team