다음을 통해 공유

도우미 API(미리 보기) 참조

  • 아티클

참고 항목

  • 파일 검색은 도우미당 최대 10,000개의 파일을 수집할 수 있으며, 이는 이전보다 500배 이상 높은 수치입니다. 빠르고 다중 스레드 검색을 통해 병렬 쿼리를 지원하며 향상된 순위 재지정 및 쿼리 다시 쓰기 기능을 제공합니다.
    • 벡터 저장소는 API의 새 개체입니다. 파일이 벡터 저장소에 추가되면 자동으로 구문 분석, 청크 분할, 포함되어 검색할 수 있는 상태가 됩니다. 벡터 저장소는 도우미와 스레드에서 사용할 수 있으므로 파일 관리 및 청구를 간소화합니다.
  • 특정 실행에서 특정 도구(예: 파일 검색, 코드 인터프리터, 함수)를 강제로 사용하는 데 사용할 수 있는 tool_choice 매개 변수에 대한 지원이 추가되었습니다.

이 문서에서는 새 도우미 API(미리 보기)에 대한 Python 및 REST에 대한 참조 설명서를 제공합니다. 더 자세한 단계별 지침은 시작 지침에서 제공됩니다.

도우미 만들기

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

모델과 지침이 포함된 도우미를 만듭니다.

요청 본문

이름 Type 필수 설명
model string Required 사용할 모델의 모델 배포 이름입니다.
name 문자열 또는 null 선택 사항 도우미의 이름입니다. 최대 길이는 256자입니다.
description 문자열 또는 null 선택 사항 도우미에 대한 설명입니다. 최대 길이는 512자입니다.
지침 문자열 또는 null 선택 사항 도우미가 사용하는 시스템 지침입니다. 최대 길이는 256,000자입니다.
tools 배열 선택 사항 기본값은 []입니다. 도우미에서 사용하도록 설정된 도구 목록입니다. 도우미당 최대 128개의 도구가 있을 수 있습니다. 도구는 현재 code_interpreter 또는 function 형식일 수 있습니다. function 설명은 최대 1,024자까지 쓸 수 있습니다.
metadata map 선택 사항 개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.
온도 숫자 또는 null 선택 사항 기본값은 1입니다. 사용할 샘플링 온도를 0과 2 사이에서 결정합니다. 0.8과 같이 값이 높을수록 출력이 더욱 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다.
top_p 숫자 또는 null 선택 사항 기본값은 1입니다. 모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 질량을 구성하는 토큰만 고려됨을 의미합니다. 일반적으로 이를 변경하거나 온도를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다.
response_format 문자열 또는 개체 선택 사항 모델이 출력해야 하는 형식을 지정합니다. GPT-4 Turbo 및 gpt-3.5-turbo-1106 이후의 모든 GPT-3.5 Turbo 모델과 호환됩니다. 이 매개 변수를 { "type": "json_object" }로 설정하면 모델이 생성하는 메시지가 유효한 JSON임을 보장하는 JSON 모드가 사용하도록 설정됩니다. 중요한 점은 JSON 모드를 사용할 때 시스템 또는 사용자 메시지를 사용하여 JSON을 직접 생성하도록 모델에 지시해야 한다는 것입니다. 이 명령이 없으면 모델은 생성이 토큰 제한에 도달할 때까지 끝없는 공백 스트림을 생성할 수 있으며, 결과적으로 오래 실행되고 "중단"된 것처럼 보이는 요청이 발생할 수 있습니다. 또한 finish_reason="length"를 사용하는 경우 메시지 콘텐츠가 부분적으로 잘릴 수 있습니다. 이는 생성이 max_tokens를 초과했거나 대화가 최대 컨텍스트 길이를 초과했음을 나타냅니다.
tool_resources 개체 선택 사항 도우미 도구에서 사용하는 리소스 집합입니다. 리소스는 도구 유형에 따라 다릅니다. 예를 들어 code_interpreter 도구에는 파일 ID 목록이 필요하지만 file_search 도구에는 벡터 저장소 ID 목록이 필요합니다.

