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

아티클
10/01/2024

참고 항목

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

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

실행 만들기

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

실행을 만듭니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	메시지를 만들 스레드의 ID입니다.

요청 본문

이름	Type	필수	설명
`assistant_id`	string	Required	이 실행을 실행하는 데 사용할 도우미의 ID입니다.
`model`	문자열 또는 null	선택 사항	이 실행을 실행하는 데 사용할 모델 배포 이름입니다. 여기에 값이 제공되면 도우미와 연결된 모델 배포 이름이 재정의됩니다. 그렇지 않은 경우 도우미와 연결된 모델 배포 이름이 사용됩니다.
`instructions`	문자열 또는 null	선택 사항	도우미의 명령을 무시합니다. 이는 실행별로 동작을 수정하는 데 유용합니다.
`additional_instructions`	string	선택 사항	실행 지침 끝에 추가 지침을 추가합니다. 이는 다른 지침을 재정의하지 않고 실행별로 동작을 수정하는 데 유용합니다.
`additional_messages`	array	선택 사항	실행을 만들기 전에 스레드에 추가 메시지를 추가합니다.
`tools`	배열 또는 null	선택 사항	도우미가 이 실행에 사용할 수 있는 도구를 재정의합니다. 이는 실행별로 동작을 수정하는 데 유용합니다.
`metadata`	map	선택 사항	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.
`temperature`	번호	선택 사항	사용할 샘플링 온도(0에서 2 사이)입니다. 0.8과 같이 값이 높을수록 출력이 더욱 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다. 기본 은(는) 1입니다.
`top_p`	번호	선택 사항	모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 질량을 구성하는 토큰만 고려됨을 의미합니다. 일반적으로 이를 변경하거나 온도를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다. 기본 은(는) 1입니다.
`stream`	부울 값	{b>선택 사항	`true`인 경우, 실행 서버에서 보낸 이벤트 중에 발생하는 이벤트 스트림을 반환하고, `data: [DONE]` 메시지를 표시하면서 실행이 터미널 상태가 될 때 종료됩니다.
`max_prompt_tokens`	정수	{b>선택 사항	실행 과정에서 사용할 수 있는 완성 토큰의 최대 수입니다. 이 실행은 여러 번의 실행 동안 지정된 수의 완성 토큰만 사용하려고 최선의 노력을 기울입니다. 실행이 지정된 완성 토큰 수를 초과하면 상태 `incomplete`로 종료됩니다.
`max_completion_tokens`	정수	{b>선택 사항	실행 과정에서 사용할 수 있는 완성 토큰의 최대 수입니다. 이 실행은 여러 번의 실행 동안 지정된 수의 완성 토큰만 사용하려고 최선의 노력을 기울입니다. 실행이 지정된 완성 토큰 수를 초과하면 상태 `incomplete`로 종료됩니다.
`truncation_strategy`	truncationObject	{b>선택 사항	실행 전에 스레드가 잘리는 방법에 대한 컨트롤입니다. 실행의 초기 컨텍스트 창을 제어하는 데 사용합니다.
`tool_choice`	문자열 또는 개체	{b>선택 사항	모델이 호출하는 도구(있는 경우)를 제어합니다. `none` 값은 모델이 도구를 호출하지 않고 대신 메시지를 생성한다는 것을 의미합니다. `auto`는 기본값이며 모델이 메시지 생성 또는 도구 호출 중에서 선택할 수 있음을 의미합니다. `{"type": "file_search"}` 또는 `{"type": "function", "function": {"name": "my_function"}}`과 같은 특정 도구를 지정하면 모델이 해당 도구를 호출하게 됩니다.
`response_format`	문자열 또는 개체	{b>선택 사항	모델이 출력해야 하는 형식을 지정합니다. `gpt-3.5-turbo-1106` 이후의 GPT-4 Turbo 및 모든 GPT-3.5 Turbo 모델과 호환됩니다. `{ "type": "json_object" }`(으)로 설정하면 모델이 생성하는 메시지가 유효한 JSON임을 보장하는 JSON 모드가 사용하도록 설정됩니다. 중요: JSON 모드를 사용하는 경우 시스템 또는 사용자 메시지를 통해 JSON을 직접 생성하도록 모델에 지시해야 합니다. 이 설정이 없으면 모델은 생성이 토큰 제한에 도달할 때까지 끝없는 공백 스트림을 생성할 수 있으며, 결과적으로 오래 실행되고 "중단"된 것처럼 보이는 요청이 발생할 수 있습니다. 또한 생성이 `max_tokens`를 초과했거나 대화가 최대 컨텍스트 길이를 초과했음을 나타내는 `finish_reason="length"`인 경우 메시지 콘텐츠가 부분적으로 잘릴 수 있습니다.

반품

실행 개체입니다.

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")
    )

run = client.beta.threads.runs.create(
  thread_id="thread_abc123",
  assistant_id="asst_abc123"
)
print(run)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "assistant_id": "asst_abc123"
  }'

스레드 만들기 및 실행

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/runs?api-version=2024-08-01-preview

스레드를 만들고 단일 요청으로 실행합니다.

요청 본문

이름	Type	필수	설명
`assistant_id`	string	Required	이 실행을 실행하는 데 사용할 도우미의 ID입니다.
`thread`	개체	선택 사항
`model`	문자열 또는 null	선택 사항	이 실행을 실행하는 데 사용할 모델 배포 이름의 ID입니다. 여기에 값이 제공되면 도우미와 연결된 모델 배포 이름이 재정의됩니다. 그렇지 않은 경우 도우미와 연결된 모델 배포 이름이 사용됩니다.
`instructions`	문자열 또는 null	선택 사항	도우미의 기본 시스템 메시지를 대체합니다. 이는 실행별로 동작을 수정하는 데 유용합니다.
`tools`	배열 또는 null	선택 사항	도우미가 이 실행에 사용할 수 있는 도구를 재정의합니다. 이는 실행별로 동작을 수정하는 데 유용합니다.
`metadata`	map	선택 사항	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.
`temperature`	번호	선택 사항	사용할 샘플링 온도(0에서 2 사이)입니다. 0.8과 같이 값이 높을수록 출력이 더욱 무작위로 생성되고, 0.2와 같이 값이 낮을수록 출력이 더욱 집중되고 결정적이게 됩니다. 기본 은(는) 1입니다.
`top_p`	번호	선택 사항	모델이 top_p 확률 질량을 가진 토큰의 결과를 고려하는 핵 샘플링이라고 하는 온도를 사용한 샘플링의 대안입니다. 따라서 0.1은 상위 10% 확률 질량을 구성하는 토큰만 고려됨을 의미합니다. 일반적으로 이를 변경하거나 온도를 변경하는 것이 좋지만 둘 다 변경하는 것은 권장하지 않습니다. 기본 은(는) 1입니다.
`stream`	부울 값	{b>선택 사항	`true`인 경우, 실행 서버에서 보낸 이벤트 중에 발생하는 이벤트 스트림을 반환하고, `data: [DONE]` 메시지를 표시하면서 실행이 터미널 상태가 될 때 종료됩니다.
`max_prompt_tokens`	정수	{b>선택 사항	실행 과정에서 사용할 수 있는 완성 토큰의 최대 수입니다. 이 실행은 여러 번의 실행 동안 지정된 수의 완성 토큰만 사용하려고 최선의 노력을 기울입니다. 실행이 지정된 완성 토큰 수를 초과하면 상태 `incomplete`로 종료됩니다.
`max_completion_tokens`	정수	{b>선택 사항	실행 과정에서 사용할 수 있는 완성 토큰의 최대 수입니다. 이 실행은 여러 번의 실행 동안 지정된 수의 완성 토큰만 사용하려고 최선의 노력을 기울입니다. 실행이 지정된 완성 토큰 수를 초과하면 상태 `incomplete`로 종료됩니다.
`truncation_strategy`	truncationObject	{b>선택 사항	실행 전에 스레드가 잘리는 방법에 대한 컨트롤입니다. 실행의 초기 컨텍스트 창을 제어하는 데 사용합니다.
`tool_choice`	문자열 또는 개체	{b>선택 사항	모델이 호출하는 도구(있는 경우)를 제어합니다. `none` 값은 모델이 도구를 호출하지 않고 대신 메시지를 생성한다는 것을 의미합니다. `auto`는 기본값이며 모델이 메시지 생성 또는 도구 호출 중에서 선택할 수 있음을 의미합니다. `{"type": "file_search"}` 또는 `{"type": "function", "function": {"name": "my_function"}}`과 같은 특정 도구를 지정하면 모델이 해당 도구를 호출하게 됩니다.
`response_format`	문자열 또는 개체	{b>선택 사항	모델이 출력해야 하는 형식을 지정합니다. `gpt-3.5-turbo-1106` 이후의 GPT-4 Turbo 및 모든 GPT-3.5 Turbo 모델과 호환됩니다. `{ "type": "json_object" }`(으)로 설정하면 모델이 생성하는 메시지가 유효한 JSON임을 보장하는 JSON 모드가 사용하도록 설정됩니다. 중요: JSON 모드를 사용하는 경우 시스템 또는 사용자 메시지를 통해 JSON을 직접 생성하도록 모델에 지시해야 합니다. 이 설정이 없으면 모델은 생성이 토큰 제한에 도달할 때까지 끝없는 공백 스트림을 생성할 수 있으며, 결과적으로 오래 실행되고 "중단"된 것처럼 보이는 요청이 발생할 수 있습니다. 또한 생성이 `max_tokens`를 초과했거나 대화가 최대 컨텍스트 길이를 초과했음을 나타내는 `finish_reason="length"`인 경우 메시지 콘텐츠가 부분적으로 잘릴 수 있습니다.

반품

실행 개체입니다.

예제 스레드 만들기 및 요청 실행

Python 1.x
REST

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")
    )

run = client.beta.threads.create_and_run(
  assistant_id="asst_abc123",
  thread={
    "messages": [
      {"role": "user", "content": "Explain deep learning to a 5 year old."}
    ]
  }
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/runs?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "assistant_id": "asst_abc123",
      "thread": {
        "messages": [
          {"role": "user", "content": "Explain deep learning to a 5 year old."}
        ]
      }
    }'

목록 실행

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

스레드에 속하는 실행 목록을 반환합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	실행이 속한 스레드의 ID입니다.

쿼리 매개 변수

이름	Type	필수	설명
`limit`	정수	선택 사항 - 기본값은 20입니다.	반환할 개체 수에 대한 제한입니다. 제한 범위는 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가 포함될 수 있습니다.

반환

run 개체 목록입니다.

예제 목록 실행 요청

Python 1.x
REST

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")
    )

runs = client.beta.threads.runs.list(
  "thread_abc123"
)
print(runs)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs?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/threads/{thread_id}/runs/{run_id}/steps?api-version=2024-08-01-preview

실행에 속하는 단계 목록을 반환합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	실행이 속한 스레드의 ID입니다.
`run_id`	string	Required	쿼리할 실행 단계와 연결된 실행의 ID입니다.

쿼리 매개 변수

이름	Type	필수	설명
`limit`	정수	선택 사항 - 기본값은 20입니다.	반환할 개체 수에 대한 제한입니다. 제한 범위는 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-08-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

run_steps = client.beta.threads.runs.steps.list(
    thread_id="thread_abc123",
    run_id="run_abc123"
)
print(run_steps)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

검색 실행

Python 1.x
REST

from openai import OpenAI
client = OpenAI()

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)

print(run)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-08-01-preview
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

실행을 검색합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	실행된 스레드의 ID입니다.
`run_id`	string	Required	검색할 실행의 ID입니다.

반환

지정된 실행 ID와 일치하는 run 개체입니다.

예 목록 실행 단계 요청

Python 1.x
REST

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")
    )

run = client.beta.threads.runs.retrieve(
  thread_id="thread_abc123",
  run_id="run_abc123"
)
print(run)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

실행 단계 검색

GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2024-08-01-preview

실행 단계를 검색합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	실행 및 실행 단계가 속한 스레드의 ID입니다.
`run_id`	string	Required	실행 단계가 속한 실행의 ID입니다.
`step_id`	string	Required	검색할 실행 단계의 ID입니다.

반환

지정된 ID와 일치하는 실행 단계 개체입니다.

예제 실행 단계 요청 검색

Python 1.x
REST

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")
    )

run_step = client.beta.threads.runs.steps.retrieve(
    thread_id="thread_abc123",
    run_id="run_abc123",
    step_id="step_abc123"
)
print(run_step)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json'

실행 수정

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-08-01-preview

실행을 수정합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	실행된 스레드의 ID입니다.
`run_id`	string	Required	수정할 실행의 ID입니다.

요청 본문

이름	Type	필수	설명
`metadata`	map	선택 사항	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.

반환

지정된 ID와 일치하는 수정된 run 개체입니다.

예제 수정 실행 요청

Python 1.x
REST

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")
    )

run = client.beta.threads.runs.update(
  thread_id="thread_abc123",
  run_id="run_abc123",
  metadata={"user_id": "user_abc123"},
)
print(run)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' 
  -d '{
    "metadata": {
      "user_id": "user_abc123"
    }
  }'

실행할 도구 출력 제출

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2024-08-01-preview

실행 상태가 "requires_action"이고 required_action.type이 submit_tool_outputs인 경우 도구 호출이 모두 완료된 후 이 엔드포인트를 사용하여 도구 호출의 출력을 제출할 수 있습니다. 모든 출력은 단일 요청으로 제출되어야 합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	이 실행이 속한 스레드의 ID입니다.
`run_id`	string	Required	도구 출력 제출이 필요한 실행의 ID입니다.

요청 본문

이름	Type	필수	설명
`tool_outputs`	array	Required	출력이 제출되는 도구 목록입니다.
`stream`	부울 값	선택 사항	`true`인 경우, 실행 서버에서 보낸 이벤트 중에 발생하는 이벤트 스트림을 반환하고, `data: [DONE]` 메시지를 표시하면서 실행이 터미널 상태가 될 때 종료됩니다.

반품

지정된 ID와 일치하는 수정된 run 개체입니다.

요청을 실행하기 위한 제출 도구 출력 예

Python 1.x
REST

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")
    )

run = client.beta.threads.runs.submit_tool_outputs(
  thread_id="thread_abc123",
  run_id="run_abc123",
  tool_outputs=[
    {
      "tool_call_id": "call_abc123",
      "output": "28C"
    }
  ]
)
print(run)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/submit_tool_outputs?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_abc123",
        "output": "28C"
      }
    ]
  }'

