anofit

양품 사진만으로 학습하는 기계 시각 이상 탐지. 긁힘·깨짐 같은 구조적 불량과, 부품이 빠졌거나 자리가 바뀐 논리적 불량을 함께 잡는다. 학습부터 임계값 결정, 검사 시험까지 대시보드 하나로 한다.

Anomaly detection for machine vision, trained from good images only — structural and logical defects, with a dashboard. Documentation is in Korean; the CLI prints Korean.

• 문서·이슈: https://github.com/pashidl-lab/anofit — 대시보드 따라하기: docs/dashboard-walkthrough.md
• 문의·라이선스: pashidl.lab@gmail.com

무엇을 하나

0.1.1 부터는 어느 분기를 쓸지 품종마다 정한다 — 티칭 때 받은 불량이 8장 이상이면 그것으로 고르고(후보 넷 {struct, +dhist, +dpat, +dpat+dhist} 중, 기본값보다 2%p 이상 나을 때만 교체), 없으면 구조부 기본값을 쓴다. 5품종 실측: 고정 both 90.91 · 고정 구조부 92.03 · 불량으로 고르면 93.00 (breakfast_box 는 85.71 → 94.04). 논리부(phist)는 그대로 학습되며 임계값 탭에서 both 로 고를 수 있다.

0.3.0 부터는 논리부 세그멘터 학습 설정을 모든 품종에 대해 바꿨다 — fill_holes 끔 · LSA min_distance 0.1 (CSAD 가 공개한 screw_bag 설정). 그리고 후보의 첫 자리를 img+maha+phist 로 바꿔 후보 넷이 {img+maha+phist, +dhist, +dpat, +dpat+dhist} 가 됐다. 논리부(phist)를 가진 번들은 여백 없이 넷 중 가장 나은 것을 고르고, phist 가 없는 번들(구조부 전용)은 0.2.0 후보 그대로다. 5품종 사전 등록 재검증(재추출 불량 10장 · 30회 × 3, 2026-09-30): 불량으로 고른 평균 93.15 → 96.25, 한 품종 빼고 고른 LOCO 95.95 · screw_bag 84.19 → 97.68 · pushpins 논리 87.67 → 92.62 · juice_bottle 99.91 → 99.42 (진단 실험 2026-09-25: 93.21 → 96.34). 새 동작은 0.3.0 으로 다시 학습한 번들에만 적용된다. 번들 형식은 그대로라 0.2.0 에서도 0.3.0 번들이 열린다(requires_anofit 0.2.0).

MVTec LOCO 5품종 실측 (AUROC, 양품 = test/good, 이상 = logical + structural, 2026-09-09):

이 숫자는 라벨 없이, 양품만 보고 학습한 값이다. 논문 값은 라벨된 테스트 셋으로 가장 좋은 에폭을 고른 것이라 직접 비교가 안 된다. 자세한 것은 저장소의 BENCH_REPORT.md.

0.4.0 부터는 품종 타입을 고른다 — 대시보드 학습 탭에서 부품·배치형과 표면·외관형 중 하나. 부품·배치형(struct · logic · both)은 0.3.0 과 같은 학습 명령으로 같은 점수를 낸다(같은 학습 캐시를 0.3.0 과 0.4.0 으로 각각 조립·채점한 실측 차 ≤ 1e-6, 2026-10-03). 표면·외관형은 새 모드 --mode surface 다 — dpat + tile05 + tile1, 원본 해상도 사진을 겹친 타일로 훑어 양품 패치 메모리를 만든다(구조부·논리부 학습 없음). 인코더는 anofit fetch --mode surface 가 받는다(DINOv2 ViT-B/14 0.35 GB, sha256 대조). 받은 불량이 8장 이상이면 {tile05, tile1, dpat+tile1} 중 가장 나은 것을 고르고, 아니면 tile1 을 쓴다. 선택용 불량은 평소 조명에서 찍은 것으로 올린다. surface 는 GPU 전제다 — RTX 4090 장당 약 0.12 s(아래 8품종 평균), CPU 실측(16 스레드) 1× 13.4 s/장 · 0.5× 3.8 s/장.

백본은 DINOv2 가 기본이고 DINOv3 ViT-B/16 을 고를 수 있다 — anofit.yaml 에 surface_backbone: dinov3 와 dinov3_dir: <사용자가 받은 Hugging Face 폴더>. DINOv3 는 transformers 4.56 이상이 필요하다(낮으면 BundleError 로 알린다 — 패키지 의존성 하한은 그대로). DINOv3 는 재배포하지 않는다: anofit fetch 가 받지 않고 .afz 에도 싣지 않으니, 라인 PC 에도 같은 dinov3_dir 가 있어야 한다.

MVTec AD 2 8품종 실측 (사전 등록 · 한 번 실행, 2026-10-03; 선택 불량 = test_public/bad 이름순 앞 12장, 평가 = test_public/good 전부 대 나머지 bad, 이미지 AUROC, DINOv2):

can 은 54.33(tile1) — 원통 반사광, 알려진 한계라 평균에서 뺐다. 7품종 평균은 사전 등록 통과선 83.0 을 넘었다.

표면 결함은 작아서 이상맵을 원본 해상도로 본다 — 대시보드 검사 탭에서 확대하고, 명령줄은 anofit score --map out.jpg <번들> photo.png. 논리부 분할이 실패한 학습은 터미널의 [LOGIC-WARN] 한 줄과 대시보드 배너로 알린다. 호환이 바뀐 곳(score_raw 반환 개수 등)은 저장소의 CHANGELOG.md 를 본다.

