小幫手 API （預覽） 執行參考

注意

• 檔案搜尋 可以擷取每個助理最多 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-05-01-preview

建立執行。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	要為其建立訊息之線程的標識碼。

要求本文

名稱	類型​​	必要	描述
assistant_id	string	必要	用來執行此執行的助理標識碼。
model	string 或 null	選擇性	要用來執行此執行的模型部署名稱。 如果此處提供值，則會覆寫與小幫手相關聯的模型部署名稱。 如果沒有，將會使用與小幫手相關聯的模型部署名稱。
instructions	string 或 null	選擇性	覆寫助理的指示。 這在每次執行的情況下修改行為很有用。
tools	array 或 null	選擇性	覆寫助理可用於此執行的工具。 這在每次執行的情況下修改行為很有用。
metadata	map	選擇性	可附加至物件的16個索引鍵/值組集合。 這對於以結構化格式儲存物件的其他資訊很有用。 索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

傳回

run 物件。

建立執行要求的範例

Python 1.x

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

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

REST

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' \
  -d '{
    "assistant_id": "asst_abc123"
  }'

建立線程並執行

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

建立線程，並在單一要求中執行。

要求本文

名稱	類型​​	必要	描述
assistant_id	string	必要	用來執行此執行的助理標識碼。
thread	object	選擇性
model	string 或 null	選擇性	要用來執行此執行之模型部署名稱的標識碼。 如果此處提供值，則會覆寫與小幫手相關聯的模型部署名稱。 如果沒有，將會使用與小幫手相關聯的模型部署名稱。
instructions	string 或 null	選擇性	覆寫助理的預設系統訊息。 這在每次執行的情況下修改行為很有用。
tools	array 或 null	選擇性	覆寫助理可用於此執行的工具。 這在每次執行的情況下修改行為很有用。
metadata	map	選擇性	可附加至物件的16個索引鍵/值組集合。 這對於以結構化格式儲存物件的其他資訊很有用。 索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

傳回

run 物件。

建立線程和執行要求的範例

Python 1.x

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

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

REST

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/runs?api-version=2024-05-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-05-01-preview

傳回屬於線程的執行清單。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	執行所屬線程的標識碼。

查詢參數

名稱	類型​​	必要	描述
limit	整數	選擇性 - 預設值為 20	要傳回之對象的數目限制。 限制的範圍可以介於 1 到 100 之間，預設值為 20。
order	字串	選擇性 - 預設值為 desc	依物件的created_at時間戳排序順序。 遞增順序的 asc 和遞減順序的 desc。
after	字串	選擇性	用於分頁的數據指標。 after 是定義清單中位置的物件標識碼。 例如，如果您提出清單要求並接收 100 個對象，結尾為 obj_foo，則後續呼叫可以包含 after=obj_foo，以擷取清單的下一頁。
before	字串	選擇性	用於分頁的數據指標。 before 是定義清單中位置的物件標識碼。 例如，如果您提出清單要求並接收 100 個對象，結尾為 obj_foo，則後續呼叫可以包含 before=obj_foo，以擷取清單的上一頁。

傳回

執行物件的清單。

範例清單執行要求

Python 1.x

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

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

REST

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-05-01-preview

傳回屬於執行的步驟清單。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	執行所屬線程的標識碼。
run_id	字串	必要	與要查詢之執行步驟相關聯的執行標識碼。

查詢參數

名稱	類型​​	必要	描述
limit	整數	選擇性 - 預設值為 20	要傳回之對象的數目限制。 限制的範圍可以介於 1 到 100 之間，預設值為 20。
order	字串	選擇性 - 預設值為 desc	依物件的created_at時間戳排序順序。 遞增順序的 asc 和遞減順序的 desc。
after	字串	選擇性	用於分頁的數據指標。 after 是定義清單中位置的物件標識碼。 例如，如果您提出清單要求並接收 100 個對象，結尾為 obj_foo，則後續呼叫可以包含 after=obj_foo，以擷取清單的下一頁。
before	字串	選擇性	用於分頁的數據指標。 before 是定義清單中位置的物件標識碼。 例如，如果您提出清單要求並接收 100 個對象，結尾為 obj_foo，則後續呼叫可以包含 before=obj_foo，以擷取清單的上一頁。

傳回

執行步驟對象的清單。

範例清單執行步驟要求

Python 1.x

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

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

REST

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

擷取