실행 취소

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2024-08-01-preview

진행 중인 실행을 취소합니다.

경로 매개 변수

매개 변수	Type	필수	설명
`thread_id`	string	Required	이 실행이 속한 스레드의 ID입니다.
`run_id`	string	Required	취소할 실행의 ID입니다.

반환

지정된 ID와 일치하는 수정된 run 개체입니다.

요청을 실행하기 위한 제출 도구 출력 예

Python 1.x
REST

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")
    )

run = client.beta.threads.runs.cancel(
  thread_id="thread_abc123",
  run_id="run_abc123"
)
print(run)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2024-08-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X POST

개체 실행

스레드에서 실행되는 실행을 나타냅니다.

이름	형식	설명
`id`	string	API 엔드포인트에서 참조할 수 있는 식별자입니다.
`object`	string	항상 thread.run인 개체 형식입니다.
`created_at`	정수	실행이 만들어진 시점의 Unix 타임스탬프(초)입니다.
`thread_id`	string	이 실행의 일부로 실행된 스레드의 ID입니다.
`assistant_id`	string	이 실행을 실행하는 데 사용되는 도우미의 ID입니다.
`status`	string	실행 상태는 `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed` 또는 `expired`일 수 있습니다.
`required_action`	개체 또는 null	실행을 계속하는 데 필요한 작업에 대한 세부 정보입니다. 작업이 필요하지 않으면 null이 됩니다.
`last_error`	개체 또는 null	이 실행과 관련된 마지막 오류입니다. 오류가 없으면 null이 됩니다.
`expires_at`	정수	실행이 만료된 시점의 Unix 타임스탬프(초)입니다.
`started_at`	정수 또는 null	실행이 시작된 시점의 Unix 타임스탬프(초)입니다.
`cancelled_at`	정수 또는 null	실행이 취소된 시점의 Unix 타임스탬프(초)입니다.
`failed_at`	정수 또는 null	실행이 실패한 시점의 Unix 타임스탬프(초)입니다.
`completed_at`	정수 또는 null	실행이 완료된 시점의 Unix 타임스탬프(초)입니다.
`model`	string	도우미가 이 실행에 사용한 모델 배포 이름입니다.
`instructions`	string	도우미가 이 실행에 사용한 지침입니다.
`tools`	배열	도우미가 이 실행에 사용한 도구 목록입니다.
`file_ids`	배열	도우미가 이 실행에 사용한 파일 ID 목록입니다.
`metadata`	map	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.
`tool_choice`	문자열 또는 개체	모델이 호출하는 도구(있는 경우)를 제어합니다. `none`은 모델이 도구를 호출하지 않고 대신 메시지를 생성함을 의미합니다. `auto`는 기본값이며 모델이 메시지 생성 또는 도구 호출 중에서 선택할 수 있음을 의미합니다. `{"type": "file_search"}` 또는 `{"type": "function", "function": {"name": "my_function"}}`과 같은 특정 도구를 지정하면 모델이 해당 도구를 호출하게 됩니다.
`max_prompt_tokens`	정수 또는 null	실행 과정에서 사용되도록 지정된 프롬프트 토큰의 최대 수입니다.
`max_completion_tokens`	정수 또는 null	실행 과정에서 사용되도록 지정된 완료 토큰의 최대 수입니다.
`usage`	개체 또는 null	실행과 관련된 사용 통계. 실행이 최종 상태가 아닌 경우(예: `in_progress`, `queued`) 이 값은 null이 됩니다.
`truncation_strategy`	개체	실행 전에 스레드가 잘리는 방법에 대한 컨트롤입니다.
`response_format`	string	모델이 출력해야 하는 형식입니다. `gpt-3.5-turbo-1106` 이후의 GPT-4 Turbo 및 모든 GPT-3.5 Turbo 모델과 호환됩니다.
`tool_choice`	string	모델이 호출하는 도구(있는 경우)를 제어합니다. `none`은 모델이 도구를 호출하지 않고 대신 메시지를 생성함을 의미합니다. `auto`는 기본값이며 모델이 메시지 생성 또는 도구 호출 중에서 선택할 수 있음을 의미합니다.

