Gradio 개요 & 설치

Gradio는 Python 함수만 있으면 웹 화면 뚝딱 만드는 마법 도구, 어려운 HTML·CSS 몰라도 AI 데모를 친구한테 인터넷 주소로 보낼 수 있는 초간단 도구

설치

⚠ 실행하자마자 ImportError 가 나면

아래 메시지가 gradio 를 import 하는 순간 길게 쏟아지면, gradio 잘못이 아니라 numpy 버전 충돌이다.

왜 나는가 — numpy 2 부터 내부 모듈 이름이 numpy.core 에서 numpy._core 로 바뀌었다. 예전 numpy 1.x 로 빌드된 pandas · matplotlib 은 아직 옛 이름을 부르기 때문에 numpy 2 환경에서 터진다.
왜 gradio 에서 터지나 — gradio 가 내부에서 pandas 를 불러오기 때문이다. gradio 는 피해자다.

고치는 법 — numpy 2 로 빌드된 최신 버전으로 갈아끼운다.

numpy 를 1.x 로 내리는 건 권하지 않는다. torch · ultralytics · gradio 최신판이 전부 numpy 2 기준이라 그쪽이 더 크게 깨진다.

어디가 깨졌는지 확인하는 법 — 하나씩 import 해보면 범인이 바로 나온다.

같은 이유로 Data 파트의 matplotlib 시각화 실습도 막힌다. 위 명령 한 번이면 둘 다 풀린다.

gr.Interface 주요 파라미터

앱 실행

참고 링크

• Gradio 공식 홈페이지 — 라이브러리 소개와 갤러리
• Quickstart 가이드 — 5분 안에 첫 앱 만들기
• gr.Interface 공식 문서 — 파라미터 전체 목록
• HuggingFace Spaces — 만든 앱 무료로 인터넷에 올리는 곳

기본 웹앱 — 이름 인사 (v21_01_gradio.py)

이름 적으면 "Hello, OOO" 인사해주는 가장 쉬운 첫 웹앱, 함수 만들기 → gr.Interface 연결 → launch 세 단계로 끝

전체 코드

포인트

• inputs="text" — 글자 적는 칸 자동으로 만들어주기
• outputs="text" — 함수가 돌려준 답을 화면에 글자로 보여주기
• launch() — 내 컴퓨터에서만 실행, share=True 붙이면 72시간 인터넷 공개 주소 자동 발급
• gr.Blocks — 버튼·탭 등 화면을 직접 짜는 도구, 05번에서 다루기

참고 링크

• Interface 클래스 가이드 — fn·inputs·outputs 사용법
• 앱 공유하기 — share=True와 영구 호스팅 방법
• gr.Textbox 문서 — "text" 컴포넌트 세부 옵션

영한 번역 웹앱 (v21_02_gradio_trans.py)

영어 문장 넣으면 한국어로 바꿔주는 자동 번역기, 구글 번역 라이브러리(GoogleTranslator)에 Gradio 화면만 입혀서 5줄로 완성

전체 코드

포인트

• GoogleTranslator(source="en", target="ko") — 구글 번역 무료로 쓰는 마법 주문, source(원본 언어)와 target(번역 언어) 두 개만 정하면 끝
• .translate(text) — 영어 문장 넣으면 한국어 문자열로 돌려주기
• title, description — 앱 화면 위쪽에 제목·설명 표시, 사용자가 무슨 앱인지 한눈에 알아보기
• .launch() — share 없이도 내 컴퓨터(127.0.0.1)에서 바로 실행

참고 링크

• deep-translator PyPI — 패키지 공식 페이지, 설치법과 지원 언어 목록
• deep-translator 공식 문서 — 구글 외 Papago·DeepL 등 번역기 사용법
• 언어 코드 표 — "en", "ko" 외 다른 언어 코드 확인

YOLO 이미지 객체 탐지 (v21_03_gradio_yolo.py)

사진 올리면 YOLO AI가 사물 찾아 네모 박스로 표시해주는 탐지기, gr.Image(type="numpy")로 이미지를 숫자 표(numpy)로 받아 모델에 바로 전달

전체 코드

포인트

