11.3 파일 업로드, 검색, 함수 조합
Chapter 11.3 파일 업로드, 검색, 함수 조합 (Assistants API 심화 활용)
OpenAI의 Assistants API는 단순한 대화형 AI를 넘어서 복잡한 작업을 처리할 수 있도록 구성된 강력한 다기능 프레임워크입니다. 특히 파일 업로드 및 검색, 사용자 정의 함수(Function) 호출을 도와주는 Tool 기능까지 연계하면 챗봇에서 ‘업로드된 문서를 분석해 요약하고’, ‘데이터를 기반으로 추론하거나 계산을 수행하는’ 복합 워크로드를 처리하는 스마트 에이전트를 구현할 수 있습니다.
이 절에서는 다음 내용을 상세히 다룹니다:
Assistants API에서의 파일 처리 방식
검색 도구(Search Tool)의 작동 원리와 설정 방법
코드 실행 및 외부 함수 호출(Function Calling)과의 연계
파일 + 검색 + 함수 의 복합 조합을 통한 실제 사용 예시
11.3.1 Assistants API에서의 파일 처리 흐름
🧾 1. 전체 흐름
Assistants API에서 파일을 다루는 일반적인 과정은 다음과 같습니다:
사용자가 파일을 업로드 (createFile)
Assistant 또는 Thread에 파일을 첨부
Assistant의 Tool 설정에 따라 파일 기반 검색 또는 코드 실행 시 활용
응답 메시지에서 파일 정보를 포함하거나, 특정 파일을 재참조
예를 들어 PDF 문서를 업로드한 뒤 해당 문서를 기반으로 요약을 요청하거나, CSV 파일 데이터를 분석하는 요구를 처리할 수 있습니다.
📁 2. 파일 업로드 방법 (Python SDK)
import openai
# PDF 파일 업로드
file = openai.files.create(
file=open("sample-document.pdf", "rb"),
purpose="assistants"
)
print("Uploaded file ID:", file.id)목적(purpose)은 항상 "assistants"로 설정해야 합니다.
지원 파일 형식: PDF, TXT, CSV 등 텍스트 기반 형식을 우선 권장
📎 3. Assistant에 파일 연결하기
파일을 Assistant에 직접 붙이는 것이 아니라, Thread → Message 또는 Run 단계에서 파일을 첨부합니다.
ex) message와 함께 파일 첨부:
thread = openai.beta.threads.create()
message = openai.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="이 문서 내용을 요약해 주세요.",
file_ids=[file.id]
)11.3.2 Tool: 파일 검색(Search) 설정
파일을 단순히 전달하는 것뿐 아니라 문서에서 정보를 추출하거나 질의응답을 하려면 "search" 기능이 필요합니다. 이를 Assistants API에서는 built-in Tool로 제공합니다.
📡 1. Assistant 생성 시 Search Tool 활성화
assistant = openai.beta.assistants.create(
name="문서 분석 에이전트",
instructions="첨부 문서를 이해하고 관련 질문에 답변해 주세요.",
model="gpt-4-1106-preview",
tools=[{"type": "file_search"}]
)tools 에 "file_search"를 포함해야 Assistant가 업로드된 문서를 검색할 수 있습니다.
내부적으로 OpenAI가 관리하는 Indexing / Embedding / 벡터 검색이 활성화됨
🔍 2. 검색 기능 작동 방식
Assistant는 메시지와 연관된 파일 내부 내용을 자동으로 분석
질의의 의도를 파악해 문서 탐색을 수행하고, 적절한 정보를 추출해 응답에 반영합니다
단순 질의응답뿐 아니라 요약, 테이블 출력, 구간 요약 등 다양하게 활용 가능
11.3.3 Tool: 코드 실행(Code Interpreter, Advanced Data Analysis)
파일을 분석하는 과정이 정적 검색으로는 부족한 경우, 동적인 코드 실행(Calculator 또는 Python Code)을 통해 문서를 처리할 수 있습니다.
예: CSV, JSON 데이터를 프로그래밍으로 분석해야 할 때
🔧 1. 코드 실행 기능 활성화
assistant = openai.beta.assistants.create(
name="코드 분석 에이전트",
model="gpt-4-1106-preview",
tools=[
{"type": "code_interpreter"},
{"type": "file_search"}
],
instructions="파일 데이터를 분석하고 통계 요약을 제공하세요."
)코드 실행 환경에서 pandas, matplotlib 등 기본적인 Python 라이브러리를 사용할 수 있음
파일 분석 입력은 자동으로 Python 코드 내에서 처리됨
🔍 2. 예시: CSV 파일 분석 요약 요청
message = openai.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="첨부된 CSV 데이터를 요약해 주세요. 평균값과 최대값을 알려 주세요.",
file_ids=[csv_file.id]
)응답에서 Assistant는 파일을 읽고, pandas 등의 메서드로 분석한 뒤 표 형식으로 결과 제공
11.3.4 Tool: 사용자 정의 함수 (Function Calling)
Assistants API는 기존 Chat Completions API의 function calling과 달리 Tool 이름을 기반으로 등록합니다. 함수를 Tool로 추가한 뒤 Assistant가 필요 시 이를 호출할 수 있습니다.
🛠️ 1. Tool Function 정의 및 등록 (예: 날씨 함수)
tools = [
{
"type": "function",
"function": {
"name": "get_current_weather",
"description": "입력된 도시의 현재 날씨를 반환합니다.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"}
},
"required": ["location"]
}
}
}
]이렇게 Tool을 정의한 뒤 assistant 생성 시 포함:
assistant = openai.beta.assistants.create(
name="날씨 도우미",
instructions="사용자가 요청하면 날씨 정보를 조회하세요.",
model="gpt-4",
tools=tools
)메시지를 처리하면 Run이 생성되며, user 메시지로부터 해당 함수 호출이 트리거됩니다.
11.3.5 파일 + 검색 + 함수의 조합 사례
이제 위 기능들을 종합한 복합적인 사용 사례를 살펴보겠습니다.
📚 예: 기업 보고서 요약 및 KPI 자동 계산기
시나리오: 사용자가 분기별 실적 데이터(
report_Q1.csv)를 업로드 후 “이번 분기 총매출과 주요 KPI를 요약해줘" 라고 요청Assistant는 search + code_interpreter를 통해 default로 분석
값이 모호할 경우 외부 API 호출 (Function Calling)로 보충
assistant = openai.beta.assistants.create(
name="경영 보고서 요약기",
model="gpt-4-1106-preview",
instructions="보고서를 요약하고 KPI를 계산하세요.",
tools=[
{"type": "file_search"},
{"type": "code_interpreter"},
{
"type": "function",
"function": {
"name": "lookup_kpi_definition",
"description": "KPI 지표에 대한 정의 / 산식 반환",
"parameters": {
"type": "object",
"properties": {
"kpi_name": {"type": "string"}
},
"required": ["kpi_name"]
}
}
}
]
)이 Assistant는 다음과 같이 작동:
file_search: 문서 내용 전체 이해
code_interpreter: CSV 분석 → 통계 도출
function: KPI 기준이 애매하면 외부 정의 사전에서 보충 정보 요청
이처럼 Tool들을 조합하면, 처리 수단(검색, 분석, API 연동)을 자유롭게 설계하고 Assistant가 목적에 맞게 유기적으로 활용할 수 있습니다.
✅ 요약 정리
파일 업로드 (createFile)
PDF, CSV 등 파일을 업로드해 Assistant에 전달 가능
file_search Tool
문서 내용 검색/요약/질의응답 등 자동화 처리
code_interpreter Tool
Python 코드 실행 가능 (CSV 분석, 그래프 출력 등)
사용자 정의 함수(Function)
외부 API 연동, 계산기, 기준 정보 반환 등 목적 기반 호출
복합 조합 활용
문서를 분석하고 보충 정보를 외부로부터 가져오는 복합 Agent 구현 가능
이를 통해 Assistants API는 단순한 Chatbot이 아니라 문서 분석, 보고서 생성, 자동화된 API 기반 비서로 진화 가능성을 확인할 수 있습니다.
다음 절에서는 이러한 조합이 실제 애플리케이션(예: 고객 상담 시스템, 리서치 요약기)에 어떻게 통합되는지 실전 개발 사례를 통해 설명합니다.
Last updated