트러블 슈팅: 딥러닝 모델 서빙(w/FastAPI)

세계 3대 인명사전 마르퀴즈 후즈후에 등재된 '임성렬 교수님'과 함께 FastAPI로 딥러닝 모델 서빙을 했다.

 

나와 같은 팀 형의 임무는 파일을 업로드하는 POST method의 Internal Server Error를 해결하는 것이었다.

우리는 문제를 해결하기 위해 많은 시간을 할애했다. 하지만, 원인은 아주 간단함 속에 있었다..

 

 

 

우리는 문제의 본질을 놓치고 있었다

프로젝트를 진행하는 과정에서 우리는 FastAPI 서버를 띄우고 브라우저에 접속했을 때 메인 페이지가 보이도록 하기 위해, main.py에 루트 경로(/)에 대한 라우팅 코드를 추가했다. HTML을 반환하는 방식으로 코드를 작성하고, 정적 파일 경로도 따로 mount 했다.

그런데 서버는 분명히 잘 실행되었음에도 메인 페이지는 표시되지 않았다. 이미지, CSS 등 정적 파일도 404 에러가 났고, 심지어 가장 기본적인 index.html 파일조차 열리지 않았다.

여기서 우리는 중요한 사실 하나를 놓치고 있었다. 정적 HTML 파일은 서버를 통해서 볼 수도 있지만, 그냥 브라우저에서 직접 열어서 확인할 수 있는 파일이라는 점이다. 루트 라우팅에 너무 집착하다 보니 처음에는 단순히 파일 경로가 잘못되었을 수 있다는 기본적인 사실조차 생각하지 못하고 다른 방향으로 해결하려고만 했다.

그 방향으로 시간을 많이 소비한 뒤에야, “사실 index.html은 그냥 열어보면 되는 것 아닌가?”라는 기본적인 아이디어로 돌아갔고, 결국 문제의 본질이 거기에 있었다는 걸 깨달았다. 이때 가장 크게 느낀 것은 문제를 어렵게만 보려 하지 말고, 항상 기본으로 돌아가자는 것이다.

 

 

디렉터리 구조와 __init__.py의 중요성

또 하나의 중요한 깨달음은 Python 프로젝트에서 디렉터리를 패키지로 인식시키기 위한 __init__.py의 존재 의미였다.

우리는 특정 디렉터리 내 모듈을 import하려고 했지만 계속해서 ModuleNotFoundError가 발생했다. 알고 보니 해당 디렉터리에 __init__.py 파일이 빠져 있었고, 그것이 패키지로 인식되지 않아 임포트가 되지 않았던 것이다. 이 파일은 내용이 비어 있어도 되지만, 그 존재 자체가 매우 중요하다는 사실을 몸소 체감했다.

이처럼 파이썬의 기본적인 원리를 정확히 알고 있느냐에 따라 에러 해결 속도는 극적으로 달라질 수 있다는 점을 다시금 확인할 수 있었다.

 

 

버전 의존성과 Poetry의 강력함

TensorFlow를 설치하려고 할 때도 또 다른 트러블이 발생했다. 이유는 단순했다. Python 3.13에서는 TensorFlow가 아직 공식 지원되지 않았기 때문이다. 이 문제를 해결하기 위해 Python 3.10이나 3.11로 버전을 낮춰야 했다.

처음엔 다소 생소했지만, poetry는 우리가 프로젝트의 의존성을 일관되고 강력하게 관리할 수 있도록 도와줬다. pyproject.toml을 기반으로 가상환경을 만들고, 필요한 패키지를 명시적으로 설치하며, 언제든지 재현 가능한 환경을 구성할 수 있게 해줬다.
Poetry는 단순한 도구 그 이상으로, 우리가 안정적인 프로젝트 환경을 유지하게 해준 핵심 요소였다.

 

 

 

뭔가 단순한 기능 구현 그 이상의 의미가 있었다. 개발을 하면서 마주한 문제들을 하나하나 해결해 나가며, 우리는 문제 해결에 대한 감각, 그리고 기초를 다시 점검하는 습관을 함께 얻을 수 있었다.

 

[결론]
·  트러블 슈팅은 고통스럽지만, 끝내고 나면 가장 값진 자산이 된다!

·  문제를 복잡하게 보지 말고, 기본 원리와 구조부터 차근차근 확인하자.

·  파이썬의 __init__.py, 버전 호환성, 패키지 구조 등은 모두 기본이지만 결코 가볍게 보면 안 되는 것들이다.

·  좋은 도구를 익히면 프로젝트 전체의 품질과 속도가 달라진다. Poetry 강추!