Skip to main content

`ai-node-agent` 상세 분석: 멀티스레드 아키텍처

ai-node-agent는 각 AI 연산 서버에서 실행되며, 중앙 시스템과의 모든 통신을 대리하는 핵심 에이전트입니다. 안정적이고 효율적인 비동기 처리를 위해, 에이전트는 여러 개의 독립적인 스레드를 실행하는 멀티스레드 아키텍처를 채택하고 있습니다.

각 스레드는 대부분의 시간을 I/O 대기(네트워크 응답 대기, 정해진 시간 동안 휴면 등) 상태로 보내므로, 여러 스레드가 동시에 실행되더라도 CPU에 거의 부하를 주지 않으며 시스템 리소스를 효율적으로 사용합니다.

스레드별 역할 및 동작 방식

ai-node-agent는 시작 시 다음과 같은 5개의 주요 백그라운드 스레드를 실행합니다.

1. SQS 폴링 스레드 (`_poll_sqs`)

역할: AWS SQS 큐를 주기적으로 확인하여 새로운 생성 작업 요청이 있는지 감시합니다.
동작:
- boto3 클라이언트를 사용하여 receive_message API를 호출합니다.
- WaitTimeSeconds (현재 10초) 설정에 따라, 새 메시지가 없을 경우 대부분의 시간을 SQS 서버의 응답을 기다리는 네트워크 I/O 대기 상태로 보냅니다.
- 새 메시지를 수신하면, 해당 메시지를 처리하는 process_message 함수를 호출합니다.
- CPU 사용량은 거의 없으며, 시스템 부하에 미치는 영향이 미미합니다.

2. WebSocket 연결 관리 스레드 (`_manage_websocket_connection`)

역할: 로컬 ComfyUI 인스턴스와의 웹소켓 연결을 생성하고, 유지하며, 메시지를 수신합니다.
동작:
- websocket-client 라이브러리의 run_forever 메서드를 통해 실행됩니다.
- 연결이 끊어지면 설정된 간격(5초)에 따라 자동으로 재연결을 시도합니다.
- 대부분의 시간을 웹소켓 서버로부터 메시지가 오기를 기다리는 네트워크 I/O 대기 상태로 보냅니다.
- 메시지를 수신하면, 해당 메시지를 웹소켓 메시지 처리 큐에 넣는 매우 가벼운 작업만 수행하고 즉시 다시 대기 상태로 돌아갑니다.

3. 시스템 모니터링 스레드 (`_monitor_system_metrics`)

역할: 생성 실행부의 시스템 리소스(CPU, RAM, 디스크 등)를 주기적으로 수집하여 Redis Pub/Sub 채널로 발행합니다.
동작:
- time.sleep(0.5)에 의해 0.5초의 주기를 가집니다.
- psutil 라이브러리를 사용하여 시스템 메트릭을 수집합니다. 이 작업은 매우 빠르게 완료됩니다.
- 수집된 데이터를 Redis에 PUBLISH합니다.
- 주기의 대부분을 휴면(Sleep) 상태로 보내므로, CPU 점유율은 매우 낮습니다.

4. 웹소켓 메시지 처리 스레드 (`_process_message_queue`)

역할: 웹소켓 연결 관리 스레드가 큐에 넣은 메시지(작업 진행률, 상태 변경 등)를 순서대로 하나씩 꺼내어 실제 비즈니스 로직을 처리합니다.
동작:
- queue.Queue가 비어있을 때는 새 항목이 들어올 때까지 블로킹(Blocking) 대기 상태가 됩니다.
- 메시지를 꺼내면, 해당 이벤트 타입에 따라 Redis에 작업 상태를 업데이트하는 등의 로직을 수행합니다.
- 이벤트 처리 로직을 수신 로직과 분리함으로써, 특정 이벤트 처리가 지연되더라도 웹소켓 메시지 수신 자체에는 영향을 주지 않아 시스템 전체의 안정성과 반응성을 높입니다.

5. 하트비트 전송 스레드 (`_send_heartbeat`)

역할: 5초마다 Redis에 자신의 nodeId를 포함한 생존 신호(하트비트)를 보내, 중앙 시스템(백엔드)이 해당 노드의 활성 상태를 감시할 수 있도록 합니다.
동작:
- time.sleep(5)에 의해 5초의 주기를 가집니다.
- Redis에 SETEX 명령을 사용하여 15초의 유효시간(TTL)을 가진 키를 생성합니다.
- 주기의 대부분을 휴면(Sleep) 상태로 보내므로, CPU 사용량은 거의 0에 가깝습니다.

스레드별 역할 및 동작 방식