• gr.Image(type="numpy") — 올린 사진을 숫자 표(numpy)로 바꿔서 YOLO에 전달, type 안 적으면 PIL 객체로 들어가 오류
• gr.Image() — outputs에 쓰면 숫자 표도 자동으로 그림으로 보여주기
• results[0].plot() — 찾은 사물 위에 네모 박스 + 이름표 그려서 결과 이미지로 돌려주기
• YOLO("yolo11n.pt") — yolo11n(가장 가볍고 빠른 모델) 파일 없으면 인터넷에서 자동 다운로드

참고 링크

• YOLO11 공식 문서 — yolo11n·s·m·l·x 모델 크기별 차이
• gr.Image 공식 문서 — type 옵션(numpy·pil·filepath) 설명
• YOLO predict 가이드 — results[0].plot() 등 결과 활용법
• 4가지 인터페이스 패턴 — 이미지·오디오·챗봇 등 입출력 조합

gr.Blocks 통합 앱 — 지금까지 만든 앱 3개를 하나로 (v21_04_gradio_block.py)

인사·번역·YOLO 를 탭 3개로 묶어 앱 하나에 넣기, 함수는 그대로 두고 화면 만드는 부분만 gr.Blocks 로 바꾸기

왜 필요한가

gr.Interface 는 앱 하나에 기능 하나다. 02·03·04번 앱을 같이 쓰려면 파이썬을 세 번 실행하고 창을 세 개 띄워야 한다.
gr.Blocks 는 화면을 내가 직접 배치하는 방식이라 탭으로 묶어 한 앱에 담을 수 있다.

gr.Blocks 가 뭔가

Interface 는 "함수 하나 주면 화면은 Gradio가 알아서" 만들어주는 완제품이다. 편한 대신 화면을 못 바꾼다.
Blocks 는 "칸을 내가 만들고, 연결도 내가 한다"는 조립 방식이다. 손이 더 가는 대신 원하는 대로 배치할 수 있다.

전체 코드

코드 읽는 순서

① with gr.Blocks() as gr_web: — 이 안에서 만든 칸은 자동으로 화면에 올라간다. 쓴 순서대로 위에서 아래로.
② with gr.Tab("인사"): — with 안에 with. 이 안에 만든 칸은 그 탭에만 들어간다. 탭을 늘리려면 with gr.Tab(...) 블록을 더 쓰면 된다.
③ name_box = gr.Textbox(...) — Interface 의 "text" 를 변수로 만드는 것. 어느 칸에서 읽고 어느 칸에 쓸지 지목해야 하니까 이름이 필요하다.
④ .click(함수, 입력칸, 출력칸) — Blocks 의 핵심 한 줄. "버튼 누르면 → 이 함수 실행 → 이 칸에서 읽어 → 저 칸에 결과". 순서가 곧 의미다.

배치 도구 — Tab 말고도

전부 with 로 쓰고, 안에 또 with 를 넣어 겹칠 수 있다. 파이썬 들여쓰기가 그대로 화면 구조가 된다.

버튼 말고 다른 실행 방법

• .click() — 버튼 눌렀을 때
• .change() — 입력 칸 내용이 바뀔 때마다 (Interface 의 기본 동작이 이것)
• .submit() — 텍스트 칸에서 엔터 쳤을 때

자주 하는 실수

• 칸 이름을 탭마다 똑같이 지음 — name_box 를 세 탭에서 다 쓰면 나중 것이 앞의 것을 덮어써서 엉뚱한 칸에 결과가 나온다. 탭마다 다른 이름으로.
• .click() 을 with 밖에 씀 — 칸을 만든 with 블록 안에 있어야 한다. 들여쓰기 확인.
• gr.Button(...) 만 쓰고 .click() 을 안 붙임 — 버튼은 보이는데 눌러도 아무 일이 없다.
• launch() 를 with 안에 씀 — 화면을 다 만든 뒤 with 밖에서 실행해야 한다.

참고 링크

• Blocks와 이벤트 리스너 — with 블록과 .click() 사용법
• 레이아웃 제어 가이드 — Row·Column·Tab으로 화면 나누기
• gr.Tab 문서 — 탭 옵션
• gr.Blocks 공식 문서 — 파라미터 전체 목록