퍼실리티 시스템 구축하기

퍼실리티(Facility)는 여러 장비에서 실행되는 AI 서비스의 상태를 확인하고, 허용된 작업을 실행하며, 장애와 변경 이력을 남기는 운영 제어판입니다. 모델을 학습시키는 화면과 구분합니다.

이 튜토리얼은 사용자 제공 「설비실 제작 프롬프트 로그」(정리일 2026-10-20)의 105개 본 작업 요청과 연관 작업을 주제별로 재구성했습니다. 원본은 요청 기록이며 현재 구현·가동의 증거가 아닙니다. 아래 스키마·API·알고리즘·검증표는 학습을 위해 정리한 설계안입니다. 실제 서버 제어 기능은 이 강의 페이지에 연결하지 않습니다.

학습 목표와 준비물

• Build: 장비·서비스 목록, 상태 조회, 개별 제어, 라우팅을 직접 설계합니다.
• Operate: 장애 원인을 분리하고 메모리·지연·작업 이력을 관찰합니다.
• Manage Risk: 관리자 권한, 명령 허용 목록, 확인 절차, 감사 로그를 적용합니다.
• 준비물: HTTP·JSON 기초, 작은 API 서버, 상태를 바꿀 수 있는 더미 서비스 두 개. 실제 GPU가 없어도 상태·폴백 실습부터 시작할 수 있습니다.

처음에는 Windows·Ubuntu·MacBook을 각각 node-win, node-linux, node-mac이라는 샘플 장비로 표현합니다. 원본의 실제 IP·MAC·로컬 경로는 게시하지 않습니다. 실제 장비는 사용자가 자기 환경의 보안 조건을 검토한 뒤 연결합니다.

실습 과제: 더미 장비 하나와 서비스 하나의 목록·상태를 표시합니다. 상태 조회는 실제 명령 실행 없이 고정 JSON부터 시작합니다.

확인 기준: 학습자가 장비 전원, 관리 에이전트, AI 서비스, 메모리에 올라온 모델을 서로 다른 대상으로 설명할 수 있습니다.

시간순 요청을 그대로 구현하면 이전 정책과 후속 정책이 충돌합니다. 요청에서 목적·대상·변경 이유를 추출하고, 최종 선택을 한 표에 기록합니다.

원본의 배경 이미지 교체, 초상화 크기 조정, UI 위치 되돌리기, 반복된 “안 켜진다” 요청은 독립 학습 단계에서 제외했습니다. 같은 장애는 뒤의 진단표로 합쳤습니다. TANet·아티뮤즈 점수 조합은 사진 평가 도메인의 업무 규칙이므로 운영 제어판의 핵심 실습과 분리합니다.

실습 과제: “수동 OFF는 어디까지 적용되는가?”를 먼저 정합니다. 이 과정에서는 서비스 전체의 수동 OFF와 특정 장비 인스턴스의 수동 OFF를 별도 명령으로 둡니다. 서비스 전체 OFF라면 모든 장비에서 자동 실행을 막고, 인스턴스 OFF라면 해당 장비만 후보에서 제외합니다.

확인 기준: 정책표에 없는 행동을 에이전트가 추측해서 실행하지 않습니다. 새 요청을 받으면 바뀐 정책과 영향을 받는 검증 시나리오를 함께 수정합니다.

장비가 응답한다고 모든 AI 서비스가 준비된 것은 아닙니다. 관리 에이전트가 꺼졌다고 PC가 종료된 것도 아닙니다. 서비스가 켜졌어도 모델이 아직 로드되지 않았을 수 있습니다.

Ollama, 임베딩, SigLIP, NIMA, OCR, TANet, 아티뮤즈, YOLO 등은 원본에서 등장한 서비스 이름입니다. 모든 장비가 모든 서비스를 지원한다고 가정하지 않습니다. 영상·오디오·ComfyUI 등도 설치 여부와 제어 가능 여부를 확인한 뒤 등록합니다.

아래는 저장 구조의 예시입니다. 주소와 인증정보는 서버 설정에 두고, 브라우저가 임의 주소를 제어 요청에 넣게 하지 않습니다.

{
  "service_id": "ocr",
  "host_id": "node-win",
  "supported": true,
  "desired_mode": "auto",
  "observed_state": "unknown",
  "last_checked_at": null,
  "last_error": null,
  "startup_enabled": true
}

desired_mode는 사용자의 의도(auto / manual_on / manual_off), observed_state는 관측 결과(unknown / starting / ready / stopping / stopped / error)입니다. 둘을 하나의 ON/OFF 값으로 합치지 않습니다.