response_format 형식

string

기본값은 auto입니다.

object

가능한 type 값: text, json_object. json_schema

json_schema

속성 형식 설명 기본값 필수/선택
description string 모델이 해당 형식에 따라 응답하는 방법을 결정하는 데 사용되는 응답 형식의 설명입니다. 선택 사항
name string 응답 형식의 이름. a~z, A~Z, 0~9 또는 밑줄과 대시를 포함해야 하며 최대 길이는 64자여야 합니다. Required
schema 개체 JSON 스키마 개체로 설명되는 응답 형식에 대한 스키마입니다. 선택 사항
strict 부울 또는 null 출력을 생성할 때 엄격한 스키마 준수를 사용하도록 설정할지 여부를 나타냅니다. true로 설정하면 모델은 항상 schema 필드에 정의된 정확한 스키마를 따릅니다. strict가 true인 경우 JSON 스키마의 하위 집합만 지원됩니다. false 선택 사항

tool_resources 속성

code_interpreter

속성 형식 설명 기본값
file_ids 배열 code_interpreter 도구에서 사용할 수 있는 파일 ID 목록입니다. 도구와 연결된 파일은 최대 20개일 수 있습니다. []

file_search

속성 형식 설명 필수/선택
vector_store_ids 배열 이 스레드에 연결된 벡터 저장소입니다. 스레드에 연결된 벡터 저장소가 최대 1개 있을 수 있습니다. 선택 사항
vector_stores 배열 file_ids를 사용하여 벡터 저장소를 만들고 이 스레드에 연결하기 위한 도우미입니다. 스레드에 연결된 벡터 저장소가 최대 1개 있을 수 있습니다. 선택 사항

vector_stores

속성 형식 설명 필수/선택
file_ids 배열 벡터 저장소에 추가할 파일 ID 목록입니다. 벡터 저장소에는 최대 10,000명의 파일이 있을 수 있습니다. 선택 사항
chunking_strategy 개체 파일을 청크하는 데 사용되는 청크 전략입니다. 설정하지 않으면 자동 전략을 사용합니다. 선택 사항
metadata map 벡터 저장소에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 벡터 저장소에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다. 선택 사항

chunking_strategy

속성 형식 설명 필수/선택
Auto Chunking Strategy 개체 기본 전략. 이 전략은 현재 800의 max_chunk_size_tokens 및 400의 chunk_overlap_tokens을 사용합니다. type는 항상 auto입니다. Required
Static Chunking Strategy 개체 type 늘 static Required

정적 청크 전략

속성 형식 설명 필수/선택
max_chunk_size_tokens 정수 각 청크의 최대 토큰 수입니다. 기본값은 800입니다. 최솟값은 100이고 최댓값은 4096입니다. Required
chunk_overlap_tokens 정수 청크 간에 겹치는 토큰 수입니다. 기본값은 400입니다. 겹침은 max_chunk_size_tokens의 절반을 초과할 수 없습니다. Required

반품

도우미 개체.

도우미 만들기 요청 예

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant = client.beta.assistants.create(
  instructions="You are an AI assistant that can write code to help answer math questions",
  model="<REPLACE WITH MODEL DEPLOYMENT NAME>", # replace with model deployment name. 
  tools=[{"type": "code_interpreter"}]
)

도우미 나열

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview

모든 도우미 목록을 반환합니다.

쿼리 매개 변수

