모든 엔지니어는 "내 컴퓨터에서는 잘 되는데."라는 말을 한 번쯤 해본 적이 있을 것입니다.

저는 그 문장이 왜 함정인지 완벽하게 보여주는 벽에 부딪혔습니다. 애플리케이션은 로컬 개발 환경에서는 완벽하게 작동했지만, 클라우드에 배포하자마자 즉시 충돌이 발생했습니다.

다음은 배포 과정에서 직면했던 두 가지 주요 장애물에 대한 사후 분석(post-mortem), 이를 어떻게 진단했는지, 그리고 에이전트를 프로덕션 환경에 안착시킨 실용적인 해결책에 대한 기록입니다.

장애 1: 'KeyError: _type' 미스터리
증상
애플리케이션은 성공적으로 배포되었지만, ChromaDB 벡터 데이터베이스 (vector database)를 초기화하려고 시도하는 순간, 눈에 띄는 'KeyError: _type'과 함께 충돌이 발생했습니다.

조사 (근본 원인 분석)
처음에는 코드를 확인하려 했지만, 초기화 로직은 두 환경 모두 동일했습니다. 문제는 환경적인 요인임이 분명했습니다. 저는 로컬 설정과 Docker 컨테이너를 비교하기 시작했습니다:

• 로컬 머신: Windows, Python 3.13.
• Docker 컨테이너: Linux, Python 3.11.

의존성 트리 (dependency tree)를 파헤친 결과 범인을 찾아냈습니다. ChromaDB는 hnswlib에 크게 의존하며 메타데이터를 기반이 되는 SQLite/JSON 형식으로 저장합니다. 저의 로컬 local_vector_db가 Windows 환경에서 Python 3.13을 사용하여 생성되었기 때문에, hnswlib와 ChromaDB의 특정 버전이 Docker 컨테이너에서 실행되는 이전 버전의 Python 3.11 Linux 패키지와는 다르게 메타데이터를 직렬화(serialize)했습니다.
클라우드 컨테이너는 본질적으로 자신이 인식하지 못하는 SQLite/JSON 스키마 (schema)를 읽으려 시도했고, 그 결과 _type 키가 누락되는 현상이 발생했습니다.

함정 (그리고 전환해야 할 시점)
저의 초기 엔지니어링 본능은 로컬 Windows 패키지를 Docker 컨테이너의 버전과 일치하도록 다운그레이드하여 동일성 (parity)을 강제로 맞추는 것이었습니다. 이것은 실수였습니다.

Windows에서 hnswlib 및 관련 C 의존성 패키지를 다운그레이드하려고 시도하자, C++ 빌드 도구 (Build Tools) 누락 오류라는 악몽이 시작되었습니다. 저는 실제 문제를 해결하는 대신 한 시간 동안 운영체제(OS)와 싸우는 데 시간을 허비했습니다. 유능한 엔지니어는 언제 구덩이 파기를 멈추고 물러나야 하는지를 압니다.

해결책: 데이터 생성의 컨테이너화 (Containerize the Data Generation)
애플리케이션이 Docker 컨테이너 내부에서 실행될 예정이라면, 애플리케이션이 소비하는 데이터 또한 정확히 동일한 환경 내부에서 생성되어야 한다는 점을 깨달았습니다:

docker run -v ${PWD}:/app -it my-ai-agent-image python ingest.py

컨테이너 내부에서 ingest.py를 실행함으로써, local_vector_db는 데이터가 읽히게 될 환경과 정확히 일치하는 Linux/Python 3.11 의존성(dependencies)을 사용하여 생성되었습니다. 이는 완벽한 스키마 일치(schema parity)를 보장했습니다. KeyError는 사라졌고, 에이전트는 결함 없이 초기화되었습니다.