sojsoj 님의 블로그

16일차_Hugging Face

sojsoj — Wed, 22 Jul 2026 16:51:24 +0900

1. Hugging Face란?

Hugging Face는 AI 모델을 검색하고, 시험하고, 내려받고, 공유하는 플랫폼입니다.

흔히 “AI 분야의 GitHub”라고 부릅니다.

Models: 텍스트·이미지·음성·영상 AI 모델
Datasets: AI 학습용 데이터
Spaces: 브라우저에서 실행해 볼 수 있는 AI 데모
Papers: 최신 AI 논문
Collections: 목적별 모델 모음

Hugging Face의 Inference Providers는 무료 계정에 매달 소액의 체험 크레딧을 제공합니다. 현재 공식 문서에는 무료 사용자가 받는 크레딧이 월 $0.10이며 변경될 수 있다고 명시돼 있습니다. 크레딧을 소진하면 추가 크레딧 또는 별도 공급자 결제가 필요합니다.

공식 요금 안내

2. 목적별 무료 다운로드 가능 모델

아래 목록은 대표적인 공개·오픈 가중치 모델입니다. API 무료 제공을 보장하는 목록은 아니며, PC 사양과 라이선스를 반드시 확인해야 합니다.

텍스트 생성·챗봇·코딩

Qwen/Qwen3-4B	다국어·한국어·코딩·추론, 비교적 작은 4B 모델	Apache-2.0
Qwen/Qwen3-0.6B	저사양 PC 실습용	Apache-2.0
google/gemma-3-4b-it	이미지와 텍스트 이해가 가능한 소형 멀티모달 모델	Google 이용약관 동의 필요
microsoft/Phi-4-mini-instruct	작은 크기, 지시 수행과 코딩	MIT
deepseek-ai/DeepSeek-R1-Distill-Qwen-7B	수학·논리 추론 특화	비교적 높은 메모리 필요

초보자에게는 Qwen3-0.6B 또는 Qwen3-4B가 편합니다. Qwen3-4B는 100개 이상의 언어를 지원하며 Apache-2.0 라이선스로 공개돼 있습니다.

모델 설명

텍스트 → 이미지

black-forest-labs/FLUX.1-schnell	빠르고 품질이 좋은 이미지 생성	12B 모델로 GPU 메모리 요구량이 큼, 접근 조건 동의 필요
stabilityai/stable-diffusion-xl-base-1.0	자료와 예제가 풍부한 SDXL	라이선스 확인 필요
stabilityai/sd-turbo	적은 단계로 빠르게 생성	세밀한 품질은 SDXL과 차이 가능

FLUX.1-schnell은 Apache-2.0 모델이지만 파일 접근 전 조건 동의가 필요할 수 있습니다. 모델 페이지

이미지 → 이미지·사진 편집

Qwen/Qwen-Image-Edit	자연어로 사진 수정, 물체·스타일 변경	고성능 GPU 권장
timbrooks/instruct-pix2pix	“배경을 밤으로 바꿔줘” 같은 지시 기반 편집	비교적 오래됐지만 예제가 많음
stabilityai/stable-diffusion-2-1-unclip	이미지를 참고한 변형 생성	라이선스 확인 필요

Qwen Image Edit는 Apache-2.0이며 Diffusers에서 이미지와 명령을 함께 입력할 수 있습니다. 사용 예제

이미지 → 텍스트·이미지 이해

Salesforce/blip-image-captioning-base	사진 설명문 생성
Salesforce/blip-vqa-base	사진에 관한 질문에 답변
Qwen/Qwen2.5-VL-3B-Instruct	이미지·문서·차트 이해
google/gemma-3-4b-it	이미지와 텍스트를 함께 이해

저사양 실습에는 BLIP, 문서·표·복합 이미지 분석에는 Qwen2.5-VL 계열이 알맞습니다.

음성 → 텍스트

openai/whisper-small	한국어 포함 99개 언어 음성 인식
openai/whisper-large-v3-turbo	정확도와 속도가 좋은 대형 모델
facebook/wav2vec2-base-960h	영어 음성 인식 실습

Whisper Small은 Apache-2.0이며 automatic-speech-recognition 파이프라인으로 실행할 수 있습니다. 모델 사용법

텍스트 → 음성

hexgrad/Kokoro-82M	작고 빠른 고품질 음성 합성	기본적으로 영어 중심
suno/bark-small	말투·효과음·다국어 음성 생성	결과가 일정하지 않을 수 있음
facebook/mms-tts-kor	한국어 음성 합성	자연스러움은 최신 상용 TTS보다 낮을 수 있음

Kokoro는 82M 크기의 Apache-2.0 오픈 가중치 모델이어서 로컬 실습에 적합합니다. 모델 설명

영상 생성

Wan-AI/Wan2.1-T2V-1.3B	텍스트 → 짧은 영상	이미지보다 훨씬 많은 GPU 메모리와 시간이 필요
stabilityai/stable-video-diffusion-img2vid-xt	이미지 → 영상	라이선스·GPU 요구사항 확인
ali-vilab/i2vgen-xl	이미지 기반 영상 생성	고성능 GPU 권장

이미지 분석·분리·깊이 측정

facebook/sam2-hiera-small	이미지·영상 속 물체 영역 분리
depth-anything/Depth-Anything-V2-Small-hf	한 장의 사진에서 깊이 추정
facebook/detr-resnet-50	사진 속 물체 탐지

SAM2 Small과 Depth Anything V2 Small은 모두 Apache-2.0으로 공개돼 있습니다. SAM2, Depth Anything

번역·임베딩·검색

facebook/nllb-200-distilled-600M	다국어 번역
intfloat/multilingual-e5-small	한국어 문서 검색·RAG·유사도
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2	다국어 문장 비교

3. Hugging Face Access Token을 VS Code에 연결하는 방법

VS Code 터미널에 Hugging Face 로그인 정보를 저장한 뒤, VS Code에서 실행하는 Python 코드가 해당 Access Token을 자동으로 사용하도록 설정합니다.

아래는 Windows와 VS Code 기준입니다.

아래처럼 venv 부분을 Conda 가상환경 기준으로 바꾸면 됩니다.

1단계: Conda 가상환경 준비

VS Code에서 File → Open Folder로 작업 폴더를 엽니다.

C:\AI\huggingface-study

VS Code에서 Terminal → New Terminal을 선택한 후 Conda 설치 여부를 확인합니다.

conda --version

Conda 가상환경 생성

Python 3.11 환경을 만듭니다.

conda create -n huggingface-study python=3.11 -y

가상환경을 활성화합니다.

conda activate huggingface-study

정상적으로 활성화되면 터미널 왼쪽에 다음처럼 표시됩니다.

(huggingface-study)

conda activate 오류가 발생할 때

다음 명령을 실행합니다.

conda init powershell

그다음 VS Code의 터미널을 모두 닫고 새 터미널을 열거나, VS Code를 재시작합니다.

conda activate huggingface-study

conda 명령 자체가 인식되지 않는다면 VS Code에서 Ctrl+Shift+P를 누르고 다음을 실행합니다.

Terminal: Select Default Profile

Command Prompt를 선택한 뒤 새 터미널에서 다시 시도할 수도 있습니다.

conda activate huggingface-study

VS Code Python 환경 선택

Ctrl+Shift+P를 누릅니다.
Python: Select Interpreter를 검색합니다.
다음과 비슷한 환경을 선택합니다.

Python 3.11 ('huggingface-study': conda)

선택된 Python 확인:

python -c "import sys; print(sys.executable)"

출력 경로에 huggingface-study 또는 Conda 환경 경로가 포함되어야 합니다.

4단계: 필요한 패키지 설치

먼저 Conda 환경이 활성화됐는지 확인합니다.

conda activate huggingface-study
python --version

pip를 업데이트합니다.

python -m pip install --upgrade pip

Hugging Face 기본 패키지를 설치합니다.

python -m pip install --upgrade huggingface_hub transformers accelerate safetensors

CPU에서 실행하는 경우

python -m pip install torch --index-url https://download.pytorch.org/whl/cpu

설치 확인:

python -c "import torch; print(torch.__version__); print('CUDA:', torch.cuda.is_available())"

CPU 환경이라면 다음처럼 표시되는 것이 정상입니다.

CUDA: False

NVIDIA GPU를 사용하는 경우

GPU 인식 여부를 확인합니다.

nvidia-smi

GPU가 표시되면 PyTorch 설치 페이지에서 다음 조건을 선택해 설치 명령을 받습니다.

OS: Windows
Package: Pip
Language: Python
Compute Platform: 자신의 CUDA 환경

설치 후 확인합니다.

python -c "import torch; print(torch.__version__); print('CUDA:', torch.cuda.is_available()); print(torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU 사용')"

이미지 생성·편집 패키지

python -m pip install diffusers pillow sentencepiece protobuf

음성 처리 패키지

python -m pip install librosa soundfile

전체 설치 확인

python -c "import torch, transformers, huggingface_hub; print('PyTorch:', torch.__version__); print('Transformers:', transformers.__version__); print('Hub:', huggingface_hub.__version__)"

5단계: Access Token으로 로그인

Conda 환경을 먼저 활성화합니다.

conda activate huggingface-study

Hugging Face에 로그인합니다.

hf auth login

메뉴에서 다음을 선택합니다.

Paste an access token

발급받은 hf_... 토큰을 붙여 넣습니다.

로그인 확인:

hf auth whoami

사용자 이름이 표시되면 정상적으로 연결된 것입니다.

로그아웃

hf auth logout

다른 토큰으로 다시 로그인

hf auth login --force

6단계: 연결 시험

Conda 환경을 활성화합니다.

conda activate huggingface-study

Python에서 로그인 상태를 확인합니다.

python -c "from huggingface_hub import whoami; print(whoami())"

모델 설정 파일 다운로드를 시험합니다.

hf download Qwen/Qwen3-0.6B config.json

파일이 내려받아지면 연결과 인증이 모두 정상입니다.

이후 VS Code를 다시 열 때

매번 새 터미널에서 다음 명령만 실행하면 됩니다.

conda activate huggingface-study

작업이 끝났을 때 가상환경 종료:

conda deactivate

전체 명령 모음

CPU 환경 기준으로 순서대로 실행할 명령입니다.

conda create -n huggingface-study python=3.11 -y
conda activate huggingface-study
python -m pip install --upgrade pip
python -m pip install --upgrade huggingface_hub transformers accelerate safetensors
python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
python -m pip install diffusers pillow sentencepiece protobuf
python -m pip install librosa soundfile
hf auth login
hf auth whoami
python -c "from huggingface_hub import whoami; print(whoami())"
hf download Qwen/Qwen3-0.6B config.json

7단계: 텍스트 AI 실행하기

VS Code에서 text_ai.py 파일을 만들고 다음 코드를 입력합니다.

from transformers import pipeline

model_id = "Qwen/Qwen3-0.6B"

generator = pipeline(
    task="text-generation",
    model=model_id,
    device_map="auto",
)

messages = [
    {
        "role": "user",
        "content": "허깅페이스가 무엇인지 초보자에게 한국어로 설명해 줘. /no_think",
    }
]

result = generator(
    messages,
    max_new_tokens=300,
    do_sample=True,
    temperature=0.7,
)

print(result[0]["generated_text"][-1]["content"])

실행합니다.

python text_ai.py

첫 실행에는 모델을 내려받기 때문에 시간이 걸립니다. 이후에는 기본적으로 다음 위치의 캐시를 사용합니다.

C:\Users\사용자이름\.cache\huggingface\hub

8단계: Access Token으로 API 호출하기

로컬 PC에서 모델 전체를 실행하지 않고 Hugging Face의 서버에 요청하는 방식입니다.

api_chat.py 파일을 만듭니다.

from huggingface_hub import InferenceClient

# hf auth login으로 저장한 토큰을 자동으로 사용합니다.
client = InferenceClient(provider="auto")

response = client.chat.completions.create(
    model="Qwen/Qwen3-4B",
    messages=[
        {
            "role": "user",
            "content": "인공지능을 초등학생도 이해할 수 있게 설명해 줘.",
        }
    ],
    max_tokens=300,
)

print(response.choices[0].message.content)

실행합니다.

python api_chat.py

모델이 현재 Inference Provider에서 제공되지 않으면 다른 API 지원 모델을 선택해야 합니다. API 사용은 무료 크레딧을 소모하며 한도 이후 비용이 발생할 수 있습니다.

9단계: 환경변수로 토큰 전달하기

CLI에 로그인하지 않고 현재 터미널에서만 토큰을 사용할 수도 있습니다.

$env:HF_TOKEN="hf_발급받은_토큰"

확인할 때 실제 토큰 전체를 출력하지 말고 다음처럼 검사합니다.

if ($env:HF_TOKEN) { "HF_TOKEN 설정됨" } else { "HF_TOKEN 없음" }

그다음 Python 프로그램을 실행합니다.

python api_chat.py

VS Code 터미널을 닫으면 이 환경변수는 사라집니다.

공식적으로 HF_TOKEN 환경변수가 설정돼 있으면 컴퓨터에 저장된 토큰보다 우선합니다. 환경변수 설명

피해야 하는 방법

다음처럼 토큰을 Python 코드에 직접 쓰지 않습니다.

# 사용 금지
token = "hf_실제토큰"

또한 토큰을 명령어에 그대로 포함하면 PowerShell 명령 기록에 남을 수 있으므로 hf auth login에서 대화식으로 붙여 넣는 방법이 가장 편리합니다.

10단계: 텍스트로 이미지 만들기

GPU가 있는 환경을 권장합니다.

image_ai.py를 만듭니다.

import torch
from diffusers import AutoPipelineForText2Image

model_id = "stabilityai/sd-turbo"

pipe = AutoPipelineForText2Image.from_pretrained(
    model_id,
    torch_dtype=torch.float16,
    variant="fp16",
)

pipe = pipe.to("cuda")

prompt = """
A quiet Korean traditional village in winter,
warm lights, cinematic composition, highly detailed
"""

image = pipe(
    prompt=prompt,
    num_inference_steps=2,
    guidance_scale=0.0,
).images[0]

image.save("generated_image.png")
print("generated_image.png 저장 완료")

실행:

python image_ai.py

일부 모델은 모델 페이지에 들어가 이용약관에 먼저 동의해야 합니다. 로그인했더라도 약관 동의가 없으면 401 또는 403 오류가 발생할 수 있습니다.

11단계: 이미지 내용을 글로 설명하기

필요 패키지:

pip install pillow transformers torch

image_caption.py:

from transformers import pipeline

captioner = pipeline(
    "image-to-text",
    model="Salesforce/blip-image-captioning-base",
    device_map="auto",
)

result = captioner("sample.jpg")
print(result[0]["generated_text"])

실행:

python image_caption.py

12단계: 음성을 텍스트로 변환하기

whisper_ai.py:

from transformers import pipeline

transcriber = pipeline(
    "automatic-speech-recognition",
    model="openai/whisper-small",
    device_map="auto",
)

result = transcriber(
    "meeting.mp3",
    generate_kwargs={
        "language": "korean",
        "task": "transcribe",
    },
)

print(result["text"])

실행:

python whisper_ai.py

13단계: Claude Code에서 Hugging Face CLI 활용하기

Claude는 Hugging Face 모델 자체가 아닙니다. 두 서비스를 연결하는 방법은 크게 두 가지입니다.

방법 A: Claude에게 실행 코드를 작성·수정하게 하기

Claude 또는 Claude Code에 다음처럼 요청할 수 있습니다.

Hugging Face의 Qwen/Qwen3-0.6B 모델을 로컬에서 실행하는
Python 프로그램을 작성해 줘.

조건:
- transformers pipeline 사용
- Windows와 VS Code 기준
- 토큰은 환경 변수로 읽기
- 한국어 입력 예제 포함
- 오류가 발생하면 원인을 설명하기

Claude Code를 VS Code 터미널에서 사용한다면 Claude가 프로젝트 파일을 만들고 실행 오류를 수정하도록 할 수도 있습니다. 다만 모델 다운로드와 실제 연산은 여전히 사용자 PC 또는 Hugging Face API에서 수행됩니다.

방법 B: Hugging Face MCP 연결하기

Hugging Face에 로그인합니다.
MCP 설정 페이지에서 Claude Desktop 또는 해당 MCP 클라이언트를 선택합니다.
페이지가 제공하는 설정을 복사합니다.
Claude의 MCP 설정에 붙여 넣습니다.
Claude를 다시 시작합니다.
다음처럼 요청합니다.

Hugging Face에서 Apache-2.0 라이선스이며
한국어를 지원하는 4B 이하 텍스트 생성 모델을 찾아서 비교해 줘.

또는:

텍스트를 이미지로 만드는 공개 모델 중
현재 Inference Provider로 시험 가능한 모델을 찾아 줘.

Hugging Face 공식 MCP는 Claude Desktop, VS Code, Cursor, Codex 등 MCP 호환 도구에서 모델·데이터셋·Spaces를 탐색할 수 있도록 지원합니다. 공식 문서

14단계: VS Code 또는 Claude에 MCP 연결하기

Hugging Face 공식 MCP 서버를 연결하면 AI 비서가 다음 작업을 수행할 수 있습니다.

모델과 데이터셋 검색
모델 설명서 확인
Hugging Face 문서 검색
Spaces 기반 커뮤니티 도구 실행

연결 순서:

Hugging Face에 로그인합니다.
Hugging Face MCP 설정을 엽니다.
VS Code 또는 Claude Desktop을 선택합니다.
화면에 제공되는 설정을 복사합니다.
해당 프로그램의 MCP 설정에 붙여 넣습니다.
VS Code 또는 Claude를 다시 시작합니다.
MCP 도구 목록에서 Hugging Face가 표시되는지 확인합니다.

