Cursor AI로 AI 이미지 분석기 만들기 | Hugging Face API + Flask 프로젝트

 CursorAI를 활용하여, 룰 기반 봇에 이어 이번에는 AI 이미지 분석기를 만들어 보았습니다.
사람은 사진을 보면 "고양이가 있네", "자동차가 지나가고 있네"라고 판단할 수 있습니다.
하지만 컴퓨터는 이미지를 픽셀 값(숫자)의 집합으로 인식하기 때문에
사람과 달리 이미지 속 객체나 특징을 추출하는 과정이 필요합니다.

 이처럼 이미지 속의 객체나 장면을 분석하는 기술을 컴퓨터 비전(Computer Vision)이라고 하며,
최근에는 다양한 AI 모델을 활용하여 이미지를 자동으로 분석할 수 있습니다.

 이번 프로젝트에서는 Hugging Face에서 제공하는 ViT 이미지 분류 모델을 활용하여
AI 이미지 분석기를 만들어보고, 이전과 마찬가지로 Flask 웹 서비스로 실행하는 과정까지 진행해보겠습니다.

1. AI 이미지 분석기 활용

이미지 분석 기술은 이미 우리 주변에서 다양하게 사용되고  있습니다.

• 스마트폰 사진 앱의 자동 분류
• 쇼핑몰 상품 이미지 자동 분류
• CCTV 객체 인식
• 의료 영상 분석
• 자율주행 자동차의 주변 환경 인식

 이러한 기술들은 모두 컴퓨터 비전 기술을 기반으로 하며, 최근에는  Hugging Face와 같은 AI 플랫폼을 이용하여
복잡한 딥러닝 모델을 직접 학습하지 않아도 활용할 수 있습니다.

이번 프로젝트에서는 가장 기본적인 이미지 분류(Image Classification) 기능을 구현해 보겠습니다.

2. 프로젝트 설명

이번 프로젝트에서 만들 프로그램은 다음과 같은 기능을 제공합니다.

• 사용자가 이미지를 업로드
• AI 모델이 이미지 분석
• 상위 5개의 예측
• 결과 출력에 대한 설명 생성
• 웹에서 실행 가능

최종 프로젝트 구조

파일	역할
main.py	콘솔 인터페이스로 이미지 경로 입력 및 결과 출력
image_analyzer.py	이미지 검증, API 호출, 결과 처리, 설명 생성
requirements.txt	의존성
.env	토큰
app.py	Flask 서버 (메인 페이지 + 이미지 분석 API)
templates/index.html	업로드·결과 표시 UI
static/css/style.css	스타일
static/js/main.js	드래그앤드롭, 업로드, 결과 렌더링

3. 개발 과정

이전과 동일하게 개발에 사용하는 프롬프트는 단 3개 입니다.

• 콘솔에서 작동하는 프로그램을 만드는 프롬프트
• Flask 웹으로 변환하는 프롬프트
• Tailwind CSS로 웹을 꾸미는 프롬프트

항상 새로운 프로젝트를 시작할 때는 가상환경을 생성합니다.

# 파이썬 가상환경 만들기
python -m venv venv

# 파이썬 실행하기
venv\Scripts\activate

가상환경을 사용하는 이유는 프로젝트마다 필요한 라이브러리를 독립적으로 관리하기 위해서입니다.

3.1. 앱을 만드는 프롬프트

프롬프트 1:파이썬으로 사용자가 업로드한 이미지를 Hugging Face API의 vit-base-patch16-224 모델을 사용해 분석하고, '이 사진에 뭐가 있는지 설명해줘'라는 질문에 답할 수 있는 기능을 콘솔에서 확인 할 수 있게 만들어줘.

 이 프롬프트 만으로도 Cursor AI는 필요한 라이브러리 설치 코드와 콘솔에 출력하는 프로그램을 생성해 줍니다.

 AI는 학습 시점의 정보를 바탕으로 코드를 생성해주기 때문에 Hugging Face에서 API 주소나 사용 방법이 변경되었더라도 이전 방식을 사용할 수 있습니다.
따라서 최신 라이브러리 버전이나 API 변경 사항은 반영되지 않을 수도 있습니다.
이 경우 발생한 오류 메시지를 그대로 Cursor AI에게 전달하면 최신 방식으로 알맞게 코드를 수정해 줍니다.

프로그램 실행 과정

크게 4단계로 구성되어 있습니다.
┌ 사용자 이미지 경로 입력 → 이미지 파일 유효성 확인
├ HF_TOKEN 읽기 → Hugging Face API 연결하기
├ ViT 모델 분석하기 → 결과 JSON 반환
└ 결과 출력하기 → 상위 5개 출력 및 설명 생성

def analyze_image(image_path: str, hf_token: str | None = None) -> tuple[list[dict], str]:
    token = hf_token or get_hf_token()
    path = validate_image_path(image_path)
    predictions = classify_image(path, token)
    description = describe_image(predictions)
    return predictions, description

프로젝트 작동 순서
Python => HTTP 요청 => Hugging Face API => ViT 모델 => 분류 결과(JSON) => Python 출력

사용자 이미지 경로 입력하기

• input 함수로 입력 받기
• PIL로 이미지 파일 확인
• pathlib로 파일 위치 확인

Hugging Face Inference API로 이미지 분석하기