실습 과제: 지원하지 않는 장비·서비스 조합 하나를 넣어 봅니다. UI는 미지원으로 표시하고 서버는 해당 제어 요청을 거절해야 합니다.

대시보드의 첫 번째 책임은 정확한 관측입니다. 토글을 누른 직후의 낙관적 ON 표시보다, 요청 중·준비 완료·실패를 구별하는 편이 운영에 유용합니다.

브라우저 → 인증된 API 서버 → 장비별 관리 어댑터
                             → 상태 저장소·감사 로그
브라우저 ← 장비·서비스별 관측값과 확인 시각

상태 조회 API는 서비스마다 제한 시간을 두고 독립적으로 결과를 반환하도록 설계합니다. 장비 하나가 응답하지 않아도 다른 장비의 관측값을 보여 줍니다. 이전 값을 재사용할 때는 “마지막 확인 시각”과 “오래된 값” 표시를 함께 둡니다.

원본의 NIMA 프록시 포트 불일치와 SigLIP·NIMA 상태 혼동은 “화면 이름과 점검 대상의 매핑” 문제로 묶습니다. 같은 프로세스를 공유하더라도 서비스별 준비 상태를 검증해야 합니다.

실습 과제: 더미 OCR의 응답을 지연시키고 Ollama는 정상 응답하도록 합니다.

확인 기준: 화면 전체가 멈추지 않고 OCR의 조회 실패를 구분합니다. “시간 제한을 없앴다”를 타임아웃 해결로 간주하지 않습니다.

토글 버튼과 대화 명령은 같은 서버의 제어 경로를 사용합니다. 에이전트는 사용자의 의도를 구조화하고, 서버는 권한·대상·허용 작업을 검증합니다. 모델 출력만으로 명령 실행을 승인하지 않습니다.

아래 경로는 구현 과제용 계약 예시이며 현재 저장소의 실제 API가 아닙니다.

“윈도우 니마 꺼줘”는 host=node-win, service=nima, action=stop으로 해석합니다. PC 종료 요청으로 확대하지 않습니다. “전부 꺼줘”처럼 범위가 모호하면 대상과 영향을 먼저 확인합니다.

{
  "host_id": "node-win",
  "service_id": "nima",
  "action": "stop",
  "mode": "manual_off",
  "request_id": "demo-stop-nima-001"
}

서버는 로그인 신원에서 권한을 읽고, 허용 목록으로 대상을 찾고, 중복 요청 ID를 확인한 뒤 작업을 접수합니다. 응답에는 작업 ID를 넣고 최종 관측이 끝나기 전에는 “중지 완료”라고 말하지 않습니다. “명령을 보냄”과 “실제 중지 확인”을 구분합니다.

실습 과제: 같은 중지 요청을 두 번 전송하고, NIMA 중지가 다른 서비스·호스트 전원에 영향을 주지 않는지 확인합니다. 승인 대상은 미리보기의 정확한 작업과 연결하고, 인자 변경 시 다시 확인하도록 합니다.

WOL(Wake-on-LAN)은 지원되는 장비를 깨우기 위한 방식입니다. 전원 끄기나 재부팅은 관리 에이전트의 별도 기능으로 설계합니다. WOL 패킷 전송 성공을 부팅 완료로 표시하지 않습니다.

Windows의 WOL 지원은 전원 상태와 하드웨어·드라이버 설정에 영향을 받습니다. Microsoft의 Windows 10 WOL 설명을 참고하고 대상 OS·장비에서 확인합니다. 완전 종료 후 항상 깨울 수 있다고 안내하지 않습니다.

깨우기 요청 → 패킷 전송 → 호스트 응답 대기
           → 관리 에이전트 응답 대기 → 서비스 준비 확인

각 단계의 제한 시간을 따로 두고, 부팅 중에는 STARTING으로 표시합니다. 원본의 “실제로 켜지는 중인데 응답 없음”은 너무 이른 최종 판정으로 설명할 수 있는 장애 사례입니다. 실제 원인은 장비 로그로 확인해야 합니다.

부팅 자동 시작은 서비스 등록표의 startup_enabled에서 관리합니다. 전체 서비스 일괄 시작은 해당 장비에서 지원하는 등록 항목을 사용하되, 메모리 한도를 확인하고 순차 시작을 고려합니다. 서비스 시작 실패를 PC 종료로 처리하지 않습니다.

실습 과제: 더미 장비를 3단계로 늦게 준비되도록 만들고 진행 상태를 보여 줍니다. PC 종료·재부팅은 별도 관리자 권한과 실행 대상 확인 후에만 접수되도록 설계합니다.