MCP 설정 형식은 프로그램 버전에 따라 바뀔 수 있으므로 공식 설정 페이지에서 현재 클라이언트용 코드를 복사하는 것이 안전합니다. 공식 MCP 안내

설치 명령 한 번에 보기

기본 텍스트·API 환경:

python -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install --upgrade huggingface_hub transformers accelerate safetensors
pip install torch --index-url https://download.pytorch.org/whl/cpu
hf auth login
hf auth whoami

이미지·음성 기능 추가:

pip install diffusers pillow sentencepiece protobuf librosa soundfile

설치 검사:

python -c "import torch; print('PyTorch:', torch.__version__)"
python -c "import transformers; print('Transformers:', transformers.__version__)"
python -c "from huggingface_hub import whoami; print(whoami())"

화면 캡처 없이도 메뉴 이름과 명령만으로 진행할 수 있도록 구성했습니다. Hugging Face 화면이 변경되더라도 Settings → Access Tokens와 공식 MCP 설정 페이지를 기준으로 진행하면 됩니다.

15일차_YOLO 심화

sojsoj — Tue, 21 Jul 2026 16:49:53 +0900

YOLO 심화

탐지에서 추적·분석·배포까지

기준 모델: yolo11n.pt (작고 빠른 Nano 모델)

0. 시작 전 꼭 알아둘 것

YOLO 모델 이름 읽기

yolo11n.pt의 n은 Nano를 뜻한다. 일반적으로 n → s → m → l → x 순서로 모델이 커지고 정확도 잠재력은 높아지지만, 속도와 메모리 부담도 커진다.

모델	특징	초보자 권장 상황
yolo11n.pt	가장 작고 빠름	CPU·저사양 PC·웹캠 실습
yolo11s.pt	속도와 정확도의 절충	Nano 결과가 부족할 때
yolo11m.pt 이상	더 무겁고 느릴 수 있음	GPU가 있고 정확도가 더 중요할 때

주의 큰 모델이 항상 내 환경에서 더 좋은 것은 아니다. 먼저 yolo11n.pt로 전체 코드가 정상 작동하는지 확인한 뒤 모델만 바꾼다.

경로와 들여쓰기: 오늘 가장 많이 만난 오류

상대 경로는 현재 실행 폴더를 기준으로 찾는다. FileNotFoundError가 나면 os.path.abspath()로 실제 탐색 위치를 확인한다.

while문 안에서 반복할 코드는 모두 4칸 들여쓴다. 반복문 밖의 break는 SyntaxError: 'break' outside loop를 만든다.

함수 호출에는 괄호가 필요하다: cap.release()와 cv2.destroyAllWindows().

실행 위치가 달라도 안전한 경로 만들기

from pathlib import Path

base_dir = Path(__file__).resolve().parent
image_path = base_dir / "demo_data" / "image_1.png"

if not image_path.exists():
print("찾고 있는 위치:", image_path)
raise SystemExit

1. 객체 탐지와 객체 추적

구분	탐지(Detection)	추적(Tracking)
목적	현재 프레임의 물체 위치·종류 찾기	프레임 사이에서 같은 물체 ID 유지
상태 기억	없음: 매 프레임 독립	있음: 이전 프레임과 연결
대표 호출	model(frame)	model.track(frame, persist=True)
활용	사진 분석, 단일 장면	동선, 출입, 속도, 체류 분석

persist=True는 ‘이번 프레임이 이전 프레임과 이어진다’고 추적기에 알려 같은 객체의 ID를 유지하도록 돕는다.

기본 추적 코드

from ultralytics import YOLO
import cv2

model = YOLO("yolo11n.pt")
cap = cv2.VideoCapture(0)

while cap.isOpened():
success, frame = cap.read()
if not success:
break

results = model.track(frame, persist=True, conf=0.6, verbose=False)
annotated_frame = results[0].plot()
cv2.imshow("TRACK", annotated_frame)

if cv2.waitKey(1) & 0xFF == ord("q"):
break

cap.release()
cv2.destroyAllWindows()

초보자 체크 단일 이미지에는 지속적인 track ID의 의미가 없다. 연속 영상 프레임에서 사용할 때 추적의 장점이 생긴다.

2. from ultralytics import solutions란?

solutions는 YOLO의 탐지·추적 결과를 실제 업무 기능으로 묶어 둔 고수준 도구 모음이다. 직접 박스 좌표와 ID를 계산하는 코드 대신, 프레임을 솔루션 객체에 넣고 SolutionResults를 받는 방식으로 사용한다.

Solutions 공통 사용 형태

from ultralytics import solutions

tool = solutions.Heatmap(model="yolo11n.pt", show=False)
results = tool(frame)
processed_frame = results.plot_im

솔루션	무엇을 하는가	대표 결과
Heatmap	객체 위치를 누적해 활동 밀도 표시	plot_im, total_tracks
ObjectCounter	선 또는 영역을 통과한 IN/OUT 계산	in_count, out_count
RegionCounter	여러 구역 안의 객체 수 계산	region_counts
SecurityAlarm	탐지 수 조건 충족 시 이메일 알림	email_sent
ObjectBlurrer	탐지된 객체 영역 자동 블러	plot_im
DistanceCalculation	선택한 두 객체 사이 픽셀 거리	pixels_distance
SpeedEstimator	추적 이동량으로 속도 추정	speed_dict
ObjectCropper	탐지 객체를 이미지로 잘라 저장	total_crop_objects
TrackZone / QueueManager	구역 추적·대기열 분석	plot_im, counts

중요 일반 YOLO 결과는 results[0].plot()을 많이 쓰지만, Solutions 반환값은 보통 results.plot_im을 사용한다.

3. 모든 영상 솔루션의 기본 반복문

반복해서 재사용할 수 있는 골격

cap = cv2.VideoCapture(video_path)

if not cap.isOpened():
print("영상을 열 수 없습니다.")
raise SystemExit

while cap.isOpened():
success, frame = cap.read()
if not success:
print("영상이 끝났거나 프레임 읽기에 실패했습니다.")
break

results = solution(frame) # 반드시 while 안쪽
cv2.imshow("RESULT", results.plot_im)

if cv2.waitKey(1) & 0xFF == ord("q"):
break

cap.release()
cv2.destroyAllWindows()

cv2.VideoCapture(0): 기본 웹캠

cv2.VideoCapture('input.mp4'): 동영상 파일

cv2.VideoCapture(stream_url): CCTV/HLS 스트림. 주소가 종료되거나 차단되면 프레임을 읽지 못할 수 있다.

4. 히트맵(Heatmap)

히트맵은 추적 객체의 위치를 시간에 따라 누적하여 자주 등장하거나 오래 머문 영역을 색의 강도로 보여준다. 매장 동선, 진열대 관심도, 체류 구역, 입지 분석에 활용할 수 있다.

색 해석 색 의미는 선택한 colormap에 따라 달라진다. 일반적으로 밝고 뜨거운 색이 누적량이 큰 영역이지만, 반드시 사용한 색상표를 기준으로 해석한다.

사람만 누적하는 히트맵

from ultralytics import solutions
import cv2

video_path = "input.mp4"
cap = cv2.VideoCapture(video_path)

heatmap = solutions.Heatmap(
model="yolo11n.pt",
show=False,
classes=[0],
conf=0.5,
colormap=cv2.COLORMAP_MAGMA
)

while cap.isOpened():
success, frame = cap.read()
if not success:
break

results = heatmap(frame)
cv2.imshow("HEATMAP", results.plot_im)

if cv2.waitKey(1) & 0xFF == ord("q"):
break

cap.release()
cv2.destroyAllWindows()

인자	의미	예
model	사용 모델	yolo11n.pt
show	솔루션 내부 창 표시 여부	False이면 직접 imshow
classes	분석할 COCO 클래스 번호	[0]=사람, [2]=자동차
conf	최소 신뢰도	0.5
colormap	색상 지도	MAGMA, JET, HOT, PARULA
region	관심 선·다각형(선택)	[(x1,y1), ...]

5. 보안 알람(SecurityAlarm)

SecurityAlarm은 탐지 개수가 records 이상이면 주석이 그려진 이미지를 첨부해 이메일을 한 번 전송하는 솔루션이다. 사람·차량 감지, 무단 침입 경보, 야간 감시에 활용할 수 있다.

Gmail 준비

Google 계정의 2단계 인증을 켠다.

앱 비밀번호에서 16자리 비밀번호를 발급한다.

일반 로그인 비밀번호 대신 앱 비밀번호를 사용한다.

보안 원칙 앱 비밀번호를 .py 파일에 직접 저장하거나 화면 캡처로 공유하지 않는다. 환경 변수로 전달하고, 설치된 ultralytics 소스 파일을 Ctrl+클릭해서 수정하지 않는다.

실행 전 환경 변수 설정

# Windows 명령 프롬프트에서 현재 창에만 설정
set GMAIL_FROM=sender@gmail.com
set GMAIL_TO=receiver@gmail.com
set GMAIL_APP_PASSWORD=발급받은16자리앱비밀번호

사람 감지 이메일 알람

from ultralytics import solutions
import cv2, os

cap = cv2.VideoCapture(0)

alarm = solutions.SecurityAlarm(
model="yolo11n.pt",
show=False,
classes=[0], # 사람만
conf=0.5,
records=1 # 1명 이상이면 알림
)

alarm.authenticate(
os.environ["GMAIL_FROM"],
os.environ["GMAIL_APP_PASSWORD"],
os.environ["GMAIL_TO"]
)

while cap.isOpened():
success, frame = cap.read()
if not success:
break

results = alarm(frame)
cv2.imshow("ALARM", results.plot_im)
print("이메일 발송 여부:", results.email_sent)

if cv2.waitKey(1) & 0xFF == ord("q"):
break

cap.release()
cv2.destroyAllWindows()

알아둘 점 기본 구현은 한 이벤트에서 이메일을 반복 발송하지 않도록 email_sent 상태를 사용한다. 실제 서비스에서는 재알림 대기시간, 오탐 방지, 로그 저장을 추가한다.

6. 개인정보 보호 블러(ObjectBlurrer)

탐지된 객체의 박스 영역을 자동으로 흐리게 만들어 얼굴·차량 등 민감한 장면의 노출을 줄인다. 단, yolo11n.pt의 COCO 클래스는 ‘얼굴’ 전용 모델이 아니므로 사람 전체가 블러될 수 있다.

사람 영역 블러

blurrer = solutions.ObjectBlurrer(
model="yolo11n.pt",
show=False,
classes=[0],
blur_ratio=0.5
)

while cap.isOpened():
success, frame = cap.read()
if not success:
break

results = blurrer(frame)
cv2.imshow("BLUR", results.plot_im)

if cv2.waitKey(1) & 0xFF == ord("q"):
break

7. 거리 계산(DistanceCalculation)

영상 창에서 탐지 박스 두 개를 왼쪽 클릭하면 두 객체 중심 사이의 픽셀 거리를 계산한다. 오른쪽 클릭은 선택 초기화다.

단위 주의 pixels_distance는 실제 미터가 아니라 화면상의 픽셀 거리다. 실제 거리로 바꾸려면 카메라 보정, 원근 보정, 기준 길이가 필요하다.

두 객체 거리와 상태 출력

distance = solutions.DistanceCalculation(
model="yolo11n.pt",
show=True
)

while cap.isOpened():
success, frame = cap.read()
if not success:
break

results = distance.process(frame)
d = results.pixels_distance

if d and d > 0:
status = "SAFE" if d >= 150 else "WARNING" if d >= 100 else "DANGER"
print(f"[거리] {d:.2f}px [상태] {status}")

if cv2.waitKey(1) & 0xFF == ord("q"):
break

NULL window 오류 OpenCV 버전 차이로 'Ultralytics Solutions' 창을 못 찾는다면 show=False로 바꾸고 cv2.namedWindow와 cv2.setMouseCallback을 직접 연결하는 우회가 필요할 수 있다.

8. 카운팅: 선, 영역, 여러 구역

ObjectCounter: 선 통과 IN/OUT

count_points = [(376, 222), (378, 268)]

counter = solutions.ObjectCounter(
model="yolo11n.pt",
show=False,
region=count_points
)

results = counter(frame)
print("IN:", results.in_count, "OUT:", results.out_count)

좌표 2개는 선을 만들고, 3개 이상은 다각형 영역을 만든다. 좌표는 실제 처리 프레임의 크기와 일치해야 한다. 프레임을 640×480으로 리사이즈했다면 좌표도 그 화면 기준이어야 한다.

RegionCounter: 여러 구역 현재 인원

딕셔너리의 각 구역 사이에는 쉼표가 필요하다

region_points = {
"region-01": [(391, 198), (395, 270), (484, 278), (481, 196)],
"region-02": [(113, 306), (116, 388), (185, 384), (170, 311)]
}

region_counter = solutions.RegionCounter(
model="yolo11n.pt",
show=False,
region=region_points,
conf=0.4
)

results = region_counter(frame)
print(results.region_counts)

목적	추천 솔루션	핵심 결과
문을 지나간 누적 출입	ObjectCounter	in_count / out_count
각 구역에 현재 몇 명인지	RegionCounter	region_counts
한 구역에서 추적만	TrackZone	plot_im / total_tracks

9. 속도 추정(SpeedEstimator)

추적 객체의 프레임 간 이동량과 meter_per_pixel을 이용해 속도를 추정한다. 카메라 각도와 실제 축척이 맞지 않으면 숫자는 참고값에 그친다.

speed = solutions.SpeedEstimator(
model="yolo11n.pt",
show=False,
classes=[2],
line_width=2,
max_speed=120,
meter_per_pixel=0.05
)

results = speed(frame)
print(results.speed_dict)

오타 주의 line_with가 아니라 line_width다. ValueError: ... is not a valid solution argument가 나오면 인자 철자를 먼저 확인한다.

10. SAHI 슬라이싱 추론

SAHI(Slicing Aided Hyper Inference)는 큰 이미지를 작은 조각으로 나누어 각 조각에서 탐지한 뒤 결과를 원본 좌표로 합친다.

멀리 있는 자동차, 드론·위성 이미지의 작은 객체처럼 전체 이미지를 축소할 때 사라지는 대상을 찾는 데 유리하다.

일반 YOLO	SAHI
전체 이미지를 한 번에 리사이즈해 추론	여러 조각으로 나눠 확대된 상태로 추론
빠르고 단순	더 느리지만 작은 객체 탐지에 유리
중복 박스 병합 부담이 적음	겹침 비율로 경계 객체를 보완한 뒤 결과 병합

SAHI 기본 예제

from sahi import AutoDetectionModel
from sahi.predict import get_sliced_prediction

detection_model = AutoDetectionModel.from_pretrained(
model_type="ultralytics",
model_path="yolo11n.pt",
confidence_threshold=0.4,
device="cpu"
)

results = get_sliced_prediction(
"demo_data/image_1.png",
detection_model,
slice_width=256,
slice_height=256,
overlap_width_ratio=0.2,
overlap_height_ratio=0.2
)

results.export_visuals(export_dir="sahi/")
print("탐지 수:", len(results.object_prediction_list))

변수 저장 AutoDetectionModel.from_pretrained() 반환값을 detection_model에, get_sliced_prediction() 반환값을 results에 저장해야 NameError가 나지 않는다.

11. FastSAM: 이름·포인트로 영역 분할

FastSAM은 박스 탐지보다 더 세밀한 마스크 형태로 사물 영역을 분리한다. 전체 분할, 박스, 포인트, 텍스트 프롬프트를 지원한다.

from ultralytics import FastSAM

model = FastSAM("FastSAM-s.pt")

# 메모리를 아끼는 전체 분할
results = model(
"image.png",
imgsz=320,
retina_masks=False,
device="cpu"
)

# 특정 포인트의 대상만 선택하려면
# results = model("image.png", points=[[170, 480]], labels=[1], imgsz=320)

텍스트 프롬프트 texts='white tent'처럼 이름만으로 선택할 수 있지만 CLIP 모델이 추가로 필요해 다운로드·SSL 오류와 메모리 사용 증가가 생길 수 있다. 저사양 PC에서는 포인트 방식이 더 안정적이다.

12. 성능 확인과 OpenVINO

FPS 측정

start_time = time.perf_counter()
results = model(frame, verbose=False)
model_time = time.perf_counter() - start_time
fps = 1 / model_time if model_time > 0 else 0

annotated_frame = results[0].plot()
cv2.putText(
annotated_frame,
f"{fps:.1f} FPS",
(10, 30),
cv2.FONT_HERSHEY_SIMPLEX,
1,
(0, 255, 0),
2
)

해석 이 값은 모델 추론 중심의 순간 FPS다. 카메라 읽기·그리기·화면 표시까지 포함한 전체 처리 FPS와는 다를 수 있다.

OpenVINO 변환

Intel CPU 환경에서는 OpenVINO 형식이 추론 속도를 높일 수 있다. 변환은 한 번만 하고, 이후 생성된 폴더를 모델로 로드한다.

1단계: 변환

# 최초 1회만 실행
from ultralytics import YOLO

model = YOLO("yolo11n.pt")
model.export(format="openvino")

2단계: OpenVINO 모델 사용

# 이후 실행에서는 변환 폴더 로드
model = YOLO("yolo11n_openvino_model")
results = model(frame, verbose=False)

금지 model.export()를 while 프레임 반복문 안에 넣지 않는다. 매 프레임마다 모델을 변환하는 심각한 오류가 된다.

