OpenAI 어시스턴트의 작동 방식

How Assistants work

어시스턴트 API는 개발자들이 다양한 작업을 수행할 수 있는 AI 어시스턴트를 구축할 수 있도록 돕도록 설계되었습니다.

1. 어시스턴트는 특정 지침(instructions)을 사용하여 OpenAI의 모델을 호출하여 모델의 성격과 능력(personality and capabilities)을 조정할 수 있습니다.
2. 어시스턴트는 병렬로 여러 도구에 접근할 수 있습니다. 이는 OpenAI에서 호스팅하는 도구 — 예를 들어 코드 해석기 및 지식 검색 — 또는 여러분이 구축/호스팅하는 도구(함수 호출을 통해)일 수 있습니다.
3. 어시스턴트는 지속적인 스레드(persistent Threads)에 접근할 수 있습니다. 스레드는 메시지 기록을 저장하고 대화가 모델의 컨텍스트 길이를 넘어서게 될 때 메시지를 잘라냄으로써 AI 애플리케이션 개발을 단순화합니다. 한 번 스레드를 생성하면 사용자가 답장할 때마다 메시지를 스레드에 추가하게 됩니다.
4. 어시스턴트는 여러 형식의 파일에 접근할 수 있으며, 이는 어시스턴트 생성의 일부이거나 사용자와 어시스턴트 간의 스레드의 일부일 수 있습니다. 도구를 사용할 때, 어시스턴트는 파일(예: 이미지, 스프레드시트 등)을 생성하고 자신이 만든 메시지에서 참조하는 파일을 인용할 수도 있습니다.

이 API는 개발자가 인공지능 기반의 어시스턴트를 만들 수 있게 도와주는 도구로서, 현재 베타 단계에 있고 지속적으로 개선되고 있습니다. 사용자의 맞춤 설정이 가능하며, 다양한 도구에 동시에 접근할 수 있는 기능을 가지고 있습니다. 또한, 대화의 흐름을 관리하기 위한 ‘스레드’ 기능을 통해 메시지 기록을 저장하고 관리할 수 있습니다. 마지막으로, 어시스턴트는 파일을 생성하고 관리하는 기능을 포함하여 여러 형식의 파일에 접근할 수 있습니다. 이러한 기능들은 개발자가 사용자와의 상호작용을 더 효율적으로 관리할 수 있게 해줍니다.

Objects

어시스턴트 생성

최상의 결과와 도구와의 최대 호환성을 위해 어시스턴트 API와 함께 OpenAI의 최신 모델 사용을 권장합니다.

시작하려면 사용할 모델을 지정하여 어시스턴트를 생성하기만 하면 됩니다. 하지만 아래 목록처럼 어시스턴트의 행동을 더 세부적으로 사용자화할 수 있습니다:

1. ‘instructions’ 매개변수를 사용하여 어시스턴트의 성격을 안내하고 목표를 정의합니다. 이 지침은 챗 완성 API(Chat Completions API)의 시스템 메시지와 유사합니다.
2. ‘tools’ 매개변수를 사용하여 어시스턴트가 최대 128개의 도구에 접근할 수 있게 합니다. OpenAI가 호스팅하는 code_interpreter 및 retrieval 같은 도구에 접근을 허용하거나 함수 호출을 통해 제3자 도구를 호출할 수 있습니다.
3. ‘file_ids’ 매개변수를 사용하여 code_interpreter 및 retrieval 같은 도구가 파일에 접근할 수 있게 합니다. 파일은 파일 업로드 엔드포인트를 사용하여 업로드되며, 이 API와 함께 사용하기 위해서는 목적이 어시스턴트로 설정되어야 합니다.

예를 들어, .csv 파일을 기반으로 데이터 시각화를 생성할 수 있는 어시스턴트를 생성하려면, 먼저 파일을 업로드합니다.

file = client.files.create(
  file=open("data.csv", "rb"),
  purpose='assistants'
)

그리고 업로드된 파일을 사용하여 어시스턴트를 생성합니다.

assistant = client.beta.assistants.create(
  name="Data visualizer",
  description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",
  model="gpt-4-1106-preview",
  tools=[{"type": "code_interpreter"}],
  file_ids=[file.id]
)

