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

아티클
06/13/2024

참고 항목

파일 검색은 도우미당 최대 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자일 수 있습니다.
file_ids	배열	선택 사항	기본값은 []입니다. 이 도우미에 첨부된 파일 ID 목록입니다. 도우미에는 최대 20개의 파일을 첨부할 수 있습니다. 파일은 만든 날짜를 기준으로 오름차순으로 정렬됩니다.
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`를 초과했거나 대화가 최대 컨텍스트 길이를 초과했음을 나타냅니다.

반품

도우미 개체.

from openai import AzureOpenAI
    
client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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"}]
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-1106-preview"
  }'

도우미 파일 만들기

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

File을 assistant에 첨부하여 도우미 파일을 만듭니다.

경로 매개 변수

매개 변수	Type	필수	설명
`assistant_id`	string	Required	파일을 첨부해야 하는 도우미의 ID입니다.

요청 본문

이름	Type	필수	설명
file_id	string	Required	도우미가 사용해야 하는 파일 ID(목적="도우미" 포함)입니다. 파일에 액세스할 수 있는 code_interpreter와 같은 도구에 유용합니다.

반환

도우미 파일 개체.

도우미 파일 요청 만들기 예

Python 1.x
REST

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

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
       "file_id": "assistant-abc123"
     }'

도우미 나열

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가 포함될 수 있습니다.

반환

도우미 개체 목록

도우미 나열 예

Python 1.x
REST

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

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

도우미 파일 나열

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

도우미 파일 목록을 반환합니다.

경로 매개 변수

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

쿼리 매개 변수

매개 변수	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가 포함될 수 있습니다.

반환

도우미 파일 개체 목록

도우미 파일 나열 예

Python 1.x
REST

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

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

도우미 검색

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

도우미를 검색합니다.

경로 매개 변수

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

반환

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

도우미 검색 예

Python 1.x
REST

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

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

도우미 파일 검색

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

도우미 파일을 검색합니다.

경로 매개 변수

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

반환

지정된 ID와 일치하는 도우미 파일 개체

도우미 파일 검색 예

Python 1.x
REST

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

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files/{file-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

도우미 수정

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-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자일 수 있습니다.
`file_ids`	배열	선택 사항	기본값은 []입니다. 이 도우미에 첨부된 파일 ID 목록입니다. 도우미에는 최대 20개의 파일을 첨부할 수 있습니다. 파일은 만든 날짜를 기준으로 오름차순으로 정렬됩니다. 이전에 목록에 첨부된 파일이 목록에 표시되지 않으면 도우미에서 삭제됩니다.
`metadata`	map	선택 사항	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.

반환

수정된 도우미 개체.

도우미 수정 예

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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
  file_ids=["assistant-abc123", "assistant-abc456"],
)

print(my_updated_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "code-interpreter"}],
      "model": "gpt-4",
      "file_ids": ["assistant-abc123", "assistant-abc456"]
    }'

도우미 삭제

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

도우미를 삭제합니다.

경로 매개 변수

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

반환

삭제 상태.

도우미 삭제 예

Python 1.x
REST

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

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

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

도우미 파일 삭제

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

도우미 파일을 삭제합니다.

경로 매개 변수

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

반환

파일 삭제 상태

도우미 파일 삭제 예

Python 1.x
REST

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

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="assistant-abc123"
)
print(deleted_assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
```  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

파일 업로드 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자일 수 있습니다.
`file_ids`	배열	이 도우미에 첨부된 파일 ID 목록입니다. 도우미에는 최대 20개의 파일을 첨부할 수 있습니다. 파일은 만든 날짜를 기준으로 오름차순으로 정렬됩니다.
`metadata`	map	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키는 최대 64자, 값은 최대 512자까지 가능합니다.

도우미 파일 개체

필드	형식	설명
`id`	string	API 엔드포인트에서 참조할 수 있는 식별자입니다.
`object`	string	항상 `assistant.file`인 개체 형식입니다.
`created_at`	정수	도우미 파일이 만들어진 시점의 Unix 타임스탬프(초)입니다.
`assistant_id`	string	파일이 첨부된 도우미 ID입니다.

다음을 통해 공유

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

도우미 만들기

요청 본문

반품

도우미 만들기 요청 예

도우미 파일 만들기

반환

도우미 파일 요청 만들기 예

도우미 나열

반환

도우미 나열 예

도우미 파일 나열

반환

도우미 파일 나열 예

도우미 검색

도우미 검색 예

도우미 파일 검색

반환

도우미 파일 검색 예

도우미 수정

도우미 수정 예

도우미 삭제

도우미 삭제 예

도우미 파일 삭제

도우미 파일 삭제 예

파일 업로드 API 참조

도우미 개체

도우미 파일 개체

피드백

피드백

추가 리소스