폴백은 특정 서비스의 주 대상이 준비되지 않았을 때 지원 가능한 예비 대상을 고르는 정책입니다. 원본 후반의 우선순위는 Windows → Ubuntu → MacBook입니다. 모든 서비스를 장비 단위로 한꺼번에 넘기지 않고 서비스별로 판단합니다.

수동 설정과 자동 정책을 분리하지 않으면 “내가 껐는데 다시 켜짐”과 “내가 켰는데 자동으로 꺼짐”이 반복됩니다. 이 과정에서는 다음 순서를 설계 기준으로 둡니다.

실행 유지와 요청 라우팅은 다른 결정입니다. 하위 장비를 수동으로 켜도, 기본 라우팅은 준비된 상위 장비를 우선합니다. 하위 장비를 실제로 사용하려면 서비스별 고정 대상(pin)을 별도로 지정하고 해제할 수 있게 합니다. 이 고정 대상은 원본의 수동 전환 충돌을 해결하기 위한 튜토리얼의 설계 보완입니다.

서비스 전체 중지? → 라우팅하지 않음
고정 대상 있음? → 지원·허용·READY 확인 후 선택, 실패 시 명시적 오류
그 외 → Windows, Ubuntu, MacBook 순서로 지원·허용·READY 후보 선택
후보 없음 → 사용 불가와 원인 표시

자동 시작·정리는 라우팅과 분리된 조정 작업이 담당합니다. 같은 서비스에 대한 동시 명령은 순서·설정 버전을 확인하고, 짧은 실패·복구 반복이 잦은 시작·종료로 이어지지 않도록 재확인 조건을 정합니다. 구체적인 대기 시간은 실습 환경에서 측정해 정합니다.

실습 과제: Windows 장애 → Ubuntu 선택 → Ubuntu 수동 중지 → MacBook 선택 → 서비스 전체 중지 순서로 실행합니다. 수동으로 켠 MacBook이 상위 장비 복구로 종료되지 않는지도 확인합니다.

장비의 모델 폴더에 파일이 있다는 것과 현재 서비스가 그 모델을 인식한다는 것은 다릅니다. 모델 목록은 실제 라우팅 대상의 서빙 API에서 읽고, 설치 모델과 메모리에 로드된 모델도 구분합니다.

호스트가 바뀌면 목록을 갱신합니다. 이전 선택 모델이 새 대상에 없으면 자동으로 같은 이름이 있을 것이라 추측하지 말고 “선택 모델 없음”을 표시합니다. 페르소나의 말투 설정은 실제 추론 호스트·모델 선택과 별개로 유지합니다.

원본의 모델 경로 이동 사례는 서비스 실행 계정·설정 경로·모델 목록을 함께 확인하는 진단 과제로 바꿉니다. 장비마다 경로를 화면 코드에 하드코딩하지 않습니다.

실습 과제: Windows에는 모델 A·B, Ubuntu에는 모델 B만 있는 더미 응답을 사용합니다. A 선택 후 Ubuntu로 전환했을 때 재선택 안내가 나타나고 실제 요청 모델도 B로 바뀌는지 확인합니다. 모델 목록 조회 실패와 빈 목록을 구별합니다.

RAM·VRAM 현황은 호스트 수준, 서비스 수준, 모델 수준을 나눠 관찰합니다. 모든 장비의 메모리 체계가 같다고 가정하지 않고, 관측할 수 없는 지표는 0으로 채우지 않습니다.

Ollama의 GET /api/ps는 현재 로드된 모델을 조회합니다. 모델 언로드는 해당 런타임이 제공하는 기능을 사용합니다. 아래는 이미 설치된 로컬 Ollama에서 확인하는 예시이며, 다른 서비스의 프로세스 전체 목록을 조회하는 명령은 아닙니다.

curl http://localhost:11434/api/ps
ollama ps
# <model-name>은 실제 로드된 모델명으로 바꿉니다.
ollama stop <model-name>

Ollama 실행 모델 API와 FAQ의 메모리·모델 유지 설정을 참고합니다. API 요청의 keep_alive: 0으로 언로드하는 방법도 제공합니다. 모델 언로드, 서비스 종료, PC 종료는 서로 다른 작업입니다.

RAM의 모델을 버튼 하나로 VRAM에 자유롭게 옮기는 일반 기능이 있다고 가정하지 않습니다. 런타임·모델·장비가 지원하는 배치 설정을 확인하고, 필요하면 작업을 마친 뒤 재로드하는 실습으로 나눕니다. ComfyUI의 메모리 정책도 해당 버전에서 별도로 검증해야 합니다.

