Supernova0417/weld-undercut-overlap-yolo

용접 비드 언더컷·오버랩 OK/NG 판정 (YOLO26m / YOLO11m)

공개 이미지 데이터셋으로 학습한 객체 검출 모델로, 용접 비드 사진에서 언더컷(undercut)과 오버랩(overlap)을 찾고 이미지 단위로 OK/NG를 판정합니다. 현장 사진 검증은 아직 하지 않았습니다.

폴더 구성

경로	내용
weld_yolo/prepare_dataset.py	원본 데이터셋 병합, 두 클래스만 남기기, 유사 이미지 그룹 분할
weld_yolo/check_dataset.py	분할 간 중복 점검, 라벨 확인용 이미지 모음
weld_yolo/train.py	학습 (기본 960px, 150 epoch, patience 40)
weld_yolo/evaluate.py	테스트 평가, 검증 세트 기준 OK/NG 임계값 결정
weld_yolo/analyze_results.py	출처별·임계값별 결과, 오판 이미지 모음
weld_yolo/judge.py	이미지나 폴더를 OK/NG로 판정 (--llm으로 VLM 소견 추가)
weld_yolo/field_test.py	시편/NG, 시편/OK 폴더로 정리한 현장 사진 채점
weld_yolo/llm_opinion.py	Roboflow Workflow(Qwen VL)로 짧은 한국어 소견 생성
weld_yolo/runs/	학습 기록, 평가 지표, 임계값 (weights/best.pt는 별도 업로드)

설치 (Windows, Python 3.13, NVIDIA GPU)

py -3.13 -m venv .venv
.venv\Scripts\python -m pip install torch torchvision --index-url https://download.pytorch.org/whl/cu130
.venv\Scripts\python -m pip install -r weld_yolo\requirements.txt

학습된 모델로 판정만 하기

1. 모델 파일 weld_yolo\runs\yolo26m\weights\best.pt(약 44MB)가 있는지 확인합니다. 없거나 1KB도 안 되면(Git LFS 없이 받은 경우) 아래 명령으로 받습니다.

   .venv\Scripts\hf download Supernova0417/weld-undercut-overlap-yolo weld_yolo/runs/yolo26m/weights/best.pt weld_yolo/runs/yolo26m/weights/thresholds.json --local-dir .
   

2. run_judge.bat을 더블클릭하고 사진 폴더 경로를 입력합니다. 폴더를 이 파일 위에 끌어다 놓아도 됩니다. 하위 폴더까지 모두 판정합니다.
3. 결과는 judged\<폴더 이름>\에 저장됩니다. 상자를 그린 사진은 원래 하위 폴더 구조대로 저장되고, report.csv에 사진별 판정이 정리됩니다.

명령줄에서는 judge.py 하나만 실행하면 됩니다. llm_opinion.py는 --llm을 붙일 때 judge.py가 불러 쓰는 모듈이라 따로 실행하지 않습니다. field_test.py는 사진을 OK/NG 폴더로 미리 나눠 두었을 때 정확도를 채점하는 별도 도구입니다.

.venv\Scripts\python weld_yolo\judge.py 사진_또는_폴더

LLM 소견을 쓰려면 프로젝트 폴더에 roboflow_api_key.txt를 만들고 API 키 한 줄만 넣습니다. 이 파일은 Git에 올라가지 않습니다. 사진이 Roboflow 서버로 전송되므로 회사 사진에는 사내 규정을 확인한 뒤에만 씁니다.

시연용: 회사 사진 3분류 (정상 / 오버랩 / 기공)

회사에서 찍은 근접 사진 70장(정상 30, 오버랩 20, 기공 20, 폴더 이름이 정답)으로 학습한 이미지 분류 모델입니다. 상자 없이 사진 한 장을 세 가지 중 하나로 판정하고, 정상이면 OK, 나머지는 NG로 표시합니다.

