[프로젝트 후일담] Docker 기반 런타임

요약

“Docker를 활용하여 리눅스 기반 런타임을 구현하였으며, 서비스별 의존성을 분리하고, 개발환경 차이에 따른 재현성을 높였으며, 추후 배포 시 이식성을 고려하였다.”

즉,

• 리눅스 기반 런타임: Docker Desktop(WLS2) 위에서 리눅스 컨테이너 실행
• 의존성 분리: YOLO, STT, LangGraph 각각 격리된 환경
• 재현성: 팀원/환경이 달라도 동일한 결과
• 이식성: 로컬 ↔ 서버 배포가 동일 이미지로 가능

A-EYE의 Docker 구조 한눈에

• 컨테이너 1: YOLO (객체·세그멘테이션 추론)
  • HTTP API (예: POST /infer) 혹은 WebSocket로 프레임/이미지 받음 → 결과 JSON 반환
• 컨테이너 2: STT (음성 인식)
  • WebSocket(실시간 스트림) 또는 REST(파일 업로드)로 음성 → 텍스트 반환
• 컨테이너 3: LangGraph (에이전트/NLP)
  • POST /perception/gaze/push, POST /perception/yolo/push, POST /image/push 등으로 이벤트/프레임/검출 JSON 수신 → 추론/대화/행동 결정
• 컨테이너 4: FastAPI 백엔드 (허브)
  • 호스트(사용자/클라이언트)에서 들어오는 요청을 받아 YOLO/STT/LangGraph와 통신하고 응답을 묶어서 반환
  • 파일 저장소/캐시/인증/라우팅 등 “게이트웨이” 역할

컨테이너들은 같은 가상 네트워크(bridge) 위에서 돌아가며, 컨테이너 이름으로 서로를 참조합니다(예: FastAPI 내부 코드에서 http://yolo:8090).

---

왜 Docker를 썼나? (요점 4가지)

1. 분리: 모델/런타임/라이브러리를 서비스별로 격리 → 서로 간 충돌/의존성 꼬임 방지
2. 재현성: 팀원이 바뀌거나 머신이 바뀌어도 docker run / compose up만으로 동일 환경 재현
3. 이식성: 로컬(Windows) ↔ 리눅스 서버(온프레/클라우드) 동일한 이미지로 배포
4. 자원제어: GPU는 YOLO만, CPU는 STT만 같은 방식으로 자원 분배가 쉬움

---

“리눅스 기반 로컬 서버인가요?”

• 윈도우에서 Docker Desktop을 쓰면, 내부적으로 WSL2(리눅스 경량 VM) 위에서 리눅스 컨테이너가 돌아갑니다.
  • 즉, 체감상 “내 PC에서 로컬 서버”지만, 런타임은 리눅스라고 보면 정확해요.
  • 포트 매핑 덕분에 **호스트에서는 http://localhost:포트**로 접근합니다.
• 같은 스택을 리눅스 서버로 옮겨도 거의 그대로 동작합니다(경로/드라이버만 맞추면 OK).

---

통신 흐름(쉽게)

1. 클라이언트 → FastAPI: 이미지/오디오/명령 요청
2. FastAPI → YOLO/STT: 필요한 모델 서비스로 요청 전달
3. FastAPI → LangGraph: YOLO 검출 JSON·시선/깊이 이벤트·이미지 프레임을 이벤트로 push
4. LangGraph → FastAPI: 의도/답변/행동 반환 → 클라이언트로 응답

컨테이너 내부에서는 http://서비스이름:포트로, 호스트(윈도우 브라우저 등)에서는 http://localhost:포트로 접근합니다.

 

운영 팁

• 네트워크: Compose 기본 bridge 사용. 컨테이너끼리는 http://서비스이름:포트, 호스트는 http://localhost:포트.
• 헬스체크: /health 같은 간단한 엔드포인트를 모든 서비스에 두면 자동 재시도/의존성 대기 용이.
• 로그/볼륨: 모델 가중치, 입력/출력 미디어는 볼륨 매핑해서 컨테이너 재시작에도 유지.
• 자원 분리: YOLO만 GPU, STT/LangGraph/Backend는 CPU로도 충분한 경우가 많아 비용/발열 절약.
• 배포 전환: 로컬에서 검증한 compose를 리눅스 서버에 그대로 가져가도 90% 이상 그대로 동작(경로/포트·보안만 맞추기).

---

핵심 요약

• A-EYE는 서비스별 컨테이너(YOLO, STT, LangGraph, FastAPI)로 구성되고, FastAPI가 허브가 되어 상호 통신을 중재합니다.
• 윈도우에서 돌려도, 실제 컨테이너 런타임은 WSL2 리눅스 위에서 동작합니다(= 로컬 리눅스 서버처럼 동작).
• 같은 이미지를 리눅스 서버에도 그대로 이식 가능—이게 Docker 채택의 가장 큰 이점입니다.