13. Streamlit으로 웹 UI 만들기

Streamlit은 Python 코드로 업로드 버튼, 슬라이더, 결과 이미지를 갖춘 간단한 웹 앱을 만든다.

모델 데모, 수업 결과 공유, 비개발자용 테스트 화면에 적합하다.

yolo_streamlit.py

import streamlit as st
from ultralytics import YOLO
from PIL import Image

st.title("YOLO 객체 탐지")

@st.cache_resource
def load_model():
return YOLO("yolo11n.pt")

model = load_model()
uploaded = st.file_uploader("이미지 선택", type=["jpg", "jpeg", "png"])

if uploaded:
image = Image.open(uploaded).convert("RGB")
results = model(image)
plotted = results[0].plot()[..., ::-1] # BGR → RGB
st.image(plotted, caption="탐지 결과", use_container_width=True)

실행 명령

# py39 환경이 활성화된 폴더에서 실행
python -m streamlit run yolo_streamlit.py

처음 실행 시 Email 입력 안내가 나오면 빈칸으로 Enter를 눌러도 된다.

Local URL: http://localhost:8501을 브라우저에서 연다.

cd yolo_streamlit.py는 잘못된 명령이다. cd는 폴더 이동에만 사용한다.

sreamit이 아니라 streamlit이다.

14. 자주 발생한 오류 빠른 해결표

오류·증상	원인	고칠 부분
break outside loop	break가 while 밖에 있음	처리·imshow·키 입력 코드를 4칸 들여쓰기
NameError	변수 이름 오타 또는 반환값 미저장	path/patn 확인, results = ... 저장
FileNotFoundError	실행 기준 폴더와 파일 위치 불일치	Path(__file__).parent 또는 절대 경로
NULL window	마우스 콜백 전에 창이 없음/버전 차이	show 설정 확인, 필요 시 namedWindow
invalid solution argument	인자 철자 오류	line_with → line_width 등 공식 이름 확인
SSLError NOT_ENOUGH_DATA	CLIP 등 추가 모델 다운로드 실패	texts 제거·네트워크 확인·포인트 방식
프레임 읽기 실패	경로·카메라·CCTV 주소 문제	cap.isOpened() 먼저 확인
결과 이미지가 저장 안 됨	cv2.imwrite 누락 또는 잘못된 폴더	폴더 생성 후 imwrite 반환값 확인
Streamlit 명령을 못 찾음	오타 또는 미설치	python -m streamlit run 파일.py

# 문제를 좁히는 기본 점검
print("현재 작업 폴더:", os.getcwd())
print("파일 절대 경로:", os.path.abspath(input_path))
print("파일 존재:", os.path.exists(input_path))
print("OpenCV 버전:", cv2.__version__)

부록 A. 클래스 번호와 좌표

COCO 사전학습 모델에서 자주 쓰는 클래스 번호 예시다.

모델이나 사용자 데이터셋이 바뀌면 번호도 달라질 수 있으므로 model.names로 확인한다.

번호	클래스	사용 예
0	person	classes=[0]
1	bicycle	classes=[1]
2	car	classes=[2]
3	motorcycle	classes=[3]
5	bus	classes=[5]
7	truck	classes=[7]

현재 모델의 클래스 번호 확인

from ultralytics import YOLO

model = YOLO("yolo11n.pt")
print(model.names)

좌표는 (x, y)이며 왼쪽 위가 (0, 0)이다.

x는 오른쪽으로, y는 아래쪽으로 커진다. resize 이후에는 새 프레임 크기를 기준으로 좌표를 다시 잡는다.

부록 B. 공식 문서

Ultralytics Solutions: https://docs.ultralytics.com/solutions/

객체 추적: https://docs.ultralytics.com/modes/track/

Heatmap: https://docs.ultralytics.com/guides/heatmaps/

Security Alarm: https://docs.ultralytics.com/guides/security-alarm-system/

SAHI 슬라이싱 추론: https://docs.ultralytics.com/guides/sahi-tiled-inference/

FastSAM: https://docs.ultralytics.com/models/fast-sam/

14일차_DATA 수집 ~ YOLO 객체 탐지

sojsoj — Mon, 20 Jul 2026 16:43:26 +0900

오늘의 AI 학습 정리: 데이터 수집부터 라벨링, YOLO 활용까지

AI가 이미지 속 사물을 인식하도록 만들기 위해서는 모델만 실행하는 것이 아니라, 데이터를 수집하고 정답을 표시한 뒤 학습과 검증을 거치는 과정이 필요합니다.

전체 과정은 다음과 같습니다.

데이터 수집 → 데이터 증강 → 라벨링 → 모델 학습 → 검증 → 추론 → 실시간 활용

1. AI 학습용 데이터 수집

AI 모델의 성능은 데이터의 양과 품질에 큰 영향을 받습니다. 같은 물체라도 방향, 거리, 크기, 밝기, 배경이 달라질 수 있으므로 다양한 환경에서 촬영한 이미지가 필요합니다.

1-1. 공개 데이터 사이트 이용

직접 모든 이미지를 촬영하기 어렵다면 공개 데이터 사이트를 이용할 수 있습니다.

Data — 학습 허브
AI Hub
COCO Dataset
Open Images
Roboflow Universe

공개 데이터를 사용할 때는 다음 내용을 확인해야 합니다.

상업적 이용이 가능한가?
데이터를 수정하거나 재배포할 수 있는가?
출처 표시가 필요한가?
얼굴이나 차량 번호판 등 개인정보가 포함되어 있는가?
현재 프로젝트의 학습 목적과 이미지 환경이 비슷한가?

데이터의 양이 많아도 실제 사용할 환경과 너무 다르면 좋은 성능을 얻기 어렵습니다.

1-2. 카메라로 직접 수집

OpenCV를 사용하면 웹캠으로 사진을 촬영하여 저장할 수 있습니다.

import cv2
import os
from datetime import datetime

save_dir = "./captured_images"
os.makedirs(save_dir, exist_ok=True)

cap = cv2.VideoCapture(0)

if not cap.isOpened():
    print("카메라를 열 수 없습니다.")
    raise SystemExit

success, frame = cap.read()

if success:
    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
    file_path = os.path.join(
        save_dir,
        f"result_{timestamp}.jpg"
    )

    cv2.imwrite(file_path, frame)
    print(f"사진 저장 완료: {file_path}")
else:
    print("카메라에서 사진을 읽지 못했습니다.")

cap.release()

VideoCapture(0)의 0은 기본 카메라를 의미합니다. 외장 카메라를 사용한다면 환경에 따라 1 또는 2로 변경해야 할 수 있습니다.

2. 데이터 증강

데이터 증강(Data Augmentation)은 기존 이미지를 회전하거나 밝기를 변경하는 방식으로 데이터의 다양성을 늘리는 기법입니다.

사진 한 장으로 여러 환경을 간접적으로 만들어 모델이 다양한 상황에 대응하도록 도울 수 있습니다.

from PIL import Image, ImageEnhance, ImageOps

img = Image.open("input.jpg")

# 90도 회전
rotated = img.rotate(90, expand=True)
rotated.save("rotated.jpg")

# 밝기를 50%로 조절
dark = ImageEnhance.Brightness(img).enhance(0.5)
dark.save("dark.jpg")

# 좌우 반전
mirrored = ImageOps.mirror(img)
mirrored.save("mirrored.jpg")

주요 증강 방법은 다음과 같습니다.

회전
밝기 변경
좌우 반전
크기 변경
일부 영역 자르기
노이즈 추가
색상 변경
원근 변환

객체 탐지 데이터 증강 시 주의사항

이미지 분류는 이미지 전체의 종류를 판단하기 때문에 사진만 변형해도 됩니다.

하지만 객체 탐지와 세그멘테이션에서는 이미지가 회전하거나 반전될 때 객체의 박스와 외곽선 좌표도 함께 변환해야 합니다.

이미지만 회전하고 라벨 좌표를 그대로 두면 객체의 실제 위치와 정답 위치가 달라져 잘못된 데이터를 학습하게 됩니다.

또한 원본 이미지를 학습·검증 데이터로 먼저 분리한 뒤 증강하는 것이 좋습니다.

같은 원본에서 만든 이미지가 학습 세트와 검증 세트에 동시에 들어가면 실제보다 성능이 높게 측정될 수 있습니다.

Ultralytics YOLO는 학습 과정에서 회전, 밝기, 좌우 반전, Mosaic 등의 데이터 증강 옵션을 제공합니다.

자세한 설정은 Ultralytics 학습 안내에서 확인할 수 있습니다.

3. 데이터 라벨링이란?

데이터 라벨링은 AI 모델에 정답을 알려주는 작업입니다.

객체 탐지에서는 이미지 속 객체를 사각형 박스로 감싸고 다음 정보를 기록합니다.

객체의 종류
객체 중심의 위치
객체 박스의 너비
객체 박스의 높이

예를 들어 식탁과 꽃병을 학습한다면 다음과 같이 클래스를 정할 수 있습니다.

names:
  0: dining_table
  1: vase

직접 학습하는 모델에서는 클래스 번호를 사용자가 정할 수 있습니다.

반면 주의 ! COCO 데이터로 사전 학습된 YOLO11 모델은 클래스 번호가 이미 정해져 있습니다.

60 = dining table
75 = vase

현재 모델의 전체 클래스 번호는 다음 코드로 확인할 수 있습니다.

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

print(model.names)

4. 라벨링 도구

4-1. LabelImg

LabelImg는 컴퓨터에 설치해서 사용하는 라벨링 도구입니다.

장점:

인터넷 없이 사용 가능
사용 방법이 비교적 간단함
이미지가 외부 서버에 업로드되지 않음
바운딩 박스 라벨링에 적합함

단점:

여러 사람이 동시에 작업하기 어려움
데이터 버전 관리 기능이 부족함
주로 객체 탐지용 박스 라벨링에 적합함

4-2. Roboflow

Roboflow는 웹 브라우저에서 데이터를 업로드하고 라벨링할 수 있는 서비스입니다.

장점:

별도의 프로그램 설치 없이 사용 가능
팀 단위 협업 가능
학습·검증·테스트 데이터 분리 지원
데이터 증강 기능 지원
YOLO 형식으로 내보내기 가능
모델을 이용한 자동 라벨링 지원

단점:

인터넷 연결 필요
서비스 요금 및 공개 범위 확인 필요
개인정보가 포함된 이미지 업로드 시 주의 필요

5. YOLO를 이용한 자동 라벨링

YOLO를 이용해서도 이미지에 라벨을 만들 수 있습니다.

정확히 말하면 YOLO가 예측한 결과를 정답 후보로 저장하는 것으로, 이를 다음과 같이 부릅니다.

자동 라벨링
사전 라벨링(Pre-labeling)
의사 라벨링(Pseudo-labeling)

5-1. 폴더 속 이미지 자동 라벨링

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

model(
    "images",
    conf=0.5,
    save=True,
    save_txt=True
)

각 옵션의 의미는 다음과 같습니다.

save=True: 박스가 그려진 결과 이미지 저장
save_txt=True: YOLO 형식의 라벨 파일 저장
conf=0.5: 신뢰도가 50% 이상인 결과만 사용

결과는 일반적으로 다음 폴더에 저장됩니다.

runs/
└─ detect/
   └─ predict/
      ├─ image01.jpg
      ├─ image02.jpg
      └─ labels/
         ├─ image01.txt
         └─ image02.txt

객체 탐지 라벨 파일에는 객체 하나당 한 줄씩 다음 값이 저장됩니다.

class_id x_center y_center width height

예:

0 0.512 0.438 0.243 0.572

좌표와 크기는 픽셀이 아니라 이미지 크기를 기준으로 0~1 사이 값으로 정규화됩니다.

5-2. 원하는 객체만 자동 라벨링

식탁과 꽃병만 라벨링하려면 classes 옵션을 사용합니다.

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

model(
    "images",
    classes=[60, 75],
    conf=0.4,
    save=True,
    save_txt=True
)

60 = dining table
75 = vase

번호를 외우지 않고 이름으로 찾을 수도 있습니다.

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

target_names = [
    "dining table",
    "vase"
]

target_ids = [
    class_id
    for class_id, class_name in model.names.items()
    if class_name in target_names
]

print(target_ids)

model(
    "images",
    classes=target_ids,
    conf=0.4,
    save=True,
    save_txt=True
)

5-3. 세그멘테이션 자동 라벨링

사각형 박스가 아니라 객체의 실제 외곽선이 필요하다면 세그멘테이션 모델을 사용합니다.

from ultralytics import YOLO

model = YOLO("yolo11n-seg.pt")

model(
    "images",
    classes=[60, 75],
    conf=0.4,
    save=True,
    save_txt=True
)

자동 라벨링의 한계

YOLO가 만든 라벨은 모델의 예측 결과이므로 완벽한 정답이 아닙니다.

실제 객체를 놓칠 수 있음
다른 물체를 잘못 탐지할 수 있음
객체 박스의 크기와 위치가 부정확할 수 있음
겹치거나 일부만 보이는 객체를 놓칠 수 있음
기본 모델이 배우지 않은 물체는 인식하기 어려움

따라서 다음 방식이 가장 안전합니다.

YOLO 자동 라벨 생성 → LabelImg 또는 Roboflow에서 검수 → 누락된 객체 추가 → 잘못된 박스 수정 → 학습 데이터로 사용

특정 제품이나 부품처럼 기본 YOLO가 모르는 객체는 먼저 일부 이미지를 사람이 직접 라벨링해야 합니다.

이후 1차 모델을 학습하고, 그 모델로 나머지 이미지에 자동 라벨을 생성하면 작업 시간을 줄일 수 있습니다.

6. YOLO란?

YOLO는 “You Only Look Once”의 약자로, 이미지나 영상에서 여러 객체의 종류와 위치를 빠르게 찾아내는 컴퓨터 비전 모델입니다.

사진 한 장뿐만 아니라 다음과 같은 입력을 처리할 수 있습니다.

이미지
이미지 폴더
동영상
웹캠
CCTV
HTTP 영상 스트림

YOLO11은 객체 탐지뿐 아니라 이미지 분류, 인스턴스 분할, 자세 추정, 회전 객체 탐지 등을 지원합니다. YOLO11 공식 모델 안내

모델기능결과

yolo11n.pt	객체 탐지	객체 이름과 사각형 박스
yolo11n-seg.pt	인스턴스 분할	객체의 실제 영역
yolo11n-pose.pt	자세 추정	사람의 관절 위치
yolo11n-cls.pt	이미지 분류	이미지 전체의 종류
yolo11n-obb.pt	회전 객체 탐지	방향이 포함된 박스

모델명에 사용되는 n, s, m, l, x는 모델의 크기를 의미합니다.

n: 가장 작고 빠른 모델
s: 작지만 n보다 정확도가 높은 모델
m: 속도와 정확도의 중간
l, x: 더 크고 많은 연산이 필요한 모델

초보자가 CPU 또는 웹캠 실습을 할 때는 yolo11n.pt부터 시작하는 것이 좋습니다.

7. YOLO 설치와 기본 객체 탐지

터미널에서 Ultralytics 패키지를 설치합니다.

pip install ultralytics

기본 객체 탐지 코드는 다음과 같습니다.

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

results = model(
    "input.jpg",
    conf=0.5,
    save=True
)

save=True를 사용하면 결과가 일반적으로 다음 위치에 저장됩니다.

runs/detect/predict

같은 코드를 반복 실행하면 기존 결과를 덮어쓰지 않고 새 폴더가 만들어집니다.

predict
predict2
predict3

작업별 기본 저장 폴더도 다릅니다.

객체 탐지       → runs/detect
세그멘테이션    → runs/segment
자세 추정       → runs/pose
이미지 분류     → runs/classify
객체 추적       → runs/track 또는 작업별 결과 폴더

8. 원하는 객체만 탐지하기

classes 옵션을 사용하면 특정 클래스만 탐지할 수 있습니다.

from ultralytics import YOLO

model = YOLO("yolo11n-seg.pt")

model(
    "input_seg.jpg",
    classes=[60, 75],
    conf=0.5,
    save=True
)

이 코드는 식탁과 꽃병만 탐지하고 분할합니다.

직접 학습한 모델에서는 클래스 번호가 data.yaml의 순서에 따라 달라집니다.

names:
  0: vase
  1: dining_table

이렇게 정의하고 학습했다면 다음과 같이 사용합니다.

model(
    "input.jpg",
    classes=[0, 1],
    save=True
)

9. 주요 파라미터

results = model(
    "input.jpg",
    conf=0.5,
    imgsz=640,
    max_det=5,
    classes=[0, 2],
    save=True,
    project="results",
    name="my_prediction"
)

파라미터설명

conf=0.5	신뢰도 50% 이상만 탐지
imgsz=640	모델 입력 이미지 크기
max_det=5	한 이미지의 최대 탐지 개수
classes=[0, 2]	지정한 클래스만 탐지
save=True	결과 이미지 저장
save_txt=True	탐지 결과를 라벨 파일로 저장
project="results"	결과를 저장할 상위 폴더
name="test1"	결과 폴더 이름
device=0	첫 번째 GPU 사용
device="cpu"	CPU 사용
verbose=False	반복 출력 메시지 줄이기

conf가 너무 높으면 실제 객체를 놓칠 수 있고, 너무 낮으면 잘못 탐지하는 객체가 늘어날 수 있습니다.

처음에는 0.25~0.5 정도에서 비교해보는 것이 좋습니다.

10. 추론 결과 직접 저장하기

YOLO의 plot()을 실행하면 탐지 박스가 그려진 이미지 배열을 얻을 수 있습니다.