0.4.1 부터는 대시보드 검사 탭에서 사진 여러 장을 고르면 파일 선택부 바로 아래에 점수 히스토그램이 뜬다 — 고른 사진의 점수 막대(OK 초록 · NG 빨강) 뒤에 같은 모드 검증 양품의 점수 분포(옅은 회색)와 지금 임계값 세로선을 겹쳐 그린다. 임계값 탭에서 σ 를 움직이면 세로선 · 표의 판정 · NG 장 수 · 아래 상세 판정이 서버를 다시 부르지 않고 같은 σ 로 바로 다시 판정된다. 표에서 줄을 누르거나 ↑/↓ 로 옮기면 그 줄이 표시되고, 키를 뗀 뒤 그 사진의 이상맵이 아래에 뜬다. 화면만 바뀐 판이다 — 번들 · 점수 · 명령은 0.4.0 과 같다.

설치

# 1) CUDA 에 맞는 torch 를 먼저 (pip 은 CPU 판을 고른다)
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 2) anofit — 학습까지 하려면 [train]
pip install "anofit[train]"

# 검사만 하는 기계(이미 학습한 번들로 점수만)면 이것으로 충분하다
pip install anofit

• Python 3.10 – 3.13, Windows / Linux
• 학습은 GPU 가 필요하다 (실측 요구 VRAM 은 anofit doctor 가 말해 준다). 검사는 CPU 로도 된다.
• 산출물·캐시·가중치를 어느 디스크에 둘지는 anofit.yaml 로 정한다 — 본보기 anofit.example.yaml. 없으면 사용자 캐시 폴더에 쌓인다.

5분 시작

anofit doctor --mode both      # 이 기계로 되는가: GPU · 디스크 · 의존성 · 가중치
anofit fetch  --mode both      # 파운데이션 가중치 10.4 GB (원 배포처에서, sha256 대조, 이어받기)
anofit serve                   # 대시보드 → http://127.0.0.1:8732

대시보드에서: 준비 탭에 양품 폴더(서버 경로 또는 업로드) → 학습 탭에서 품종 이름을 정하고 시작 → 끝나면 임계값 탭에서 운용점을 고르고 검사 탭에 사진을 넣어 본다.

명령줄로 같은 일:

anofit train --category my_part --good ./good --mode both       # 번들 생성
anofit threshold <번들>                                          # 임계값이 뜻하는 것
anofit score <번들> photo.png --models-dir <번들>                 # 한 장 판정
anofit export <번들> -o my_part.afz                               # 현장으로 옮길 파일 하나

현장으로 옮기기 (0.2.0)

• .afz 하나면 된다. 번들이 쓰기로 고른 분기에 필요한 사전학습 인코더(DINOv2 88 MB · wide_resnet50 100 MB)가 같이 실려서, 인터넷 없는 라인 PC 에서도 첫 채점부터 돈다. anofit info my_part.afz 가 무엇이 실렸는지 보여 준다.
• 번들 가중치는 pickle 이 아니다(형식 2). 0.1.x 가 내보낸 .afz 는 가중치가 pickle 이라 — 열면 그 안의 코드가 돌 수 있다 — 가져오기를 거부한다. 만든 쪽에서 0.2.0 으로 다시 내보내거나, 만든 사람을 믿으면 anofit import old.afz <폴더> --trust-legacy.
• 이미 가진 번들 폴더는 anofit migrate <번들> 로 형식 2 로 바꿔 둔다(점수는 그대로).
• 대시보드는 자기 기계에서만 받는다. 다른 PC 에서 열려면 SSH 터널을 쓰거나 anofit serve --host 0.0.0.0 --allow-host <그 PC 가 쓰는 이름/IP> (인증이 없으니 믿는 망에서만). 서버를 다시 켰으면 화면을 새로 고친다.

가중치는 동봉하지 않는다

패키지에는 없다 — anofit fetch 가 원 배포처에서 받는다(.afz 가 싣는 인코더는 위 절). 각 가중치는 배포처의 라이선스를 따른다 (THIRD_PARTY_NOTICES.md §6, 매니페스트 anofit/fetch_manifest.json).

--mode struct 만이면 6.7 GB, logic 만이면 6.3 GB. 첫 학습 때 라이브러리가 스스로 받는 것이 1 GB 쯤 더 있다 (bert-base-uncased, timm wide_resnet50_2, dino_vitbase8).

라이선스 · 체험

평가용 라이선스다 (LICENSE). 처음 실행한 날부터 90일은 그대로 쓴다. 그 뒤에는 학습·대시보드·fetch 가 멈추고, 이미 학습한 번들로 검사하는 것은 계속 된다 — 돌고 있는 라인이 서지 않는다.

anofit license                       # 남은 날짜
anofit license --install "<key>"     # 받은 키 설치 (또는 환경 변수 ANOFIT_LICENSE)

키는 pashidl.lab@gmail.com 으로 요청한다. 학습한 모델과 사진은 전부 사용자의 것이다.

포함된 오픈소스(GroundingDINO · SAM · RAM++ · CSAD · SALAD)는 각자의 라이선스를 그대로 가지며, 무엇을 고쳤는지는 THIRD_PARTY_NOTICES.md 에 파일 단위로 적었다.

안 되는 것 · 알아 둘 것

• 안전이 걸린 곳에는 쓰지 않는다 (LICENSE §7).
• 정확도는 사진·조명·부품에 달렸다. 위 표는 MVTec LOCO 에서의 측정이지 약속이 아니다.
• 학습 시간: 품종당 최대 2시간 (RTX 4090, both, 양품 300장 기준). 캐시 1~3 GB, 번들 0.1 GB.
• Windows 에서 폴더 가져오기는 심볼릭 링크를 쓰고, 안 되면 복사한다.