코드 인터프리터

코드 인터프리터 (Code Interpreter)

Code Interpreter 도구는 모델이 샌드박스 환경에서 Python 코드를 작성·실행해 데이터 분석, 코딩, 수학 같은 도메인의 복잡한 문제를 풀게 해줘요. 다음 용도에 쓰세요.

다양한 데이터와 형식의 파일 처리
데이터와 그래프 이미지가 있는 파일 생성
코드를 반복적으로 작성·실행해 문제 해결 — 예를 들어 실행에 실패하는 코드를 쓴 모델이 성공할 때까지 다시 쓰고 실행할 수 있어요
최신 reasoning 모델(예: o3, o4-mini)의 시각 지능 강화. 모델이 이 도구로 이미지를 자르고·확대하고·회전시키고·다르게 처리·변환할 수 있어요.

출처: 문서

본문

Responses API에 Code Interpreter 도구 호출을 하는 예시예요.

from openai import OpenAI

client = OpenAI()

instructions = """
You are a personal math tutor. When asked a math question,
write and run code using the python tool to answer the question.
"""

resp = client.responses.create(
    model="gpt-6-astra",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto", "memory_limit": "4g"},
        }
    ],
    instructions=instructions,
    input="I need to solve the equation 3x + 11 = 14. Can you help me?",
)

print(resp.output)

이 도구를 Code Interpreter라고 부르지만 모델은 이걸 "python tool"로 알아요. 모델은 보통 코드 인터프리터 도구를 언급하는 프롬프트를 이해하지만, 가장 명시적인 호출 방법은 프롬프트에서 "the python tool"을 요청하는 거예요.

컨테이너

Code Interpreter 도구는 컨테이너 객체가 필요해요. 컨테이너는 모델이 Python 코드를 실행할 수 있는 완전히 샌드박스된 가상 머신이에요. 업로드하거나 생성한 파일을 담을 수 있어요.

응답 output에서 type: "code_interpreter_call" 항목으로 모델이 Python 코드 블록을 실행하기 위해 호출한 것을 확인할 수 있어요. 이 항목의 call_id는 나중에 code_interpreter_call_output로 실행 결과를 반환할 때 사용해요.

만료 (Expiration)

컨테이너는 일시적(ephemeral)으로 취급하고 이 도구 사용과 관련된 모든 데이터는 자체 시스템에 저장하는 것을 강력히 권장해요.

컨테이너는 20분 동안 사용되지 않으면 만료돼요. 그러면 v1/responses에서 그 컨테이너를 쓰는 것이 실패해요. 만료 시점에 컨테이너 메타데이터의 스냅샷은 여전히 볼 수 있지만, 컨테이너와 연결된 모든 데이터는 시스템에서 폐기되고 복구할 수 없어요. 컨테이너가 활성인 동안 필요한 파일을 다운로드하세요.
만료된 컨테이너를 활성 상태로 되돌릴 수 없어요. 대신 새 컨테이너를 만들고 파일을 다시 업로드하세요. 이전 컨테이너 메모리의 상태(예: python 객체)는 손실된다는 점에 유의하세요.
컨테이너 조회, 파일 추가·삭제 같은 어떤 컨테이너 연산도 컨테이너의 last_active_at 시간을 자동으로 갱신해요.

파일 다루기

Code Interpreter를 실행할 때 모델이 자체 파일을 만들 수 있어요. 예를 들어 플롯을 만들거나 CSV를 만들라고 하면 이 이미지를 컨테이너에 직접 만들어요. 그럴 때 다음 메시지의 annotations에서 이 파일을 인용해요.

모델이 생성한 파일·이미지는 어시스턴트 메시지의 어노테이션으로 반환돼요. container_file_citation 어노테이션은 컨테이너에서 생성된 파일을 가리키고, container_id, file_id, filename을 포함해요. 이 어노테이션을 파싱해 다운로드 링크를 표시하거나 파일을 처리할 수 있어요. 생성된 파일은 get container file content 메서드로 다운로드할 수 있어요. 모델 입력의 파일은 자동으로 컨테이너에 업로드돼요. 명시적으로 업로드할 필요가 없어요.

파일 업로드·다운로드

Create container file로 컨테이너에 새 파일을 추가해요. 이 엔드포인트는 multipart 업로드나 file_id가 있는 JSON 본문을 받아요. List container files로 기존 컨테이너 파일을 나열하고, Retrieve container file content로 바이트를 다운로드해요.

지원되는 파일

.c, .cs, .cpp, .csv, .doc, .docx, .html, .java, .json, .md, .pdf, .php, .pptx, .py, .rb, .tex, .txt, .css, .js, .sh, .ts, .jpeg, .jpg, .gif, .pkl, .png, .tar, .xlsx, .xml, .zip 형식을 지원해요.

사용 메모

Code Interpreter는 Responses, Chat Completions, Assistants API에서 사용할 수 있고, 조직당 100 RPM rate limit이 있어요. 자세한 내용은 Pricing과 ZDR and data residency를 참고하세요.

코드 인터프리터