from ultralytics import YOLO
import cv2

model = YOLO("yolo11n.pt")
results = model("input.jpg")

result_image = results[0].plot()

cv2.imwrite("result.jpg", result_image)

print("결과 이미지가 저장되었습니다.")

다음처럼 plot 뒤에 괄호가 없으면 함수가 실행되지 않습니다.

results[0].plot    # 잘못된 사용
results[0].plot()  # 올바른 사용

추론 결과에는 작업에 따라 다음 정보가 들어 있습니다.

results[0].boxes       # 객체 탐지 박스
results[0].masks       # 세그멘테이션 마스크
results[0].keypoints   # 자세 추정 관절 좌표
results[0].probs       # 이미지 분류 확률

자세한 결과 구조는 Ultralytics 추론 안내에서 확인할 수 있습니다.

11. 웹캠 실시간 객체 탐지

from ultralytics import YOLO
import cv2

model = YOLO("yolo11n.pt")
cap = cv2.VideoCapture(0)

if not cap.isOpened():
    print("카메라를 열 수 없습니다.")
    raise SystemExit

while cap.isOpened():
    success, frame = cap.read()

    if not success:
        print("프레임 읽기 실패")
        break

    results = model(
        frame,
        conf=0.5,
        verbose=False
    )

    annotated_frame = results[0].plot()

    cv2.imshow(
        "YOLO Webcam",
        annotated_frame
    )

    if cv2.waitKey(1) & 0xFF == ord("q"):
        print("q키를 눌러 종료합니다.")
        break

cap.release()
cv2.destroyAllWindows()

초보자가 자주 틀리는 코드는 다음과 같습니다.

cap.isOpened()  # isOpend()가 아님
ord("q")        # waitKey 결과와 비교할 때 사용

break는 반드시 while 또는 for 반복문 내부에서 사용해야 합니다.

12. HTTP CCTV 스트림 연결

웹캠 대신 HTTP 영상 스트림 주소를 전달할 수도 있습니다.

from ultralytics import YOLO
import cv2

stream_url = "http://example.com/live/playlist.m3u8"

cap = cv2.VideoCapture(stream_url)
model = YOLO("yolo11n.pt")

if not cap.isOpened():
    print("스트림을 열 수 없습니다.")
    raise SystemExit

while cap.isOpened():
    success, frame = cap.read()

    if not success:
        print("스트림 프레임 읽기 실패")
        break

    results = model(
        frame,
        conf=0.5,
        verbose=False
    )

    annotated_frame = results[0].plot()

    cv2.imshow(
        "CCTV YOLO",
        annotated_frame
    )

    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

HTTP 스트림은 다음 원인으로 열리지 않을 수 있습니다.

스트림 주소 만료
서버 접속 제한
네트워크 연결 문제
OpenCV가 지원하지 않는 코덱
동시 접속자 제한
인증이 필요한 스트림

공개 CCTV 영상을 사용할 때는 해당 서비스의 이용 조건과 개인정보 관련 규정도 확인해야 합니다.

13. 영상 속 객체 추적하기

객체 탐지는 각 프레임에서 객체를 새로 찾습니다. 객체 추적은 같은 객체에 ID를 부여해 영상이 진행되어도 계속 구분하는 기능입니다.

from ultralytics import YOLO
import cv2

model = YOLO("yolo11n.pt")
cap = cv2.VideoCapture(0)

while cap.isOpened():
    success, frame = cap.read()

    if not success:
        break

    results = model.track(
        frame,
        persist=True,
        conf=0.5,
        verbose=False
    )

    annotated_frame = results[0].plot()

    cv2.imshow(
        "YOLO Tracking",
        annotated_frame
    )

    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

persist=True는 이전 프레임의 추적 정보를 다음 프레임에서도 이어서 사용하라는 의미입니다.

객체 추적은 다음 분야에 활용할 수 있습니다.

사람 수 계산
차량 이동 분석
위험 구역 진입 감지
물류 제품 이동 추적
특정 객체의 이동 경로 분석

자세한 내용은 Ultralytics 객체 추적 안내에서 확인할 수 있습니다.

14. 나만의 객체 탐지 모델 학습하기

기본 YOLO11 탐지 모델은 COCO 데이터셋의 80개 클래스를 학습한 모델입니다.

기본 목록에 없는 제품, 부품, 불량 유형, 특정 도구 등을 탐지하려면 직접 데이터를 수집하고 학습해야 합니다.

데이터 폴더 구조

dataset/
├─ images/
│  ├─ train/
│  └─ val/
├─ labels/
│  ├─ train/
│  └─ val/
└─ data.yaml

data.yaml 작성

path: ./dataset

train: images/train
val: images/val

names:
  0: dining_table
  1: vase

YOLO 객체 탐지 라벨은 이미지마다 하나의 .txt 파일로 저장합니다.

class_id x_center y_center width height

클래스 번호는 0부터 시작하고 좌표는 0~1 사이의 값으로 정규화합니다. 자세한 구조는 Ultralytics 객체 탐지 데이터 형식에서 확인할 수 있습니다.

모델 학습

from ultralytics import YOLO

model = YOLO("yolo11n.pt")

model.train(
    data="data.yaml",
    epochs=100,
    imgsz=640,
    batch=16
)

학습 결과는 일반적으로 다음 폴더에 저장됩니다.

runs/detect/train

가장 성능이 좋았던 모델은 다음 파일입니다.

runs/detect/train/weights/best.pt

학습한 모델로 추론

from ultralytics import YOLO

model = YOLO(
    "runs/detect/train/weights/best.pt"
)

model(
    "test.jpg",
    conf=0.5,
    save=True
)

15. 효율적인 자동 라벨링 학습 순서

직접 만든 객체를 학습할 때는 다음 순서가 효율적입니다.

여러 환경에서 이미지를 수집한다.
일부 이미지에 사람이 직접 라벨링한다.
직접 만든 라벨로 1차 YOLO 모델을 학습한다.
1차 모델로 나머지 이미지에 자동 라벨을 생성한다.
LabelImg 또는 Roboflow에서 자동 라벨을 검수한다.
잘못된 박스를 수정하고 누락된 객체를 추가한다.
수정된 전체 데이터로 최종 모델을 다시 학습한다.
학습에 사용하지 않은 테스트 이미지로 성능을 확인한다.

이 과정을 반복하면 사람이 모든 이미지에 처음부터 박스를 그리는 시간을 줄일 수 있습니다.

마무리

좋은 데이터 수집 → 정확한 라벨링 → 모델 학습 → 결과 검증 → 실제 환경 적용

오늘 학습의 핵심 : AI 프로젝트 전체 흐름을 이해

목적에 맞는 이미지를 수집한다.

필요한 경우 데이터를 증강한다.

객체 위치와 종류를 정확히 라벨링한다.

학습·검증 데이터를 분리한다.

작업에 맞는 YOLO 모델을 선택한다.

파라미터를 조절하며 추론 결과를 확인한다.

이미지, 웹캠, CCTV 및 영상 추적으로 확장한다.

YOLO는 다음과 같은 기능을 제공합니다.

이미지 분류
객체 탐지
인스턴스 분할
자세 추정
객체 추적
이미지·동영상 추론
결과 이미지와 라벨 저장
원하는 클래스만 선택
파라미터 조절
웹캠 및 CCTV 스트림 처리
자동 라벨링
사용자 데이터 학습

13일차_ Anaconda / Python문법

sojsoj — Thu, 16 Jul 2026 16:42:02 +0900

Anaconda

오늘의 학습 정리 — 아나콘다 설치와 활용

참고: Python 학습 사이트

1. 아나콘다란?

아나콘다는 파이썬과 여러 패키지, 개발 도구를 편리하게 설치하고 관리할 수 있게 해주는 프로그램이다.

특히 가상환경을 만들어 프로젝트별로 파이썬 버전과 패키지를 따로 관리할 수 있다.

예를 들어:

py39: Python 3.9 학습 환경
cv_env: OpenCV 실습 환경

각 환경은 서로 독립되어 있어 한 환경에 설치한 패키지가 다른 환경에 영향을 주지 않는다.

2. 아나콘다 설치

아나콘다 공식 다운로드 페이지로 이동한다.
Windows용 설치 프로그램을 내려받는다.
설치 프로그램을 실행한다.
설치 방식은 Just Me를 선택한다.
특별한 이유가 없다면 기본 설정으로 설치한다.
설치가 끝나면 Windows 검색창에서 Anaconda Prompt를 찾아 실행한다.

아나콘다 공식 설명에서도 Windows 설치 시 Just Me를 권장하며, PATH 옵션은 일반적으로 선택하지 않는 것을 권장한다. Windows 설치 안내

설치가 정상적으로 완료되면 Anaconda Prompt 앞부분에 다음과 같이 표시된다.

(base) C:\Users\사용자이름>

base는 아나콘다의 기본 환경이다.

3. 가상환경 만들기

Python 3.9를 사용하는 py39 환경을 만들려면 다음 명령어를 입력한다.

conda create -n py39 python=3.9

명령어의 의미:

conda create: 새로운 환경 생성
-n py39: 환경 이름을 py39로 지정
python=3.9: Python 3.9 설치

설치 도중 다음 질문이 나오면 y를 입력하고 Enter를 누른다.

Proceed ([y]/n)?

환경 이름은 원하는 이름으로 정할 수 있다.

conda create -n cv_env python=3.9

4. 가상환경 활성화

만든 환경을 사용하려면 먼저 활성화해야 한다.

conda activate py39

cv_env라는 환경을 사용한다면:

conda activate cv_env

활성화되면 프롬프트 앞에 현재 환경 이름이 나타난다.

(py39) C:\Users\Har27>

즉, 다음과 같이 이해하면 된다.

conda activate 환경이름

py39와 cv_env를 동시에 입력하는 것이 아니라, 내가 사용할 환경 이름 하나를 입력한다.

5. 가상환경 목록 확인

현재 컴퓨터에 만들어진 환경을 확인한다.

conda env list

또는:

conda info --envs

예시:

base    C:\Users\Har27\anaconda3
py39 *  C:\Users\Har27\anaconda3\envs\py39

여기서 * 표시는 현재 활성화된 환경을 뜻한다. 제공한 캡처에서는 py39 옆에 *가 있으므로 py39 환경이 정상적으로 활성화된 상태이다. Conda 환경 관리 안내

6. 패키지 설치

환경을 활성화한 뒤 필요한 패키지를 설치한다.

큰 그림 글씨 출력

pip install pyfiglet

터미널 글자에 색상 적용

pip install termcolor

웹캠 및 영상 처리

pip install opencv-python

중요한 순서:

conda activate py39
pip install pyfiglet

이렇게 하면 pyfiglet은 현재 활성화된 py39 환경에 설치된다.

7. 설치된 패키지 확인

현재 환경에 설치된 패키지 목록을 확인한다.

pip list

특정 패키지가 설치되었는지 확인하려면:

pip show pyfiglet

제공한 캡처에서는 다음 내용이 확인된다.

Successfully installed pyfiglet-1.0.4

따라서 pyfiglet 설치가 정상적으로 완료된 것이다.

8. 설치한 패키지 활용하기

pyfiglet으로 큰 글씨 출력

from pyfiglet import figlet_format

print(figlet_format("HAPPY", font="slant"))

글꼴과 색상을 함께 적용

from pyfiglet import figlet_format
from termcolor import colored

big_text = lambda text, font="standard", color="blue": colored(
    figlet_format(text, font=font),
    color
)

print(big_text("HAPPY", "slant", "magenta"))

각 입력값의 의미:

big_text("HAPPY", "slant", "magenta")
#         글자      글꼴       색상

termcolor에는 "pink" 색상이 없으므로 비슷한 "magenta" 또는 "light_magenta"를 사용한다.

9. 가상환경 종료

작업이 끝나면 현재 환경을 비활성화한다.

conda deactivate

실행 전:

(py39) C:\Users\Har27>

실행 후:

(base) C:\Users\Har27>

py39 표시가 사라졌다면 환경이 종료된 것이다.

핵심 명령어 요약

# 가상환경 생성
conda create -n py39 python=3.9

# 가상환경 활성화
conda activate py39

# 가상환경 목록 확인
conda env list

# 패키지 설치
pip install pyfiglet
pip install termcolor
pip install opencv-python

# 설치된 패키지 확인
pip list

# 현재 환경 종료
conda deactivate

가장 중요한 작업 흐름은 다음과 같다.

Anaconda Prompt 실행
→ 가상환경 생성
→ 가상환경 활성화
→ 필요한 패키지 설치
→ 파이썬 코드 실행
→ 가상환경 종료

Python

Python 변수 타입과 클래스, 정말 쉽게 이해하기

변수는 값을 가리키는 이름표이고, 클래스는 비슷한 물건을 여러 개 만들기 위한 설계도입니다.

1. 변수란 무엇일까?

변수는 값을 기억하기 위해 붙이는 이름표입니다.

다음은 파이선에서 변수를 지정하는 법입니다. 숫자에는 "" 를 붇이지 않습니다.

name = "민수"
age = 20

이 코드는 다음과 같은 뜻입니다.

name ──→ "민수"
age  ──→ 20

name이라는 이름표가 "민수"라는 값을 가리킵니다.
age라는 이름표가 20이라는 값을 가리킵니다.
=는 오른쪽 값을 왼쪽 이름에 저장한다는 뜻입니다.

print(name)
print(age)

실행 결과:

민수
20

2. 변수 타입이란?

타입은 변수에 들어 있는 값의 종류입니다.

사람에게도 이름, 나이, 키처럼 서로 다른 정보가 있듯이 Python의 값에도 여러 종류가 있습니다.

name = "민수"       # 글자
age = 20            # 정수
height = 175.5      # 소수
is_student = True   # 참 또는 거짓

Python에서는 하나의 변수에 다른 종류의 값을 다시 넣을 수도 있습니다.

value = 10
value = "안녕하세요"

따라서 정확히 말하면 변수 자체에 고정된 타입이 있는 것이 아니라, 변수가 현재 가리키는 값에 타입이 있다고 이해하면 좋습니다.

Python 공식 입문 문서에서도 숫자, 문자열, 리스트 등을 서로 다른 값의 종류로 설명합니다. Python 공식 입문 문서

자주 사용하는 타입

타입의미예

int	소수점이 없는 정수	10, -3
float	소수점이 있는 실수	3.14, 175.5
str	글자와 문장	"Python"
bool	참 또는 거짓	True, False
list	순서가 있고 수정 가능한 목록	[10, 20, 30]
tuple	수정할 수 없는 목록	(10, 20)
dict	이름표와 값을 짝지어 저장	{"name": "민수"}
set	중복을 허용하지 않는 값의 모음	{1, 2, 3}
NoneType	값이 없는 상태	None

2-1. int: 정수

소수점이 없는 숫자입니다.

age = 20
score = 95

print(age + 1)

결과:

주로 나이, 개수, 점수처럼 소수점이 필요 없는 값을 저장합니다.

2-2. float: 실수

소수점이 있는 숫자입니다.

height = 175.5
temperature = 23.7

print(temperature + 1.5)

결과:

25.2

키, 몸무게, 온도, 비율 등에 사용합니다.

2-3. str: 문자열

글자나 문장을 나타냅니다. 문자열은 따옴표로 감쌉니다.

name = "민수"
message = "안녕하세요"

문자열끼리는 +를 사용해 연결할 수 있습니다.

print(name + "님, 안녕하세요!")

결과:

민수님, 안녕하세요!

다음 두 값은 겉보기에는 비슷하지만 타입이 다릅니다.

number1 = 10
number2 = "10"

10은 계산할 수 있는 정수입니다.
"10"은 글자로 저장된 문자열입니다.

print(10 + 5)       # 15
print("10" + "5")   # 105

2-4. bool: 참과 거짓

조건이 맞는지 틀린지를 나타냅니다.

is_student = True
is_raining = False

주로 조건문과 함께 사용합니다.

if is_raining:
    print("우산을 챙기세요.")
else:
    print("우산이 필요 없습니다.")

True와 False의 첫 글자는 반드시 대문자로 작성합니다.

2-5. list: 여러 값을 담는 목록

리스트는 여러 값을 순서대로 보관합니다.

fruits = ["사과", "바나나", "딸기"]

Python의 순서는 1이 아니라 0부터 시작합니다.

값       사과   바나나   딸기
순서      0      1      2

print(fruits[0])

결과:

사과

리스트에는 새로운 값을 추가할 수도 있습니다.

fruits.append("포도")

print(fruits)

결과:

['사과', '바나나', '딸기', '포도']

2-6. dict: 이름표와 값을 함께 저장

딕셔너리는 데이터를 키: 값 형태로 저장합니다.

person = {
    "name": "민수",
    "age": 20,
    "job": "학생"
}

키를 이용해 원하는 값을 꺼낼 수 있습니다.

print(person["name"])
print(person["age"])

결과:

민수
20

딕셔너리는 이름, 나이, 직업처럼 각 값의 의미가 중요한 정보를 관리할 때 편리합니다.

2-7. 변수 타입 확인하기

type()을 사용하면 값의 타입을 확인할 수 있습니다.

name = "민수"
age = 20
height = 175.5

print(type(name))
print(type(age))
print(type(height))

결과:

<class 'str'>
<class 'int'>
<class 'float'>

type()은 객체가 어떤 타입인지 알려주는 내장 함수입니다. Python type() 공식 설명

그런데 결과에 왜 class라는 단어가 나올까요?

<class 'str'>

Python에서는 문자열, 정수, 리스트 같은 기본 타입도 모두 클래스로 만들어져 있기 때문입니다.