단계 개체 실행

실행 단계를 나타냅니다.

이름	형식	설명
`id`	string	API 엔드포인트에서 참조할 수 있는 실행 단계의 식별자입니다.
`object`	string	항상 thread.run.step인 개체 형식입니다.
`created_at`	정수	실행 단계가 만들어진 시점의 Unix 타임스탬프(초)입니다.
`assistant_id`	string	실행 단계와 연결된 도우미의 ID입니다.
`thread_id`	string	실행된 스레드의 ID입니다.
`run_id`	string	이 실행 단계가 포함된 실행의 ID입니다.
`type`	string	message_creation 또는 tool_calls일 수 있는 실행 단계의 형식입니다.
`status`	string	실행 단계의 상태는 `in_progress`, `cancelled`, `failed`, `completed` 또는 `expired`일 수 있습니다.
`step_details`	개체	실행 단계의 세부 정보입니다.
`last_error`	개체 또는 null	이 실행 단계와 관련된 마지막 오류입니다. 오류가 없으면 null이 됩니다.
`expired_at`	정수 또는 null	실행 단계가 만료된 시점의 Unix 타임스탬프(초)입니다. 부모 실행이 만료되면 단계가 만료된 것으로 간주됩니다.
`cancelled_at`	정수 또는 null	실행 단계가 취소된 시점의 Unix 타임스탬프(초)입니다.
`failed_at`	정수 또는 null	실행 단계가 실패한 시점의 Unix 타임스탬프(초)입니다.
`completed_at`	정수 또는 null	실행 단계가 완료된 시점의 Unix 타임스탬프(초)입니다.
`metadata`	map	개체에 연결할 수 있는 16개의 키-값 쌍 집합입니다. 이는 구조화된 형식으로 개체에 대한 추가 정보를 저장하는 데 유용할 수 있습니다. 키의 길이는 최대 64자이고 값은 최대 512자까지 가능합니다.

