2025년 3월 11일 기준으로, 새로운 Agents 플랫폼의 구성 요소(빌딩 블록)를 공개했습니다. 자세한 내용은 Responses API에 대한 API 문서, Web Search, File Search, Computer Use를 포함한 Tools, 그리고 Agents SDK(Tracing 포함)를 참고해 주세요. Assistants API beta에 대한 여러분의 피드백을 바탕으로, Responses API에 핵심 개선 사항을 반영했습니다. 전체 기능 동등성(feature parity)을 달성한 뒤, 2026년 상반기를 목표 종료 시점으로 하여 올해 안에 Assistants API의 지원 종료(deprecation) 계획을 발표할 예정입니다.
Assistants API란 무엇인가요?
Assistants API를 사용하면 개발자가 앱 안에서 강력한 AI 어시스턴트를 쉽게 구축할 수 있습니다. 이 API는 대화 기록을 직접 관리할 필요를 없애고, Code Interpreter 및 File Search 같은 OpenAI 호스팅 도구에 대한 액세스를 제공합니다. 또한 서드파티 도구를 위한 개선된 함수 호출도 지원합니다.
Assistants API v1 beta를 계속 사용할 수 있나요?
아니요. 2024년 12월 18일부터 사용자는 Assistant API beta의 v1 버전에 더 이상 접근할 수 없습니다. 현재는 v2만 지원합니다. API 호출을 v1에서 v2로 전환하려면 이 마이그레이션 가이드를 확인해 주세요.
어떻게 접근하나요?
Assistants API는 OpenAI API 계정이 있는 누구나 사용할 수 있습니다. 또한 Assistants Playground를 통해 시작할 수도 있습니다.
Assistant란 무엇인가요?
Assistant는 OpenAI의 모델을 사용하고, 파일에 접근하며, 영구 스레드를 유지하고, 도구를 호출할 수 있는 목적 특화형 AI를 의미합니다.
Thread란 무엇인가요?
Thread는 Assistant와 사용자 간의 대화 세션입니다. Threads는 메시지 기록을 저장하고, 대화가 모델의 컨텍스트 길이에 비해 너무 길어지면 이를 잘라내어(truncate) 애플리케이션 개발을 단순화합니다.
File Search 도구란 무엇인가요?
file_search 도구는 파일에서 적절한 데이터를 추출해 모델의 응답을 보강할 수 있도록, 여러 검색(리트리벌) 모범 사례를 기본으로 제공합니다. 자세한 내용은 개발자 문서를 참고해 주세요.
기본적으로 file_search 도구는 다음 설정을 사용합니다:
청크 크기: 800 토큰
청크 오버랩: 400 토큰
임베딩 모델: 256차원에서
text-embedding-3-large컨텍스트에 추가되는 최대 청크 수: 20
파일 업로드 제한 사항은 무엇인가요?
파일 업로드 제한 사항은 다음과 같습니다:
파일당 512 MB
파일당 5M 토큰
벡터 스토어당 10k 파일
Assistant당 1개 벡터 스토어
Thread당 1개 벡터 스토어
조직 내 각 프로젝트의 전체 저장 한도는 100 GB입니다.
File Search 도구의 제한 사항은 무엇인가요?
향후 몇 달 내 지원을 추가하기 위해 작업 중인 알려진 제한 사항이 몇 가지 있습니다:
현재는 청킹, 임베딩 또는 리트리벌 설정을 수정할 방법이 없습니다.
문서 내 이미지 파싱을 지원하지 않습니다.
.csv 또는 .jsonl 같은 구조화된 파일 형식에 대한 리트리벌을 지원하지 않습니다. 지원되는 파일 유형을 참고하세요.
Assistants API의 레이트 리밋은 어떻게 되나요?
Assistants API의 레이트 리밋은 사용량 티어 및 모델에 연동되지 않습니다. 대신 요청 유형별 기본 한도가 있으며, 몇 가지 예외가 있습니다:
GET: 1000 RPM
POST: 300 RPM
/v1/threads/<thread_id>/runs로 POST: 200 RPM/v1/threads/runs로 POST: 200 RPM
DELETE: 분당 300건 요청
API에서 Code Interpreter 과금은 어떻게 되나요?
Code Interpreter는 세션당 $0.03로 과금됩니다. Assistant가 동시에 두 개의 서로 다른 스레드에서 Code Interpreter를 호출하면, Code Interpreter 세션이 2개 생성됩니다(2 * $0.03). 각 세션은 기본적으로 1시간 동안 활성 상태이며, 즉 사용자가 같은 스레드에서 최대 1시간 동안 Code Interpreter에 계속 지시를 내리는 경우 이 비용은 한 번만 청구됩니다.
API에서 File Search 과금은 어떻게 되나요?
File Search는 벡터 스토어 저장 용량 기준으로 하루 $0.10/GB로 과금됩니다(첫 1GB는 무료). 벡터 스토어의 크기는 파일이 파싱되고, 청킹되고, 임베딩된 이후 생성된 벡터 스토어의 결과 크기를 기준으로 합니다.
2024년 4월 17일 이전에 생성된 벡터 스토어는 2024년 말까지 무료이며, 이후에는 다음 중 하나로 처리됩니다:
2024년 4월 17일 이후에 생성된 Run에서 최소 1회라도 사용된 경우, 현재 요금(현재 $0.10/GB/일)으로 청구
2024년 4월 17일부터 2024년 12월 31일까지 단 한 번의 Run에서도 사용되지 않은 경우 삭제 — 이는 가격 변경이 공지되기 전에 생성했지만 사용하지 않은 벡터 스토어에 대해 과금되는 일을 방지하기 위함입니다.
생성할 수 있는 assistant 수에 제한이 있나요?
조직(org)이 생성할 수 있는 assistant 수에는 제한이 없습니다.
API에서 스트리밍을 사용할 수 있나요?
네, Assistants API에서 스트리밍을 사용할 수 있습니다.
Assistants API에서 JSON 모드를 사용할 수 있나요?
네, Assistants 또는 Run 객체의 response_format 파라미터를 통해 Assistants API에서 JSON 모드를 사용할 수 있습니다.
Assistants API가 서드파티 함수 호출 요청도 관리하나요?
아니요. 함수 호출을 통해 모델이 도구를 선택하고 해당 도구에 대한 요청 형식을 만들 수는 있지만, 서드파티 도구 호출의 실행은 OpenAI에서 관리하지 않습니다.
OpenAI로 보내는 데이터는 어떻게 처리되나요?
플랫폼의 다른 부분과 마찬가지로, OpenAI API에 전달되는 데이터와 파일은 모델 학습에 절대 사용되지 않으며, 필요할 때 언제든지 데이터를 삭제할 수 있습니다. Assistants API에 업로드된 데이터는 사용자가 수동으로 삭제하기 전까지 무기한 저장됩니다.
Assistants API를 통해 DALL-E를 사용할 수 있나요?
현재로서는 DALL-E를 사용할 수 없습니다.
Assistants API용 UI가 있나요?
Assistants API용 Playground를 확인해 보세요. 왼쪽 사이드바에서 Assistants 뷰에 있는지, 그리고 켜려는 도구(Tools)와 호환되는 모델을 사용하고 있는지 확인하세요.
Assistants API에서 assistant instructions의 문자 제한은 얼마인가요?
Assistant가 사용하는 시스템 지침(system instructions)의 최대 길이는 256,000자입니다.
“The server had an error while processing your request. Sorry about that! You can retry your request, or contact us through our help center at help.openai.com if the error persists. “ 같은 오류가 발생합니다. 어떻게 해야 하나요?
이 오류가 발생한다면, 프롬프트 설정이 올바르지 않다는 뜻일 수 있습니다. 요청을 계속 재시도해도 실패한다면, 다음을 시도해 보세요:
함수처럼 보이는 명령은 함수로 취급하도록 프롬프트를 재구성했는지 확인
프롬프트의 명령을
tools에 함수로 추가
왜 File Search 도구가 잘 작동하지 않나요?
File Search 도구를 사용할 때는 max_prompt_tokens를 최소 20,000 이상으로 설정하는 것을 권장합니다. 더 긴 대화나 File Search와의 여러 차례 상호작용이 있는 경우에는 이 한도를 50,000으로 늘리거나, 이상적으로는 최고 품질의 결과를 위해 max_prompt_tokens 제한을 아예 제거하는 것을 고려하세요. 자세한 내용은 여기에서 확인할 수 있습니다.
피드백은 어떻게 제공할 수 있나요?
개발자 포럼, help.openai.com의 도움말 센터, 또는 트위터 @OpenAIDevs를 통해 여러분의 피드백을 듣고 싶습니다.