OpenAI API의 Code Interpreter는 모델이 Python 코드를 실행해 파일 처리, 데이터 분석, 수학 계산, 이미지 처리 같은 작업을 수행하게 해주는 도구입니다. 문서상 이름은 Code Interpreter지만 모델에게는 python tool로 명시하는 것이 더 확실하다고 안내됩니다. 실무에서 중요한 포인트는 기능 자체보다 컨테이너 운영 방식입니다.
많은 개발자가 Code Interpreter를 ‘모델이 코드를 실행한다’ 정도로 이해하고 바로 붙입니다. 하지만 운영 환경에서는 컨테이너 생성 방식, 메모리 제한, 파일 업로드, 만료 시간, 생성 파일 회수 방식이 품질과 비용을 좌우합니다. 이 글은 API 기반 제품에 Code Interpreter를 붙일 때 확인해야 할 설계 기준을 정리합니다.
Code Interpreter는 단순 질의응답용 도구가 아닙니다. 모델이 계산을 정확히 해야 하거나, 입력 파일을 실제로 파싱해야 하거나, 중간 결과를 반복 실행하며 고쳐야 할 때 가치가 있습니다. 예를 들어 CSV 정리, 엑셀 요약, 로그 분석, 이미지 histogram 계산, 수식 검증, PDF에서 추출한 표 후처리 같은 작업이 적합합니다.
반대로 단순 텍스트 요약, 일반 코드 설명, 짧은 정규식 생성에는 과합니다. 컨테이너를 만들고 파일을 올리고 실행 결과를 회수하는 비용이 있기 때문입니다. 사용자가 파일을 업로드하지 않았고, 계산도 필요 없다면 일반 Responses API 호출로 충분한 경우가 많습니다.
실무 기준은 다음과 같이 잡으면 됩니다.
OpenAI 문서에는 두 가지 컨테이너 생성 방식이 나옵니다. 첫 번째는 auto mode입니다. Response 생성 시 tool 설정에 container: { type: "auto" }를 넘기면 새 컨테이너를 만들거나, 이전 code_interpreter_call 문맥의 활성 컨테이너를 재사용합니다. 빠르게 붙이기 좋고, 대화형 분석 흐름에 적합합니다.
두 번째는 explicit mode입니다. /v1/containers로 컨테이너를 먼저 만들고, 그 id를 tool 설정에 넣습니다. 이 방식은 서버가 컨테이너 생명주기를 더 명확히 관리해야 할 때 적합합니다. 예를 들어 사용자가 여러 파일을 업로드하고, 여러 단계의 분석을 이어가고, 중간 생성물을 다운로드해야 한다면 explicit mode가 낫습니다.
간단한 MVP라면 auto mode로 시작해도 됩니다. 하지만 유료 고객용 기능, 장시간 분석, 감사 로그가 필요한 업무 도구라면 explicit mode를 고려하세요. 어떤 컨테이너에 어떤 파일이 올라갔고, 어떤 응답에서 어떤 파일이 생성됐는지 서버가 알아야 장애 대응이 쉬워집니다.
문서 기준으로 Code Interpreter 컨테이너는 기본 1GB 외에 4GB, 16GB, 64GB 같은 memory_limit 선택지가 있습니다. 여기서 흔한 실수는 처음부터 큰 메모리로 올리는 것입니다. 큰 메모리는 비용이 증가하고, 제품이 처리할 수 있는 입력 크기에 대한 기대치도 같이 키웁니다.
운영에서는 입력 파일 크기와 작업 종류를 기준으로 tier를 나눠야 합니다.
중요한 것은 실패 메시지입니다. 메모리 부족이 발생했을 때 ‘다시 시도하세요’라고만 하면 사용자는 무엇을 줄여야 할지 모릅니다. 파일 크기, row 수, sheet 수, 이미지 해상도 같은 제한을 UI에 명시하고, 초과 시 업그레이드나 샘플링 옵션을 제공해야 합니다.
Code Interpreter 컨테이너는 사용하지 않으면 20분 후 만료됩니다. 만료된 컨테이너는 다시 active로 되돌릴 수 없고, 내부 데이터도 복구할 수 없습니다. 이 조건은 제품 UX에 직접 영향을 줍니다.
예를 들어 사용자가 30분 전에 업로드한 파일을 기반으로 “아까 그 분석 이어서 해줘”라고 요청하면 실패할 수 있습니다. 따라서 서버는 원본 파일을 자체 저장소에 보관하거나, 컨테이너 만료 전에 필요한 결과물을 회수해야 합니다. 문서에서도 컨테이너는 ephemeral로 취급하고 필요한 데이터는 자체 시스템에 저장하라고 권장합니다.
실무 설계는 다음 중 하나입니다.
사용자에게는 “분석 세션은 20분 동안 유지됩니다”처럼 명확히 알려주는 편이 좋습니다.
Code Interpreter는 모델 입력 파일을 컨테이너에 자동 업로드할 수 있고, 컨테이너 파일 API로 파일을 추가하거나 목록을 조회하고 다운로드할 수도 있습니다. 모델이 그래프나 CSV 같은 파일을 만들면 assistant message의 annotation에 container_id, file_id, filename이 붙습니다.
제품에서는 이 annotation을 그냥 화면에 출력하면 안 됩니다. 서버가 annotation을 파싱해서 다운로드 가능한 파일로 바꾸고, 권한 검사를 거친 뒤 사용자에게 링크를 제공해야 합니다. 특히 여러 사용자가 같은 서버를 쓰는 SaaS라면 file_id만으로 접근을 허용하면 안 됩니다. 반드시 사용자 id, 세션 id, 작업 id와 연결해 검증해야 합니다.
또한 생성 파일 이름도 정리해야 합니다. 모델이 만든 기본 filename은 사람이 읽기 어렵습니다. 사용자가 다운로드할 때는 sales-summary-2026-06.csv처럼 의미 있는 이름으로 바꿔주는 것이 좋습니다.
모델은 필요하다고 판단하면 python tool을 사용할 수 있지만, 제품 품질을 위해서는 도구 사용 조건을 명확히 적는 것이 좋습니다. 예를 들어 데이터 분석 제품이라면 다음 규칙을 system 또는 developer instruction에 넣을 수 있습니다.
계산, 통계, 파일 파싱, 그래프 생성이 필요한 경우 python tool을 사용한다.
파일 내용에 근거하지 않은 값을 만들지 않는다.
코드 실행 실패 시 원인을 요약하고 한 번 수정해 재실행한다.
생성 파일이 있으면 파일명과 용도를 짧게 설명한다.
이렇게 하면 모델이 텍스트로 대충 계산해 버리는 문제를 줄일 수 있습니다. 동시에 모든 요청에 무조건 도구를 쓰는 낭비도 줄어듭니다.
Code Interpreter 기반 기능은 장애가 생겼을 때 원인 파악이 어렵습니다. 모델 출력, 실행 코드, 컨테이너 상태, 파일 목록이 섞이기 때문입니다. 최소한 다음 항목은 서버 로그로 남기세요.
단, 원본 파일 내용과 민감한 데이터는 그대로 로그에 남기면 안 됩니다. 파일명, 크기, MIME type, row 수 같은 메타데이터 중심으로 기록하는 것이 안전합니다.
출처: OpenAI API Code Interpreter 문서, Containers API와 file input 안내.