共用方式為

助理 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

使用模型和指示建立助理。

要求本文

名稱 類型​​ 必要 描述
機型 字串 必要 要使用的模型部署名稱。
NAME string 或 null 選擇性 助理的名稱。 最大長度是 256 個字元。
description string 或 null 選擇性 助理的描述。 長度上限為 512 個字元。
指示 string 或 null 選擇性 助理所使用的系統指示。 長度上限為 256,000 個字元。
tools 陣列 選擇性 預設為 []。 在助理上啟用的工具清單。 每個助理最多可以有 128 個工具。 工具目前可以是 code_interpreter 類型或 function。 function 描述最多可以有 1,024 個字元。
中繼資料 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 object 選擇性 助理的工具所使用的一組資源。 工具的類型專用的資源。 例如，code_interpreter 工具需要檔案識別碼的清單，而 file_search 工具則需要向量存放區識別碼的清單。

傳回

助理物件。

建立助理要求的範例

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

傳回所有助理的清單。

查詢參數

參數 類型​ 必要 描述
limit 整數 選擇性 要傳回的物件數目限制。 限制的範圍可以介於 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")
    )

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

擷取助理。

路徑參數

參數 類型​ 必要 描述
assistant_id string 必要 要擷取的助理識別碼。

傳回

符合指定識別碼的助理物件。

擷取助理範例

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

修改助理。

路徑參數

參數 類型​ 必要 描述
assistant_id 字串 必要 檔案所屬助理的識別碼。

要求本文

參數 類型​ 必要 描述
model 選擇性 要使用的模型部署名稱。
name string 或 null 選擇性 助理的名稱。 最大長度是 256 個字元。
description string 或 null 選擇性 助理的描述。 長度上限為 512 個字元。
instructions string 或 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 object 選擇性 助理的工具所使用的一組資源。 工具的類型專用的資源。 例如，code_interpreter 工具需要檔案識別碼的清單，而 file_search 工具則需要向量存放區識別碼的清單。

傳回

修改過的助理物件。

修改助理範例

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

刪除助理。

路徑參數

參數 類型​ 必要 描述
assistant_id string 必要 檔案所屬助理的識別碼。

傳回

刪除狀態。

刪除助理範例

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 字串 識別碼，可在 API 端點中參考。
object 字串 物件類型，一律為助理。
created_at 整數 助理建立時的 Unix 時間戳記 (以秒為單位)。
name string 或 null 助理的名稱。 最大長度是 256 個字元。
description string 或 null 助理的描述。 長度上限為 512 個字元。
model 字串 要使用的模型部署名稱。
instructions string 或 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 object 助理的工具所使用的一組資源。 工具的類型專用的資源。 例如，code_interpreter 工具需要檔案識別碼的清單，而 file_search 工具則需要向量存放區識別碼的清單。