어시스턴트당 최대 20개의 파일을 첨부할 수 있으며, 각 파일은 최대 512MB까지 가능합니다. 또한, 여러분의 조직에서 업로드하는 모든 파일의 크기는 100GB를 초과하지 않아야 합니다. 이 저장 한도를 증가시키고 싶다면, 도움말 센터를 사용하여 요청할 수 있습니다.

AssistantFile 객체를 사용하여 어시스턴트와 파일 객체 사이의 연결을 생성, 삭제 또는 조회할 수도 있습니다. 어시스턴트파일을 삭제한다고 해서 원본 파일 객체가 삭제되는 것은 아니며, 단지 해당 파일과 어시스턴트 사이의 연결만 삭제됩니다. 파일을 삭제하려면 파일 삭제 엔드포인트를 대신 사용하세요.

사용자는 OpenAI의 최신 모델을 사용하여 어시스턴트 API와의 호환성을 높일 수 있고, 명령어를 통해 어시스턴트의 성격과 목표를 지정할 수 있습니다. 또한, 다양한 도구에 대한 접근 권한을 설정하고, 필요한 파일을 업로드하여 도구가 사용할 수 있게 할 수 있습니다. 이 모든 것은 API를 통해 프로그래밍 방식으로 관리되며, 어시스턴트와 파일 사이의 연결을 관리하는 기능도 제공합니다.

스레드 및 메시지 관리

스레드와 메시지는 어시스턴트와 사용자 간의 대화 세션을 나타냅니다. 스레드에 저장할 수 있는 메시지의 수에는 제한이 없습니다. 메시지의 크기가 모델의 컨텍스트 창을 초과하면 스레드는 지능적으로 이를 적절히 잘라내어 맞춥니다. 다음과 같이 초기 메시지 목록으로 스레드를 생성할 수 있습니다:

thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "이 파일의 추세에 기반하여 3가지 데이터 시각화를 만들어주세요.",
      "file_ids": [file.id]
    }
  ]
)

메시지에는 텍스트, 이미지 또는 파일이 포함될 수 있습니다. 현재 사용자가 생성한 메시지에는 이미지 파일을 포함할 수 없지만, 향후 이 기능을 추가할 계획입니다.

요약하면 스레드는 대화 내용을 메시지 형태로 저장하며, 저장된 메시지의 양이 많아지더라도 모델이 처리할 수 있는 범위 내로 자동으로 내용을 조정합니다. 사용자는 스레드를 생성할 때 초기 메시지를 설정할 수 있으며, 메시지에는 텍스트 또는 파일을 포함할 수 있습니다. 이미지 파일을 포함하는 기능은 아직 지원되지 않지만, 미래에는 이 기능이 추가될 예정입니다.

메시지 주석(Message annotations)

어시스턴트가 생성한 메시지는 객체의 content 배열 내에 annotations을 포함할 수 있습니다. 주석은 메시지 텍스트에 어떻게 주석을 달아야 하는지에 대한 정보를 제공합니다.

주석에는 두 가지 유형이 있습니다:

1. file_citation: 파일 인용은 retrieval 도구에 의해 생성되며, 어시스턴트가 응답을 생성하는 데 사용한 특정 파일 내의 특정 인용문에 대한 참조를 정의합니다.
2. file_path: 파일 경로 주석은 code_interpreter  도구에 의해 생성되며, 도구에 의해 생성된 파일에 대한 참조를 포함합니다.

메시지 객체 안에 주석이 있으면, 주석으로 교체해야 할 모델이 생성한 읽기 어려운 부분 문자열을 텍스트에서 볼 수 있습니다. 이러한 문자열은 ​​ 또는 sandbox:/mnt/data/file.csv 같은 형태로 보일 수 있습니다.

# 메시지 객체 검색
message = client.beta.threads.messages.retrieve(
  thread_id="...",
  message_id="..."
)

# 메시지 내용 추출
message_content = message.content[0].text
annotations = message_content.annotations
citations = []

# 주석을 순회하면서 각주 추가
for index, annotation in enumerate(annotations):
    # 텍스트를 각주로 교체
    message_content.value = message_content.value.replace(annotation.text, f' [{index}]')

    # 주석 속성을 기반으로 인용문 수집
    if (file_citation := getattr(annotation, 'file_citation', None)):
        cited_file = client.files.retrieve(file_citation.file_id)
        citations.append(f'[{index}] {file_citation.quote} from {cited_file.filename}')
    elif (file_path := getattr(annotation, 'file_path', None)):
        cited_file = client.files.retrieve(file_path.file_id)
        citations.append(f'[{index}] Click <here> to download {cited_file.filename}')
        # 참고: 위 코드에서는 간결성을 위해 파일 다운로드 기능이 구현되지 않았습니다.

