imai immersivecast ai
설치 · 사용 · REST API · 성능과 한계 · FAQ
v0.9.0 · 2026-07-09
Word(.docx) 다운로드 ↓ 인쇄 / PDF 저장 ← 자료실 imai 홈 ↖
사용자매뉴얼

설치 · 사용 · REST API · 성능과 한계 · FAQ

사용자매뉴얼 — imai (구조물 결함 점검 AI) v0.9.0

GS인증 시험 대상물 2/3. 설치 → 사용 → API → 성능과 한계 → 문제해결.

1. 설치

1.1 사전 요건

1.2 설치 절차 (오프라인/폐쇄망 가능)

  1. 배포 패키지를 서버의 임의 디렉토리에 복사·해제.
  2. VLM 모델 아카이브를 models-vlm/cosmos-reason2-8b/ 로 배치.
  3. 실행: bash install.sh - 이미지 로드 → 서비스 기동 → 헬스체크까지 자동 수행. - 완료 메시지: INSTALL_DONE, 웹 UI 주소 안내.
  4. 브라우저에서 http://<서버IP>:10036/ 접속.

1.3 설치 검증 (권장)

설치 직후 고객 노드에서 실제 동작을 확인합니다:

bash install-verify.sh   # GPU 사양·서비스 헬스·스모크 검출·지연 → install-report.json

1.4 서비스 관리

작업 명령
상태 확인 docker compose ps / curl http://127.0.0.1:10036/health
중지 / 시작 docker compose down / docker compose up -d
로그 docker logs imai-app, docker logs imai-vlm
버전 확인 /health 응답의 version 필드

2. 웹 UI 사용법

2.1 분석 흐름 (4단계)

  1. 설정 — 상단바에서 ①시설 유형(bridge/sewer/tunnel) 선택 ②촬영 스케일(mm/px, 아는 경우) 입력 ③VLM 오탐게이트 on/off.
  2. 업로드 — 점검 이미지를 드래그하거나 이미지 선택. 절대 mm·상태평가등급이 필요하면 [스케일 보정]으로 기지 길이 2점을 찍어 mm/px를 산출(또는 상단 mm/px 직접 입력) → [분석 시작].
  3. 검토(리뷰) — 이미지별 카드에서 결함 확인: - 주석 이미지(결함 윤곽·폭 라벨), 결함 표(종류·크기·심각도·VLM 판정+한국어 근거) - VLM이 기각(NOT_CRACK)한 항목은 취소선 — 점검자가 [유지/제외] 버튼으로 최종 결정 가능.
  4. 검토 확정(학습 반영, 선택) — 검토를 마치면 [검토 확정(학습 반영)] 을 누르면 점검자의 유지/제외 결정이 학습 데이터로 저장됩니다(§2.4). 안 눌러도 산출물엔 영향 없음.
  5. 산출물 — [리포트 다운로드](검토 반영 HTML, 인쇄→PDF) / [점검대장 CSV](Excel 호환) / [점검대장 Excel](.xlsx — 점검대장·손상물량 집계 2시트, 상태평가등급 포함) / [조서 문안 초안](선택 모듈 — LLM이 외관조사 서술문 초안 생성, 약 20~60초, 복사해 조서에 활용. 자동 초안이므로 수치·판단은 책임기술자 확인 후 사용).

2.2 리포트 구성

요약 통계 → 결함 종류/심각도 분포 → 손상물량 집계표(종류별 개소·연장/면적) → 점검대장(전체 결함 + 상태평가등급 참고) → 이미지별 상세. Excel(.xlsx)로도 export.

상태평가등급은 「시설물 안전·유지관리 실시 세부지침」 표6.2-4 참고 자동 제안이며, 부재·환경·누수/철근 동반 여부에 따라 인증 책임기술자가 확정합니다. 절대값은 스케일 보정 시에만 유효(허용균열폭 0.3mm 기준).

2.3 이력비교 (결함 진전 추적)

2.4 데이터 해자 — 점검자 검토로 모델이 개선됩니다 (선택 기능)

3. REST API

메서드/경로 기능 주요 파라미터
GET /health 상태·버전 —
GET /facilities 시설·결함종류 목록 —
POST /inspect 검출+게이트+주석 (JSON) files[], facility, mm_per_px, gate, want_report, save
POST /report 즉시 HTML 리포트 files[], facility, mm_per_px, gate, customer
POST /build_report 검토 반영 리포트(재추론 없음) JSON {results, customer, facility, mm_per_px}
GET /inspections 저장된 점검 이력 facility
POST /compare 이력비교 진전 리포트 JSON {baseline_id, current_id} 또는 결과셋 직접
POST /draft 조서 문안 초안(선택 모듈) JSON {results, summary, customer} — 모듈 미기동 시 503
POST /feedback 검토(유지/제외)를 학습 라벨로 확정 JSON {inspection_id, decisions:{defect_id: kept}}
GET /feedback_stats 축적 데이터 현황(리뷰·교정·시설별) —

예시:

curl -X POST http://<서버IP>:10036/inspect \
  -F "files=@img1.jpg" -F "files=@img2.jpg" \
  -F "facility=bridge" -F "gate=true" -F "mm_per_px=0.5"

4. 온프렘 PoC 평가 (icinspect-evaluate) — 귀사 데이터로 실측

도입 전, 귀사 시설 데이터로 정직한 측정 SLA를 방화벽 안에서 직접 확인합니다. 데이터는 밖으로 나가지 않습니다.

bash icinspect-evaluate.sh --facility bridge \
  --images /경로/점검사진 --out /경로/report.html [--customer "기관명"] [--limit N]

계약 성공기준(예: "FP X%→Y% @ recall 보존")을 광고가 아니라 귀사 데이터로 사전 합의하는 것이 목적입니다.

5. 성능과 한계 (정직 고지)

본 제품은 점검자 보조 도구입니다. 최종 결함 판정·구조 안전 판단·법적 책임은 인증 점검자에게 있습니다.

6. 문제해결(FAQ)

증상 조치
웹 UI 접속 불가 docker compose ps로 imai-app 기동 확인, 방화벽 10036 개방
"서비스에 연결할 수 없습니다" curl http://127.0.0.1:10036/health — 서비스 재기동
VLM 판정이 전부 SKIP VLM 서비스 로딩 중(수 분) 또는 미기동 — docker logs imai-vlm. 게이트 없이 검출은 정상 동작(자동 degrade)
GPU 메모리 부족 다른 GPU 프로세스 확인(nvidia-smi). VLM 게이트 비활성 운용 가능
분석이 느림 GPU 공유 부하 확인. 이미지 다량 시 배치 분할 업로드 권장
점검 이력이 사라짐 inspections 도커 볼륨 상태 확인(docker volume ls)
검토 확정 데이터 확인 feedback 도커 볼륨 + curl http://127.0.0.1:10036/feedback_stats

지원: pr@immersivecast.com

© immersivecast · imai 구조물 결함 점검 AI 문의 pr@immersivecast.com