매개 변수 Type 필수 설명
limit 정수 선택 사항 반환할 개체 수에 대한 제한입니다. 제한 범위는 1~100이며 기본값은 20입니다.
order string 선택 사항 - 기본값은 desc입니다. 개체의 Created_at 타임스탬프를 기준으로 정렬 순서입니다. 오름차순은 asc, 내림차순은 desc입니다.
after string 선택 사항 페이지 매김에 사용되는 커서입니다. after는 목록에서의 위치를 정의하는 개체 ID입니다. 예를 들어, 목록 요청을 하고 obj_foo로 끝나는 100개의 개체를 받은 경우 목록의 다음 페이지를 페치 위해 후속 호출에 after=obj_foo가 포함될 수 있습니다.
before string 선택 사항 페이지 매김에 사용되는 커서입니다. before는 목록에서의 위치를 정의하는 개체 ID입니다. 예를 들어, 목록 요청을 하고 obj_foo로 끝나는 100개의 개체를 받은 경우 목록의 이전 페이지를 페치 위해 후속 호출에 before=obj_foo가 포함될 수 있습니다.

반환

도우미 개체 목록

도우미 나열 예

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

도우미 검색

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

도우미를 검색합니다.

경로 매개 변수

매개 변수 Type 필수 설명
assistant_id string Required 검색할 도우미의 ID입니다.

반환

지정된 ID와 일치하는 도우미 개체입니다.

도우미 검색 예

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

도우미 수정

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

도우미를 수정합니다.

경로 매개 변수

매개 변수 Type 필수 설명
assistant_id string Required 파일이 속한 도우미의 ID입니다.

요청 본문

매개 변수 Type 필수 설명
model 선택 사항 사용할 모델의 모델 배포 이름입니다.
name 문자열 또는 null 선택 사항 도우미의 이름입니다. 최대 길이는 256자입니다.
description 문자열 또는 null 선택 사항 도우미에 대한 설명입니다. 최대 길이는 512자입니다.
instructions 문자열 또는 null 선택 사항 도우미가 사용하는 시스템 지침입니다. 최대 길이는 32768자입니다.
tools 배열 선택 사항 기본값은 []입니다. 도우미에서 사용하도록 설정된 도구 목록입니다. 도우미당 최대 128개의 도구가 있을 수 있습니다. 도구는 code_interpreter 또는 함수 형식일 수 있습니다. function 설명은 최대 1,024자까지 쓸 수 있습니다.
metadata map 선택 사항 개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.
temperature 숫자 또는 null 선택 사항 기본값은 1입니다. 사용할 샘플링 온도를 0과 2 사이에서 결정합니다. 0.8과 같이 값이 높을수록 출력이 더욱 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다.
top_p 숫자 또는 null 선택 사항 기본값은 1입니다. 모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 질량을 구성하는 토큰만 고려됨을 의미합니다. 일반적으로 이를 변경하거나 온도를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다.
response_format 문자열 또는 개체 선택 사항 모델이 출력해야 하는 형식을 지정합니다. GPT-4 Turbo 및 gpt-3.5-turbo-1106 이후의 모든 GPT-3.5 Turbo 모델과 호환됩니다. 이 매개 변수를 { "type": "json_object" }로 설정하면 모델이 생성하는 메시지가 유효한 JSON임을 보장하는 JSON 모드가 사용하도록 설정됩니다. 중요한 점은 JSON 모드를 사용할 때 시스템 또는 사용자 메시지를 사용하여 JSON을 직접 생성하도록 모델에 지시해야 한다는 것입니다. 이 명령이 없으면 모델은 생성이 토큰 제한에 도달할 때까지 끝없는 공백 스트림을 생성할 수 있으며, 결과적으로 오래 실행되고 "중단"된 것처럼 보이는 요청이 발생할 수 있습니다. 또한 finish_reason="length"를 사용하는 경우 메시지 콘텐츠가 부분적으로 잘릴 수 있습니다. 이는 생성이 max_tokens를 초과했거나 대화가 최대 컨텍스트 길이를 초과했음을 나타냅니다.
tool_resources 개체 선택 사항 도우미 도구에서 사용하는 리소스 집합입니다. 리소스는 도구 유형에 따라 다릅니다. 예를 들어 code_interpreter 도구에는 파일 ID 목록이 필요하지만 file_search 도구에는 벡터 저장소 ID 목록이 필요합니다.