실행 결과 스트리밍(미리 보기)

도구 출력을 제출한 후 실행을 실행 또는 실행을 재개한 결과를 스트리밍합니다. 다음 이후에 이벤트를 스트리밍할 수 있습니다.

스레드 만들기 및 실행
실행 만들기
도구 출력 제출

결과를 스트리밍하려면 실행을 만드는 동안 "stream": true를 전달합니다. 응답은 서버에서 보낸 이벤트 스트림입니다.

스트리밍 예

from typing_extensions import override
from openai import AssistantEventHandler
 
# First, we create a EventHandler class to define
# how we want to handle the events in the response stream.
 
class EventHandler(AssistantEventHandler):    
  @override
  def on_text_created(self, text) -> None:
    print(f"\nassistant > ", end="", flush=True)
      
  @override
  def on_text_delta(self, delta, snapshot):
    print(delta.value, end="", flush=True)
      
  def on_tool_call_created(self, tool_call):
    print(f"\nassistant > {tool_call.type}\n", flush=True)
  
  def on_tool_call_delta(self, delta, snapshot):
    if delta.type == 'code_interpreter':
      if delta.code_interpreter.input:
        print(delta.code_interpreter.input, end="", flush=True)
      if delta.code_interpreter.outputs:
        print(f"\n\noutput >", flush=True)
        for output in delta.code_interpreter.outputs:
          if output.type == "logs":
            print(f"\n{output.logs}", flush=True)
 
