정정지용
기술스택 목록
백엔드

Uvicorn

프로젝트 1개에서 사용했습니다. 각 프로젝트에서 어떤 역할로 썼는지 아래에 정리했습니다.

이 기술은 무엇인가요?

Python ASGI 애플리케이션을 실행하는 고성능 비동기 웹 서버

Uvicorn은 uvloop와 httptools를 기반으로 만들어진 빠른 ASGI 서버입니다. FastAPI, Starlette 같은 비동기 Python 웹 프레임워크를 프로덕션 환경에서 실행할 수 있도록 설계되었습니다. WSGI 방식의 동기 서버와 달리, 비동기 I/O를 활용해 동시 연결을 효율적으로 처리합니다.

이럴 때 사용합니다

  • FastAPI, Starlette 같은 ASGI 프레임워크를 프로덕션에서 실행할 때
  • 비동기 I/O가 많은 API 서버에서 높은 동시 처리 성능이 필요할 때
  • WebSocket이나 Server-Sent Events 같은 실시간 통신을 지원해야 할 때
  • 가벼우면서도 안정적인 Python 웹 서버가 필요할 때

핵심 개념

ASGI
Asynchronous Server Gateway Interface의 약자로, Python 비동기 웹 애플리케이션과 서버 사이의 표준 인터페이스입니다. WSGI의 비동기 버전이라고 볼 수 있습니다.
uvloop
Python의 기본 asyncio 이벤트 루프를 대체하는 고성능 구현체입니다. Uvicorn은 이를 사용해 더 빠른 비동기 처리를 제공합니다.
Worker
Uvicorn이 실행하는 독립적인 프로세스 단위입니다. 멀티 워커로 실행하면 CPU 코어를 여러 개 활용해 동시 처리 성능을 높일 수 있습니다.
Lifespan
애플리케이션 시작과 종료 시점에 실행되는 이벤트 훅입니다. 데이터베이스 연결 초기화나 리소스 정리 같은 작업을 처리할 때 사용합니다.

FastAPI 앱을 Uvicorn으로 실행

main.py 파일의 app 객체를 ASGI 애플리케이션으로 실행합니다. --reload 옵션은 코드 변경 시 자동 재시작, --workers는 멀티 프로세스 실행을 의미합니다.

Shell
# 기본 실행 (개발 환경)
uvicorn main:app --reload

# 프로덕션 실행 (멀티 워커, 특정 호스트/포트)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

# Python 코드에서 직접 실행
# main.py
import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

처음 쓸 때 흔한 함정

  • 개발 시 --reload 옵션은 편리하지만, 프로덕션에서는 사용하지 말아야 합니다
  • 멀티 워커는 메모리를 워커 수만큼 배로 사용하므로, 서버 리소스를 고려해 설정해야 합니다
  • Windows에서는 멀티 워커가 제대로 동작하지 않을 수 있어, 리눅스 환경 사용이 권장됩니다

위 개요는 기술 학습을 돕기 위해 자동 생성된 일반 설명입니다. 정확한 사양과 최신 정보는 공식 문서를 확인하세요.

프로젝트별 활용 방식

위 개념이 실제 프로젝트에서 어떻게 쓰였는지 보여줍니다.

함께 사용한 기술

위 프로젝트들에서 같이 쓰인 다른 기술입니다.

AsyncioDockerFastAPIMultiprocessingONNX RuntimeOpenCVPyArmorPythonPyTorch