11.2 코드 실행(Code Interpreter) 연동
Chapter 11.2 코드 실행(Code Interpreter) 연동
OpenAI Assistants API의 핵심 기능 중 하나는 바로 Tool 기능입니다. 이 중 Code Interpreter는 많은 사용자에게 잘 알려진 ChatGPT의 “Advanced Data Analysis(구 Advanced Code Interpreter)” 기능과 같은 것으로, 자연어 명령을 해석하여 Python 코드를 실행하고, 그 결과를 다시 대화로 이어가는 형식의 강력한 도구입니다. 이 절에서는 Assistants API에서 Code Interpreter를 연동하고 활용하는 방법을 실습과 함께 알아봅니다.
11.2.1 Code Interpreter란?
Code Interpreter는 안전한 샌드박스 환경에서 사용자 명령에 따라 Python 코드를 생성하고 실행하며 결과를 Markdown 또는 자연어로 요약해 주는 도구입니다. 주요 특징은 다음과 같습니다:
Python 언어 지원
Numpy, Pandas, Matplotlib 등 주요 라이브러리 내장
CSV, JSON, 이미지 등 다양한 파일 형식 분석 가능
그래프 시각화 자동 처리
자연어로 데이터 이해 및 피봇팅 가능
OpenAI Assistant API에서는 해당 기능을 tool로 활성화시켜 사용할 수 있으며, 파일 업로드와 함께 사용하면 더욱 강력한 데이터 분석 기능을 발휘할 수 있습니다.
11.2.2 Code Interpreter 활성화하기
Code Interpreter는 Assistants API에서 tools 매개변수에 "code_interpreter"를 포함하여 활성화합니다. 먼저 Assistant를 생성할 때 다음과 같이 설정합니다.
📌 Python 예시:
from openai import OpenAI
client = OpenAI()
assistant = client.beta.assistants.create(
name="Data Analyst",
instructions="업로드된 데이터를 분석하고 요약해 주세요.",
model="gpt-4-1106-preview",
tools=[{"type": "code_interpreter"}]
)여기서 tools 필드에 {"type": "code_interpreter"} 항목을 추가함으로써 해당 Assistant는 코드 실행이 가능한 환경을 가집니다.
11.2.3 Code Interpreter 사용 흐름
Code Interpreter의 사용 흐름은 일반적인 Assistants API 호출 흐름과 유사하지만, 파일 연동과 코드 실행 결과 반환이 중요하게 작동합니다. 기본 흐름은 다음과 같습니다:
Assistant 생성 (tools에 code_interpreter 포함)
Thread 생성
파일 업로드 (선택 사항)
메시지 추가 (문자열로 질문)
Run 실행
Run 상태(pending, in_progress, completed) 모니터링
결과 메시지 확인 (코드 실행 결과 포함)
아래 예시는 CSV 파일을 업로드하고, 특정 질문을 던지며 Assistant가 이를 코드로 해석해 분석 응답을 하는 전형적인 워크플로입니다.
11.2.4 파일 업로드 및 연결
Code Interpreter와 함께 가장 자주 사용되는 기능 중 하나는 파일 업로드입니다. 예를 들어 데이터를 담은 CSV 파일을 분석 대상으로 첨부하려면 다음과 같이 파일을 업로드하고 메시지에 연결합니다.
📌 파일 업로드 예시:
# CSV 파일 업로드
file = client.files.create(
file=open("sales_data.csv", "rb"),
purpose="assistants"
)파일 업로드 이후, 메시지를 보낼 때 file_id를 함께 전달하여 Assistant가 해당 데이터를 코드 해석에 참조하게 할 수 있습니다.
📌 메시지 추가 예시 (파일 연결 포함):
thread = client.beta.threads.create()
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="이 데이터에서 월별 평균 판매량을 계산해줘.",
file_ids=[file.id]
)이후 run을 실행하면서 실제 코드 실행이 시작됩니다.
📌 Run 생성:
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id
)11.2.5 코드 실행 및 결과 확인
실행 이후 run 상태를 체크하며 최종 완료될 때까지 대기해야 합니다. 일반적으로 다음처럼 polling 방식으로 진행합니다.
📌 Run 상태 확인:
import time
while True:
run_status = client.beta.threads.runs.retrieve(
thread_id=thread.id,
run_id=run.id
)
if run_status.status in ["completed", "failed"]:
break
time.sleep(1)📌 실행 결과 확인:
messages = client.beta.threads.messages.list(thread_id=thread.id)
for msg in messages.data:
print(msg.role + ":", msg.content[0].text.value)여기서 출력되는 assistant의 응답에는 분석 결과 또는 시각화 내용이 Markdown 형태로 포함될 수 있으며, 이미지 출력도 가능합니다. 예를 들어 matplotlib를 통해 생성된 그래프가 이미지 base64 형태로 포함될 수 있습니다.
11.2.6 복수 파일 처리 및 고급 질문 예시
❖ 여러 개의 파일을 업로드하고 종합 분석 요청하기:
file1 = client.files.create(file=open("2022_sales.csv", "rb"), purpose="assistants")
file2 = client.files.create(file=open("2023_sales.csv", "rb"), purpose="assistants")
msg = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="두 파일의 월별 평균 매출을 비교해 차트를 보여줘.",
file_ids=[file1.id, file2.id]
)❖ 복잡한 데이터 변환 요구:
" 고객별 총 구매금액을 집계해 1위를 알려주고, 구매 추이도 그래프로 보여줘."
이 경우 Assistant는 다음과 같은 단계를 수행합니다:
Pandas로 읽기 → 그룹화(groupby) → 합계 계산
최대값 추출 → 시각화 (Matplotlib)
Markdown 응답으로 요약 + 그래프 이미지 포함
11.2.7 오류 처리 및 디버깅 팁
파일 크기 제한은 현재 약 500MB, 너무 크면 오류 발생
업로드한 파일은 메시지에 명확히 file_ids로 연결해야 함
Assistant instructions에 데이터 형식, 언어, 분석 목적 등을 구체적으로 기재하면 분석 정밀도 향상
run 실패 시 run.status를 확인하면 오류 유형을 분석 가능 ("failed" 상태에서 error.message 확인)
11.2.8 Code Interpreter 기능 제약 및 주의사항
외부 API 호출
불가능 (HTTP 요청 제한됨)
파일 저장
가능하나 유저 접근은 제한적
실행 시간
복잡한 분석은 타임아웃 발생 가능성
보안
업로드된 파일은 OpenAI 서버 내 임시 저장됨
또한, Assistant 세션별로 상태를 유지하므로 연속적인 분석 흐름을 설계할 수 있습니다. 단, 각 분석단계가 독입적으로 수행되므로 명확한 연결 지시가 필요합니다.
11.2.9 실전 예제: 시각화 포함 데이터 분석 챗봇
전처리 & 시각화를 포함한 인사이트 챗봇 구성
분석 유형: 분포 분석, 이상치 탐지, 추세 추정, 상관계수 계산 등
사용 기술: Assistant API + Code Interpreter + file_ids 리플레이스
📌 전체 워크플로 예시 코드는 다음과 같습니다:
# 어시스턴트 생성
assistant = client.beta.assistants.create(
name="CSV Insight Bot",
instructions="CSV 데이터를 분석하고 시각화된 결과를 제공합니다.",
model="gpt-4-1106-preview",
tools=[{"type": "code_interpreter"}]
)
# Thread 생성
thread = client.beta.threads.create()
# 데이터 파일 업로드
file = client.files.create(
file=open("dataset.csv", "rb"),
purpose="assistants"
)
# 질문 메시지 추가
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="이 데이터에서 상관관계를 분석하고 scatter plot으로 보여줘.",
file_ids=[file.id]
)
# 실행
run = client.beta.threads.runs.create(
thread_id=thread.id,
assistant_id=assistant.id
)
# Run 상태 확인 및 결과 출력
while True:
run_status = client.beta.threads.runs.retrieve(
thread_id=thread.id,
run_id=run.id
)
if run_status.status == "completed":
break
elif run_status.status == "failed":
print("오류 발생:", run_status.last_error)
break
time.sleep(1)
messages = client.beta.threads.messages.list(thread_id=thread.id)
for msg in messages.data:
print(msg.role + ":", msg.content[0].text.value)11.2.10 정리 및 다음 스텝
Code Interpreter 도구는 OpenAI Assistants API의 주요 파워 기능입니다. 단순 대화형 Agent를 넘어서 실질적인 데이터 분석 업무를 자동화하거나 CSV 기반 레포트 생성기를 구현하는 데 매우 적합합니다. 향후 Chapters에서는 Code Interpreter뿐 아니라 Search, Function Call과 조합된 멀티 툴 기반의 고도화된 에이전트 설계로 확장하게 됩니다.
➡︎ 다음 절에서는 파일 업로드 + 검색 + 코드 실행을 함께 활용하는 복합 Tool 조합 예제를 다룹니다.
Last updated