실습 과제: 먼저 더미 메모리 목록에서 대상을 선택하고 영향 미리보기를 표시합니다. 실제 연동 시에는 정상 언로드 → 정상 서비스 중지 → 운영자 확인을 거친 강제 종료 순서로 설계하며, 공유 프로세스의 다른 서비스까지 종료되지 않는지 확인합니다.

“안 켜진다”는 하나의 원인이 아닙니다. 제어 API, 장비 접근, 프로세스, 서비스 준비, 모델 로드, UI 갱신 중 어디에서 실패했는지 나눠 기록합니다.

설비 점검 기록은 “문제사항”과 “해결 방안”을 분리하고, 기대 결과·실제 결과·재현 조건·변경 내용·검증 결과를 붙입니다. 해결 전에는 가설을 원인 확정으로 기록하지 않습니다.

감사 로그에는 요청 ID, 로그인 사용자 식별자, 대상, 작업, 변경 전후 의도, 관측 결과, 시각을 남깁니다. 인증 토큰·비밀값·모델 입력 원문은 그대로 저장하지 않습니다.

실습 과제: 더미 에이전트의 경로 하나를 잘못 설정해 Not Found를 만들고 위 형식으로 점검 기록을 작성합니다. 수정 후 같은 요청으로 재검증합니다.

원본의 Docker와 Vercel 간 프론트엔드 서빙 전환은 GPU 서비스 폴백과 다른 문제입니다. 학습 범위를 넓히기 전에 상태 조회·개별 제어·폴백의 기본 검증부터 마칩니다.

선택 과제로 진행한다면 현재 서빙 대상, 전환 예정 대상의 준비 상태, 실행 권한, 전환 결과, 복구 경로를 별도 계약으로 정의합니다. 단순히 토글의 색이 바뀌었다고 실제 트래픽 전환이 끝난 것은 아닙니다.

대상 준비 확인 → 운영자 변경 확인 → 전환 실행
             → 실제 요청 확인 → 성공 기록 또는 이전 대상으로 복구

실습 과제: 실제 도메인을 변경하지 않고 두 개의 더미 응답 사이에서 대상 선택만 시뮬레이션합니다. 현재 저장소의 배포 설정이나 DNS를 이 강의 때문에 수정하지 않습니다.

확인 기준: GPU 서비스 시작·중지 권한과 배포 전환 권한이 분리되고, 전환 전후의 대상과 복구 기준이 기록됩니다.

기능을 많이 등록하는 것보다 의도한 대상만 바뀌는지 검증하는 것이 먼저입니다. 아래 표는 수강생이 채울 평가표이며 실행 완료 결과가 아닙니다.

첫 단계는 더미 서비스로 검증하고, 다음은 격리된 로컬 서비스 하나, 마지막으로 사용자가 관리하는 장비로 확장합니다. 실제 데이터·장비 연결 전에 권한과 네트워크 접근 범위를 확인합니다.

학습자는 코드뿐 아니라 서비스 등록표, 상태 계약, 정책표, 검증 결과, 점검 기록을 함께 보관합니다. 사용 중 발견한 문제를 Documents·Prompt·Tool·Workflow·평가 시나리오에 반영하고 다시 검증합니다. 이것이 Build → Use → Observe → Update → Evaluate → Improve의 운영 흐름입니다.

AI Coding Agent에게 줄 구현 과제 예시

더미 장비 3개와 OCR 서비스로 퍼실리티 제어판을 구현한다.
먼저 상태 조회와 개별 제어만 만든다. 실제 장비 명령은 실행하지 않는다.
의도(desired_mode)와 관측(observed_state)을 분리한다.
정책은 Windows > Ubuntu > MacBook, 수동 OFF 우선이다.
수동 ON은 실행 유지이며 라우팅 고정과 구분한다.
위 검증표 중 해당 단계 시나리오를 실행하고 기대·실제·로그를 보고한다.
불확실한 대상과 전원 명령은 추측해서 실행하지 않는다.

원본을 다시 확인할 때

정책 변화는 원본 요청 20·39·64·75·86·97·104, 관측과 장애는 33·40·46·48·50·94, 모델은 62·63·78·81·85, 자원 관리는 8789·102105를 비교하면 맥락을 복원할 수 있습니다. 날짜·대화 ID 나열과 중복 요청은 본문에서 생략했고, 구현 과제·완료 기준은 튜토리얼 편집 과정에서 보완했습니다.