머신러닝 프레임워크를 활용하다 보면 가장 흔히 마주하는 문제 중 하나가 바로 의존성 충돌이다. 특히 TensorFlow, Numpy, 그리고 ml-dtypes와 같은 핵심 패키지는 내부적으로 긴밀히 연결되어 있기 때문에 버전이 맞지 않을 경우 다양한 오류가 발생한다. 최근 사용자들이 가장 많이 접하는 메시지 중 하나가 _ARRAY_API not found 혹은 ImportError: numpy.core._multiarray_umath failed to import 같은 에러다. 이 글에서는 이러한 오류가 발생하는 근본적인 원인과 해결 방법을 심층적으로 살펴본다.
1. 오류의 원인
에러 메시지를 분석하면 공통적으로 다음과 같은 특징을 보인다.
_ARRAY_API not found: 이는 ml-dtypes 라이브러리가 Numpy의 새로운 내부 API를 호출하려고 했지만, 현재 설치된 Numpy 버전에 해당 속성이 존재하지 않을 때 발생한다. 즉, ml-dtypes가 요구하는 최소 Numpy 버전보다 낮은 버전이 설치된 경우다._multiarray_umath failed to import: 이는 C 확장 모듈과 파이썬 인터페이스 사이의 불일치에서 비롯된다. 보통 Numpy를 업그레이드 또는 다운그레이드했는데, 기존 빌드된 바이트코드(.so, .pyd 파일)가 여전히 시스템에 남아 충돌하는 상황에서 나타난다.
TensorFlow 2.15 버전은 기본적으로 numpy>=1.26과 ml-dtypes 0.2.x 조합을 전제로 설계되어 있다. 따라서 이보다 낮은 버전을 쓰면 반드시 충돌이 발생한다.
2. 해결 방법
의존성 충돌을 해결하기 위한 방법은 다음과 같이 정리할 수 있다.
① 버전 호환성 맞추기
TensorFlow 2.15의 경우 가장 안정적인 조합은 다음과 같다.
- TensorFlow 2.15.x
- Numpy 1.26.4
- ml-dtypes 0.2.0
따라서 다음과 같은 명령어로 맞추는 것이 일반적이다.
pip uninstall -y numpy ml-dtypes
pip install numpy==1.26.4 ml-dtypes==0.2.0
② 깨끗한 환경 재설치
pip 캐시와 기존 잔여 파일이 충돌의 원인이 될 수 있으므로, 캐시를 제거하고 재설치를 시도하는 것이 좋다.
pip cache purge
pip install --upgrade --force-reinstall tensorflow numpy ml-dtypes
③ 환경 분리
시스템 전체에 설치된 패키지와 사용자 로컬 환경의 패키지가 뒤섞이면 충돌이 잦다. 가상환경(venv)이나 conda 환경을 만들어 작업하는 것이 안전하다.
python -m venv tf_env
source tf_env/bin/activate
pip install tensorflow==2.15.0 numpy==1.26.4 ml-dtypes==0.2.0
④ 불필요한 경로 차단
Transformers 같은 라이브러리가 자동으로 TensorFlow 모듈을 불러오면서 충돌을 유발할 수 있다. PyTorch만 사용할 경우에는 불필요한 TensorFlow 임포트를 차단하는 방법도 있다.
import os
os.environ["TRANSFORMERS_NO_TF"] = "1"
3. 교훈과 실무적 제언
이번 문제는 단순히 버전을 맞추는 수준에서 끝나지 않는다. 대규모 머신러닝 생태계는 상호 의존성이 복잡하게 얽혀 있고, 각 패키지가 특정한 조합에 맞춰 빌드되기 때문에 버전을 올바르게 관리하는 것이 곧 안정성의 핵심이다.
- 첫째, 항상 사용 중인 프레임워크의 공식 호환성 표를 먼저 확인해야 한다.
- 둘째, 가능하다면 프로젝트마다 별도의 가상환경을 만들어 독립적으로 관리하는 습관을 들여야 한다.
- 셋째, 시스템 전역 설치보다는 환경 관리 도구(conda, poetry, venv 등)를 활용하는 것이 장기적으로 훨씬 안전하다.
머신러닝 프로젝트는 단순한 코드 작성 이상의 환경 구축과 유지가 필수적이다. 올바른 버전 관리와 환경 분리를 통해 예기치 못한 충돌을 예방하고, 연구와 개발의 연속성을 확보하는 것이 무엇보다 중요하다.
답글 남기기