助理 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 工具則需要向量存放區識別碼的清單。 |