도우미 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 목록이 필요합니다. |
반품
도우미 개체.
도우미 만들기 요청 예
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 목록이 필요합니다. |