# Then, we use the `create_and_stream` SDK helper 
# with the `EventHandler` class to create the Run 
# and stream the response.
 
with client.beta.threads.runs.stream(
  thread_id=thread.id,
  assistant_id=assistant.id,
  instructions="Please address the user as Jane Doe. The user has a premium account.",
  event_handler=EventHandler(),
) as stream:
  stream.until_done()

잘림 개체

실행 전에 스레드가 잘리는 방법에 대한 컨트롤입니다. 실행의 초기 컨텍스트 창을 제어하는 데 사용합니다.

속성	형식	설명	필수
`type`	string	스레드에 사용할 잘림 전략입니다. 기본값은 `auto`입니다. `last_messages`로 설정하면 스레드가 스레드에서 가장 최근의 n개의 메시지로 잘립니다. `auto`로 설정하면 스레드 중간에 있는 메시지가 모델의 컨텍스트 길이, `max_prompt_tokens`에 맞게 삭제됩니다.	예
`last_messages`	정수	실행에 대한 컨텍스트를 생성할 때 스레드의 가장 최근 메시지 수입니다.	아니요

메시지 델타 개체

메시지 델타를 나타냅니다. 예를 들어, 스트리밍 중에 메시지의 변경된 필드가 있습니다.

속성	형식	설명
`id`	string	API 엔드포인트에서 참조할 수 있는 메시지의 식별자입니다.
`object`	string	항상 `thread.message.delta`인 개체 형식입니다.
`delta`	개체	메시지에서 변경된 필드가 포함된 델타입니다.