# 사용자에게 표시하기 전에 메시지 끝에 각주 추가
message_content.value += '\n' + '\n'.join(citations)

주석은 메시지 내용의 특정 부분을 문서 내 다른 부분이나 생성된 파일에 대한 참조로 대체해야 할 때 사용됩니다. ‘file_citation’과 ‘file_path’ 두 가지 유형의 주석이 있으며, 이를 통해 응답 내용과 관련된 자료나 파일을 명확하게 참조할 수 있습니다. 주석이 포함된 메시지를 처리할 때는 코드를 통해 주석에 해당하는 문자열을 식별하고 해당 정보로 교체하여 사용자에게 보여주는 과정을 포함합니다.

실행과 실행 단계(Runs and Run Steps)

사용자로부터 필요한 모든 컨텍스트를 스레드에 담았다면, 선택한 어시스턴트로 스레드를 실행할 수 있습니다.

run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id
)

기본적으로 실행은 어시스턴트 객체에 지정된 모델과 도구 설정을 사용하지만, 더욱 유연하게 대응하기 위해 실행 생성 시 대부분의 설정을 재정의할 수 있습니다:

run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id,
  model="gpt-4-1106-preview",
  instructions="추가 지침",
  tools=[{"type": "code_interpreter"}, {"type": "retrieval"}]
)

참고: 실행 생성 중에 어시스턴트와 연관된 file_ids는 재정의할 수 없습니다. 이를 위해서는 어시스턴트 수정(modify Assistant ) 엔드포인트를 사용해야 합니다.

요약하면 실행은 기본적으로 어시스턴트에 설정된 모델과 도구를 사용하지만, 실행을 생성할 때 이러한 설정의 대부분을 재정의할 수 있어 사용자가 필요에 따라 유연하게 설정을 조정할 수 있음을 나타냅니다. 그러나 실행 중에는 어시스턴트에 연결된 파일 ID를 변경할 수 없으며, 이를 변경하려면 어시스턴트를 수정하는 별도의 절차를 거쳐야 한다는 점에 유의해야 합니다.

실행 생명주기

실행 객체는 여러 상태를 가질 수 있습니다.

업데이트에 대한 폴링

실행 상태를 최신 상태로 유지하려면 주기적으로 Run(retrieve the Run ) 객체를 검색해야 합니다. 객체를 검색할 때마다 실행 상태를 확인하여 애플리케이션이 다음에 무엇을 해야 할지 결정할 수 있습니다. 우리는 이를 더 간단하게 만들기 위해 스트리밍에 대한 지원을 가까운 미래에 추가할 계획입니다.

스레드 잠금

실행이 진행 중이고 종료 상태가 아닐 때, 스레드는 잠깁니다. 이는 다음을 의미합니다:

• 스레드에 새로운 메시지를 추가할 수 없습니다.
• 스레드에 새로운 실행을 생성할 수 없습니다.

실행 단계

실행 단계 상태는 실행 상태와 동일한 의미를 가집니다.

실행 단계 객체에서 가장 흥미로운 세부 정보는 step_details 필드에 있습니다. 실행 단계 세부 정보에는 두 가지 유형이 있을 수 있습니다:

• message_creation: 이 실행 단계는 어시스턴트가 스레드에 메시지를 생성할 때 생성됩니다.
• tool_calls: 이 실행 단계는 어시스턴트가 도구를 호출할 때 생성됩니다. 이에 대한 자세한 내용은 Tools 가이드의 관련 섹션에서 다룹니다.

제한 사항

이 베타 기간 동안, 우리는 몇 주에서 몇 달 안에 해결하고자 하는 몇 가지 알려진 제한 사항들이 있습니다. 추가 기능에 대한 지원을 추가할 때 이 페이지에 변경 사항을 게시할 예정입니다.

• 메시지 및 실행 단계를 포함한 스트리밍 출력에 대한 지원.
• 폴링 없이 객체 상태 업데이트를 공유할 수 있는 알림 지원.
• 도구로서의 DALL·E 지원.
• 이미지를 포함한 사용자 메시지 생성 지원.