어시스턴트 API는 여러분의 애플리케이션 내에서 AI 어시스턴트를 구축할 수 있게 해줍니다. 어시스턴트는 지시사항을 가지고 있으며, 모델, 도구, 지식을 활용하여 사용자의 질문에 답변할 수 있습니다. 현재 어시스턴트 API는 세 가지 유형의 도구를 지원합니다: 코드 해석기, 검색, 함수 호출. 미래에는 더 많은 OpenAI 제작 도구를 출시하고, 여러분이 우리 플랫폼에서 여러분의 도구를 제공할 수 있도록 할 계획입니다.
고수준에서, 어시스턴트 API의 전형적인 통합 흐름은 다음과 같습니다:
- API에서 어시스턴트를 생성하여 맞춤 지시사항을 정의하고 모델을 선택합니다. 도움이 된다면 코드 해석기, 검색, 함수 호출과 같은 도구를 활성화하세요.
- 사용자가 대화를 시작할 때 스레드를 생성합니다.
- 사용자가 질문을 하면 스레드에 메시지를 추가합니다.
- 스레드에서 어시스턴트를 실행하여 응답을 받을 수 있습니다. 이것은 자동으로 관련 도구를 호출합니다.
어시스턴트 API는 베타 버전이며, 더 많은 기능을 추가하는 것에 적극적으로 작업 중입니다. 개발자 포럼에서 여러분의 피드백을 공유해주세요!
이 시작 가이드는 코드 해석기를 사용하는 어시스턴트를 생성하고 실행하는 주요 단계를 안내합니다.
1단계: 어시스턴트 생성
어시스턴트는 사용자의 메시지에 반응하기 위해 다음과 같은 여러 매개변수를 사용하여 설정될 수 있는 엔티티를 나타냅니다:
- 지시사항: 어시스턴트와 모델이 어떻게 행동하거나 반응해야 하는지
- 모델: GPT-3.5 또는 GPT-4 모델을 지정할 수 있으며, 튜닝된 모델도 포함됩니다. 검색 도구는 gpt-3.5-turbo-1106 및 gpt-4-1106-preview 모델을 필요로 합니다.
- 도구: API는 OpenAI에 의해 구축되고 호스팅되는 코드 해석기와 검색을 지원합니다.
- 함수: API는 우리의 함수 호출 기능과 유사한 동작으로 사용자 정의 함수 시그니처를 정의할 수 있게 합니다.
이 예에서, 우리는 코드 해석기 도구가 활성화된 개인 수학 튜터로서 어시스턴트를 생성하고 있습니다:
어시스턴트 API 호출은 베타 헤더를 전달해야 합니다. OpenAI의 공식 파이썬 및 Node.js SDK를 사용하는 경우 이는 자동으로 처리됩니다.
OpenAI-Beta: assistants=v1
assistant = client.beta.assistants.create(
name="Math Tutor",
instructions="You are a personal math tutor. Write and run code to answer math questions.",
tools=[{"type": "code_interpreter"}],
model="gpt-4-1106-preview"
)
위 코드는 어시스턴트 API를 통해 개인 수학 튜터 어시스턴트를 생성하는 과정을 보여줍니다. 이 과정에서, 사용자가 수학 문제에 대한 답변을 작성하고 실행할 수 있도록 “수학 튜터”라는 이름과 함께 구체적인 지시사항이 설정됩니다. 또한, 코드를 해석하고 실행하는 ‘code_interpreter’ 도구를 활성화하여, 어시스턴트가 프로그래밍 코드를 이해하고 사용자가 제기한 수학 문제를 해결할 수 있도록 합니다. 선택한 모델은 ‘gpt-4-1106-preview’로, 이는 사용자의 요청에 따라 수학 문제를 해결하는 데 필요한 능력을 갖춘 최신 AI 모델 중 하나입니다.
2단계: 스레드 생성
스레드는 대화를 나타냅니다. 사용자가 대화를 시작하는 즉시 사용자마다 스레드를 하나씩 생성하는 것이 좋습니다. 이 스레드에서 사용자 특정 컨텍스트와 파일을 패스하여 메시지를 생성하여 전달하세요.
thread = client.beta.threads.create()
스레드는 크기 제한이 없습니다. 원하는 만큼 많은 메시지를 스레드에 전달할 수 있습니다. API는 모델로의 요청이 최대 컨텍스트 윈도우 내에 들어맞도록, 절단(truncation, 청킹?)과 같은 관련 최적화 기법을 사용하여 보장할 것입니다.
위의 파이썬 코드는 사용자와의 대화를 관리하기 위한 스레드를 생성하는 과정을 나타냅니다. 대화를 나타내는 스레드는 사용자마다 개별적으로 만들어져야 하며, 사용자가 대화를 시작할 때 바로 생성됩니다. 이렇게 함으로써, 사용자별 맥락과 파일 등을 대화에 포함시킬 수 있습니다. 이 스레드에 메시지를 추가함으로써, 사용자가 제공한 정보를 기반으로 어시스턴트가 효과적으로 반응할 수 있습니다. 스레드에는 크기 제한이 없으며, 원하는 만큼 많은 메시지를 추가할 수 있습니다. 이는 대화가 길어지더라도 모든 정보가 적절히 관리되고 최적화될 수 있음을 의미합니다. OpenAI API는 최대 컨텍스트 윈도우를 초과하지 않도록 요청을 관리하며, 필요한 경우 내용을 적절히 절단하는 기법을 사용하여 정보가 손실되지 않도록 합니다.
3단계: 스레드에 메시지 추가
메시지는 사용자의 텍스트를 포함하며, 선택적으로 사용자가 업로드하는 파일도 포함할 수 있습니다. 현재 이미지 파일은 지원되지 않지만, 향후 몇 달 내에 지원을 추가할 계획입니다.
message = client.beta.threads.messages.create(
thread_id=thread.id,
role="user",
content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)
이제 스레드에서 메시지를 나열하면, 이 메시지가 생성 시 스레드에 추가된 것을 볼 수 있습니다:
{
"object": "list",
"data": [
{
"created_at": 1696995451,
"id": "msg_4rb1Skx3XgQZEe4PHVRFQhr0",
"object": "thread.message",
"thread_id": "thread_34p0sfdas0823smfv",
"role": "user",
"content": [{
"type": "text",
"text": {
"value": "I need to solve the equation `3x + 11 = 14`. Can you help me?",
"annotations": []
}
}],
...
}
]
}
이 단계에서는 사용자의 입력을 스레드에 메시지로 추가하는 방법을 보여줍니다. 사용자가 “3x + 11 = 14” 방정식을 풀고 싶다는 내용의 메시지를 스레드에 추가하여, 어시스턴트가 이에 대한 해결책을 제공할 수 있도록 합니다. 현재 API는 텍스트 입력만을 지원하지만, 이미지 파일은 아직 지원하지 않습니다. 그러나 이미지 파일 지원은 향후 몇 달 내에 추가될 예정입니다. 이 메시지는 JSON 형태로 나열되어, 생성된 시간, 메시지 ID, 스레드 ID, 역할 및 내용 등을 포함하고 있습니다. 이 정보는 어시스턴트가 사용자의 요청에 대한 컨텍스트를 이해하고 적절히 반응하는 데 사용됩니다.
4단계: 어시스턴트 실행
사용자 메시지에 대한 답변을 위해 어시스턴트를 실행하려면 ‘Run’을 생성해야 합니다. 이를 통해 어시스턴트는 스레드를 읽고 도구를 호출할지 또는 사용자 쿼리에 가장 잘 답변하기 위해 모델만 사용할지 결정합니다. 실행이 진행됨에 따라 어시스턴트는 “assistant” 역할(role=”assistant”)로 스레드에 메시지를 추가합니다.
Run을 생성할 때 추가적인 지시사항을 어시스턴트에게 선택적으로 전달할 수 있습니다:
run = client.beta.threads.runs.create( thread_id=thread.id, assistant_id=assistant.id, instructions="Please address the user as Jane Doe. The user has a premium account." )
이 코드는 어시스턴트가 사용자의 대화 스레드를 읽고 적절한 응답을 제공하기 위해 ‘Run’을 생성하는 과정을 보여줍니다. 어시스턴트는 이 ‘Run’을 통해 사용자의 메시지를 분석하고, 사용자의 질문에 대해 도구를 활용하거나 AI 모델로 직접 응답을 결정합니다. ‘Run’이 진행됨에 따라, 어시스턴트는 자동으로 “assistant” 역할로 스레드에 메시지를 추가하여 대화에 응답합니다.
추가적으로, ‘Run’을 생성할 때 어시스턴트에게 추가 지시사항을 제공할 수 있습니다. 예를 들어, 사용자를 ‘Jane Doe’라고 호칭하도록 지시하거나 사용자가 프리미엄 계정을 가지고 있음을 알려줌으로써, 어시스턴트가 더 개인화된 서비스를 제공하도록 할 수 있습니다. 이러한 지시사항은 어시스턴트가 사용자에게 보다 맞춤화된 경험을 제공하는 데 도움이 됩니다.
5단계: 어시스턴트의 응답 표시
이 단계에서는 대기(queued) 상태인 ‘Run’을 생성합니다. ‘Run’의 상태를 주기적으로 검색하여 완료(completed)로 변경되었는지 확인할 수 있습니다.
run = client.beta.threads.runs.retrieve( thread_id=thread.id, run_id=run.id )
‘Run’이 완료되면, 어시스턴트가 스레드에 추가한 메시지를 검색할 수 있습니다.
messages = client.beta.threads.messages.list( thread_id=thread.id )
그리고 마지막으로, 이 메시지들을 사용자에게 표시합니다! 이 ‘Run’ 동안, 어시스턴트는 스레드에 두 개의 새로운 메시지를 추가했습니다.
| 역할 | 내용 |
| user | 방정식 3x + 11 = 14를 풀어야 해요. 도와주실 수 있나요? |
| assistant | 물론이죠, Jane Doe님. 방정식 (3x + 11 = 14)에서 (x)를 풀기 위해서는, (x)를 방정식의 한쪽으로 분리하고 싶을 겁니다. 다음과 같이 할 수 있어요: 방정식 양쪽에서 11을 빼서 (3x = 3)을 얻습니다. 그 다음, 양쪽을 3으로 나누어 (x)를 풉니다. (x)의 값을 계산해 드릴게요. |
| assistant | 방정식 (3x + 11 = 14)의 해는 (x = 1)입니다. |
이 단계에서는 ‘Run’의 상태를 주기적으로 확인하여 어시스턴트가 사용자의 메시지에 대한 응답을 완료했는지 확인하는 과정입니다. ‘Run’이 완료되면, API를 통해 어시스턴트가 추가한 메시지들을 검색하고 이를 사용자에게 표시합니다. 이 과정에서 어시스턴트는 사용자의 요청에 대해 단계별로 해설을 더한 후 최종 답변을 제공합니다. 어시스턴트는 사용자에게 논리적인 계산 과정을 설명하고, 최종적으로 방정식의 해를 제시합니다. 필요한 경우, ‘Run Steps’를 검색하여 어시스턴트가 사용자의 질문을 처리하는 내부 과정을 보다 상세히 확인할 수도 있습니다. 이를 통해 어시스턴트의 동작 방식을 이해하거나 문제 해결 과정을 사용자에게 보다 투명하게 보여줄 수 있습니다.
