quandao92/vision-inventory-inspection

프레스 생산 라인의 제품 판별 예측 용 YOLO 모델 카드

모델 세부사항

모델 설명

이 모델은 생산 라인에서 제품을 인식하여 생산된 제품의 수를 추정하고, 재고 수준을 계산하는 데 사용됩니다.
YOLOv7 및 YOLOv10 모델은 고속 객체 인식 및 분류를 위해 설계되어, 실시간으로 제품을 감지하고 개수를 셈으로써 생산량과 재고를 관리할 수 있습니다.

• Developed by: 박진제
• Funded by: 4INLAB INC.
• Shared by: None
• Model type: YOLOv7, YOLOv10 (Object Detection)
• Language(s): Python, PyTorch
• License: Apache 2.0, MIT, GPL-3.0

기술적 제한사항

• 이 모델은 제품을 인식하는 데 적절한 훈련 데이터를 필요로 합니다. 훈련 데이터셋이 부족하거나 불균형하면 성능이 떨어질 수 있습니다.
• 실시간 인식 성능은 하드웨어 사양에 따라 달라질 수 있으며, 높은 해상도에서의 인식 정확도가 떨어질 수 있습니다.
• 제품 간의 유사성이 매우 높거나 겹침이 있을 경우 정확도가 낮아질 수 있습니다.

학습 세부사항

Hardware

• CPU: Intel Core i9-13900K (24 Cores, 32 Threads)
• RAM: 64GB DDR5
• GPU: NVIDIA RTX 4090Ti 24GB
• Storage: 1TB NVMe SSD + 2TB HDD
• Operating System: Windows 11 pro

데이터셋 정보

이 모델은 프레스 생산 라인에서 촬영된 영상 및 이미지 데이터를 기반으로 학습되었습니다. 각 이미지에는 제품의 위치와 클래스(정상/불량 등)가 라벨링되어 있으며, YOLO 형식(.txt)으로 어노테이션 되어 있습니다. 데이터는 OpenCV 및 Albumentations 기반의 전처리와 데이터 증강(회전, 밝기 조정, 노이즈 추가 등) 과정을 거쳐 YOLOv7 및 YOLOv10 모델의 입력 크기(640×640)에 맞게 정규화됩니다.

학습된 모델은 객체 탐지를 통해 생산된 제품 수량을 자동으로 산출하고, 이를 기반으로 실시간 재고 수준 추정 및 생산량 분석에 활용됩니다.

• Data sources: https://huggingface.co/datasets/quandao92/vision-inventory-prediction-data
• Training size:
• Time-step: 5~7초

-Data Labelling Guide

YOLOv7 Model Architecture

• model: -input_layer:
  • image_size: [640, 640, 3] # Standard input size -backbone:
  • name: CSPDarknet53 # Backbone for feature extraction
  • filters: [32, 64, 128, 256, 512, 1024] # Filters for each layer -neck:
  • name: PANet # Path Aggregation Network for feature fusion
  • name: SPP # Spatial Pyramid Pooling for multi-scale context -head:
  • name: YOLOv7 Detection Head # Final detection layer
  • outputs:
    • boxes: 4 # Bounding box prediction (x, y, width, height)
    • classes: N # Number of object classes

YOLOv10 Model Architecture

• model:

  • input_layer:

    • image_size: [640, 640, 3] # 표준 입력 크기

  • backbone:

    • name: C2f-Backbone # YOLOv10 계열의 경량/고효율 C2f 모듈 기반 백본
    • stem: CBS(3, 32, k=3, s=2) # Conv-BN-SiLU 예시
    • stages:
      • {depth: 1, out_channels: 64, module: C2f} # P2 (stride=4) - 옵션
      • {depth: 2, out_channels: 128, module: C2f} # P3 (stride=8)
      • {depth: 2, out_channels: 256, module: C2f} # P4 (stride=16)
      • {depth: 1, out_channels: 512, module: C2f} # P5 (stride=32)
    • extras:
      • {name: SPPF, out_channels: 512} # 필요 시 사용(경량 SPPF)

  • neck:

    • name: PAN-FPN # 경로 집계 + FPN 결합(상/하향 피처 융합)
    • connections:
      • P3 <-> P4 <-> P5 # 상향/하향 경로 연결
      • ops: [Concat, CBS, C2f] # 융합 이후 경량 블록

  • head:

    • stride: [8, 16, 32] # 각 피처 맵에 대응
    • branches:
      • cls_branch: [CBS, CBS] # 클래스 예측 경로
      • box_branch: [CBS, CBS] # 박스 회귀 경로 (dx, dy, dw, dh)
      • obj_branch: [CBS] # 객체성(필요 시)
    • outputs:
      • boxes: 4 # (cx, cy, w, h) 또는 오프셋 파라미터
      • classes: N # 클래스 수
      • objectness: 1 # 선택적(설정에 따라 사용/미사용)

  참고: YOLOv10은 NMS-free/anchor-free 구성이 가능하며,