반환

수정된 도우미 개체.

도우미 수정 예

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_updated_assistant = client.beta.assistants.update(
  "asst_abc123",
  instructions="You are an HR bot, and you have access to files to answer employee questions about company policies. Always respond with info from either of the files.",
  name="HR Helper",
  tools=[{"type": "code-interpreter"}],
  model="gpt-4", #model = model deployment name
)

print(my_updated_assistant)

도우미 삭제

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-08-01-preview

도우미를 삭제합니다.

경로 매개 변수

매개 변수 Type 필수 설명
assistant_id string Required 파일이 속한 도우미의 ID입니다.

반환

삭제 상태.

도우미 삭제 예

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

파일 업로드 API 참조

도우미는 파일 업로드에 미세 조정과 동일한 API를 사용합니다. 파일을 업로드할 때 목적 매개 변수에 적절한 값을 지정해야 합니다.

도우미 개체

필드 형식 설명
id string API 엔드포인트에서 참조할 수 있는 식별자입니다.
object string 항상 도우미인 개체 형식입니다.
created_at 정수 도우미가 만들어진 시점의 Unix 타임스탬프(초)입니다.
name 문자열 또는 null 도우미의 이름입니다. 최대 길이는 256자입니다.
description 문자열 또는 null 도우미에 대한 설명입니다. 최대 길이는 512자입니다.
model string 사용할 모델 배포 이름입니다.
instructions 문자열 또는 null 도우미가 사용하는 시스템 지침입니다. 최대 길이는 32768자입니다.
tools 배열 도우미에서 사용하도록 설정된 도구 목록입니다. 도우미당 최대 128개의 도구가 있을 수 있습니다. 도구는 code_interpreter 또는 함수 형식일 수 있습니다. function 설명은 최대 1,024자까지 쓸 수 있습니다.
metadata map 개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.
temperature 숫자 또는 null 기본값은 1입니다. 사용할 샘플링 온도를 0과 2 사이에서 결정합니다. 0.8과 같이 값이 높을수록 출력이 더욱 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다.
top_p 숫자 또는 null 기본값은 1입니다. 모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 질량을 구성하는 토큰만 고려됨을 의미합니다. 일반적으로 이를 변경하거나 온도를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다.
response_format 문자열 또는 개체 모델이 출력해야 하는 형식을 지정합니다. GPT-4 Turbo 및 gpt-3.5-turbo-1106 이후의 모든 GPT-3.5 Turbo 모델과 호환됩니다. 이 매개 변수를 { "type": "json_object" }로 설정하면 모델이 생성하는 메시지가 유효한 JSON임을 보장하는 JSON 모드가 사용하도록 설정됩니다. 중요한 점은 JSON 모드를 사용할 때 시스템 또는 사용자 메시지를 사용하여 JSON을 직접 생성하도록 모델에 지시해야 한다는 것입니다. 이 명령이 없으면 모델은 생성이 토큰 제한에 도달할 때까지 끝없는 공백 스트림을 생성할 수 있으며, 결과적으로 오래 실행되고 "중단"된 것처럼 보이는 요청이 발생할 수 있습니다. 또한 finish_reason="length"를 사용하는 경우 메시지 콘텐츠가 부분적으로 잘릴 수 있습니다. 이는 생성이 max_tokens를 초과했거나 대화가 최대 컨텍스트 길이를 초과했음을 나타냅니다.
tool_resources 개체 도우미 도구에서 사용하는 리소스 집합입니다. 리소스는 도구 유형에 따라 다릅니다. 예를 들어 code_interpreter 도구에는 파일 ID 목록이 필요하지만 file_search 도구에는 벡터 저장소 ID 목록이 필요합니다.