이제 클래스를 알아보겠습니다.

3. 클래스는 왜 필요할까?

게임 캐릭터를 관리하는 프로그램을 만든다고 생각해 보겠습니다.

캐릭터가 한 명이라면 다음처럼 만들 수 있습니다.

character1_name = "기사"
character1_hp = 100
character1_level = 1

두 명이 되면 변수가 늘어납니다.

character1_name = "기사"
character1_hp = 100
character1_level = 1

character2_name = "마법사"
character2_hp = 70
character2_level = 1

캐릭터가 100명이라면 어떻게 될까요?

character1_name
character1_hp
character1_level

character2_name
character2_hp
character2_level

character3_name
character3_hp
character3_level
...

변수가 너무 많아지고 어떤 정보가 누구의 것인지 관리하기 어려워집니다.

이럴 때 사용하는 것이 클래스입니다.

4. 클래스는 설계도다

클래스는 비슷한 특징을 가진 객체를 만들기 위한 설계도입니다.

게임 캐릭터에 비유하면 다음과 같습니다.

Character 클래스
      │
      ├── 기사 객체
      ├── 마법사 객체
      └── 궁수 객체

집을 짓는 설계도는 한 장이지만, 같은 설계도로 여러 채의 집을 만들 수 있습니다.

마찬가지로 클래스는 하나만 정의하고, 그 클래스로 여러 객체를 만들 수 있습니다.

Python 공식 문서에서는 새 클래스를 정의하면 새로운 타입이 만들어지고, 그 타입의 인스턴스를 만들 수 있다고 설명합니다. 여기서 인스턴스는 클래스로 만든 실제 객체를 뜻합니다. Python 클래스 공식 안내

5. 가장 간단한 클래스 만들기

먼저 내용이 없는 간단한 클래스를 만들어 보겠습니다.

class Character:
    pass

각 부분의 의미는 다음과 같습니다.

class Character:
#     클래스 이름

class: 클래스를 만들겠다는 Python 문법
Character: 클래스 이름
:: 클래스의 내용이 시작된다는 표시
pass: 아직 작성할 내용이 없다는 표시

일반적으로 클래스 이름은 각 단어의 첫 글자를 대문자로 작성합니다.

class GameCharacter:
    pass

6. 클래스로 객체 만들기

클래스를 정의했다면 실제 객체를 만들 수 있습니다.

class Character:
    pass


warrior = Character()
wizard = Character()

Character는 설계도입니다.
warrior는 그 설계도로 만든 객체입니다.
wizard도 같은 설계도로 만든 또 다른 객체입니다.

Character 설계도
      │
      ├── warrior
      └── wizard

두 객체는 같은 클래스로 만들었지만 서로 다른 객체입니다.

print(warrior)
print(wizard)

실행하면 두 객체의 메모리 위치가 다르게 표시됩니다.

7. 객체에 정보를 넣어보자

캐릭터마다 이름과 체력이 필요합니다.

이 정보는 __init__에서 저장할 수 있습니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp

처음 보면 복잡해 보이지만 한 부분씩 나누면 어렵지 않습니다.

init은 처음 설정하는 곳

__init__은 객체가 만들어질 때 자동으로 실행됩니다.

warrior = Character("기사", 100)

객체를 만드는 순간 다음 값이 전달됩니다.

"기사" ──→ name
100     ──→ hp

그리고 다음 코드가 실행됩니다.

self.name = name
self.hp = hp

전달받은 이름과 체력을 해당 객체 안에 저장하는 것입니다.

완성된 객체는 다음과 같은 정보를 가집니다.

warrior
├── name: "기사"
└── hp: 100

8. self는 무엇일까?

self는 현재 작업 중인 객체 자기 자신을 뜻합니다.

쉽게 표현하면 다음과 같습니다.

self.name은 “내 이름”, self.hp는 “내 체력”이라는 뜻입니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp

기사 객체를 만들면:

warrior = Character("기사", 100)

self는 warrior를 가리킵니다.

따라서 내부적으로 다음과 비슷하게 이해할 수 있습니다.

warrior.name = "기사"
warrior.hp = 100

마법사 객체를 만들면:

wizard = Character("마법사", 70)

이번에는 self가 wizard를 가리킵니다.

wizard.name = "마법사"
wizard.hp = 70

즉, self 덕분에 객체마다 자신의 정보를 따로 보관할 수 있습니다.

9. 객체의 정보 꺼내기

점 .을 사용하면 객체가 가진 정보를 확인할 수 있습니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp


warrior = Character("기사", 100)
wizard = Character("마법사", 70)

print(warrior.name)
print(warrior.hp)

print(wizard.name)
print(wizard.hp)

결과:

기사
100
마법사
70

이때 name과 hp를 속성이라고 합니다.

속성은 객체가 가지고 있는 정보입니다.

10. 객체에게 행동을 만들어주자

캐릭터가 자기소개하는 행동을 추가해 보겠습니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp

    def introduce(self):
        print(f"나는 {self.name}입니다.")
        print(f"현재 체력은 {self.hp}입니다.")

클래스 안에 정의된 함수를 메서드라고 합니다.

warrior = Character("기사", 100)
warrior.introduce()

결과:

나는 기사입니다.
현재 체력은 100입니다.

메서드 안의 self.name은 메서드를 실행한 객체의 이름을 사용합니다.

wizard = Character("마법사", 70)
wizard.introduce()

결과:

나는 마법사입니다.
현재 체력은 70입니다.

같은 introduce() 메서드를 실행했지만 객체가 다르므로 결과도 달라집니다.

11. 공격받는 기능 추가하기

이번에는 캐릭터의 체력을 줄이는 기능을 만들어 보겠습니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp

    def introduce(self):
        print(f"나는 {self.name}입니다.")
        print(f"현재 체력은 {self.hp}입니다.")

    def take_damage(self, damage):
        self.hp -= damage
        print(f"{self.name}이 {damage}의 피해를 받았습니다.")
        print(f"남은 체력: {self.hp}")

사용 방법:

warrior = Character("기사", 100)

warrior.take_damage(30)

결과:

기사가 30의 피해를 받았습니다.
남은 체력: 70

이 메서드에서:

self.hp -= damage

는 다음 코드와 같습니다.

self.hp = self.hp - damage

현재 객체의 체력에서 피해량을 빼고 다시 저장합니다.

12. 클래스 코드를 한 줄씩 읽어보기

전체 코드를 다시 살펴보겠습니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp

    def introduce(self):
        print(f"나는 {self.name}입니다.")

    def take_damage(self, damage):
        self.hp -= damage
        print(f"남은 체력: {self.hp}")


warrior = Character("기사", 100)
warrior.introduce()
warrior.take_damage(30)

코드를 순서대로 해석하면 다음과 같습니다.

Character라는 캐릭터 설계도를 만듭니다.
캐릭터를 만들 때 이름과 체력을 받습니다.
받은 이름과 체력을 객체 안에 저장합니다.
자기소개하는 행동을 정의합니다.
피해를 받는 행동을 정의합니다.
이름이 기사이고 체력이 100인 객체를 만듭니다.
기사가 자기소개합니다.
기사가 30의 피해를 받습니다.

13. 클래스의 핵심 용어

용어쉬운 의미코드

클래스	객체를 만드는 설계도	class Character:
객체	설계도로 만든 실제 대상	warrior
인스턴스	클래스로 만든 객체를 부르는 말	warrior
속성	객체가 가지고 있는 정보	self.name, self.hp
메서드	객체가 할 수 있는 행동	introduce()
__init__	객체를 처음 만들 때 실행되는 설정	이름과 체력 저장
self	현재 사용 중인 객체 자기 자신	self.name

초보 단계에서는 객체와 인스턴스를 거의 같은 뜻으로 이해해도 괜찮습니다.

14. 함수와 클래스는 무엇이 다를까?

함수와 클래스는 서로 경쟁하는 문법이 아닙니다. 사용하는 목적이 다릅니다.

함수

하나의 작업을 묶을 때 사용합니다.

def add(a, b):
    return a + b

함수는 “어떤 일을 하는 도구”입니다.

클래스

관련된 정보와 행동을 하나로 묶을 때 사용합니다.

class Character:
    def __init__(self, name, hp):
        self.name = name
        self.hp = hp

    def introduce(self):
        print(self.name)

클래스는 “정보와 행동을 함께 가진 대상의 설계도”입니다.

정리하면:

함수
└── 작업을 묶음

클래스
├── 정보인 속성을 묶음
└── 행동인 메서드를 묶음

15. 언제 클래스를 사용하면 좋을까?

다음처럼 같은 구조를 가진 대상을 여러 개 관리해야 할 때 클래스가 유용합니다.

여러 명의 학생
여러 개의 상품
여러 대의 자동차
여러 마리의 강아지
여러 명의 게임 캐릭터
여러 개의 은행 계좌

예를 들어 학생마다 이름과 점수가 있고, 자신의 결과를 출력해야 한다면 클래스로 묶을 수 있습니다.

class Student:
    def __init__(self, name, score):
        self.name = name
        self.score = score

    def show_result(self):
        print(f"{self.name}: {self.score}점")


student1 = Student("민수", 90)
student2 = Student("지영", 85)

student1.show_result()
student2.show_result()

결과:

민수: 90점
지영: 85점

마지막 핵심 정리

변수 타입

변수가 가리키는 값의 종류입니다.

age = 20                     # int
height = 175.5               # float
name = "민수"                # str
is_student = True            # bool
scores = [90, 80, 70]        # list
person = {"name": "민수"}    # dict

클래스

정보와 행동을 함께 묶어 비슷한 객체를 여러 개 만들기 위한 설계도입니다.

class 클래스이름:
    def __init__(self, 값):
        self.속성 = 값

    def 메서드(self):
        실행할 코드

처음에는 다음 세 문장만 기억해도 충분합니다.

클래스는 설계도다.
객체는 설계도로 만든 실제 대상이다.
self는 현재 객체 자기 자신이다.

12일차_Vercel배포

sojsoj — Wed, 15 Jul 2026 16:47:17 +0900

Vercel 배포 과정 정리

Vercel Drop → CLI → GitHub 연동 → Claude 자동화

이 글은 hancom-nine.vercel.app/vercel.html 학습 허브 페이지에 정리된 순서를 바탕으로, 실제로 진행된 배포 흐름(① Vercel Drop 업로드 → ② CLI 배포 → ③ GitHub 연동 → ④ Claude 연동)을 다시 정리한 것입니다. 각 단계는 이전 단계에서 만든 같은 프로젝트·같은 URL을 이어받아 진행됩니다.

전체 흐름 한눈에 보기

네 단계는 순서대로 이어지며, 뒤 단계로 갈수록 더 적은 수동 작업으로 같은 사이트를 갱신하는 방법을 갖추게 됩니다.

단계방법핵심 특징

① Vercel Drop	브라우저 드래그 앤 드롭	Git·CLI·설치 없이 즉시 배포. 일회성
② CLI 배포	vercel / vercel --prod	터미널 명령으로 같은 프로젝트에 재배포
③ GitHub 연동	Git 저장소 연결	push할 때마다 자동으로 재배포
④ Claude 연동	"푸시해줘" 한마디	커밋·푸시를 Claude가 대신 실행, 이후는 ③번 자동배포 그대로 작동

1단계 · Vercel Drop — 브라우저에 끌어다 놓기

파일·폴더·.zip을 vercel.com/drop 화면에 드래그하면 배포됩니다. Git 저장소도, CLI 설치도 필요 없어 프로토타입이나 정적 사이트를 빠르게 공개할 때 적합합니다.

배포 순서 (클릭 4번)

vercel.com/drop 접속
파일·폴더·.zip 드래그 (또는 파일/폴더 선택)
팀 선택 + 프로젝트 이름 입력
Deploy 클릭 → Production URL 즉시 발급

알아둘 점

정적 사이트는 빌드 없이 그대로 게시되고, 프레임워크 프로젝트는 Vercel이 자동으로 감지해 빌드합니다.
최상위 폴더에 index.html이 없으면 Vercel이 첫 화면으로 무엇을 보여줄지 물어봅니다. "No root page"를 선택하면 루트(/) 주소는 404가 되고, 각 파일은 자기 경로로만 접속됩니다.

한계 — 재배포가 안 됩니다

Vercel Drop에는 "기존 프로젝트에 새 파일 드롭"이라는 기능이 없습니다. 같은 폴더를 또 드롭하면 완전히 새로운 프로젝트와 새로운 URL이 생성됩니다. 같은 URL을 유지하면서 업데이트하려면 2단계(CLI)의 vercel --prod 또는 3단계(GitHub 연동)가 필요합니다.

2단계 · CLI 배포 — 터미널 명령으로 재배포

배포란 결국 내 코드를 인터넷 서버에 올려서 누구나 접속할 수 있는 URL을 받는 일입니다. 1단계에서 만든 프로젝트를 같은 URL로 다시 배포하려면 터미널에서 Vercel CLI를 사용합니다.

어디서 실행하나요? — 프로젝트 폴더 안에서

vercel 명령은 실행한 현재 디렉토리를 배포 대상으로 인식합니다. package.json이 있는 프로젝트 루트 폴더 안에서 실행해야 하며, 폴더 밖에서 실행하면 엉뚱한 폴더가 올라갑니다.

cd my-app        # 프로젝트 루트로 이동 (package.json 있는 곳)
ls                # package.json이 보이면 위치가 맞는 것

설치 · 로그인 · 배포

npm i -g vercel   # CLI 설치 (최초 1회)
vercel login      # 브라우저 인증 (1회)
vercel            # preview 배포 — 임시 URL
vercel --prod     # production 배포 — 실서비스 URL

vercel 과 vercel --prod 의 차이

명령어결과비고

vercel	Preview 배포 (임시 URL)	실행할 때마다 새 임시 URL이 생기고 실서비스에는 영향 없음
vercel --prod	Production 배포 (실서비스 URL)	1단계 Drop에서 만든 것과 같은 도메인이 갱신됨

오타 주의: --prod를 --pord 등으로 잘못 입력하지 않도록 확인합니다.

3단계 · GitHub 연동 — push하면 자동 배포

GitHub 저장소를 Vercel 프로젝트에 연결하면, 그 뒤로는 git push할 때마다 Vercel이 자동으로 재배포합니다. 코드만 올리면 배포는 자동으로 이루어지는, 실무에서 가장 널리 쓰이는 방식입니다.

GitHub에 코드 올리기

git init
git add .
git commit -m "first deploy"
git branch -M main
git remote add origin https://github.com/내아이디/my-app.git
git push -u origin main

Vercel 웹에서 저장소 연동하기 (권장)

2단계에서 CLI로 만든 프로젝트에 Git을 연결하는 방법입니다. 클릭만으로 끝나며 CLI 인증이 꼬일 일이 없습니다.

Vercel 웹사이트 로그인 → 해당 프로젝트 클릭
프로젝트 대시보드 진입 → 좌측 사이드바 맨 아래 Settings 클릭
Settings 탭 목록에서 Git 선택
Connect Git Repository 클릭 → GitHub 저장소 선택 후 연동
연동 후 git push → 자동 재배포가 켜짐

주의할 점

.vercel/ 폴더는 프로젝트 연결 정보이므로 git에 커밋하지 않습니다.
.gitignore에 node_modules, dist, .vercel이 포함되어 있는지 확인합니다.
모노레포 구조라면 Settings → Root Directory에서 배포할 하위 폴더를 지정합니다.

4단계 · Claude 연동 — "푸시해줘" 한마디로 배포

3단계에서 GitHub와 Vercel이 이미 연결되어 있으므로, 이제부터는 Claude에게 코드 작업을 시키고 "깃허브에 푸시해줘"라고만 하면 Vercel에 자동으로 반영됩니다. 터미널이나 CLI를 직접 만질 필요가 없습니다.

흐름

Claude에게 코드 수정 요청
"깃허브 푸시해줘" 한마디
Claude가 git add · commit · push 실행
Vercel이 push를 감지해 자동 재배포
잠시 뒤 실서비스 URL에 반영

예시 대화

나: 버튼 색 파란색으로 바꾸고 깃허브에 푸시해줘

Claude: 색상 변경 완료. 커밋·푸시했습니다.
→ Vercel이 배포 시작 (1~2분 후 URL 반영)

주의: 커밋 author 이메일이 Vercel 계정과 연결된 이메일과 일치해야 정상적으로 배포됩니다. 배포가 안 되면 git config user.email 값을 확인합니다.

자주 쓰는 설정 위치 요약

하고 싶은 일메뉴 경로

GitHub 저장소 연결/변경	프로젝트 → Settings → Git → Connect Git Repository
배포 브랜치(Production Branch) 변경	프로젝트 → Settings → Environments → Production → Branch Tracking
코드 변경 없이 재빌드만	프로젝트 → Deployments → 최신 배포 ⋯ → Redeploy

연결한 작업 브랜치와 Production 브랜치(기본값 main)가 다르면 push해도 자동 배포가 되지 않습니다. Branch Tracking 설정을 원하는 브랜치로 바꾸거나, 작업 브랜치를 main에 머지해서 push하면 해결됩니다.

한 장 요약

Vercel Drop = 일회성 배포. 다시 드롭하면 새 프로젝트가 생성됨
같은 URL로 계속 업데이트하려면 CLI의 vercel --prod 또는 GitHub 연결이 필요
GitHub 연결은 Settings → Git → Connect Git Repository
배포 브랜치 변경은 Settings → Environments → Production → Branch Tracking
자동 배포 조건은 Production 브랜치에 push하는 것 (브랜치가 다르면 배포 안 됨)
GitHub 연동이 끝나면 Claude에게 "푸시해줘"라고만 해도 배포가 자동으로 이어짐