실행 단계 델타 개체

실행 단계 델타를 나타냅니다. 예를 들어, 스트리밍 중 실행 단계에서 변경된 필드입니다.

속성	형식	설명
`id`	string	API 엔드포인트에서 참조할 수 있는 실행 단계의 식별자입니다.
`object`	string	항상 `thread.run.step.delta`인 개체 형식입니다.
`delta`	개체	실행 단계에서 변경된 필드가 포함된 델타입니다.

도우미 스트림 이벤트

실행을 스트리밍할 때 발생하는 이벤트를 나타냅니다. 서버에서 보낸 이벤트 스트림의 각 이벤트에는 이벤트 및 데이터 속성이 있습니다.

event: thread.created
data: {"id": "thread_123", "object": "thread", ...}

새 개체가 만들어지거나, 새 상태로 전환되거나, 부분(델타)으로 스트리밍될 때마다 이벤트가 발생합니다. 예를 들어, 새 실행이 만들어지면 thread.run.created가 내보내지고, 실행이 완료되면 thread.run.completed가 내보내집니다. 도우미가 실행 중에 메시지 만들기를 선택하면 thread.message.created 이벤트, thread.message.in_progress 이벤트, 많은 스레드가 발생합니다.message.delta 이벤트, 마지막으로 thread.message.completed 이벤트입니다.