직접 딥러닝 모델을 구현하거나 학습시키지 않아도, 이미 학습된 모델을 API 형태로 사용할 수 있기 때문에
비교적 짧은 코드만으로도 AI 기능을 구현할 수 있습니다.
 API와 로컬을 연결하기 위해서는 API Key가 필요합니다. Hugging Face는 API 토큰을 사용합니다.
하지만 이 키 혹은 토큰은 민감한 정보를 가지고 있기 때문에 별도 파일로 관리하며, 업로드 하지 않게 조심해야 합니다.

from huggingface_hub import InferenceClient
from dotenv import load_dotenv

def get_hf_token() -> str:
	load_dotenv()
	token = os.getenv("HF_TOKEN", "").strip()
	return token

def classify_image(image_path: Path, hf_token: str) -> list[dict[str, float | str]]:
	client = InferenceClient(api_key=hf_token, provider="hf-inference", timeout=60)
	result = client.image_classification(str(image_path), model=MODEL_ID)
	return result
    
def describe_image(predictions: list[dict[str, float | str]], top_k: int = TOP_K) -> str:
	ranked = predictions[:top_k]
	top = ranked[0]
	top_label = str(top.get("label", "알 수 없음"))
	top_score = float(top.get("score", 0.0))
	return (
        f"이 사진에는 '{top_label}'이(가) 있을 가능성이 가장 높습니다 "
        f"(신뢰도 {top_score * 100:.1f}%).{others}"
	)

• dotenv을 이용한 환경 변수으로 API 토큰 관리
• Hugging Face InferenceClient 사용하기

ViT(Base Path16-224)

 학습된 ViT(Base Patch16-224) 모델은 Hugging Face에서 제공하는 ViT(Vision Transformer) 기반 모델입니다.
사용한 ViT는 224X 224 크기의 입력 이미지를 16 x16 작은 패치(Patch 16-224) 단위로 나누어 Transformer 구조로 분석하는 컴퓨터 비전의 기본(Base) 크기의 모델입니다.

3.2. Flask 앱으로 변환하고 꾸미는 프롬프트

이전과 동일한 프롬프트를 사용하였습니다.

프롬프트2: Web으로 실행하기 위해 flask 기능의 파일을 만들어줘. 파일은 app.py를 flask 실행을 위해 파일을 만들고 templates 폴더 안에 index.html을 만들고 static 폴더 안에 필요한 css, js 파일을 만들어줘

Flask는 AI 모델을 실행하는 것이 아니라 사용자가 업로드한 이미지를 Python 프로그램으로 전달하고, 분석 결과를 다시 웹 화면에 표시하는 역할을 합니다.

프롬프트3: Tailwind CSS를 적용해서 예쁘게 만들어줘.

업로드한 사진은 저희 형네 시바견 "레오"입니다.

• Flask 프로젝트 구조
• 웹페이지의 구조
• templates 폴더(동적 HTML)
• static 폴더(CSS, JavaScript, 이미지)
  
• HTML / CSS / JavaScript의 역할

---

느낌점

  AI를 활용하면 이미지 분석 기능도 비교적 짧은 프롬프트만으로 빠르게 구현할 수 있었습니다.
하지만 AI가 생성한 코드를 그대로 사용하는 것은 라이브러리 버전이나 API 변경으로 인해 오류가 발생할 수 있기 때문에
실제로 실행해 보면서 호환성 문제를 확인하고 수정하는 과정이 반드시 필요하다는 것도 알게 되었습니다.

 이미지 분석 결과도 흥미로웠습니다. 사진은 실제로는 시바견이었지만, AI는 가장 높은 확률로 켈피(Kelpie) 품종으로 예측했습니다. 두 견종은 외형이나 털 색상이 비슷한 부분이 있어 AI가 혼동했을 가능성이 있습니다.
또한 단일 사진만으로는 실제 크기나 거리 정보를 정확하게 알기 어렵고, 품종을 구분하는 데 필요한 꼬리 모양이나 체형 같은 특징도 촬영 각도에 따라 충분히 반영되지 않을 수 있다는 점을 확인할 수 있었습니다.

 이번 프로젝트에서는 직접 AI 모델을 학습시키지 않고 Hugging Face에서 제공하는 사전 학습 모델을 활용했습니다.
이러한 방식은 복잡한 딥러닝 과정을 거치지 않아도 높은 수준의 이미지 분석 기능을 빠르게 구현할 수 있다는 장점이 있습니다.
반면, 특정 품종을 정확하게 구분하거나 일반적이지 않은 결과를 원하는 경우에는 한계가 있을 수 있다는 점도 느꼈습니다.

 결과적으로 일반적인 사물이나 동물을 분류하는 작업에서는 충분히 좋은 성능을 확인할 수 있었지만,
세밀한 분류가 필요한 경우에는 AI의 예측 결과를 그대로 신뢰하기보다는
참고 자료로 활용하는 것이 적절하다는 점을 배울 수 있었습니다.
이번 프로젝트를 통해 컴퓨터 비전 기술의 기본 동작 원리와 사전 학습 모델을 활용하는 방법을 이해할 수 있었으며,
AI가 가진 장점과 한계를 함께 경험할 수 있는 좋은 실습이었습니다.

---

 이번 프로젝트에서는 Cursor AI를 활용해 컴퓨터 비전 기술 중 하나인 이미지를 분석하는 AI를 만들어 보았습니다.
다음 프로젝트에서는 텍스트를 이해하는 AI로 뉴스 자동 요약을 직접 만들어보겠습니다.