Optimizer and Loss Function

• training:
  • optimizer:
    • name: AdamW # Adam optimizer with weight decay
    • lr: 0.001 # Learning rate
  • loss:
    • classification_loss: 1.0 # Loss for classification (cross-entropy)
    • localization_loss: 1.0 # Loss for bounding box regression (MSE)
    • objectness_loss: 1.0 # Loss for objectness score (binary cross-entropy)

Metrics

• metrics:
  • Precision # Precision metric for evaluation
  • Recall # Recall metric for evaluation
  • mAP # Mean Average Precision for object detection
  • F1-Score # F1-Score for a balanced evaluation

Training Parameters

하이퍼파라미터 설정

• Learning Rate: 0.001.
• Batch Size: 1.
• Epochs: 200.

Data Parameters

● 데이터 증강

• 회전을 적용하여 모델의 일반화 성능 강화.

Evaluation Parameters

• F1-score: 95%이상.

학습 성능 및 테스트 결과

• 학습 및 검증 손실 그래프:

• 학습 결과표:

  

  학습 결과 버전1

  

  학습 결과 버전2

  

  학습 결과 버전3

• 테스트 결과 그래프:

모델 이력

학습 및 테스트 타임라인

날짜	버전	엔진	주요 변경	목표
2024-09-01	v0.1	YOLOv7	초기 베이스라인 수립, 데이터셋 v1 구성	mAP@0.5 ≥ 0.85
2024-10-05	v0.2	YOLOv7	증강(rotate/HSV), 앵커 재조정	F1 ≥ 0.90
2024-11-18	v0.3	YOLOv7	클래스 불균형 보정, Hard negative 샘플 추가	오탐 감소
2025-01-12	v0.4	YOLOv7	SPPF 경량화, FP16 추론	Latency 감소
2025-03-01	v1.0 (YOLOv7-Final)	YOLOv7	프로덕션 태깅, 안정판 배포	운영 이관
2025-03-20	v1.1	YOLOv10	C2f 백본/Anchor-free 전환, 재학습	mAP@0.5 +2~3%
2025-04-22	v1.2	YOLOv10	PAN-FPN 튜닝, Conf Threshold 조정	F1 ≥ 0.95
2025-05-28	v1.3	YOLOv10	채널 프루닝, TensorRT 최적화	FPS ≥ 30
2025-06-25	v2.0 (YOLOv10-Final)	YOLOv10	고객 PoC 완료, 문서화 및 아카이브	안정판

버전 간 비교 요약

항목	YOLOv7-Final (v1.0)	YOLOv10-Final (v2.0)	차이
mAP@0.5	0.90	0.96	+0.06
mAP@0.5:0.95	0.63	0.74	+0.11
F1-score	0.94	≥0.95	+
Latency (ms/frame)	5.6	3.9	-30%
Params (M)	37.2	22.5	경량화
FLOPs (G)	120	85	효율 향상
FPS (4090 기준)	190	260	+36%

설치 및 실행 가이라인

이 모델을 실행하려면 Python과 함께 다음 라이브러리가 필요합니다:

• numpy: 수치 연산.
• torch: 딥러닝 모델 학습을 위한 라이브러리.
• torch.distributed: 분산 학습을 위한 라이브러리.
• torch.nn: 신경망 구성 및 학습을 위한 라이브러리.
• torch.optim: 최적화 알고리즘을 위한 라이브러리.
• torch.utils.data: 데이터 로딩 및 처리.
• yaml: 설정 파일을 처리하는 라이브러리.
• tqdm: 훈련 진행 상황을 시각적으로 표시.
• test: 모델 평가를 위한 코드 (mAP 계산).
• models.experimental: YOLO 모델 로드 및 설정.
• models.yolo: YOLO 모델 클래스 정의.
• utils.autoanchor: 앵커 박스 체크 함수.
• utils.datasets: 데이터 로더 생성.
• utils.general: 데이터셋 확인, 요구사항 점검 등 유틸리티 함수.
• utils.google_utils: 모델 다운로드 기능.
• utils.loss: 손실 함수 계산.
• utils.plots: 학습 결과 시각화 함수.
• utils.torch_utils: 모델 저장, 분산 학습 관련 유틸리티.
• utils.wandb_logging.wandb_utils: WandB와 관련된 로깅 유틸리티.