속성	형식	설명
`thread.created`	`data`는 스레드입니다.	새 스레드가 만들어질 때 발생합니다.
`thread.run.created`	`data`는 실행입니다.	새 실행이 만들어지면 발생합니다.
`thread.run.queued`	`data`는 실행입니다.	실행이 큐 상태로 전환되면 발생합니다.
`thread.run.in_progress`	`data`는 실행입니다.	실행이 in_progress 상태로 전환되면 발생합니다.
`thread.run.requires_action`	`data`는 실행입니다.	실행이 `requires_action` 상태로 이동할 때 발생합니다.
`thread.run.completed`	`data`는 실행입니다.	실행이 완료되면 발생합니다.
`thread.run.failed`	`data`는 실행입니다.	실행이 실패할 때 발생합니다.
`thread.run.cancelling`	`data`는 실행입니다.	실행이 `cancelling` 상태로 이동할 때 발생합니다.
`thread.run.cancelled`	`data`는 실행입니다.	실행이 취소되면 발생합니다.
`thread.run.expired`	`data`는 실행입니다.	실행이 만료되면 발생합니다.
`thread.run.step.created`	`data`는 실행 단계입니다.	실행 단계가 만들어지면 발생합니다.
`thread.run.step.in_progress`	`data`는 실행 단계입니다.	실행 단계가 `in_progress` 상태로 이동할 때 발생합니다.
`thread.run.step.delta`	`data`는 실행 단계 델타입니다.	실행 단계의 일부가 스트리밍될 때 발생합니다.
`thread.run.step.completed`	`data`는 실행 단계입니다.	실행 단계가 완료되면 발생합니다.
`thread.run.step.failed`	`data`는 실행 단계입니다.	실행 단계가 실패하면 발생합니다.
`thread.run.step.cancelled`	`data`는 실행 단계입니다.	실행 단계가 취소되면 발생합니다.
`thread.run.step.expired`	`data`는 실행 단계입니다.	실행 단계가 만료되면 발생합니다.
`thread.message.created`	`data`는 메시지입니다.	메시지가 만들어질 때 발생합니다.
`thread.message.in_progress`	`data`는 메시지입니다.	메시지가 in_progress 상태로 이동할 때 발생합니다.
`thread.message.delta`	`data`는 메시지 델타입니다.	메시지의 일부가 스트리밍될 때 발생합니다.
`thread.message.completed`	`data`는 메시지입니다.	메시지가 완료되면 발생합니다.
`thread.message.incomplete`	`data`는 메시지입니다.	메시지가 완료되기 전에 종료되면 발생합니다.
`error`	`data`는 오류입니다.	오류가 발생하면 발생합니다. 이는 내부 서버 오류 또는 시간 제한으로 인해 발생할 수 있습니다.
`done`	`data`가 `[DONE]`인 경우	스트림이 종료되면 발생합니다.

다음을 통해 공유

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

실행 만들기

반품

예 실행 요청 만들기

스레드 만들기 및 실행

반품

예제 스레드 만들기 및 요청 실행

목록 실행

반환

예제 목록 실행 요청

실행 단계 나열

반환

예 목록 실행 단계 요청

검색 실행

반환

예 목록 실행 단계 요청

실행 단계 검색

반환

예제 실행 단계 요청 검색

실행 수정

반환

예제 수정 실행 요청

실행할 도구 출력 제출

반품

요청을 실행하기 위한 제출 도구 출력 예

실행 취소

반환

요청을 실행하기 위한 제출 도구 출력 예

개체 실행

단계 개체 실행

실행 결과 스트리밍(미리 보기)

스트리밍 예

잘림 개체

메시지 델타 개체

실행 단계 델타 개체

도우미 스트림 이벤트

피드백

추가 리소스