助理 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-08-01-preview
建立執行。
路徑參數
| 參數 | 類型 | 必要 | 描述 |
|---|---|---|---|
thread_id |
string | 必要 | 要為其建立訊息的對話識別碼。 |
要求本文
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
assistant_id |
string | 必要 | 用來執行此執行的助理識別碼。 |
model |
string 或 null | 選擇性 | 要用來執行此執行的模型部署名稱。 在這裡提供的值將會覆寫與助理相關聯的模型部署名稱。 若未提供，則會使用與助理相關聯的模型部署名稱。 |
instructions |
string 或 null | 選擇性 | 覆寫助理的指示。 這有助於修改個別執行的行為。 |
additional_instructions |
字串 | 選擇性 | 在執行的指令結尾附加其他指令。 這有助於修改個別執行的行為，而無須覆寫其他指令。 |
additional_messages |
陣列 | 選擇性 | 在建立執行之前，將其他訊息新增至執行緒。 |
tools |
陣列或 null | 選擇性 | 覆寫助理可用於此執行的工具。 這有助於修改個別執行的行為。 |
metadata |
map | 選擇性 | 可附加至物件的索引鍵/值組 (16 個為一組)。 這有助於以結構化格式儲存物件的其他相關資訊。 索引鍵的長度上限為 64 個字元，而值的長度上限為 512 個字元。 |
temperature |
數值 | 選擇性 | 要使用的取樣溫度，介於 0 到 2 之間。 0.8 之類的較高值會讓輸出更隨機，而 0.2 之類的較低值會使它更集中且具決定性。 預設 為 1。 |
top_p |
數值 | 選擇性 | 核取樣是溫度取樣的替代方法，在此方法中，模型會考慮包含 top_p 機率質量的權杖結果。 因此，0.1 表示只考慮組成前 10% 機率質量的權杖。 一般會建議改變這個值或溫度，但不建議同時改變。 預設 為 1。 |
stream |
boolean | 選用 | 若為 true，則會傳回在以伺服器傳送的事件形式執行期間發生，並在執行進入終端狀態且顯示 data: [DONE] 訊息時終止的事件資料流。 |
max_prompt_tokens |
整數 | 選用 | 在執行過程中可能使用的完成權杖數目上限。 執行會盡可能在多個執行回合中僅使用指定數目的完成權杖。 如果執行超過指定的完成權杖數目，執行將會以狀態 incomplete 結束。 |
max_completion_tokens |
整數 | 選用 | 在執行過程中可能使用的完成權杖數目上限。 執行會盡可能在多個執行回合中僅使用指定數目的完成權杖。 如果執行超過指定的完成權杖數目，執行將會以狀態 incomplete 結束。 |
truncation_strategy |
truncationObject | 選用 | 決定在執行之前如何截斷執行緒的控制項。 使用此項目，可控制執行的初始內容視窗。 |
tool_choice |
字串或物件 | 選用 | 控制模型所呼叫的工具 (若有)。 none 值表示模型不會呼叫工具，而是會產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} 等特定工具，會強制模型呼叫該工具。 |
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-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)
建立執行緒並執行
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/runs?api-version=2024-08-01-preview
在單一要求中建立執行緒並加以執行。
要求本文
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
assistant_id |
string | 必要 | 用來執行此執行的助理識別碼。 |
thread |
object | 選擇性 | |
model |
string 或 null | 選擇性 | 要用來執行此執行的模型部署名稱識別碼。 在這裡提供的值將會覆寫與助理相關聯的模型部署名稱。 若未提供，則會使用與助理相關聯的模型部署名稱。 |
instructions |
string 或 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 |
boolean | 選用 | 若為 true，則會傳回在以伺服器傳送的事件形式執行期間發生，並在執行進入終端狀態且顯示 data: [DONE] 訊息時終止的事件資料流。 |
max_prompt_tokens |
整數 | 選用 | 在執行過程中可能使用的完成權杖數目上限。 執行會盡可能在多個執行回合中僅使用指定數目的完成權杖。 如果執行超過指定的完成權杖數目，執行將會以狀態 incomplete 結束。 |
max_completion_tokens |
整數 | 選用 | 在執行過程中可能使用的完成權杖數目上限。 執行會盡可能在多個執行回合中僅使用指定數目的完成權杖。 如果執行超過指定的完成權杖數目，執行將會以狀態 incomplete 結束。 |
truncation_strategy |
truncationObject | 選用 | 決定在執行之前如何截斷執行緒的控制項。 使用此項目，可控制執行的初始內容視窗。 |
tool_choice |
字串或物件 | 選用 | 控制模型所呼叫的工具 (若有)。 none 值表示模型不會呼叫工具，而是會產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 指定 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}} 等特定工具，會強制模型呼叫該工具。 |
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-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."}
]
}
)
列出執行
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs?api-version=2024-08-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 來擷取清單的上一頁。 |
傳回
執行物件清單。
列出執行要求範例
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)
列出執行步驟
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps?api-version=2024-08-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 來擷取清單的上一頁。 |
傳回
執行步驟物件清單。
列出執行步驟要求範例
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)
擷取執行
from openai import OpenAI
client = OpenAI()
run = client.beta.threads.runs.retrieve(
thread_id="thread_abc123",
run_id="run_abc123"
)
print(run)
擷取執行。
路徑參數
| 參數 | 類型 | 必要 | 描述 |
|---|---|---|---|
thread_id |
string | 必要 | 已執行之執行緒的識別碼。 |
run_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")
)
run = client.beta.threads.runs.retrieve(
thread_id="thread_abc123",
run_id="run_abc123"
)
print(run)
擷取執行步驟
GET https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/steps/{step_id}?api-version=2024-08-01-preview
擷取執行步驟。
路徑參數
| 參數 | 類型 | 必要 | 描述 |
|---|---|---|---|
thread_id |
string | 必要 | 執行和執行步驟所屬的執行緒識別碼。 |
run_id |
字串 | 必要 | 執行步驟所屬的執行識別碼。 |
step_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")
)
run_step = client.beta.threads.runs.steps.retrieve(
thread_id="thread_abc123",
run_id="run_abc123",
step_id="step_abc123"
)
print(run_step)
修改執行
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}?api-version=2024-08-01-preview
修改執行。
路徑參數
| 參數 | 類型 | 必要 | 描述 |
|---|---|---|---|
thread_id |
string | 必要 | 已執行之執行緒的識別碼。 |
run_id |
字串 | 必要 | 要修改的執行識別碼。 |
要求本文
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
metadata |
map | 選擇性 | 可附加至物件的索引鍵/值組 (16 個為一組)。 這有助於以結構化格式儲存物件的其他相關資訊。 索引鍵的長度上限為 64 個字元，而值的長度上限為 512 個字元。 |
傳回
符合指定識別碼的已修改執行物件。
修改執行要求範例
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)
提交要執行的工具輸出
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 時，可使用此端點在工具呼叫全部完成後提交其輸出。 所有輸出必須在單一要求中提交。
路徑參數
| 參數 | 類型 | 必要 | 描述 |
|---|---|---|---|
thread_id |
string | 必要 | 此執行所屬的執行緒識別碼。 |
run_id |
字串 | 必要 | 需要工具輸出提交的執行識別碼。 |
要求本文
| 名稱 | 類型 | 必要 | 描述 |
|---|---|---|---|
tool_outputs |
陣列 | 必要 | 要提交輸出的工具清單。 |
stream |
boolean | 選擇性 | 若為 true，則會傳回在以伺服器傳送的事件形式執行期間發生，並在執行進入終端狀態且顯示 data: [DONE] 訊息時終止的事件資料流。 |
傳回
符合指定識別碼的已修改執行物件。
提交要執行的工具輸出要求範例
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)
取消執行
POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/{thread_id}/runs/{run_id}/cancel?api-version=2024-08-01-preview
取消處於 in_progress 的執行。
路徑參數
| 參數 | 類型 | 必要 | 描述 |
|---|---|---|---|
thread_id |
string | 必要 | 此執行所屬的執行緒識別碼。 |
run_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")
)
run = client.beta.threads.runs.cancel(
thread_id="thread_abc123",
run_id="run_abc123"
)
print(run)
執行物件
代表在執行緒上執行的執行。
| 名稱 | 類型 | 描述 |
|---|---|---|
id |
字串 | 識別碼，可在 API 端點中參考。 |
object |
字串 | 物件類型，一律為 thread.run。 |
created_at |
整數 | 執行建立時的 Unix 時間戳記 (以秒為單位)。 |
thread_id |
字串 | 在此執行的過程中執行之執行緒的識別碼。 |
assistant_id |
字串 | 用來執行此執行的助理識別碼。 |
status |
字串 | 執行的狀態，可以是 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 |
字串 | 助理用於此執行的模型部署名稱。 |
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 | 與執行相關的使用量統計資料。 如果執行並非處於終端狀態 (例如 in_progress、queued)，此值將是 null。 |
truncation_strategy |
object | 決定在執行之前如何截斷執行緒的控制項。 |
response_format |
字串 | 模型必須輸出的格式。 與 GPT-4 Turbo 和 gpt-3.5-turbo-1106 之後的所有 GPT-3.5 Turbo 模型相容。 |
tool_choice |
字串 | 控制模型所呼叫的工具 (若有)。 none 表示模型不會呼叫工具，而是會產生訊息。 auto 是預設值，表示模型可以選擇產生訊息或呼叫工具。 |
執行步驟物件
代表執行中的步驟。
| 名稱 | 類型 | 描述 |
|---|---|---|
id |
字串 | 執行步驟的識別碼，可在 API 端點中參考。 |
object |
字串 | 物件類型，一律為 thread.run.step。 |
created_at |
整數 | 執行步驟建立時的 Unix 時間戳記 (以秒為單位)。 |
assistant_id |
字串 | 與執行步驟相關聯的助理識別碼。 |
thread_id |
字串 | 已執行之執行緒的識別碼。 |
run_id |
字串 | 此執行步驟所屬的執行識別碼。 |
type |
字串 | 執行步驟的類型，可以是 message_creation 或 tool_calls。 |
status |
字串 | 執行步驟的狀態，可以是 in_progress、cancelled、failed、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()
截斷物件
決定在執行之前如何截斷執行緒的控制項。 使用此項目，可控制執行的初始內容視窗。
| 名稱 | 類型 | 描述 | 必要 |
|---|---|---|---|
type |
字串 | 要用於執行緒的截斷策略。 預設值為 auto。 如果設定為 last_messages，執行緒將會截斷為執行緒中的 n 個最新訊息。 設定為 auto 時，將會捨棄執行緒中間的訊息以符合模型的內容長度 max_prompt_tokens。 |
Yes |
last_messages |
整數 | 建構執行的內容時，執行緒中最新的訊息數目。 | No |
訊息差異物件
代表訊息差異。 例如，訊息在串流處理期間的任何欄位變更。
| 名稱 | 類型 | 描述 |
|---|---|---|
id |
字串 | 訊息的識別碼，可在 API 端點中參考。 |
object |
字串 | 物件類型，一律為 thread.message.delta。 |
delta |
object | 包含訊息中已變更欄位的差異。 |
執行步驟差異物件
代表執行步驟差異。 例如，執行步驟在串流處理期間的任何欄位變更。
| 名稱 | 類型 | 描述 |
|---|---|---|
id |
字串 | 執行步驟的識別碼，可在 API 端點中參考。 |
object |
字串 | 物件類型，一律為 thread.run.step.delta。 |
delta |
object | 包含執行步驟中已變更欄位的差異。 |
助理資料流事件
代表在串流執行時發出的事件。 在伺服器傳送的事件資料流中，每個事件都有 event 和 data 屬性：
event: thread.created
data: {"id": "thread_123", "object": "thread", ...}
每當新物件建立、轉換至新狀態，或局部進行串流處理 (差異) 時，就會發出事件。 例如，在新的執行建立時發出 thread.run.created、在執行完成時發出 thread.run.completed，依此類推。 當助理選擇在執行期間建立訊息時，我們會依序發出 thread.message.created 事件、thread.message.in_progress 事件、多個 thread.message.delta 事件，最後發出 thread.message.completed 事件。
| 名稱 | 類型 | 描述 |
|---|---|---|
thread.created |
data 是執行緒。 |
在新的執行緒建立時發生。 |
thread.run.created |
data 是執行。 |
在新的執行建立時發生。 |
thread.run.queued |
data 是執行。 |
在執行進入 queued 狀態時發生。 |
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] |
在資料流結束時發生。 |