Python 1.x

from openai import OpenAI
client = OpenAI()

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

print(run)

REST

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

擷取執行。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	執行之線程的標識碼。
run_id	字串	必要	要擷取的執行標識碼。

傳回

符合指定之執行標識碼的執行物件。

範例清單執行步驟要求

Python 1.x

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

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

REST

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

擷取執行步驟。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	執行和執行步驟所屬線程的標識碼。
run_id	字串	必要	執行步驟所屬的執行標識碼。
step_id	字串	必要	要擷取的執行步驟標識碼。

傳回

符合指定標識碼的執行步驟物件。

擷取執行步驟要求的範例

Python 1.x

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

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

REST

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

修改執行。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	執行之線程的標識碼。
run_id	字串	必要	要修改之回合的標識碼。

要求本文

名稱	類型​​	必要	描述
metadata	map	選擇性	可附加至物件的16個索引鍵/值組集合。 這對於以結構化格式儲存物件的其他資訊很有用。 索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

傳回

符合指定標識碼的修改 回合 物件。

修改執行要求的範例

Python 1.x

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

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

REST

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

當執行的狀態為「requires_action」，且required_action.type 已submit_tool_outputs時，此端點就可以用來提交工具呼叫的輸出。一旦全部完成。 所有輸出都必須在單一要求中提交。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	這個執行所屬線程的標識碼。
run_id	字串	必要	需要工具輸出提交的執行標識碼。

要求本文

名稱	類型​​	必要	描述
tool_outputs	陣列	必要	正在提交輸出的工具清單。

傳回

符合指定標識碼的修改 回合 物件。

範例提交工具輸出以執行要求

Python 1.x

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

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)

REST

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

取消in_progress的執行。

路徑參數

參數	類型​	必要	描述
thread_id	string	必要	這個執行所屬線程的標識碼。
run_id	字串	必要	要取消的執行標識碼。

傳回

符合指定標識碼的修改 回合 物件。

範例提交工具輸出以執行要求

Python 1.x

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

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

REST

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

Run 物件

表示線程上的執行。

名稱	類型​​	描述
id	字串	標識碼，可在 API 端點中參考。
object	字串	對象類型，一律為 thread.run。
created_at	整數	建立執行時的 Unix 時間戳（以秒為單位）。
thread_id	字串	執行時執行之線程的識別碼。
assistant_id	字串	用於執行此執行之小幫手的標識碼。
status	字串	執行的狀態，可以是 queued、in_progress、、、requires_action、cancelledcancelling、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	字串	助理用於執行此執行的模型部署名稱。
instructions	字串	助理用於此執行的指示。
tools	陣列	助理用於此執行的工具清單。
file_ids	陣列	用於此執行之助理的檔案識別碼清單。
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	與執行相關的使用量統計數據。 如果執行不是處於終端機狀態，這個值會是 null （例如 in_progress， queued）。

執行步驟物件

表示執行中的步驟。

名稱	類型​​	描述
id	字串	執行步驟的標識碼，可在 API 端點中參考。
object	字串	物件類型，一律為 thread.run.step。
created_at	整數	建立執行步驟時的 Unix 時間戳（以秒為單位）。
assistant_id	字串	與執行步驟相關聯的助理標識碼。
thread_id	字串	執行之線程的標識碼。
run_id	字串	此執行步驟所屬的執行標識碼。
type	字串	執行步驟的類型，可以是message_creation或tool_calls。
status	字串	執行步驟的狀態，可以是in_progress、、cancelledfailed、 completed或 expired。
step_details	object	執行步驟的詳細數據。
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()

訊息差異物件

表示訊息差異。 例如，串流期間訊息上任何已變更的欄位。

名稱	類型​​	描述
id	字串	訊息的標識碼，可在 API 端點中參考。
object	字串	物件類型，一律為 thread.message.delta。
delta	object	差異，包含訊息上已變更的欄位。

執行步驟差異物件

表示執行步驟差異。 例如，串流期間執行步驟上任何已變更的欄位。

名稱	類型​​	描述
id	字串	執行步驟的標識碼，可在 API 端點中參考。
object	字串	物件類型，一律為 thread.run.step.delta。
delta	object	差異，包含執行步驟上已變更的欄位。

小幫手串流事件

表示串流執行時發出的事件。 伺服器傳送事件數據流中的每個事件都有事件和資料屬性：

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]	當數據流結束時發生。