12일차_Node·Express /POST 보내기/

sojsoj — Tue, 14 Jul 2026 16:47:09 +0900

초보자를 위한 Express POST 완전 안내서

1. POST란 무엇인가요?

웹 프로그램에서는 보통 다음과 같은 왕복이 일어납니다.

사용자 입력
   ↓
프론트엔드가 서버에 POST 요청
   ↓
서버가 req.body에서 데이터 확인
   ↓
서버가 처리 결과를 JSON으로 응답
   ↓
프론트엔드가 응답을 받아 화면에 표시

예를 들어 AI 채팅에서는 사용자가 작성한 질문을 서버로 보내야 합니다.

질문 작성 → POST 전송 → AI 서버 처리 → 답변 수신

회원가입, 로그인, 글쓰기, 주문, 댓글 작성, 파일 등록 등도 대체로 POST 또는 비슷한 쓰기용 HTTP 메서드를 사용합니다.

2. GET과 POST의 기본 차이

구분GETPOST

주요 목적	데이터 조회	데이터 제출·생성·처리 요청
데이터 위치	주로 URL 쿼리 문자열	주로 요청 body
주소창 실행	가능	일반적인 주소창 입력으로는 불가능
대표 사례	상품 목록, 검색, 게시글 조회	회원가입, 글쓰기, AI 질문
새로고침·공유	비교적 적합	같은 요청이 다시 실행될 수 있어 주의
긴 데이터 전송	부적합	비교적 적합

GET 요청의 예:

GET /api/products?category=book

POST 요청의 예:

POST /api/chat
Content-Type: application/json

{
  "message": "POST가 무엇인가요?"
}

중요한 점은 POST라고 해서 데이터가 자동으로 안전해지는 것은 아니라는 사실입니다. POST 데이터는 주소창에는 나타나지 않지만, 암호화하려면 반드시 HTTPS를 사용해야 합니다.

3. 실습 준비

이번 실습에서는 다음 프로그램 두 개를 실행합니다.

index.js  → 메시지를 받는 서버
send.js   → 메시지를 보내는 클라이언트

권장 폴더 구조:

08_node_express/
└─ 06_post/
   ├─ index.js
   ├─ send.js
   ├─ package.json
   └─ node_modules/

Node.js 버전 확인

터미널에서 다음 명령을 실행합니다.

node -v
npm -v

fetch()를 별도 패키지 없이 사용하려면 Node.js 18 이상이 편리합니다.

프로젝트 만들기

mkdir 08_node_express\06_post
cd 08_node_express\06_post
npm init -y
npm install express

각 명령의 의미:

mkdir: 폴더 만들기
cd: 해당 폴더로 이동하기
npm init -y: Node.js 프로젝트 설정 파일 만들기
npm install express: Express 설치하기

4. 서버 만들기: index.js

const express = require('express')
const app = express()

// JSON 형식으로 전송된 요청 본문을 자바스크립트 객체로 변환합니다.
app.use(express.json())

app.post('/api/chat', (req, res) => {
  const { message } = req.body

  console.log('받은 메시지:', message)

  res.json({
    ok: true,
    받은문장: message
  })
})

app.listen(3000, () => {
  console.log('서버 실행: http://localhost:3000')
})

한 줄씩 이해하기

Express 불러오기

const express = require('express')

설치한 Express 라이브러리를 현재 파일에서 사용할 수 있게 가져옵니다.

Express 앱 만들기

const app = express()

app은 서버를 설정하고 요청을 처리하는 중심 객체입니다.

JSON 해석 기능 켜기

app.use(express.json())

클라이언트가 보내는 JSON 문자열을 자바스크립트 객체로 변환합니다.

클라이언트가 다음 JSON을 보냈다고 가정해 보겠습니다.

{
  "message": "안녕하세요"
}

express.json()이 있으면 서버에서 다음과 같이 사용할 수 있습니다.

req.body.message

결과:

안녕하세요

express.json()이 없으면 req.body가 undefined가 되어 데이터를 읽지 못할 수 있습니다.

POST 요청 처리하기

app.post('/api/chat', (req, res) => {

의미는 다음과 같습니다.

POST 방식으로 /api/chat 주소에 요청이 오면 이 함수를 실행한다.

같은 /api/chat이라도 요청 방식이 다르면 다른 요청입니다.

GET  /api/chat
POST /api/chat

현재 서버에는 POST 처리만 있으므로 브라우저 주소창에서 http://localhost:3000/api/chat을 열면 원하는 결과가 나오지 않습니다. 주소창은 기본적으로 GET 요청을 보내기 때문입니다.

구조 분해 할당으로 message 꺼내기

const { message } = req.body

다음 코드의 짧은 표현입니다.

const message = req.body.message

서버 터미널에 출력하기

console.log('받은 메시지:', message)

이 내용은 사용자의 브라우저가 아니라 node index.js를 실행한 서버 터미널에 표시됩니다.

JSON으로 답장하기

res.json({
  ok: true,
  받은문장: message
})

서버가 클라이언트에게 다음과 같은 응답을 보냅니다.

{
  "ok": true,
  "받은문장": "안녕하세요"
}

res.json()은 객체를 JSON 문자열로 변환하고 JSON 응답이라는 정보도 함께 설정합니다.

3000번 포트에서 기다리기

app.listen(3000, () => {
  console.log('서버 실행: http://localhost:3000')
})

서버가 3000번 포트를 사용해 요청을 기다립니다.

5. 입력받아 POST 보내기: send.js

const readline = require('readline')

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
})

rl.question('메시지: ', async (message) => {
  try {
    const response = await fetch('http://localhost:3000/api/chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ message })
    })

    if (!response.ok) {
      throw new Error(`서버 오류: ${response.status}`)
    }

    const result = await response.json()
    console.log('서버 답장:', result)
  } catch (error) {
    console.error('요청 실패:', error.message)
    console.log('서버를 먼저 실행했는지 확인하세요.')
  } finally {
    rl.close()
  }
})

기존 .then() 방식도 올바르지만, 초보자가 실행 순서를 읽기 쉬운 async/await 형태로 작성한 예제입니다.

입력창 만들기

const readline = require('readline')

Node.js 터미널에서 사용자의 키보드 입력을 받기 위한 기본 모듈입니다.

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout
})

process.stdin: 키보드로 입력받기
process.stdout: 터미널에 글자 출력하기

메시지 입력받기