1. 모델 weld_yolo\runs_cls\demo\weights\best.pt(약 21MB)를 확인합니다. 없으면 받습니다.

   .venv\Scripts\hf download Supernova0417/weld-undercut-overlap-yolo weld_yolo/runs_cls/demo/weights/best.pt --local-dir .
   

2. run_demo.bat에 사진 폴더를 끌어다 놓습니다. 결과는 judged\<폴더 이름>_cls\에 저장됩니다.

• 사진을 긴 방향으로 세 조각 내어 각각 판정한 뒤 평균을 냅니다.
• NG 사진에는 모델이 판정 근거로 삼은 부분을 히트맵으로 겹치고, 가장 강한 부분(최댓값의 50% 이상)을 윤곽선으로 그립니다(Class Activation Map). 학습 이미지에 그린 것이 아니라 판정할 때 계산한 결과입니다. 기공은 구멍 위에, 오버랩은 비드와 모재 경계에 주로 나타납니다. 결함 경계를 측정한 값은 아니고 대략적인 위치입니다. --level 0.6처럼 윤곽선 기준을 바꿀 수 있고, --cam-ok를 붙이면 OK 사진에도 히트맵을 그립니다.
• 먼저 train 55장으로 학습하고 test 15장으로 확인했을 때 14장을 맞혔습니다. 틀린 1장은 사진 끝에 기공 하나만 걸친 사진입니다. test 사진도 같은 날 같은 시편을 찍은 것이라, 다른 시편에서도 이만큼 맞는다는 근거는 아닙니다.
• 비드가 화면 대부분을 차지하는 근접 사진에서만 씁니다. 멀리서 찍은 사진에도 셋 중 하나를 골라 답하므로 결과를 믿을 수 없습니다. 언더컷은 회사 사진이 없어 판정하지 않습니다.

실행 (학습부터)

공개 데이터셋 ZIP(YOLO 형식)을 data\raw\<이름>\에 풀어 둔 뒤 실행합니다.

.venv\Scripts\python weld_yolo\prepare_dataset.py --data-root data
.venv\Scripts\python weld_yolo\train.py --data-root data --model yolo26m.pt
.venv\Scripts\python weld_yolo\evaluate.py --data-root data --weights weld_yolo\runs\yolo26m\weights\best.pt
.venv\Scripts\python weld_yolo\judge.py 사진_또는_폴더
.venv\Scripts\python weld_yolo\field_test.py data\field

judge.py와 field_test.py에 --llm을 붙이면 사진마다 Qwen 3.8 VL 27B의 짧은 소견이 llm_opinion 열로 추가됩니다. roboflow_api_key.txt 또는 환경 변수 ROBOFLOW_API_KEY가 필요하고, 사진이 Roboflow 서버로 전송되므로 회사 사진에 쓰기 전에 사내 규정을 확인해야 합니다. 소견은 참고용이며 OK/NG 판정을 바꾸지 않습니다.

판정 기준

• 언더컷이나 오버랩이 임계값 이상으로 하나라도 검출되면 NG, 아니면 OK입니다. OK는 정상 용접이라는 뜻이 아니라 두 결함이 검출되지 않았다는 뜻입니다.
• 임계값은 검증 세트에서 정하고 weights/thresholds.json에 저장합니다. 현재 저장값은 NG 재현율 95% 기준인 0.0185이며, --threshold로 바꿀 수 있습니다.

결과 (공개 데이터 테스트 186장: NG 116, 배경 70)

항목	YOLO26m	YOLO11m
검증 mAP50 / mAP50-95	0.810 / 0.540	0.809 / 0.505
테스트 mAP50 / mAP50-95	0.767 / 0.526	0.735 / 0.478
테스트 언더컷 / 오버랩 AP50	0.713 / 0.821	0.666 / 0.803
학습 시간 (RTX 5090 Laptop)	5.1시간, 144 epoch	4.6시간, 150 epoch

YOLO26m의 이미지 단위 결과입니다. 임계값은 모두 검증 세트에서 정했습니다.