모델 실행 단계:

1. 필요한 패키지 설치

pip을 통해 YOLOv7, YOLOv10에 필요한 패키지를 설치합니다.

pip install torch torchvision matplotlib opencv-python

2. 데이터 로드

• OpenCV 또는 이미지 파일 경로를 사용하여 데이터셋을 로드합니다.
• YOLOv7 모델은 이미지를 기반으로 객체를 인식하므로, 이미지 데이터를 준비하고 해당 데이터를 YOLO 형식에 맞게 라벨링해야 합니다.

3. 데이터 전처리

• 이미지 크기를 모델에 맞게 리사이징합니다. YOLOv7, v10 모델은 일반적으로 640x640 크기의 입력을 받습니다.
• 라벨링된 데이터가 YOLO 형식으로 되어 있는지 확인합니다 (각각의 객체에 대해 바운딩 박스를 포함한 텍스트 파일).

4. 스크립트 실행

• 데이터셋을 훈련 세트와 테스트 세트로 분할합니다.
• YOLOv7 모델을 불러오고, 훈련할 준비를 합니다.
• 모델을 훈련시키고, 테스트 데이터에서 성능을 평가합니다.

5. 모델 성능 최적화 및 튜닝

• 모델 훈련 후, 성능이 미비할 경우, 하이퍼파라미터 튜닝을 통해 모델을 최적화할 수 있습니다.
• 예를 들어, 학습률, 배치 크기, 또는 네트워크 구조를 조정하여 성능을 개선할 수 있습니다.

오픈소스 라이브러리 보안·라이선스 위험 관리 체계

본 프로젝트는 YOLOv7 기반 제품 판별 예측 모델로, Python 및 PyTorch 환경에서 다수의 오픈소스 라이브러리를 사용합니다.
이 문서는 해당 오픈소스 구성요소의 보안·라이선스 리스크를 관리하기 위한 절차와 준수 사항을 정의합니다.
내부망(On-premise) 환경이라도, 공급망(Supply Chain) 취약점과 라이선스 불이행은 법적 분쟁 및 서비스 중단으로 이어질 수 있습니다.

---

1. 위험 진술 (Risk Statement)

• 보안 위험: 외부 패키지(PyTorch, OpenCV 등) 또는 전이 종속성에서 발견되는 CVE 취약점으로 인한 악성 코드 삽입, 원격 코드 실행, 데이터 유출 위험.
• 법적 위험: Apache 2.0, MIT, GPL-3.0 등 라이선스 조건을 준수하지 않을 경우,
  소스 공개·배포 제한·손해배상·법적 분쟁 발생 가능.
• 운영 위험: SBOM 미작성, 버전 관리 부재, 승인 없는 오픈소스 반입으로 인해
  재현성 및 감사 대응 실패, 공급망 위협 발생 가능.

---

2. 적용 범위 (Scope)