rl.question('메시지: ', async (message) => {

터미널에 다음과 같이 표시됩니다.

메시지:

사용자가 문장을 작성하고 Enter를 누르면 그 내용이 message 변수에 저장됩니다.

fetch로 POST 요청 보내기

const response = await fetch('http://localhost:3000/api/chat', {

fetch()는 다른 서버 주소로 HTTP 요청을 보내는 함수입니다.

await는 서버 응답이 도착할 때까지 해당 함수 안에서 기다린다는 뜻입니다.

POST 방식 지정하기

method: 'POST'

이 요청이 데이터 제출을 위한 POST 요청이라고 지정합니다.

JSON이라는 사실 알리기

headers: {
  'Content-Type': 'application/json'
}

서버에게 다음과 같이 알려주는 꼬리표입니다.

요청 body에 JSON을 넣어서 보냅니다.

서버의 express.json()은 이 정보를 보고 JSON 본문을 해석합니다.

객체를 JSON 문자열로 바꾸기

body: JSON.stringify({ message })

{ message }는 다음의 축약 표현입니다.

{
  message: message
}

사용자가 반갑습니다라고 입력했다면:

{ message: '반갑습니다' }

JSON.stringify()를 거치면 전송할 수 있는 JSON 문자열이 됩니다.

{"message":"반갑습니다"}

서버 응답 확인하기

if (!response.ok) {
  throw new Error(`서버 오류: ${response.status}`)
}

서버가 400, 404, 500 같은 오류 상태를 돌려준 경우 오류로 처리합니다.

fetch()는 서버가 404나 500을 보내도 자동으로 catch로 넘어가지 않기 때문에 response.ok 확인이 중요합니다.

응답 JSON을 객체로 변환하기

const result = await response.json()

서버가 보낸 JSON 문자열을 자바스크립트 객체로 변환합니다.

console.log('서버 답장:', result)

예상 결과:

서버 답장: { ok: true, '받은문장': '안녕하세요' }

6. 실행 방법

터미널을 두 개 엽니다.

첫 번째 터미널: 서버 실행

node index.js

출력:

서버 실행: http://localhost:3000

이 터미널은 종료하지 말고 그대로 둡니다.

두 번째 터미널: 메시지 보내기

node send.js

입력:

메시지: POST 연습 중입니다

보내는 쪽 출력:

서버 답장: { ok: true, '받은문장': 'POST 연습 중입니다' }

서버 쪽 출력:

받은 메시지: POST 연습 중입니다

이로써 다음 왕복이 완료된 것입니다.

send.js
  └─ body로 메시지 전송
       ↓
index.js
  └─ req.body에서 메시지 확인
       ↓
index.js
  └─ res.json()으로 응답
       ↓
send.js
  └─ response.json()으로 응답 확인

7. 데이터가 실제로 어떻게 변하는지

사용자가 다음 문장을 입력했다고 가정해 보겠습니다.

오늘 날씨가 어때?

① 입력 직후

message === '오늘 날씨가 어때?'

② 자바스크립트 객체 만들기

{ message: '오늘 날씨가 어때?' }

③ JSON 문자열로 변환하기

JSON.stringify({ message })

결과:

{"message":"오늘 날씨가 어때?"}

④ 서버가 JSON 해석하기

app.use(express.json())

서버의 req.body:

{
  message: '오늘 날씨가 어때?'
}

⑤ 서버가 message 꺼내기

const { message } = req.body

⑥ 서버가 결과 보내기

res.json({
  ok: true,
  받은문장: message
})

⑦ 클라이언트가 응답 해석하기

const result = await response.json()

최종 객체:

{
  ok: true,
  받은문장: '오늘 날씨가 어때?'
}

8. 안전한 서버 코드로 개선하기

현재 코드에서는 body가 없거나 message가 잘못 들어오면 문제가 생길 수 있습니다. 실제 서버에 가깝게 검증 기능을 넣어보겠습니다.

const express = require('express')
const app = express()

app.use(express.json())

app.post('/api/chat', (req, res) => {
  const { message } = req.body

  if (typeof message !== 'string' || message.trim() === '') {
    return res.status(400).json({
      ok: false,
      error: 'message를 문자열로 입력해 주세요.'
    })
  }

  const cleanMessage = message.trim()

  console.log('받은 메시지:', cleanMessage)

  res.status(200).json({
    ok: true,
    받은문장: cleanMessage,
    글자수: cleanMessage.length
  })
})

app.listen(3000, '0.0.0.0', () => {
  console.log('서버 실행: http://localhost:3000')
})

검증한 내용:

message가 실제 문자열인지 확인
빈 문장인지 확인
앞뒤 공백 제거
문제가 있으면 400 Bad Request 반환
성공하면 200 OK 반환

return이 중요한 이유:

return res.status(400).json(...)

오류 응답을 보낸 뒤 함수 실행까지 즉시 끝냅니다. return이 없으면 아래의 성공 응답도 보내려다가 “응답을 두 번 보냈다”는 오류가 발생할 수 있습니다.

9. HTML 페이지에서 POST 보내기

터미널 프로그램이 아니라 실제 웹페이지에서도 원리는 같습니다.

<!doctype html>
<html lang="ko">
<head>
  <meta charset="UTF-8">
  <title>POST 채팅 연습</title>
</head>
<body>
  <h1>메시지 보내기</h1>

  <input id="message" placeholder="메시지를 입력하세요">
  <button id="sendButton">보내기</button>

  <pre id="result"></pre>

  <script>
    const messageInput = document.querySelector('#message')
    const sendButton = document.querySelector('#sendButton')
    const resultBox = document.querySelector('#result')

    sendButton.addEventListener('click', async () => {
      const message = messageInput.value

      try {
        const response = await fetch('/api/chat', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({ message })
        })

        const result = await response.json()

        if (!response.ok) {
          throw new Error(result.error || '요청에 실패했습니다.')
        }

        resultBox.textContent = JSON.stringify(result, null, 2)
      } catch (error) {
        resultBox.textContent = error.message
      }
    })
  </script>
</body>
</html>

서버에서 HTML 파일을 제공하려면 public/index.html로 저장하고 다음 코드를 추가할 수 있습니다.

app.use(express.static('public'))

그다음 브라우저에서 아래 주소를 엽니다.

http://localhost:3000

이제 버튼을 누르면 웹페이지가 POST 요청을 보냅니다.

10. Claude·ChatGPT 같은 AI 서비스와의 관계

AI 채팅 서비스도 개념적으로 비슷한 흐름을 사용합니다.

사용자가 프롬프트 작성
→ 웹페이지가 서버에 요청
→ 서버가 AI 모델을 호출
→ 생성된 답변을 웹페이지에 응답
→ 웹페이지가 답변 표시

단순 예제와 실제 AI 서비스의 차이도 있습니다.

인증 정보가 추가될 수 있음
대화 기록이 함께 전송될 수 있음
응답이 한꺼번에 오지 않고 스트리밍될 수 있음
오류 처리와 사용량 제한이 있음
보안, 저장, 필터링 같은 서버 처리가 추가됨

따라서 전체 원리는 같지만, 실제 서비스가 반드시 단순 POST 한 번만 사용한다고 단정할 수는 없습니다. 스트리밍을 위해 SSE, WebSocket 또는 스트리밍 HTTP 응답을 사용할 수도 있습니다.

11. curl로 POST 요청 보내기

send.js 없이도 curl로 서버를 시험할 수 있습니다.

PowerShell에서는 따옴표 충돌을 줄이기 위해 다음 형태가 편리합니다.

curl.exe -X POST "http://localhost:3000/api/chat" `
  -H "Content-Type: application/json" `
  -d '{\"message\":\"curl에서 보낸 인사\"}'

한 줄 버전:

curl.exe -X POST "http://localhost:3000/api/chat" -H "Content-Type: application/json" -d '{\"message\":\"안녕하세요\"}'

환경에 따라 PowerShell의 따옴표 처리 방식이 다르게 느껴질 수 있습니다. 이때는 다음 명령도 사용할 수 있습니다.

$body = @{ message = "PowerShell에서 보낸 인사" } | ConvertTo-Json

Invoke-RestMethod `
  -Uri "http://localhost:3000/api/chat" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

우리반 배치도 만들기

* GET과 POST의 차이

GET은 서버에서 데이터를 받아올 때 사용한다.
POST는 서버에 데이터를 보내 새로운 데이터를 만들 때 사용한다.

예를 들면 다음과 같다.

학생 명단 조회: GET
회원가입: POST
글 작성: POST
AI에게 질문 보내기: POST
새로운 학생 추가: POST

다만 “GET은 받기, POST는 보내기”라고만 외우면 부족하다. GET도 요청을 보내고 응답을 받으며, POST도 데이터를 보낸 뒤 서버의 응답을 받는다.

즉, 둘 다 요청과 응답의 왕복이다.

브라우저 → 서버에 요청
브라우저 ← 서버의 응답

2. fetch 요청을 구성하는 네 가지

오늘 사용한 fetch 코드는 다음과 같은 형태였다.

fetch('http://192.168.10.28:5000/hancom/이름/users', {
  method: 'POST',

  headers: {
    'Content-Type': 'application/json',
    Authorization: 'HANCOM'
  },

  body: JSON.stringify({
    name: '홍길동'
  })
})

fetch 요청은 크게 네 부분으로 생각하면 쉽다.

1. URL

요청을 받을 서버의 주소다.

'http://192.168.10.28:5000/hancom/이름/users'

주소는 다시 다음과 같이 나눌 수 있다.

http://192.168.10.28:5000  → 서버 주소와 포트
/hancom/이름/users       → API 경로

2. method

서버에 어떤 행동을 요청할지 정한다.

method: 'POST'

GET 요청은 기본값이므로 생략할 수 있지만, 초보 단계에서는 의도를 분명하게 표시해도 좋다.

3. headers

내가 어떤 요청을 보내는지 서버에 알려주는 정보다.

headers: {
  'Content-Type': 'application/json',
  Authorization: 'HANCOM'
}

Content-Type은 body에 JSON을 보낸다는 뜻이다.

Authorization은 서버가 요청을 허용할지 판단할 때 사용하는 인증 정보다.

오늘 나는 토큰을 주소창이나 HTML 화면에 입력해야 하는지 헷갈렸다. 하지만 토큰은 fetch의 headers 안에 넣는 것이었다.

4. body

서버에 전달할 실제 데이터다.

body: JSON.stringify({
  name: '홍길동'
})

JavaScript 객체는 그대로 전송하지 않고 JSON.stringify()를 사용해 JSON 문자열로 변환한다.

4. 서버에서는 데이터를 어떻게 받는가

Express 서버에서는 다음 코드가 중요하다.

app.use(express.json())

클라이언트가 보낸 JSON 문자열을 해석해서 req.body로 사용할 수 있게 해준다.

app.post('/api/chat', (req, res) => {
  const { message } = req.body

  console.log('받은 메시지:', message)

  res.json({
    ok: true,
    받은문장: message
  })
})

전체 왕복은 다음과 같다.

사용자가 문장을 입력
        ↓
fetch의 body로 전송
        ↓
Express가 express.json()으로 해석
        ↓
req.body에서 값 꺼내기
        ↓
서버가 res.json()으로 응답
        ↓
브라우저가 response.json()으로 받기
        ↓
화면에 결과 표시

여기서 한 쌍으로 기억할 것이 있다.

보내는 쪽: JSON.stringify()
받는 서버: express.json()

express.json()이 없으면 req.body가 undefined로 나올 수 있다.

5. 응답을 받는 과정

서버 응답도 JSON 문자열 상태로 도착하기 때문에 JavaScript 객체로 바꿔야 한다.

fetch(url, options)
  .then(response => response.json())
  .then(data => {
    console.log(data)
  })
  .catch(error => {
    console.error(error)
  })

각 단계의 의미는 다음과 같다.

.then(response => response.json())

서버의 JSON 응답을 JavaScript에서 사용할 수 있는 값으로 해석한다.

.then(data => {
  console.log(data)
})

해석된 데이터를 사용한다.

.catch(error => {
  console.error(error)
})

요청 과정에서 발생한 오류를 확인한다.

6. 오늘 수행한 CRUD 과제

오늘의 핵심 과제는 오염된 수강생 명단을 정상 명단으로 정리하고 HTML 배치도로 보여주는 것이었다.

CRUD는 다음 네 가지 작업을 의미한다.

작업HTTP 메서드의미

Create	POST	새로운 학생 추가
Read	GET	학생 명단 조회
Update	PUT	기존 학생 정보 수정
Delete	DELETE	학생 삭제

GET: 명단 조회

fetch(`${BASE_URL}/hancom/${CLASS_NAME}/users`, {
  headers: {
    Authorization: 'HANCOM'
  }
})
  .then(response => response.json())
  .then(students => {
    console.log(students)
  })

POST: 학생 추가

fetch(`${BASE_URL}/hancom/${CLASS_NAME}/users`, {
  method: 'POST',
  headers: {
    Authorization: 'HANCOM',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '추가할 이름'
  })
})

PUT: 이름 수정

fetch(`${BASE_URL}/hancom/${CLASS_NAME}/users/${id}`, {
  method: 'PUT',
  headers: {
    Authorization: 'HANCOM',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: '새로운 이름'
  })
})

DELETE: 학생 삭제

fetch(`${BASE_URL}/hancom/${CLASS_NAME}/users/${id}`, {
  method: 'DELETE',
  headers: {
    Authorization: 'HANCOM'
  }
})

모든 요청에는 다음 인증 헤더가 필요했다.

Authorization: 'HANCOM'

7. 이름과 ID는 다르다

오늘 발생한 문제 중 하나는 학생 이름을 수정했더니 다른 자리가 바뀌거나 중복이 생기는 현상이었다.

여기서 중요한 사실은 다음과 같다.

이름 = 변경할 수 있는 정보
ID = 한 사람을 정확하게 찾는 고유 주소

예를 들어 다음 두 데이터가 있으면 문제가 된다.

{ id: 1, name: '박진' }
{ id: 1, name: '양하은' }

ID가 같기 때문에 서버는 어떤 학생을 수정해야 하는지 정확히 구분하기 어렵다.

정상적인 데이터는 다음과 같아야 한다.

{ id: 1, name: '박진' }
{ id: 2, name: '양하은' }

PUT과 DELETE는 이름이 아니라 ID를 기준으로 대상을 찾는다.

PUT /users/14
DELETE /users/14

따라서 이름 중복뿐 아니라 ID 중복도 반드시 확인해야 한다.

8. 서버 데이터와 좌석 데이터를 섞으면서 생긴 문제

과제를 진행하면서 자리 이동, 빈자리, 자리 없는 사람, 자동 정리 등의 기능을 추가했다.

아이디어 자체는 좋았지만, 서버 명단과 브라우저 좌석 정보가 동시에 학생 상태를 관리하면서 충돌이 생겼다.

예를 들어 다음처럼 두 곳에서 정보를 관리할 수 있다.

강사 서버: 14번 ID 학생은 양하은
브라우저 좌석 정보: 14번 좌석은 박진

이렇게 데이터의 주인이 두 곳이 되면 다음 문제가 생길 수 있다.

이름을 수정했는데 빈자리로 이동함
한 사람이 두 자리에 나타남
화면과 서버의 명단 수가 다름
삭제 버튼을 두 번 눌러야 반영됨
누락 인원 수와 화면 명단 수가 다름

이 문제를 줄이려면 서버를 명단의 기준으로 삼는 것이 좋다.

서버 데이터 변경
      ↓
GET으로 최신 명단 다시 조회
      ↓
받은 데이터로 화면 전체를 다시 그림

화면에서 값을 억지로 예상해서 바꾸는 것보다 서버의 최신 데이터를 다시 받아오는 방식이 안전하다.

9. AI 질문 기능도 같은 POST 구조였다

Groq를 사용한 AI 질문 기능도 기본 구조는 같았다.

브라우저 입력
     ↓
내 Express 서버에 POST
     ↓
Express 서버가 Groq API에 요청
     ↓
Groq의 답변
     ↓
Express 서버가 브라우저에 응답
     ↓
화면에 AI 답변 표시

클라이언트가 Groq API에 직접 요청하지 않고 내 서버를 거치는 중요한 이유는 API 키를 보호하기 위해서다.

client/index.html
    ↓ 질문만 전송
server/index.js
    ↓ .env의 API 키 사용
Groq API

API 키는 클라이언트 HTML에 넣으면 안 된다. 브라우저에서 누구나 확인할 수 있기 때문이다.

10. 서버가 켜진 것처럼 보였지만 실제로 종료된 경우

터미널에 다음과 같이 출력되었다.

http://localhost:3000
PS C:\프로젝트\server>

주소가 출력됐기 때문에 서버가 실행됐다고 생각하기 쉽다.

하지만 PowerShell 입력 프롬프트가 바로 돌아왔다면 Node 프로세스가 종료됐을 가능성이 있다.

정상적으로 서버가 계속 실행 중이라면 일반적으로 해당 터미널은 서버 프로세스가 차지하고 있어야 한다.

오늘은 이미 3000번 포트를 다른 프로그램이 사용하고 있어 충돌이 생겼고, 서버와 클라이언트를 3001번 포트로 맞췄다.

app.listen(3001)

fetch('http://localhost:3001/api/chat')

여기서 배운 중요한 기준은 다음과 같다.

서버가 듣는 포트 = 클라이언트가 요청하는 포트

둘 중 하나만 바꾸면 연결되지 않는다.

12. 오류 메시지를 해석하는 방법

앞으로는 화면이 작동하지 않는다고 무작정 코드를 여러 군데 고치지 말아야겠다.

401 Unauthorized

인증 정보가 없거나 잘못된 경우다.

확인할 부분:

headers: {
  Authorization: 'HANCOM'
}

주소창으로 API에 직접 접속하면 Authorization 헤더를 넣을 수 없기 때문에 401이 나올 수 있다.

req.body가 undefined

서버에서 다음 코드가 있는지 확인한다.

app.use(express.json())

클라이언트도 다음 두 설정을 확인한다.

headers: {
  'Content-Type': 'application/json'
}

body: JSON.stringify(data)

서버 안 켜짐 또는 fetch failed

다음 순서로 확인한다.

서버 터미널이 계속 실행 중인가?
서버 주소가 맞는가?
포트가 같은가?
서버 라우트가 맞는가?
브라우저 Console에 실제 오류가 무엇인가?
서버 터미널에는 어떤 오류가 있는가?

이름 수정 후 중복이나 빈자리 발생

다음 항목을 확인한다.

ID가 중복됐는가?
PUT URL에 올바른 ID를 넣었는가?
서버 데이터와 별도의 좌석 데이터가 충돌하는가?
수정 후 GET으로 최신 데이터를 다시 받았는가?

10일차_React (components)

sojsoj — Fri, 10 Jul 2026 16:44:55 +0900

1. 리액트 컴포넌트(Component)의 생성과 사용

리액트 컴포넌트는 재사용할 수 있는 독립적인 'UI 조각'입니다.

한 번 정의해 두면 원하는 곳에서 여러 번 반복해서 사용할 수 있습니다.

① 컴포넌트 만들기 (예시 - Hello.jsx)

components 폴더에 Hello.jsx 파일을 생성하고 화면에 렌더링할 함수를 작성합니다.
파일 하단에 export default Hello를 작성합니다. (이 컴포넌트를 외부 파일에서 사용할 수 있도록 내보내는 역할)

② 메인 화면에서 조립하기 (App.jsx)

불러오기: 파일 상단에 import Hello from './components/Hello.jsx'를 작성해 컴포넌트를 가져옵니다.
사용하기: 화면에 출력할 위치에 <Hello /> 태그 형태로 작성합니다.
<Hello />를 여러 번 작성하면 화면에도 동일한 UI가 여러 번 렌더링됩니다.

2. 컴포넌트 작성 시 3가지 필수 규칙

오류 없이 컴포넌트를 화면에 렌더링하기 위해 반드시 지켜야 하는 규칙입니다.

① 컴포넌트 이름의 첫 글자는 반드시 대문자
- (O) <Hello /> / (X) <hello />
- 이유: 리액트는 첫 글자가 소문자인 태그를 기존 HTML 태그(<div>, <h1> 등)로 인식하기 때문에, 개발자가 만든 컴포넌트임을 명시하기 위해 대문자를 사용합니다.
② 반환(return) 시 최상위 부모 태그는 오직 1개
- 리액트는 여러 개의 요소를 병렬로 반환할 수 없으므로, 전체를 감싸는 하나의 래퍼(Wrapper) 태그가 필요합니다.
- 빈 태그 <></> (Fragment) 활용: 화면 코드(DOM)에 불필요한 <div>를 남기지 않고 구조만 묶고 싶을 때 사용합니다.
③ 파일 하단에 export default 작성
- 해당 코드가 없으면 다른 파일(App.jsx 등)에서 이 컴포넌트를 import로 불러올 수 없습니다.

3. 컴포넌트에 CSS 스타일 적용하기

리액트에서는 컴포넌트 단위로 구조(JSX)와 스타일(CSS)을 세트로 관리하는 것이 일반적입니다.

① 전용 CSS 파일 생성 (Hello.css)

Hello.jsx 파일과 같은 폴더에 Hello.css 파일을 만들고 스타일 코드를 작성합니다.

② 컴포넌트에서 CSS 연결 (Hello.jsx)

파일 최상단에 import './Hello.css'를 선언하여 스타일 파일을 불러옵니다.
주의: 태그에 클래스명을 부여할 때는 HTML의 class 대신 className을 사용해야 합니다.
(자바스크립트의 예약어인 class와의 충돌을 피하기 위한 리액트 문법입니다.)

③ 메인 파일에서는 구조만 호출 (App.jsx)

App.jsx에서 <Hello />를 호출하면, Hello.jsx 내부에 연결된 CSS가 자동으로 함께 적용되어 화면에 출력됩니다.
메인 파일에서 별도의 디자인 코드를 추가할 필요가 없습니다.

4.리액트 부품 조립의 전체 흐름도

우리가 만들 파일들이 서로 어떻게 연결되는지 한눈에 보여주는 지도입니다.

단계	역할 (비유)	파일명	하는 일
1단계	옷장	Hello.css	글자색, 배경색 등 부품의 디자인(CSS)을 적어둡니다.
2단계	도장(부품) 조각하기	Hello.jsx	화면에 보여줄 뼈대를 만들고, 옷장(CSS)을 가져와 입힙니다.
3단계	다이어리에 도장 찍기	App.jsx	만들어진 도장을 가져와서 실제 메인 화면에 쾅쾅 찍어줍니다. 실질적인 화면에 보여지는 역활을 합니다.

(1) 도장(부품) 조각하고 옷 입히기 (Hello.jsx)

먼저 "안녕!"이라고 쓰인 예쁜 박스를 하나 만들어 보겠습니다.

Hello.jsx

import './Hello.css'        // ① 내 전용 옷장(CSS) 가져오기

const Hello = () => {       // ② 'Hello'라는 이름의 도장(컴포넌트) 만들기 시작!
  return (                  // ③ 도장을 찍었을 때 화면에 나올 모양
    <div className="box">   // ④ 대장 상자 (이름표: box)
      <h1>안녕!</h1>        // ⑤ 제일 큰 제목
      <p>반가워요  </p>    // ⑥ 작은 설명 글
    </div>
  )
}

export default Hello        // ⑦ "이 도장 다 만들었으니 밖에서 가져다 써도 돼!" 허락하기

태그 및 코드 상세 설명

import './Hello.css': "이 파일과 같은 폴더(.)에 있는 Hello.css 가져오기.
const Hello = () => { }: 화살표 함수라고 부르는 문법입니다.
쉽게 말해 "지금부터 Hello라는 이름의 요리 레시피(부품)를 정의할게!"라는 선언입니다. (첫 글자는 무조건 대문자!)
return ( ): "이 괄호 안의 내용을 최종적으로 화면에 내보내 줘!"
<div className="box">: 투명한 묶음 상자(<div>)입니다.
CSS(옷장)에서 이 상자를 꾸밀 수 있도록 box라는 이름표(className)를 달아주었습니다.
className은 HTML의 class와 똑같은 역할입니다!
<h1>과 <p>: 제목(Heading)을 뜻하는 굵은 글씨 태그, 그리고 문단(Paragraph)을 뜻하는 일반 글씨 태그입니다.
export default Hello: 다 만든 부품을 서랍(파일) 밖으로 내보내는 필수 마무릿줄입니다.

(2). 부품을 예쁘게 꾸며줄 옷장 (Hello.css)

방금 만든 도장(컴포넌트)에 입힐 디자인 코드입니다.

CSS

/* Hello.jsx에서 className="box"라고 이름표를 붙인 녀석을 꾸밉니다 */
.box {                     
  padding: 20px;          /* 상자 안쪽 여백을 20px만큼 빵빵하게 줍니다 */
  background: #f3e8ff;    /* 배경색을 연한 보라색으로 칠합니다 */
  border-radius: 12px;    /* 상자 모서리를 둥글게 깎아줍니다 */
  text-align: center;     /* 상자 안의 글자들을 가운데로 정렬합니다 */
}

/* box 상자 안에 있는 큰 제목(h1)만 특별히 꾸밉니다 */
.box h1 { 
  color: #aa3bff;         /* 글자색을 진한 보라색으로 바꿉니다 */
}

주의: 리액트 파일 안이 아니라, 반드시 별도의 .css 확장자를 가진 파일에 적어야 합니다!

(3) 메인 화면에 부품 조립하기 (App.jsx)

이제 옷까지 완벽하게 입은 Hello 도장을 가져와서 진짜 화면(App)에 출력하기

JavaScript

import Hello from './components/Hello.jsx'   // ① 서랍에서 Hello 도장 꺼내오기

const App = () => {             // ② 전체 웹사이트의 메인 화면 시작!
  return (
    <>                          // ③ 투명 포장지 (화면에 박스 흔적 안 남기기)
      <Hello />                 // ④ 첫 번째 도장 쾅!
      <Hello />                 // ⑤ 두 번째 도장 쾅! (재사용)
    </>
  )
}

export default App              // ⑥ 메인 화면도 바깥으로 내보내기

태그 및 코드 상세 설명

import Hello from '...': 지정된 경로 폴더(components) 안에 있는 Hello.jsx 파일을 현재 파일로 가져와서 Hello라는 이름으로 쓰겠다는 뜻입니다.
<></> (Fragment): 리액트의 "반드시 하나의 태그로 감싸야 한다"는 규칙을 지키면서도, 화면에 불필요한 <div> 상자를 만들지 않게 해주는 '투명 랩'입니다.
<Hello />: 우리가 정성껏 만든 도장(컴포넌트)을 드디어 사용하는 모습입니다!
빈 태그 닫기 규칙에 따라 끝에 꼭 슬래시(/)를 넣어주어야 합니다.
이렇게 한 줄만 적으면 그 자리에 방금 만든 보라색 박스가 통째로 그려집니다.

️ (4) 예상 그림 (실제 브라우저 결과 화면)

위의 모든 코드를 합쳐서 컴퓨터(브라우저)에서 실행하면?

짜잔! 아래와 같이 예쁜 보라색 상자가 메인 화면에 두 번 연달아 찍혀 나옵니다.

Plaintext

 ┌──────────────────────────────────────────────────┐
 │   내 메인 웹사이트 (App.jsx)                     │
 ├──────────────────────────────────────────────────┤
 │                                                  │
 │   ╭──────────────────────────────────────────╮   │
 │   │                                          │   │
 │   │                안녕! (진한 보라색)         │   │  <-- 첫 번째 <Hello />
 │   │             반가워요                    │   │
 │   │                                          │   │
 │   ╰──────────────────────────────────────────╯   │
 │                                                  │
 │   ╭──────────────────────────────────────────╮   │
 │   │                                          │   │
 │   │                안녕! (진한 보라색)         │   │  <-- 두 번째 <Hello />
 │   │             반가워요                    │   │
 │   │                                          │   │
 │   ╰──────────────────────────────────────────╯   │
 │                                                  │
 └──────────────────────────────────────────────────┘

9일차_ React_(App.jsx구조)

sojsoj — Fri, 10 Jul 2026 16:26:31 +0900

⚛️ 1. React(리액트)란 무엇일까요?

리액트를 한마디로 정의하면 "웹사이트를 레고 블록 조립하듯 뚝딱뚝딱 만드는 도구"입니다.

예전에는 웹사이트(집)를 만들 때 벽돌을 처음부터 끝까지 하나하나 쌓아 올렸다면, 리액트는 미리 만들어둔 '블록(컴포넌트)'들을 가져다 끼우기만 하면 됩니다.

게다가 블록 안의 글자(데이터)만 쓱 바꾸면, 리액트가 알아서 화면을 고쳐줍니다.

[개별 레고 블록들]                 [완성된 웹사이트 화면]
 ┌───────────┐                     ┌────────────────────┐
 │   검색창 │                     │   검색창          │
 └───────────┘                     ├─────────┬──────────┤
 ┌───────────┐      조립(React)    │         │          │
 │   프로필 │    ────────────▶    │  프로필│  ️사진 1 │
 └───────────┘                     │         │          │
 ┌───────────┐                     ├─────────┼──────────┤
 │  ️ 사진 1 │                     │ ⚙️ 설정 │  ️사진 2 │
 └───────────┘                     └─────────┴──────────┘

2. JSX : 자바스크립트 안에 HTML 쓰기

리액트에서는 JSX라는 아주 특별한 문법을 씁니다.

쉽게 말해 "자바스크립트(JS) 파일 안에서 HTML 뼈대를 마음껏 쓸 수 있게 해주는 규칙"입니다.

HTML과 거의 똑같이 생겼지만, 딱 3가지 작은 규칙만 주의하시면 됩니다.

HTML과 JSX의 결정적 차이점 3가지

구분	기존 HTML 방식	리액트 JSX 방식 (✨)	왜 다를까요?
① 이름표 (클래스)	<div class="box">	<div className="box">	자바스크립트에 이미 class라는 단어가 있어서 겹치지 않게 피한 거예요!
② 데이터 넣기	<p>수강생님 환영합니다</p>	<p>{name}님 환영합니다</p>	{ } 중괄호를 열면 그 안에 'JS 값이나 계산식'을 넣을 수 있어요.
③ 태그 닫기	<img src="a.png">	<img src="a.png" />	리액트는 아주 엄격해서 짝이 없는 빈 태그는 끝에 꼭 /로 닫아줘야 해요.

{ } 중괄호는 "자, 지금부터 자바스크립트 값이 들어간다!" 라고 알려주는 마법의 주머니라고 생각하시면 됩니다.

변수, 숫자 계산, 함수 등 뭐든 들어갈 수 있어요.

3. 실전 예제와 예상 화면

리액트(JSX) 코드

const App = () => {
  const name = "수강생"
  const age = 20

  return (
    <div className="box"> 
      <h1>안녕, {name}!</h1>      
      <p>{1 + 1}</p>                   
      <img src="a.png" alt="이미지" /> 
      <p>{name}님은 {age}살, 내년엔 {age + 1}살</p> 
    </div>
  )
}

[예상 그림] 실제 인터넷 창에 뜨는 결과

┌──────────────────────────────────────────────────┐
 │   내 첫 리액트 웹사이트                         │
 ├──────────────────────────────────────────────────┤
 │                                                  │
 │  안녕, 수강생!                                   │
 │                                                  │
 │  2                                               │
 │                                                  │
 │  [  ️ a.png 이미지 사진이 뜨는 자리 ]            │
 │                                                  │
 │  수강생님은 20살, 내년엔 21살                    │
 │                                                  │
 └──────────────────────────────────────────────────┘

구간별 이해하기

[1. ] 변수 선언 구역 (재료 준비)

JavaScript

const App = () => {    // 1. App이라는 요리사(컴포넌트)를 만들게요!
  const name = "수강생" // 2. 'name'이라는 상자에 "수강생" 글자를 담아둡니다 (재료 1)
  const age = 20       // 3. 'age'이라는 상자에 20이라는 숫자를 담아둡니다 (재료 2)

️ [2. ] return ( ) 구역 (실제 화면에 보여지는 접시)

JavaScript

  return (
    <div className="box"> 
      <h1>안녕, {name}!</h1>      
      <p>{1 + 1}</p>                   
      <img src="a.png" alt="이미지" /> 
      <p>{name}님은 {age}살, 내년엔 {age + 1}살</p> 
    </div>
  )
}

역할: 여기서부터가 진짜 인터넷 화면에 그려지는 코드입니다! * 요리사가 준비한 재료들을 예쁜 그릇(<div>, <h1>, <p>)에 담아서 손님(사용자)에게 내놓는(return) 과정입니다.
컴퓨터는 이 return ( ) 안에 적힌 코드를 읽어서 우리 눈에 보이는 웹사이트 화면을 만들어 줍니다.

CSS 적용할 때 <div>를 쓴다.

HTML이나 리액트에서 <div>는 아무 기능이 없는 '투명한 빈 상자(Box)'입니다.

글자나 이미지를 이 상자 안에 예쁘게 묶어두고, 상자에 이름표(className)를 붙여서 CSS로 스타일을 꾸밉니다.

코드 분석: <div className="box">
의미: "지금부터 이 상자 안에 들어가는 모든 요소들을 'box'라는 이름의 구역으로 묶을게! 그리고 CSS 파일에 가서 .box한테 예쁜 배경색이랑 테두리를 달아줘!"라고 명령하는 것입니다. 구역을 나누고 디자인을 입힐 때 <div>는 가장 많이 쓰이는 필수 태그입니다.

<></> (프래그먼트) 배우기

리액트의 대원칙: return ( ) 안의 모든 코드들은 반드시 커다란 하나의 상자(태그) 안에 다 감싸져 있어야 한다!

만약 아래처럼 대장 상자(<div>) 없이 알맹이들만 덜렁 내놓으면 리액트는 "누가 대장 상자야?!" 하면서 에러를 냅니다.

JavaScript

// ❌ 에러 발생! 감싸주는 대장 상자가 없어요.
return (
  <h1>안녕!</h1>
  <p>반가워</p>
)

이때 굳이 CSS 디자인을 줄 것도 아니고,

화면 구조상 무의미한 <div> 상자를 또 만들고 싶지 않을 때 쓰는 마법의 투명 상자가 바로 <> </> (React Fragment) 입니다.

️ <></>를 사용한 코드 예시

JavaScript

const App = () => {
  return (
    <>  {/* 무의미한 div 대신 투명 상자로 시작! */}
      <h1>안녕!</h1>
      <p>반가워</p>
    </> {/* 투명 상자 끝! */}
  )
}

[도표] <div> vs <></> 차이점 정리

방식	코드 모양	실제 브라우저(HTML) 결과	언제 쓰나요?
① <div> 상자	<div> ... </div>	<div> 상자가 화면 구조에 실제로 남음	테두리, 배경색 등 CSS 디자인을 직접 입혀야 할 때
② <></> 투명 상자	<> ... </>	감싸는 태그 없이 알맹이만 깔끔하게 남음	디자인은 필요 없고, 리액트의 "하나로 감싸라"는 규칙만 통과하고 싶을 때

7일차_ _JavaScript 문법 / 7가지 데이터 타입

sojsoj — Thu, 9 Jul 2026 16:32:36 +0900

JavaScript 문법

문법의미코드에서 사용하는 형태쉽게 기억하기

let	값이 바뀔 수 있는 변수	let myName = nameInput.value;	메모장
const	바뀌지 않는 변수	const out = document.querySelector("#out");	이름표
=	오른쪽 값을 왼쪽 변수에 저장	let myName = nameInput.value;	상자에 넣기
document	현재 웹페이지	document.querySelector("#name")	교실 전체
querySelector()	HTML 요소 찾기	document.querySelector("#greet")	물건 찾기
.value	입력창 안의 값	nameInput.value	사용자가 쓴 내용
.textContent	글자 바꾸기	out.textContent = "안녕!";	칠판 글씨 바꾸기
addEventListener()	이벤트가 발생하면 실행	button.addEventListener("click", () => {})	버튼을 누르면 행동하기
"click"	이벤트 중 "클릭" 이벤트	"click"	마우스로 누르기
` `	템플릿 리터럴	`안녕, ${myName}!`	문자열 안에 변수 넣기
${}	변수 값을 문자열에 삽입	`안녕, ${myName}!`	빈칸에 값 채우기

데이터 타입(Data Type) — 상자에 담는 값의 종류

변수(상자) 안에는 아무 값이나 넣을 수 있는 것 같지만, 값에도 종류(데이터 타입) 가 있습니다.

값도 글자, 숫자, 참/거짓 등 여러 종류가 있습니다.

데이터 타입에 따라 사용할 수 있는 기능과 작성 방법이 조금씩 달라집니다.

값의 종류

데이터 타입의미코드에서 사용하는 형태쉽게 기억하기

String	글자(문자열)	let name = "Bob";	글자
Number	숫자	let age = 10;	계산하는 숫자
Boolean	참 또는 거짓	let isLogin = true;	스위치(ON/OFF)
undefined	아직 값을 넣지 않음	let x;	빈 상자
null	일부러 비워 둠	let user = null;	비워두기로 결정한 상자
Array	여러 값을 순서대로 저장	let list = [1, "Bob", 10];	여러 칸이 있는 서랍
Object	여러 정보를 하나로 묶음	let user = { name: "Bob", age: 10 };	정보 묶음(가방)

하나씩 알아보기

1. String (문자열)

글자를 저장하는 데이터 타입입니다.

글자는 반드시 따옴표(" 또는 ') 로 감싸야 합니다.

let name = "Bob";
let city = "Seoul";

사용 예

out.textContent = "안녕하세요!";

2. Number (숫자)

숫자를 저장하는 데이터 타입입니다.

숫자는 따옴표를 사용하지 않습니다.

let age = 20;
let score = 100;

계산 가능

let a = 10;
let b = 5;

console.log(a + b);

결과

3. Boolean (참 / 거짓)

그런데 프로그램을 만들다 보면 "맞다" 또는 "아니다" 처럼 두 가지 상태만 저장해야 하는 경우가 많습니다.

예를 들어

로그인했나요?
성인인가요?
전등이 켜져 있나요?
숙제를 했나요?

이 질문들은 모두 예 / 아니오로 대답할 수 있습니다.

이럴 때 사용하는 데이터 타입이 Boolean입니다.

Boolean은 딱 두 가지 값만 있습니다.

Boolean은 true 또는 false 둘 중 하나만 저장할 수 있습니다.

예제 1. 전등

전등을 생각해 봅시다.

전등이 켜져 있을 때

let light = true;

뜻

전등이 켜져 있다.

전등이 꺼져 있을 때

let light = false;

뜻

전등이 꺼져 있다.

프로그램에서는 왜 사용할까요?

컴퓨터는

"예"

또는

"아니오"

를 판단해서 다음 행동을 결정합니다.

예를 들어 로그인 버튼을 눌렀다고 해봅시다.

let isLogin = true;

if (isLogin) {
    console.log("환영합니다!");
}

실행 순서

로그인했나요?

↓

예(true)

↓

환영합니다!

반대로

let isLogin = false;

if (isLogin) {
    console.log("환영합니다!");
}

실행 결과

아무것도 실행되지 않음

왜냐하면

로그인하지 않았기 때문입니다.

코드에서 사용하는 형태

Boolean	예 또는 아니오를 저장하는 값	let isLogin = true;	ON / OFF 스위치
true	예, 맞다, 켜짐	let light = true;	✅ 켜짐
false	아니오, 아니다, 꺼짐	let light = false;	❌ 꺼짐

4. undefined

변수는 만들었지만 아직 아무 값도 넣지 않은 상태입니다.

let x;

결과

console.log(x);

undefined

5. null

비어 있다는 것을 개발자가 일부러 표시하는 값입니다.

let user = null;

예를 들어

회원 정보

↓

아직 없음

이라는 뜻입니다.

쉽게 기억하기

일부러 비워 둔 상자

6. Array (배열) [ ]

여러 개의 값을 하나의 변수에 저장합니다.

let fruits = ["사과", "바나나", "포도"];

숫자도 가능합니다.

let numbers = [1, 2, 3];

섞어서도 가능합니다.

let data = [1, "Bob", true];

쉽게 기억하기

[   ][   ][   ]

↓

여러 칸이 있는 서랍

7. Object (객체) { }

관련 있는 여러 정보를 하나로 묶는 데이터 타입입니다.

let user = {
    name: "Bob",
    age: 20
};

여기에는

이름
나이
주소
전화번호

처럼 여러 정보를 함께 저장할 수 있습니다.

값 꺼내기

console.log(user.name);

결과

Bob

쉽게 기억하기

학생

이름 : Bob

나이 : 20

학년 : 3

↓

학생 한 명의 정보 묶음

데이터 타입 한눈에 보기

데이터 타입예시어떤 값인가?

String	"Bob"	글자
Number	10	숫자
Boolean	true	참/거짓
undefined	let x;	아직 값 없음
null	null	일부러 비움
Array	["사과", "배"]	여러 값을 순서대로 저장
Object	{ name: "Bob", age: 20 }	여러 정보를 하나로 묶음

6일차 _JavaScript 기초

sojsoj — Mon, 6 Jul 2026 16:41:22 +0900

JavaScript 보기 전 알아야 하는 개념

JavaScript는 HTML을 새로 만드는 언어가 아니라, 이미 만들어진 HTML을 찾아서 제어하는 언어입니다.

예를 들어 HTML에 아래와 같은 코드가 있다고 가정해 봅시다.

<h1 id="title">안녕하세요</h1>

<button id="btn">확인</button>

JavaScript는 이 요소들을 직접 만들지 않습니다.

대신

"HTML에서 title이라는 이름표(id)를 가진 요소를 찾아와."

라고 명령합니다.

찾아온 요소를 JavaScript 안에서 사용할 수 있도록 변수(또는 상수)에 저장한 후 원하는 기능을 추가하는 것입니다.

즉,

HTML
        ↓
JavaScript가 HTML 요소를 찾는다.
        ↓
찾은 요소를 변수(상수)에 저장한다.
        ↓
저장된 요소를 이용해서 글자를 바꾸거나,
색을 바꾸거나,
클릭 이벤트를 추가한다.

const란?

const title = document.querySelector("#title");

먼저 const부터 살펴보겠습니다.

const는 상수(Constant)를 만드는 키워드입니다.

상수는 한 번 저장한 값을 다른 값으로 다시 바꾸지 않는 변수라고 생각하면 됩니다.

쉽게 말하면

html이나 css  a 인것을 JS에서 a로 하기 위한  코드

document는 무엇일까?

document

는

현재 열려 있는 웹페이지 전체(HTML 문서)를 의미합니다.

브라우저는 HTML을 하나의 document(문서)로 관리합니다.

querySelector()는 무엇일까?

document.querySelector("#title")

는

document 안에서 원하는 요소를 찾는 명령입니다.

쉽게 번역하면

웹페이지(document) 안에서

id가 title인 요소를 찾아라.

라는 뜻입니다.

#은 왜 붙을까?

HTML에서는

id="title"

이라고 작성합니다.

하지만 JavaScript에서 id를 찾을 때는

"#title"

처럼 **#**을 붙입니다.

코드 전체를 해석해 보기

const title = document.querySelector("#title");

한 줄씩 해석하면

const
↓
title라는 상수를 만든다.

document
↓
현재 웹페이지에서

querySelector("#title")
↓
id가 title인 요소를 찾는다.

=
↓
찾은 요소를 title 상자에 저장한다.

최종 해석

웹페이지에서 id가 title인 HTML 요소를 찾아 title이라는 상수에 저장한다.

또 다른 예제

const a = document.querySelector("#a");

이 코드도 같은 원리입니다.

HTML

<div id="a">안녕하세요</div>

JavaScript

const a = document.querySelector("#a");

해석

HTML에서 id가 a인 요소를 찾아 JavaScript에서 a라는 상수에 저장한다.

즉,

HTML의 요소를 JavaScript에서 사용할 수 있도록 연결하는 과정입니다.

addEventListener()는 무엇일까?

이번에는 아래 코드를 보겠습니다.

document.querySelector("#calc").addEventListener("click", () => {

});

처음 보면 길어 보이지만, 작은 단위로 나누면 쉽습니다.

① document.querySelector("#calc")

document.querySelector("#calc")

↓

웹페이지에서

id가 calc인 요소를 찾는다.

② addEventListener()

.addEventListener()

의 뜻은

이 요소에 이벤트를 등록한다.

입니다.

여기서 이벤트(Event)란

어떤 일이 발생하는 것입니다.

예를 들어

버튼 클릭
키보드 입력
마우스 이동
화면 스크롤

모두 이벤트입니다.

③ "click"

"click"

은

클릭 이벤트를 의미합니다.

즉,

사용자가 이 요소를 클릭하면

이라는 뜻입니다.

④ () => { }

() => 에서 괄호 안에 아무것도 넣지 않는다. 의미는 바뀔거야 {}로

() => {

}

은 화살표 함수(Arrow Function)입니다.

쉽게 말하면

{} 클릭했을 때 실행할 명령을 적는 공간

입니다.

전체 코드 해석

document.querySelector("#calc").addEventListener("click", () => {

});

순서대로 해석하면

① HTML에서 id가 calc인 요소를 찾는다.

↓

② 그 요소에 클릭 이벤트를 등록한다.

↓

③ 사용자가 클릭하면

↓

④ { } 안에 작성된 코드가 실행된다.

즉,

HTML에서 id가 calc인 요소를 찾아, 클릭 이벤트를 등록하고, 사용자가 클릭하면 { } 안의 코드를 실행하라는 의미입니다.

여기서 중요한 점은

{ }의 상태로 바뀌는 것이 아니라, { } 안의 코드가 실행되는 것입니다.

이 표현이 JavaScript의 동작 원리를 가장 정확하게 설명합니다.

() => 이것의 의미는 이것을 클릭하면 이것이된다 라고 해석됨 정해진 양식으로 ()안에 무엇을 따로 입력할 필요는 없다.