검증 기준	임계값	테스트 NG 재현율	테스트 배경 OK 비율
재현율 95%	0.0185	97.4% (113/116)	38.6% (27/70)
재현율 90%	0.1377	81.9% (95/116)	87.1% (61/70)
재현율 80%	0.3946	76.7% (89/116)	95.7% (67/70)

배경 이미지 70장 중 57장은 다른 결함(크랙, 기공, 스패터 등)이 있는 사진입니다. 그래서 배경 OK 비율은 양품 통과율이 아닙니다. 테스트 세트가 작고 데이터 출처가 두 곳뿐이라, 현장 사진 성능은 따로 확인해야 합니다.

출처

사전학습 모델

모델	출처	라이선스
YOLO26m (yolo26m.pt)	Ultralytics, COCO 사전학습 가중치	AGPL-3.0 (상용은 Ultralytics Enterprise License)
YOLO11m (yolo11m.pt)	Ultralytics, COCO 사전학습 가중치	AGPL-3.0 (상용은 Ultralytics Enterprise License)
Qwen 3.8 VL 27B (소견 생성)	Alibaba Qwen, Roboflow Workflow qwen_vlm@v4 블록으로 호출	모델 라이선스는 Qwen 배포 조건을 따름

학습 프레임워크는 Ultralytics 8.4.208, PyTorch 2.14.1 (CUDA 13.0)입니다.

학습에 사용한 데이터셋

데이터셋	버전	사용한 클래스	라이선스
WeldDefects (ugur-jeif9)	v16	undercut, overlap	CC BY 4.0
Weld Classifier (defspace)	v1	Undercut, Overlap (나머지는 배경으로 사용)	MIT

내려받았지만 아직 학습에 넣지 않은 데이터셋

데이터셋	이미지	라이선스	상태
welding crack (wonmu-huh) v2	169	CC BY 4.0	후보
2r_weld_dataset (mehak-laif)	2,926	CC BY 4.0	후보
CAT-Welding (asir-lni0w)	453	CC BY 4.0	후보 (빈 라벨 150장 확인 필요)
smawfilletweld (ai-weld-masters)	117	CC BY 4.0	후보 (필릿 용접)
Welding Defects (dave-prospect-sandbox)	1,284	CC BY 4.0	제외 (언더컷·오버랩 라벨 없음)
SMAW 용접 결함 (Mendeley Data f7j76vz53p)	원본 71장	페이지 표기 확인 필요	외부 언더컷 검증용 후보 (오버랩 없음, COCO 형식)

CC BY 4.0 데이터는 배포 시 출처 표기가 필요합니다.

다음 단계 검토

• 모델: 같은 데이터와 설정에서 YOLO26m이 테스트 mAP50-95 0.526으로 YOLO11m(0.478)보다 높고, 특히 언더컷에서 차이가 큽니다. 다음 학습은 YOLO26m을 기준으로 합니다.
• 추가 결함 클래스: 아래는 수집한 6개 데이터셋에서 클래스별로 결함이 있는 원본 사진 수를 센 값입니다. Roboflow 증강 복사본은 하나로 셌지만, 타일이나 유사 사진은 아직 묶지 않아 실제보다 많을 수 있습니다.

클래스	원본 사진 수	라벨이 있는 출처 수	판단
언더컷	약 1,170	6	현재 대상
오버랩	약 1,390	6	현재 대상
기공 (porosity)	약 1,100	5	추가 1순위
스패터 (spatter)	약 980	4	추가 1순위
크랙 (crack)	약 510	3	추가 2순위
용락 (burn-through)	약 170	3	보류 (대부분 한 출처)
융합 불량 (lack of fusion)	약 210	2	보류 (외관 기준 모호)
산화·변색	0	0	불가 (데이터 없음)

출처마다 라벨을 단 결함 종류가 달라, 어떤 데이터셋에서는 기공이 있어도 라벨이 없을 수 있습니다. 클래스를 늘리기 전에 출처별로 빠진 라벨을 처리하는 방법을 정해야 합니다.