구분	내용
코드	YOLOv7 학습 및 추론 스크립트 (train.py, detect.py, models/*.py, utils/*.py)
모델	학습된 YOLOv7 가중치 파일 (.pt)
데이터	라벨링 이미지 데이터, YOLO 형식의 어노테이션 텍스트
환경	내부망 서버 (GPU 학습용, API 서버, 배포 서버)
문서	모델 카드, 매뉴얼, SBOM, LICENSE, THIRD_PARTY_NOTICES.txt

---

3. 거버넌스 정책 (Governance Policy)

✅ 허용 라이선스

• Apache 2.0, MIT, BSD-2/3-Clause — 저작권/라이선스 고지 필수, Apache는 NOTICE 포함.
• PSF License, CC-BY — 출처 및 원저작자 명시.

⚠️ 조건부 허용

• LGPL, MPL-2.0, EPL-2.0 — 수정 시 공개 의무 확인 필요.
• Creative Commons SA — 동일조건배포(Share-Alike) 준수 필요.

⛔ 금지 라이선스

• GPL-2.0, GPL-3.0, AGPL-3.0
  • 외부 배포 또는 네트워크 서비스 제공 시 소스 공개 의무 발생.
  • 내부망이라도 재배포/서비스 제공 가능성이 있을 경우 사용 금지.
  • 단순 내부 실험 목적(비배포형)에 한해 예외적 검토 가능.

---

4. 오픈소스 반입 및 검증 절차

📌 A. 반입 단계

1. 등록 요청:
   • 패키지명, 버전, 출처(URL), 용도, 라이선스 명시
2. 보안 점검:
   • OSV-Scanner, Trivy, Grype 등으로 CVE 스캔 수행
3. 라이선스 검토:
   • SPDX 식별자 기반으로 허용/조건부/거절 분류
4. 승인 및 기록:
   • 허용된 패키지만 사내 미러(PyPI, Conda, Torch Hub Mirror)에 등록

⚙️ B. 개발 및 학습 단계

• requirements.txt, environment.yml 내 버전 고정 (예: torch==2.1.2)
• 가중치 파일 해시(SHA256) 기록
• 학습 로그에 프레임워크 버전 자동 기록

🚀 C. 배포 단계

• SBOM(Software Bill of Materials) 작성 (형식: CycloneDX JSON)
• THIRD_PARTY_NOTICES.txt 포함
• 컨테이너 이미지 또는 모델 패키지에 LICENSE / NOTICE 첨부

🔁 D. 운영 단계

• 월 1회 SCA 재스캔 및 보안 업데이트 반영
• CVSS 7.0 이상 고위험 취약점 → 즉시 버전 업 또는 차단
• 조치 내역 /logs/security_patch_history.txt 저장

---

5. Library requirements.txt 버전 이력 관리

본 프로젝트는 의존성 재현성과 공급망 보안을 위해 requirements.in → requirements.txt(해시 포함) → SBOM 순으로 잠금(lock) + 이력(History) + 감사(Traceability) 를 관리합니다.

1) 디렉터리 구조

/configs/dependency/
├─ base/
│ ├─ requirements.in
│ └─ requirements.txt # 해시 포함 (pip-compile 생성)
├─ dev/
│ ├─ requirements-dev.in
│ └─ requirements-dev.txt
├─ constraints.txt # 팀 공통 제약(충돌 방지/상·하한)
└─ CHANGELOG_requirements.md # 의존성 변경 이력

2) 브랜치/태그 규칙

• 브랜치: dep/upgrade-YYYYMMDD (예: dep/upgrade-20251021)
• 태그: deps-vMAJOR.MINOR.PATCH (예: deps-v1.4.2)
• 커밋 메시지 규칙:
  • deps(lock): pin versions (TF 2.15.0, numpy 1.26.4) + hashes
  • deps(upgrade): pandas 2.2.1 → 2.2.2 (CVE-XXXX fix)
  • deps(revert): rollback to deps-v1.3.0 due to perf regression

3) 이력(CHANGELOG) 표기

/configs/dependency/CHANGELOG_requirements.md 에 기록:

날짜	태그	변경 유형	주요 변경	근거/링크	영향
2024-09-25 (수)	deps-v0.1.0	initial / pin	초기 잠금: requirements.in → requirements.txt 생성 (--generate-hashes) — torch==1.13.1, torchvision, opencv-python, numpy, pandas 등 기본 의존성 고정 및 해시 포함	초기 보안정책·프로젝트 셋업	의존성 재현성 확보, 신규 환경 설치 시 동일성 보장
2024-11-18 (월)	deps-v0.2.0	security upgrade	SCA 대응: OpenCV / urllib3 / PyYAML 보안 패치 반영(버전 업) 및 pip-compile 재생성. Ultralytics/YOLO 관련 종속성 라이선스(AGPL 여부) 검토 기록 추가	SCA 리포트 2024-11 (OSV/Trivy)	고위험 CVE 완화, 라이선스 리스크 검토 필요(AGPL 대응)
2025-01-14 (화)	deps-v0.3.0	policy / constraints	constraints.txt 도입 (protobuf, grpcio 등 상·하한 제약), requirements-dev.txt 분리, THIRD_PARTY_NOTICES.txt 템플릿 추가 및 가중치(.pt) 해시 정책 명문화	내부 거버넌스 회의 2025-01	Dev/Staging 일관성 강화, 법적 증빙 준비
2025-04-15 (화)	deps-v1.0.0	upgrade (major)	PyTorch 버전(1.x → 2.1.x 계열) 및 관련 CUDA 툴체인 업데이트 반영; SBOM(CycloneDX) 자동생성 파이프라인 추가; SCA 재검증(고위험 CVE 패치)	OSV/Trivy 2025-04 보고서	성능·보안 개선, Staging에서 재훈련·검증 필요 (GPU 드라이버/컨테이너 영향)
2025-07-23 (수)	deps-v1.1.0	stabilization / pin	안정화 조치: 일부 패키지(예: numpy, torchvision) 버전 재핀 및 해시 재생성; THIRD_PARTY_NOTICES 업데이트(AGPL 표기 포함); 배포용 컨테이너에 LICENSE/NOTICE 동봉 규정 확정	성능/라이선스 검증 결과(2025-06~07)	프로덕션 배포 준비 완료, 법무·보안 감사 대응 체계 마련

원칙: 모든 변경은 왜 바꾸었는지(근거) 와 영향도 를 같이 남깁니다.

4) 승격(Dev→Staging→Prod) 워크플로

1. Dev 잠금: pip-compile --generate-hashes -o base/requirements.txt base/requirements.in
2. SCA 스캔: OSV-Scanner/Trivy로 CVE 확인 → 결과 첨부
3. Staging 검증: 재학습 스모크 테스트(샘플 데이터), pip check 무결성 확인
4. SBOM 생성: cyclonedx-py -o sbom_cyclonedx.json
5. Prod 승격: 태그(deps-vX.Y.Z) 달고 CHANGELOG 기록, 아티팩트 보관

5) 롤백 정책

• 문제가 발생하면 바로 이전 태그의 lockfile로 되돌립니다.
• 실행:

  git checkout tags/deps-v1.3.0 -- configs/dependency/base/requirements.txt
  pip install --require-hashes -r configs/dependency/base/requirements.txt
  

6) 생성/업그레이드 커맨드

# 도구 설치
  pip install pip-tools==7.4.1
  
  # (선택) 제약 파일 사용
  # constraints.txt 내 공통 제약 관리 (예: protobuf<5)
  
  # 1) 잠금파일 생성(해시 포함)
  pip-compile \
 --generate-hashes \
 --resolver=backtracking \
 --output-file configs/dependency/base/requirements.txt \
 configs/dependency/base/requirements.in
  
  # 2) 설치 시 해시 검증
  pip install --require-hashes -r configs/dependency/base/requirements.txt
  
  # 3) 의존성 충돌 검사
  pip check
  
  # 4) SBOM 생성 (감사/감리 대응)
  cyclonedx-py -o artifacts/sbom/sbom_cyclonedx_$(date +%F).json

5. SBOM 및 NOTICE

📘 SBOM 필드

항목	예시
Name	torch
Version	2.1.2
License	BSD-3-Clause
Hash	sha256:62ad4b6f9d8d2e10c6...
Supplier	PyTorch Foundation
Source URL	https://pypi.org/project/torch/

📜 THIRD_PARTY_NOTICES.txt

This product includes the following open-source components:

• Ultralytics 8.x - AGPL-3.0
• PyTorch 2.1.2 — BSD-3-Clause
• OpenCV 4.9.0 — Apache-2.0
• NumPy 1.26.4 — BSD-3-Clause
• Matplotlib 3.8.x — PSF License
• tqdm 4.66.2 — MPL-2.0
• PyYAML 6.0 — MIT License All copyrights belong to their respective owners.

6. 취약점 및 법적 리스크 대응 시나리오

시나리오	영향	대응	증적
CVE 고위험 패키지 발견	원격 코드 실행, 시스템 침해	버전 업그레이드, 교체, 영향 분석 보고서 작성	SCA 결과 리포트
GPL/AGPL 코드 혼입	소스 공개 요구, 배포 차단	대체 라이브러리로 전환	라이선스 검토서
데이터 약관 위반	법적 분쟁, 데이터 사용 제한	출처 명시, 약관 확인, 대체 데이터 확보	데이터 사용 로그
SBOM 미작성	감사 및 RCA 실패	즉시 SBOM 생성, 검증 프로세스 강화	SBOM 파일

---

7. 개발자 체크리스트

• [✔] YOLOv10 학습 환경 구성 (RTX 4090 / CUDA 12.3)
• [✔] 기존 YOLOv7 가중치 → YOLOv10 전이 학습(finetune) 적용
• [✔] requirements.txt 버전 고정 및 해시 기록
• [✔] SBOM 및 THIRD_PARTY_NOTICES.txt 포함
• [✔] SCA/라이선스 스캔 통과 리포트 첨부
• [✔] 데이터·모델 출처 및 권리 명시
• [✔] 배포 시 LICENSE / NOTICE 동봉
• [✔] 운영 로그에 버전 및 해시 기록

---

8. 역할 및 책임 (Roles & Responsibility)

역할	책임
개발팀	오픈소스 검증, SBOM 생성, 라이선스 관리
보안관리자	취약점 분석, 패치 계획 수립
법무팀	라이선스 해석 및 분쟁 대응
운영팀	로그 관리, 배포 검증, SBOM 보관