---
tags:
- clipsegmentation
- pytorch
- research
- computer-vision
library_name: torch
datasets:
- quandao92/ad-clip-dataset
metrics:
- f1
base_model:
- openai/clip-vit-base-patch32
---
CLIP 기반 제품 결함 탐지 모델 카드
## 목차 (Table of Contents)
- [모델 세부사항](#모델-세부사항)
- [모델 설명](#모델-설명)
- [기술적 제한사항](#기술적-제한사항)
- [학습 세부사항](#학습-세부사항)
- [하드웨어 환경](#하드웨어-환경)
- [소프트웨어 환경](#소프트웨어-환경)
- [데이터셋 정보](#데이터셋-정보)
- [데이터 라벨링 가이드](#데이터-라벨링-가이드)
- [AD-CLIP Model Architecture](#ad-clip-model-architecture)
- [Optimizer and Loss Function](#optimizer-and-loss-function)
- [Metrics](#metrics)
- [Training Parameters](#training-parameters)
- [Pre-trained CLIP model](#pre-trained-clip-model)
- [Evaluation Parameters](#evaluation-parameters)
- [학습 성능 및 테스트 결과](#학습-성능-및-테스트-결과)
- [모델 변경 이력](#모델-변경-이력-model-update-history)
- [모델 버전 관리 체계](#모델-버전-관리-체계-model-version-management)
- [설치 및 실행 가이드](#설치-및-실행-가이드)
- [모델 실행 단계](#모델-실행-단계)
- [Dataset Configuration](#dataset-configuration)
- [Image Pre-processing](#2-image-pre-processing-transformation)
- [Prompt Generating](#3-prompt-generating)
- [Initial Setting for Training](#4-initial-setting-for-training)
- [Hyper Parameters Setting](#5-hyper-parameters-setting)
- [Depth Parameter](#depth-parameter)
- [Image Size](#image-size)
- [Training Parameters](#training-parameters)
- [DPAM (Deep Prompt Attention Mechanism)](#dpam-deep-prompt-attention-mechanism)
- [Test Process](#6-test-process)
- [모델 공격 취약점 분석](#모델-공격-취약점-분석)
- [오픈소스 라이브러리 보안·라이선스 위험 관리 체계](#오픈소스-라이브러리-보안라이선스-위험-관리-체계)
- [References](#references)
---
## 모델 세부사항
### 모델 설명
AnomalyCLIP은 특정 객체에 의존하지 않는 텍스트 프롬프트를 학습하여 이미지 내의 전경 객체와 상관없이 일반적인 정상 및 비정상 패턴을 포착하는 것을 목표로 합니다.
이 모델은 CLIP 기반 이상 탐지 기법을 활용하여 제품 결함을 탐지합니다.
사전 학습된 CLIP 모델을 파인튜닝(Fine-tuning)하여 제품 이미지에서 결함을 식별하며, 이를 통해 생산 라인의 품질 관리 및 결함 탐지 작업을 자동화할 수 있습니다.
| 속성 | 값 |
|------|-----|
| **개발자** | 윤석민 |
| **제작 후원** | SOLUWINS Co., Ltd. (솔루윈스) |
| **참고 연구** | zhou2023 anomalyclip [[github](https://github.com/zqhang/AnomalyCLIP.git)] |
| **모델 유형** | CLIP (Contrastive Language-Image Pretraining) - Domain-Agnostic Prompt Learning Model |
| **프로그래밍 언어** | Python |
| **라이선스** | Apache 2.0, MIT, OpenAI |
### 기술적 제한사항
| 제한사항 | 설명 |
|---------|------|
| **데이터 요구사항** | 충분하고 다양한 훈련 데이터가 필요하며, 데이터셋이 부족하거나 불균형할 경우 모델 성능이 저하될 수 있습니다. |
| **성능 제한** | 실시간 결함 감지 성능은 하드웨어 사양에 따라 달라질 수 있으며, 높은 해상도에서의 정확도가 떨어질 수 있습니다. |
| **탐지 한계** | 결함이 미세하거나 제품 간 유사성이 매우 높은 경우, 모델이 결함을 정확하게 탐지하지 못할 수 있습니다. |
## 학습 세부사항
### 하드웨어 환경
| 구성 요소 | 사양 |
|---------|------|
| **CPU** | Intel Core i9-13900K (24 Cores, 32 Threads) |
| **RAM** | 64GB DDR5 |
| **GPU** | NVIDIA RTX 4090Ti 24GB |
| **Storage** | 1TB NVMe SSD + 2TB HDD |
### 소프트웨어 환경
| 구성 요소 | 버전 |
|---------|------|
| **OS** | Windows 11 64 bit / Ubuntu 20.04LTS |
| **Python** | 3.8 (anaconda) |
| **PyTorch** | 1.9.0 |
| **OpenCV** | 4.5.3 |
| **Cuda Toolkit** | 11.8 |
| **CuDNN** | 9.3.0.75 for cuda11 |
### 데이터셋 정보
이 모델은 제품의 정상 이미지와 결함 이미지를 사용하여 훈련됩니다.
이 데이터는 제품의 이미지, 결함 영역에 대한 ground truth 정보, 그리고 기타 관련 특성을 포함하고 있습니다.
이미지는 CLIP 모델의 입력 형식에 적합하도록 전처리되며, 결함 영역의 평가를 위해 ground truth 마킹이 포함됩니다.
- **데이터 소스:** https://huggingface.co/datasets/quandao92/ad-clip-dataset
- **데이터 수집 장비:**
- 수집 H/W: jetson orin nano 8GB
- 카메라: BFS-U3-89S6C Color Camera
- 렌즈: 8mm Fiexd Focal Length Lens
- 조명: LIDLA-120070
- 데이터 형식: .bpm, .jpg
#### 데이터 버전 관리
**1차: 20240903_V0_간이 환경 데이터 수집**
- V01: 전처리 전 데이터 원본 → 데이터 수집 원본: 120ea
- V02: 데이터 분류 → 정상/불량 분류: 116ea/4ea
- V03: 데이터 분류, 데이터 회전 → 이미지 증강_45/90/135도로 회전_360ea
Ground Truth Marking
PCA 분포 시각화
Isolation Forest로 이상값 식별 결과
**2차: 20240910_V1_하우징 내 이미지 수집**
- V01: 전처리 전 데이터 원본 → 데이터 수집 원본: 350ea
- V02: 데이터 분류 → 정상/불량 분류: 336ea/14ea
- V03: 데이터 분류, 데이터 회전 → 이미지 증강: 1,050ea
Ground Truth Marking
PCA 분포 시각화
Isolation Forest로 이상값 식별 결과
**3차: 20250328_V2_설비 내 데이터 수집**
- V01: 전처리 전 데이터 원본 → 이미지 수집_2,010개
- V02: 데이터 분류 → 정상/불량 분류 수행_1,918/92
- V03: 데이터 분류, 데이터 회전 → 이미지 증강 수행_이미지 회전을 통해 이미지 개수 6,030개
Ground Truth Marking
PCA 분포 시각화
Isolation Forest로 이상값 식별 결과
#### Data Configuration
**이미지 크기 조정 및 정규화:**
- 이미지는 일정한 크기(예: 518x518)로 리사이즈되며, CLIP 모델의 입력으로 적합하게 처리됩니다.
- 정규화를 통해 픽셀 값을 [0, 1] 범위로 변환합니다.
**Ground Truth 마킹:**
- 결함이 있는 이미지에 대해 결함 영역을 bounding box 형식 또는 binary mask로 표시합니다.
- 마킹된 데이터를 JSON 또는 CSV 형식으로 저장하여 모델 평가 시 사용합니다.
Ground Truth Marking
**데이터 분류:**
- Normal: 결함이 없는 정상 제품의 이미지.
- Error: 결함이 있는 제품의 이미지. 결함 위치와 관련 정보가 포함됩니다.
Normal Product Images
Error Product Images
### 데이터 라벨링 가이드
본 데이터 라벨링 가이드는 AnomalyDetection 기반 모델 학습을 위해 수집된 데이터를 라벨링하는 기준과 프로세스를 명확히 정의합니다.
데이터는 주로 정상(normal) 데이터를 중심으로 구성되며, 최소한의 비정상(anomaly) 데이터를 포함합니다.
본 가이드는 데이터의 품질을 유지하고 모델 학습 및 테스트를 최적화하는 데 목표를 둡니다.
#### 라벨링 범위
1. **정상(normal) 데이터:**
- 전체 데이터의 약 **95% 이상**을 차지.
- 다양한 환경 조건에서 수집된 데이터를 포함 (조명, 각도, 배경 등).
- 정상적인 상태의 금속 표면, 정밀한 구조, 균일한 광택을 가진 데이터.
2. **비정상(anomaly) 데이터:**
- 전체 데이터의 약 **5% 이하**로 제한.
- 결함 유형:
- **Scratch**: 스크래치.
- **Contamination**: 얼룩 또는 이물질.
- **Crack**: 표면 균열.
#### 데이터 라벨링 기준
**1. 파일 네이밍 규칙**
- 데이터 버전별 파일명은 버전별로 상이함.
- 각 버전의 데이터 관리 문서 참고.
- 데이터 폴더명은 **`<수집년월일>__<간단한 설명>`** 형식으로 작성.
- 예시: `20240910_V0_간이 환경 데이터 수집`.
**2. 라벨 메타데이터**
라벨 메타데이터는 CSV 형식으로 저장하며, 각 데이터의 라벨 및 설명을 포함합니다.
필수 필드:
- `image_id`: 이미지 파일명.
- `label`: 정상(`normal`) 또는 비정상(`anomaly`) 여부.
- `description`: 상세 설명(예: 결함 유형).
예시:
```json
{
"image_id": "normal_20241111_001.jpg",
"label": "normal",
"description": "매끄러운 표면을 가진 정상적인 금속 부품, 광택이 균일함."
}
{
"image_id": "abnormal_20241111_002.jpg",
"label": "error",
"description": "표면에 선형 스크래치가 발견됨."
}
```
## AD-CLIP Model Architecture
AD-CLIP 모델은 CLIP (ViT-B-32)을 백본으로 사용하여 이미지에서 특징을 추출하고, 대조 학습을 통해 이상을 탐지합니다.
최종 출력은 이미지가 비정상인지 정상인지를 판별하는 이상 점수와 각 클래스의 확률을 제공합니다.
CLIP-based Anomaly Detection Model Architecture
### 모델 구조
**입력 계층 (Input Layer):**
- 입력 이미지: 모델은 크기 [640, 640, 3]의 이미지를 입력받습니다. 여기서 640x640은 이미지의 가로와 세로 크기이며, 3은 RGB 색상의 채널 수를 나타냅니다.
- 기능: 이 계층은 입력된 이미지를 처리하고 모델의 나머지 부분에 맞는 형식으로 데이터를 준비하는 역할을 합니다.
**Backbone:**
- CLIP (ViT-B-32): 모델은 CLIP의 Vision Transformer (ViT-B-32) 아키텍처를 사용하여 이미지에서 특징을 추출합니다. ViT-B-32는 이미지를 이해하는 데 필요한 고급 특성을 추출할 수 있는 능력을 가지고 있습니다.
- 필터: 필터 크기 [32, 64, 128, 256, 512]는 각 ViT 레이어에서 사용되며, 이미지의 각 레벨에서 중요한 정보를 추출하여 특징을 학습합니다.
**Neck:**
- 이상 탐지 모듈 (Anomaly Detection Module): 이 모듈은 CLIP에서 추출된 특징을 기반으로 이미지를 분석하고 이상 여부를 판단합니다. 이 단계에서는 이미지 내에서 정상과 비정상 데이터를 구별하기 위한 중요한 처리가 이루어집니다.
- 대조 학습 (Contrastive Learning): 대조 학습 방법은 정상 이미지와 비정상 이미지 간의 차이를 학습하여, 이미지의 이상 여부를 더욱 명확하게 구분할 수 있게 도와줍니다.
**Head:**
- 이상 탐지 헤드 (Anomaly Detection Head): 모델의 마지막 부분으로, 이 계층은 이미지가 비정상적인지 정상적인지를 결정합니다.
- Outputs:
- 이상 점수 (Anomaly Score): 모델은 이미지가 이상인지 아닌지를 나타내는 점수(예: 1은 이상, 0은 정상)를 출력합니다.
- 클래스 확률 (Class Probabilities): 모델은 각 클래스에 대한 확률을 출력하며, 이 확률을 통해 결함이 있는지 없는지의 여부를 판단합니다.
## Optimizer and Loss Function
### Training
**optimizer:**
```python
name: AdamW # AdamW 옵티마이저 (가중치 감쇠 포함)
lr: 0.0001 # 학습률
```
**loss:**
```python
classification_loss: 1.0 # 분류 손실 (교차 엔트로피)
anomaly_loss: 1.0 # 결함 탐지 손실 (이상 탐지 모델에 대한 손실)
contrastive_loss: 1.0 # 대조 학습 손실 (유사도 기반 손실)
```
## Metrics
- Precision # 정밀도 (Precision)
- Recall # 재현율 (Recall)
- mAP # 평균 정밀도 (Mean Average Precision)
- F1-Score # F1-점수 (균형 잡힌 평가 지표)
## Training Parameters
**하이퍼파라미터 설정:**
- Learning Rate: 0.001
- Batch Size: 8
- Epochs: 200
## Pre-trained CLIP model
| Model | Download |
| --- | --- |
| ViT-B/32 | [download](https://openaipublic.azureedge.net/clip/models/40d365715913c9da98579312b702a82c18be219cc2a73407c4526f58eba950af/ViT-B-32.pt) |
| ViT-B/16 | [download](https://openaipublic.azureedge.net/clip/models/5806e77cd80f8b59890b7e101eabd078d9fb84e6937f9e85e4ecb61988df416f/ViT-B-16.pt) |
| ViT-L/14 | [download](https://openaipublic.azureedge.net/clip/models/b8cca3fd41ae0c99ba7e8951adf17d267cdb84cd88be6f7c2e0eca1737a03836/ViT-L-14.pt) |
| ViT-L/14@336px | [download](https://openaipublic.azureedge.net/clip/models/3035c92b350959924f9f00213499208652fc7ea050643e8b385c2dac08641f02/ViT-L-14-336px.pt) |
## Evaluation Parameters
- F1-score: 90% 이상 (1년차)
- F1-score: 98% 이상 (2년차)
## 학습 성능 및 테스트 결과
### 학습성능 결과 그래프
학습 과정 예시
1차 학습 성능
2차 학습 성능
3차 학습 성능
### 테스트 결과표
### 테스트 결과
Anomaly Product
Normal Product
---
## 모델 변경 이력 (Model Update History)
> AD-CLIP 기반 이상탐지 모델은 **총 3개 버전**으로 관리되고 있으며,
> 각 버전은 데이터 품질 개선 및 모델 성능 향상에 맞춰 체계적으로 변경·승인되었다.
> 모든 이력은 **데이터 버전, 모델 성능(F1), 승인자, 비고 사항**과 함께 기록되어 추적 가능하다.
| 버전 | 변경일 | 주요 변경 내용 | 데이터 버전 | 성능 (F1) | 조치자 | 검수자 | 비고 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| **v1.0.0** | 2024-09-23 | 초기 데이터셋 기반 모델 최초 학습 | 20240910_V0 | 0.91 | 윤석민 | 최종호 | 최초 배포 |
| **v1.1.0** | 2024-09-26 | 데이터 증강(회전·조명) 및 Prompt 수정 | 20240920_V1 | 0.94 | 윤석민 | 최종호 | 성능 안정화 |
| **v2.0.0** | 2025-06-19 | 데이터 30% 증가, 전체 재학습 수행 | 20250610_V3 | 0.98 | 윤석민 | 최종호 | 2차년도 목표 충족 (고도화 완료) |
---
## 모델 버전 관리 체계 (Model Version Management)
> AD-CLIP 모델의 변경·교체 시점은 **데이터 버전, 코드 버전, 성능 로그, 승인 기록**이 상호 연계되며,
> 이를 통해 **모델 신뢰성, 재현성, 추적성**을 동시에 확보한다.
### 버전 명명 규칙
| 구분 | 규칙 | 예시 |
|------|------|------|
| **데이터 버전** | `YYYYMMDD_V#` 형식 | `20240910_V0` |
| **모델 버전** | `vX.Y.Z` 형식 | `v2.0.0` |
| **운영 로그 버전** | `LOG_YYYYMMDD` 형식 | `LOG_20251027` |
---
### 관리 구성요소
| 구분 | 관리 항목 | 설명 |
|------|------------|------|
| **데이터 관리** | 수집·라벨링·무결성 검증 | 해시(SHA256) 기반 데이터 추적 |
| **모델 관리** | 학습·평가·재학습 결과 기록 | 각 버전별 체크포인트 및 메타데이터 저장 |
| **운영 관리** | 배포·로그·성능 추적 | 운영 중 Probability·F1 모니터링 |
| **보안 관리** | Adversarial 탐지·Poisoning 방지 | 공격 탐지 시 모델 격리 및 복원 수행 |
---
### 모델 변경 절차 요약
| 단계 | 주요 활동 | 산출물 |
|------|------------|--------|
| ① 성능 감시 | Probability 및 F1 Score 자동 모니터링 | `eval_log.json` |
| ② 교체 검토 | 기준 미달 시 재학습 모델 생성 | `candidate_model.pth` |
| ③ 성능 비교 | 기존 vs 신규 모델 검증 | `compare_result.xlsx` |
| ④ 승인 | 검수자 승인 및 회의록 기록 | `approval_log.json` |
| ⑤ 배포 | 운영 반영 및 로그 등록 | `release_note.md` |
| ⑥ 추적 | 모델 교체 이력 업데이트 | `model_version_log.csv` |
---
### 모델 메타데이터 예시
```json
{
"model_name": "ADCLIP_v2.0.0",
"data_version": "20250610_V3",
"created_at": "2025-06-19T10:00:00Z",
"f1_score": 0.98,
"precision": 0.977,
"recall": 0.982,
"optimizer": "AdamW",
"framework": "PyTorch 2.0.0",
"base_model": "openai/clip-vit-base-patch32",
"author": "윤석민 책임연구원",
"reviewer": "최종호 책임연구원",
"status": "Active",
"notes": "2차년도 전체 재학습 및 성능 고도화 버전"
}
```
---
## 설치 및 실행 가이드
이 모델을 실행하려면 Python과 함께 다음 라이브러리가 필요합니다:
### 필수 라이브러리
- **ftfy==6.2.0**: 텍스트 정규화 및 인코딩 문제를 해결하는 라이브러리
- **matplotlib==3.9.0**: 데이터 시각화 및 그래프 생성을 위한 라이브러리
- **numpy==1.24.3**: 수치 연산을 위한 핵심 라이브러리
- **opencv_python==4.9.0.80**: 이미지 및 비디오 처리용 라이브러리
- **pandas==2.2.2**: 데이터 분석 및 조작을 위한 라이브러리
- **Pillow==10.3.0**: 이미지 파일 처리 및 변환을 위한 라이브러리
- **PyQt5==5.15.10**: GUI 애플리케이션 개발을 위한 프레임워크
- **PyQt5_sip==12.13.0**: PyQt5와 Python 간의 인터페이스를 제공하는 라이브러리
- **regex==2024.5.15**: 정규 표현식 처리를 위한 라이브러리
- **scikit_learn==1.2.2**: 기계 학습 및 데이터 분석을 위한 라이브러리
- **scipy==1.9.1**: 과학 및 기술 계산을 위한 라이브러리
- **setuptools==59.5.0**: Python 패키지 배포 및 설치를 위한 라이브러리
- **scikit-image**: 이미지 처리 및 분석을 위한 라이브러리
- **tabulate==0.9.0**: 표 형태로 데이터를 출력하는 라이브러리
- **thop==0.1.1.post2209072238**: PyTorch 모델의 FLOP 수를 계산하는 도구
- **timm==0.6.13**: 다양한 최신 이미지 분류 모델을 제공하는 라이브러리
- **torch==2.0.0**: PyTorch 딥러닝 프레임워크
- **torchvision==0.15.1**: 컴퓨터 비전 작업을 위한 PyTorch 확장 라이브러리
- **tqdm==4.65.0**: 진행 상황을 시각적으로 표시하는 라이브러리
- **pyautogui**: GUI 자동화를 위한 라이브러리
### 설치 명령어
```bash
pip install -r requirements.txt
```
---
## 모델 실행 단계
### Dataset Configuration
Dataset configuration 예시:
```
├── data/
│ ├── COMP_1/
│ │ ├── product_1/
│ │ │ ├── ground_truth
│ │ │ │ ├── anomaly_1
│ │ │ │ ├── anomaly_2
│ │ │ │
│ │ │ ├── test/
│ │ │ │ ├── good
│ │ │ │ ├── anomaly_1
│ │ │ │ ├── anomaly_2
│ │ │ │
│ │ │ ├── train/
│ │ │ │ ├── good
│ │ │ │ ├── anomaly_1
│ │ │ │ ├── anomaly_2
│ │
│ │ ├── product_2/
│ │
│ │ ├── meta.json
│
│ ├── COMP_2/
```
#### JSON 파일 생성
데이터셋의 모든 정보를 JSON 파일(meta_train.json, meta_test.json)로 저장:
```bash
cd dataset_config
python dataset_get_json.py
```
#### Ground Truth 생성
수동으로 모든 ground truth(anomaly mask만) 생성:
```bash
cd dataset_config
python image_ground_truth.py
```
#### 학습 및 테스트용 데이터셋 설정
```bash
cd training_libs
python dataset.py
```
**Dataset 클래스 동작 방식:**
- `__init__` 메서드: 데이터셋의 루트 디렉토리, 변환 함수, 데이터셋 이름, 모드를 입력으로 받습니다
- 메타 정보를 담은 JSON 파일 (meta_train.json)을 읽어와 클래스 이름 목록과 모든 데이터 항목을 리스트에 저장합니다
- `generate_class_info` 함수를 호출하여 클래스 정보를 생성하고 클래스 이름을 클래스 ID에 매핑합니다
- `__len__` 메서드: 데이터셋의 샘플 수를 반환합니다
- `__getitem__` 메서드: 주어진 인덱스의 샘플 데이터를 반환합니다
- 이미지 경로를 통해 이미지를 읽고, 이상 여부에 따라 마스크 이미지를 생성합니다
- 필요시 이미지와 마스크에 변환 함수를 적용합니다
- 이미지, 마스크, 클래스 이름, 이상 여부, 이미지 경로, 클래스 ID를 포함한 딕셔너리를 반환합니다
### 2. Image Pre-processing (Transformation)
학습 및 테스트를 위한 이미지 전처리:
```python
# training_libs/utils.py
# AnomalyCLIP_lib/transform.py
```
**Data Processing Techniques:**
- **normalization**: 이미지 픽셀 값을 평균 및 표준편차로 표준화
- 방법: `'Normalize' from 'torchvision.transforms'`
- **max_resize**: 이미지의 최대 크기를 유지하며, 비율을 맞추고 패딩을 추가하여 크기 조정
- 방법: `Custom 'ResizeMaxSize' class`
- **random_resized_crop**: 훈련 중에 이미지를 랜덤으로 자르고 크기를 조정하여 변형을 추가
- 방법: `'RandomResizedCrop' from 'torchvision.transforms'`
- **resize**: 모델 입력에 맞게 이미지를 고정된 크기로 조정
- 방법: `'Resize' with BICUBIC interpolation`
- **center_crop**: 이미지의 중앙 부분을 지정된 크기로 자르기
- 방법: `'CenterCrop'`
- **to_tensor**: 이미지를 PyTorch 텐서로 변환
- 방법: `'ToTensor'`
- **augmentation (optional)**: 데이터 증강을 위해 다양한 랜덤 변환 적용, `'AugmentationCfg'`로 설정 가능
- 방법: `Uses 'timm' library if specified`
### 3. Prompt Generating
```python
# training_lib/prompt_ensemble.py
```
**Prompts Built in the Code:**
1. Normal Prompt: `["{}"]`
- Normal Prompt Example: "object"
2. Anomaly Prompt: `["damaged {}"]`
- Anomaly Prompt Example: "damaged object"
**Construction Process:**
1. `prompts_pos (Normal)`: Combines the class name with the normal template
2. `prompts_neg (Anomaly)`: Combines the class name with the anomaly template
### 4. Initial Setting for Training
학습 데이터셋 경로 및 모델 체크포인트 저장 경로 정의:
```python
parser.add_argument("--train_data_path", type=str, default="./data/", help="train dataset path")
parser.add_argument("--dataset", type=str, default='smoke_cloud', help="train dataset name")
parser.add_argument("--save_path", type=str, default='./checkpoint/', help='path to save results')
```
### 5. Hyper Parameters Setting
#### Depth Parameter
프롬프트 학습 중 학습할 임베딩의 깊이를 설정합니다. 이는 모델이 데이터에서 복잡한 특징을 학습하는 능력에 영향을 미칩니다:
```python
parser.add_argument("--depth", type=int, default=9, help="image size")
```
#### Image Size
학습에 사용할 입력 이미지의 크기를 정의합니다 (픽셀 단위):
```python
parser.add_argument("--image_size", type=int, default=518, help="image size")
```
#### Training Parameters
학습 파라미터 설정:
```python
parser.add_argument("--epoch", type=int, default=500, help="epochs")
parser.add_argument("--learning_rate", type=float, default=0.0001, help="learning rate")
parser.add_argument("--batch_size", type=int, default=8, help="batch size")
```
#### DPAM (Deep Prompt Attention Mechanism)
DPAM의 크기/깊이 파라미터:
```python
parser.add_argument("--dpam", type=int, default=20, help="dpam size")
```
**DPAM 설정 가이드:**
- ViT-B/32 and ViT-B/16: `--dpam` should be around 10-13
- ViT-L/14 and ViT-L/14@336px: `--dpam` should be around 20-24
**DPAM 설명:**
- DPAM은 특히 Vision Transformers (ViT)에서 모델의 특정 레이어를 개선하고 향상시키는 데 사용됩니다
- Attention 메커니즘을 통해 모델이 각 레이어 내에서 중요한 특징에 집중할 수 있도록 도와줍니다
- DPAM은 여러 레이어에 적용되어 더 깊고 세부적인 특징 추출을 가능하게 합니다
- DPAM이 영향을 미치는 레이어 수는 조정 가능합니다 (`--dpam`), 모델을 얼마나 fine-tune할지 제어합니다
- 전체 모델을 개선하려면 `--dpam`을 모델의 레이어 수로 설정할 수 있습니다 (예: ViT-B의 경우 12, ViT-L의 경우 24)
- 최종 레이어(일반적으로 모델이 복잡한 특징을 학습하는 곳)에만 집중하려면 더 적은 DPAM 레이어를 선택할 수 있습니다
### 6. Test Process
**Load pre-trained and Fine tuned (Checkpoints) models:**
1. **Pre-trained model** (`./pre-trained model/`):
- 사전 학습된 모델 (ViT-B, ViT-L, 등) 포함
- CLIP 모델 학습의 시작점으로 사용됨
- 사전 학습된 모델은 이전에 학습된 특징을 활용하여 학습 속도를 높이고 개선하는 데 도움이 됩니다
2. **Fine-tuned models** (`./checkpoint/`):
- 이 폴더의 "epoch_N.pth" 파일은 fine-tuning 과정 중 모델의 상태를 저장합니다
- 각 ".pth" 파일은 사전 학습된 모델에서 fine-tuned된 모델의 버전을 나타냅니다
- 이러한 체크포인트는 fine-tuning 재개, 다양한 단계에서 모델 평가, 또는 성능이 가장 좋은 버전 선택에 사용할 수 있습니다
---
## 모델 공격 취약점 분석
본 문서는 AnomalyCLIP 모델의 취약점 분석 및 적대적 공격(Adversarial Attacks)에 대한 방어 대책을 체계적으로 수립하기 위해 작성되었습니다.
모델의 신뢰성과 안정성을 확보하고 데이터 무결성을 유지하기 위해, 데이터 및 모델 수준의 방어 전략을 구현하고 성능을 평가한 결과를 포함합니다.
### 1. 취약점 분석
#### 적대적 공격 시나리오
1. **Adversarial Examples:**
- 설명: 입력 데이터에 작은 노이즈를 추가하여 모델의 예측을 왜곡합니다.
- 예: 정상 이미지를 결함 이미지로 예측하도록 유도합니다.
2. **Data Poisoning:**
- 설명: 학습 데이터에 악의적 데이터를 삽입하여 모델 학습을 왜곡합니다.
- 예: 비정상 데이터를 정상 데이터로 학습시키는 경우입니다.
3. **Evasion Attacks:**
- 설명: 추론 시 모델의 분류 결과를 조작합니다.
- 예: 결함 데이터를 정상으로 예측하도록 유도합니다.
#### 모델 및 데이터셋 영향
- 성능 저하: 적대적 샘플 입력 시 모델의 정확도 감소
- 무결성 손상: 데이터 변조로 인해 학습된 모델이 실제 환경에서 신뢰성을 상실
- 악의적 활용 가능성: 모델의 의사결정이 오작동하여 생산 품질 관리 실패 가능성 증가
### 2. 대응 방안
#### 데이터 수준 방어 대책
1. **데이터 정제:**
- 흐릿하거나 잘린 이미지 제거
- 데이터 노이즈 제거 및 결함 복구
- 결과: 데이터 품질 강화로 적대적 노이즈 효과 감소
2. **데이터 증강(Data Augmentation):**
- 랜덤 회전, 크기 조정, 밝기 및 대비 조정
- Gaussian Noise 및 Salt-and-Pepper Noise 추가
- 결과: 데이터 다양성 확보 및 모델 일반화 성능 강화
3. **데이터 무결성 검증:**
- 각 데이터 해시값(MD5) 저장 및 위변조 여부 확인
- 결과: 데이터셋 신뢰성 및 무결성 보장
#### 모델 수준 방어 대책
1. **Adversarial Training:**
- FGSM 기반의 적대적 샘플을 학습 데이터에 포함
- 결과: 적대적 샘플에서도 평균 정확도 5% 향상
2. **Gradient Masking:**
- 그래디언트를 숨겨 모델이 적대적 공격에 노출되지 않도록 방어
3. **Temperature Scaling:**
- 모델의 예측 확률을 조정하여 적대적 샘플 민감도 완화
#### 시스템 수준 방어 대책
1. **실시간 탐지 및 대응:**
- 입력 데이터의 이상 패턴을 실시간으로 탐지하는 시스템 구축
- 결과: 적대적 공격 발생 시 즉각적인 경고 및 대응 가능
2. **자동화된 방어 도구:**
- Adversarial Examples 생성 및 방어 테스트 자동화
### 3. 실험 결과
#### 평가 데이터
- 정상 데이터: 110건
- 결함 데이터: 10건
- 적대적 데이터(FGSM 공격): 100건
#### 주요 성능 지표
| 메트릭 | 기본 데이터 | 적대적 데이터 | 변화율 |
|--------|------------|---------------|--------|
| Accuracy | 98% | 92% | -6% |
| F1 Score | 0.935 | 0.91 | -2.5% |
| False Positive | 2% | 5% | +3% |
| False Negative | 3% | 7% | +4% |
### 4. 향후 계획
1. **다양한 공격 기법 테스트:**
- PGD, DeepFool 등 새로운 공격 기법 적용 및 평가
2. **모델 개선:**
- Contrastive Learning 및 앙상블 학습을 통한 견고성 강화
3. **실시간 방어 시스템 구축:**
- 모델의 실시간 예측 데이터를 분석하여 적대적 입력 탐지 및 차단
---
## 오픈소스 라이브러리 보안·라이선스 위험 관리 체계
> 본 섹션은 AnomalyCLIP/AD-CLIP 기반 모델 카드의 **보안·라이선스 거버넌스**를 정의합니다.
> 목적: 공급망(Software Supply Chain) 리스크 최소화, 라이선스 의무 준수, 재배포/상용화 적합성 확보.
### 1) 범위(Scope) & 원칙
- 대상: 학습/추론 코드, 스크립트, 도구 체인, 파생 산출물(가중치·체크포인트·GUI 실행파일), 배포 번들(whl/zip/docker)
- 원칙:
- 최소권한(Principle of Least Privilege)
- 재현가능 빌드(Reproducible Build)
- 투명성(명시적 라이선스 고지)
- 신속한 취약점 패치
- 상용 배포 시 모든 OSS 의무(저작권/NOTICE/소스 제공 범위 등) 선이행 후 배포
### 2) 라이브러리 & 라이선스 매트릭스
> 실제 사용하는 버전/라이선스는 `pip-licenses`/`cyclonedx-py` 산출물로 **자동생성**하여 본 테이블을 정기 업데이트합니다.
| 패키지 | 버전(예) | 라이선스(예) | 핵심 의무 |
|--------|---------|--------------|-----------|
| ftfy | 6.2.0 | MIT | 저작권 고지 유지 |
| matplotlib | 3.9.0 | PSF/MATPL | 저작권 고지 |
| numpy | 1.24.3 | BSD-3 | 저작권/면책 고지 |
| opencv-python | 4.9.0.80 | Apache-2.0 | NOTICE 포함 권장 |
| pandas | 2.2.2 | BSD-3 | 저작권/면책 고지 |
| Pillow | 10.3.0 | HPND-PIL | 저작권 고지 |
| PyQt5 / PyQt5-sip | 5.15.10 / 12.13.0 | GPLv3/상용듀얼 | 상용 배포·정적 링크 주의 |
| regex | 2024.5.15 | PSF | 저작권 고지 |
| scikit-learn | 1.2.2 | BSD-3 | 저작권 고지 |
| scipy | 1.9.1 | BSD-3 | 저작권 고지 |
| setuptools | 59.5.0 | MIT | 저작권 고지 |
| scikit-image | 최신 | BSD-3 | 저작권 고지 |
| tabulate | 0.9.0 | MIT | 저작권 고지 |
| thop | 0.1.1.post... | MIT | 저작권 고지 |
| timm | 0.6.13 | Apache-2.0 | NOTICE 포함 권장 |
| torch | 2.0.0 | BSD-3 | 저작권 고지 |
| torchvision | 0.15.1 | BSD-3 | 저작권 고지 |
| tqdm | 4.65.0 | MPL-2.0 | 수정 배포 시 소스 공개 요건 확인 |
| pyautogui | 최신 | BSD-3 | 저작권 고지 |
| CLIP 가중치(ViT-B/32 등) | 링크 참조 | OpenAI Terms(모델 가중치) | 상업적 이용 가능 여부/재배포 제한 사항을 개별 약관으로 재확인 필요 |
⚠️ **주의**: PyQt5는 GPLv3(또는 상용 라이선스)로 배포됩니다. 상용 배포/정적 링크 시 코드 공개 의무가 발생할 수 있으므로, 필요 시 상용 라이선스 구매 또는 Qt의 대체 GUI(예: PySide6 LGPL, 웹 프론트엔드) 검토가 필요합니다.
⚠️ **OpenAI CLIP 가중치**는 OpenAI 제공 약관을 반드시 확인해 재배포/상업적 사용 범위를 검증하세요.
### 3) 배포 시 필수 고지(Attribution) & NOTICE
- 저장소 루트에 `LICENSE`, `NOTICE`, `THIRD_PARTY_LICENSES/` 유지
- 패키지별 저작권·면책 고지 포함(자동수집 산출물 병합)
- 모델 가중치/데이터셋의 원저작자·약관을 README에 명시
### 4) 취약점 관리 프로세스 (CVE/SBOM)
**도구 체인(권장):**
- SBOM: `cyclonedx-py` / `pipdeptree` → `bom.json`/`bom.xml`
- 라이선스: `pip-licenses --format=json`
- 취약점: `pip-audit`, `safety`, (컨테이너) `trivy`
**정책:**
1. 주기적 스캔: 메인 브랜치 주 1회, 릴리스 직전 1회
2. 임계치: High/CRITICAL 발견 시 릴리스 중단, 패치/우회버전 평가
3. 변경관리: 패치 후 회귀 테스트, 성능 영향 보고
4. 추적: `SECURITY.md`에 CVE, 영향범위, 대응상태 기록
**예시 커맨드:**
```bash
# SBOM
python -m pip install cyclonedx-bom pipdeptree pip-licenses pip-audit safety
cyclonedx-py -o sbom.json
pipdeptree --json-tree > deps.json
pip-licenses --format=json --with-license-file > THIRD_PARTY_LICENSES/licenses.json
# 취약점
pip-audit # PyPI 에코시스템 취약점 스캔
safety check # 안전성 DB 기반 스캔
# 컨테이너(있을 경우)
trivy fs . # 소스/종속성 스캔
```
### 5. 개발·빌드 보안 (Development & Build Security)
> 안전하고 재현 가능한 빌드 파이프라인을 유지하여 공급망 리스크를 최소화합니다.
**권장 설정:**
- 잠금파일(`requirements.txt` / `constraints.txt`)에 정확한 버전(pin) 명시
- `pip-tools`를 사용해 의존성 동결 (`pip-compile`)
- CI/CD에서 `--require-hashes` 옵션으로 해시 검증
- 배포 아티팩트에 SHA256 해시 및 SBOM 포함
- API Key / Token은 코드에 절대 포함 금지 (환경변수 또는 Secret Manager 사용)
- 서명/무결성 관리: 해시 검증 및 SBOM 동시 배포
- 권한 분리: 학습/추론 서버는 최소 권한으로 실행
**설치 예시:**
```bash
pip install pip-tools
pip install cyclonedx-bom pipdeptree pip-licenses pip-audit safety
```
**빌드/검증 명령어:**
```bash
# 의존성 동결
pip-compile requirements.in --output-file requirements.txt
# SBOM 생성
cyclonedx-py -o sbom.json
# 라이선스 및 의존성 리스트
pip-licenses --format=json --with-license-file > THIRD_PARTY_LICENSES/licenses.json
# 취약점 점검
pip-audit
safety check
```
### 6. 데이터·모델 아티팩트 보안 (Data & Model Artifact Security)
> 모델과 데이터는 AI 공급망의 핵심 자산입니다.
> 아래 지침은 데이터 무결성과 모델의 신뢰성을 보장하기 위한 최소 보안 기준을 정의합니다.
**핵심 목표:**
1. 학습 및 평가 데이터의 무결성(Integrity) 보장
2. 모델 체크포인트(.pth 등)의 위변조 방지 및 추적성 확보
3. 적대적 공격(Adversarial Attack) 및 데이터 오염(Data Poisoning) 대응
4. 학습 재현성(Reproducibility) 보장
**데이터 보안 관리 절차:**
| 단계 | 설명 | 도구 / 실행 예시 |
|------|------|------------------|
| ① 수집 | 원본 데이터 수집 후 MD5/SHA256 해시 기록 | `sha256sum dataset.zip > dataset.sha256` |
| ② 검증 | 데이터 로딩 전 해시 일치 여부 확인 | `sha256sum -c dataset.sha256` |
| ③ 라벨 관리 | 라벨링 메타데이터를 별도 JSON/CSV로 분리 관리 | `meta_train.json`, `meta_test.json` |
| ④ 접근 제어 | 데이터 폴더 권한 최소화 (r-- 권한으로 공유) | `chmod 440 data/*` |
| ⑤ 버전 관리 | 변경 시점마다 버전명 기록 (예: `20241002_V2`) | Git tag 또는 DVC 사용 |
**모델 아티팩트 관리:**
| 항목 | 관리 방법 | 주의사항 |
|------|-------------|-----------|
| **모델 가중치 (.pth)** | 체크포인트 파일마다 SHA256 생성 및 보관 | 파일명에 Epoch, 버전, 날짜 포함 (`adclip_e120_v2.pth`) |
| **학습 로그** | TensorBoard 또는 CSV 포맷으로 기록 | 손실 곡선 및 성능 지표 포함 |
| **모델 설정값 (Config)** | `config.yaml` 파일과 함께 저장 | 하이퍼파라미터 변경 시 버전 변경 필수 |
| **추적성 확보** | MLflow / W&B 또는 로컬 DB 사용 | `run_id`, `commit_id`, `data_version` 연동 |
| **비공개 저장소 관리** | 내부 NAS 또는 S3 Private Bucket 활용 | 공개 저장소 업로드 금지 (특히 고객 이미지 포함 시) |
**체크포인트 메타데이터 구조 (예시):**
```json
{
"model_name": "ad_clip_epoch_120.pth",
"sha256": "3f83c2a0aef2d7d9c2225b18d9ea435d...",
"data_version": "20241002_V2",
"created_at": "2024-10-12T09:30:00Z",
"train_command": "python train.py --config config.yaml --epochs 200",
"framework": "PyTorch 2.0.0",
"base_model": "openai/clip-vit-base-patch32",
"f1_score": 0.91,
"author": "윤석민",
"organization": "SOLUWINS Co., Ltd."
}
```
**적대적 공격(Adversarial Attack) 방어 강화:**
| 공격 유형 | 설명 | 대응 방안 |
|------------|------|------------|
| **FGSM (Fast Gradient Sign Method)** | 입력 이미지에 작은 노이즈 추가 | 학습 시 FGSM 샘플 포함 (Adversarial Training) |
| **PGD (Projected Gradient Descent)** | 반복적으로 노이즈 최적화 | `torchattacks` 라이브러리 기반 방어 테스트 |
| **Data Poisoning** | 학습 데이터에 악성 데이터 삽입 | 데이터 정제 및 해시 기반 무결성 검증 |
| **Evasion Attack** | 추론 시 입력 조작 | 확률 임계값 조정 + Gradient Masking |
**무결성 검증 자동화 스크립트 (예시):**
```bash
#!/bin/bash
echo "[INFO] Starting dataset integrity check..."
for file in $(cat dataset.sha256 | awk '{print $2}'); do
sha256sum -c dataset.sha256 --status $file
if [ $? -eq 0 ]; then
echo "[OK] $file integrity verified."
else
echo "[ERROR] $file integrity mismatch!"
exit 1
fi
done
echo "[INFO] Dataset integrity check completed successfully."
```
**권장 도구:**
| 목적 | 도구 | 비고 |
|------|------|------|
| 데이터 버전 관리 | DVC (Data Version Control) | Git 연동 가능 |
| 모델 실험 추적 | MLflow / W&B | 하이퍼파라미터 및 결과 추적 |
| 보안 스캔 | trivy, safety, pip-audit | 의존성 취약점 점검 |
| 무결성 검증 | sha256sum / openssl dgst | 해시 기반 검증 |
**예시 워크플로우 (모델 아카이브 생성):**
```bash
# 1. 해시 생성
sha256sum ad_clip_epoch_120.pth > ad_clip_epoch_120.pth.sha256
# 2. 메타데이터 생성
python gen_metadata.py --model ad_clip_epoch_120.pth --out model_info.json
# 3. 아카이브 패키징
tar -czvf adclip_model_v2.tar.gz ad_clip_epoch_120.pth model_info.json
# 4. 업로드 전 무결성 검증
sha256sum -c ad_clip_epoch_120.pth.sha256
```
**문서화 예시:**
> `/security/model_security/README.md` 파일 내 포함 권장
```markdown
# Model Artifact Security Policy
- 모든 모델 가중치는 SHA256 기반 무결성 검증 후 업로드됩니다.
- 각 모델에는 학습 환경, 데이터 버전, 하이퍼파라미터가 명시된 `model_info.json`이 포함됩니다.
- 데이터셋 및 모델 변경 시, 새로운 버전 태그(`_Vx.x`)를 부여하고 SBOM을 재생성합니다.
```
### 7. 재배포·상업화 가이드 (Redistribution & Commercialization)
> 오픈소스 라이선스 및 데이터셋·모델 약관을 준수하여 법적 리스크를 방지합니다.
**원칙:**
| 라이선스 | 사용 가능성 | 주의사항 |
|-----------|-------------|-----------|
| MIT / BSD / Apache-2.0 | 자유로운 상업적 사용 가능 | 저작권, NOTICE 파일 유지 |
| GPL / MPL 등 카피레프트 | 조건부 허용 | 링크 방식에 따라 소스 공개 의무 발생 |
| OpenAI CLIP 가중치 | 제한적 | 상업적 이용 약관 별도 확인 필요 |
| HuggingFace Dataset | 출처별 확인 | 데이터 제공자 약관 준수 필요 |
**체크리스트:**
- [x] `THIRD_PARTY_LICENSES/` 최신화
- [x] PyQt5 등 GPL 계열 의존성 검토
- [x] CLIP 가중치 약관 문서 첨부
- [x] SBOM + 해시 포함하여 배포
### 8. 내부 승인·RACI (Internal Approval & RACI)
> 프로세스 상 책임과 권한을 명확히 정의합니다.
| 활동 | Responsible | Consulted | Accountable |
|------|--------------|------------|--------------|
| 신규 OSS 도입 검토 | 개발팀 | 보안팀, 법무 | 보안팀장 |
| SBOM/라이선스 스캔 | 개발팀 | 보안팀 | 보안팀장 |
| 취약점 패치 적용 | 개발팀 | 보안팀 | 개발팀장 |
| 릴리스 승인 | 개발팀 | 보안·법무 | 제품 책임자(PO) |
### 9. PR 체크리스트 (Pull Request Checklist)
> 릴리스/병합 전 보안·법적 준수를 위한 점검 항목입니다.
```markdown
- [ ] requirements.txt 버전 핀 및 해시 포함
- [ ] pip-audit / safety: High·Critical 취약점 없음
- [ ] SBOM(cyclonedx-py) 생성 및 커밋
- [ ] THIRD_PARTY_LICENSES/ 갱신 완료
- [ ] NOTICE 및 LICENSE 최신화
- [ ] 모델 가중치·데이터셋 약관 검증 문서 첨부
- [ ] GUI 프레임워크(PyQt5 등) 상용성 검토 결과 첨부
- [ ] CI 빌드·테스트 통과
```
---
## References
- AnomalyCLIP: Object-agnostic Prompt Learning for Zero-shot Anomaly Detection [[github](https://github.com/zqhang/AnomalyCLIP.git)]