小幫手 API （預覽）參考

發行項
06/14/2024

注意

檔案搜尋可以擷取每個助理最多 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 個字元。
file_ids	陣列	選擇性	預設為 []。附加至此小幫手的檔案標識符清單。最多可以附加至助理 20 個檔案。檔案的建立日期會依其建立日期依遞增順序排序。
中繼資料	map	選擇性	可附加至物件的16個索引鍵/值組集合。這對於以結構化格式儲存物件的其他資訊很有用。索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。
溫度	number 或 null	選擇性	預設值為 1。決定要使用的取樣溫度，介於 0 到 2 之間。 0.8 之類的較高值會讓輸出更隨機，而 0.2 之類的較低值會使它更集中且具決定性。
top_p	number 或 null	選擇性	預設值為 1。核取樣是溫度取樣的替代方法，在此方法中，模型會考慮包含 top_p 機率質量的權杖結果。因此，0.1 表示只考慮組成前 10% 機率質量的權杖。一般會建議改變這個值或溫度，但不建議同時改變。
response_format	字串或物件	選擇性	指定模型必須輸出的格式。與 GPT-4 Turbo 和 GPT-3.5 Turbo 模型相容，因為 gpt-3.5-turbo-1106。將此參數設定為 `{ "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-05-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"}]
)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "instructions": "You are an AI assistant that can write code to help answer math questions.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4-1106-preview"
  }'

建立小幫手檔案

POST https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview

將 File 附加至 assistant，以建立小幫手檔案。

路徑參數

參數	類型	必要	描述
`assistant_id`	string	必要	應該附加檔案之小幫手的標識碼。

要求本文

名稱	類型	必要	描述
file_id	字串	必要	助理應該使用的檔案標識碼（purpose=“assistants”）。適用於可存取檔案之code_interpreter等工具。

傳回

助理檔案物件。

建立小幫手檔案要求的範例

Python 1.x
REST

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

assistant_file = client.beta.assistants.files.create(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files?api-version=2024-05-01-preview \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
       "file_id": "assistant-abc123"
     }'

列出助理

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，以擷取清單的上一頁。

傳回

助理物件清單

範例清單助理

Python 1.x
REST

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

my_assistants = client.beta.assistants.list(
    order="desc",
    limit="20",
)
print(my_assistants.data)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?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/assistants/{assistant_id}/files?api-version=2024-05-01-preview

傳回助理檔案的清單。

路徑參數

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

查詢參數

參數	類型	必要	描述
`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，以擷取清單的上一頁。

傳回

助理檔案物件清單

範例清單助理檔案

Python 1.x
REST

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

assistant_files = client.beta.assistants.files.list(
  assistant_id="asst_abc123"
)
print(assistant_files)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files?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/assistants/{assistant_id}?api-version=2024-05-01-preview

擷取助理。

路徑參數

參數	類型	必要	描述
`assistant_id`	string	必要	要擷取之助理的標識碼。

傳回

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

擷取小幫手

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

my_assistant = client.beta.assistants.retrieve("asst_abc123")
print(my_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-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/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview

擷取小幫手檔案。

路徑參數

參數	類型	必要	描述
assistant_id	字串	必要	檔案所屬助理的標識碼。
file_id	字串	必要	我們取得之檔案的標識碼

傳回

符合指定標識碼的助理檔案物件

擷取小幫手檔案範例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

assistant_file = client.beta.assistants.files.retrieve(
  assistant_id="asst_abc123",
  file_id="assistant-abc123"
)
print(assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}/files/{file-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/assistants/{assistant_id}?api-version=2024-05-01-preview

修改助理。

路徑參數

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

要求本文

參數	類型	必要	描述
`model`		選擇性	要使用的模型部署名稱。
`name`	string 或 null	選擇性	助理的名稱。最大長度是 256 個字元。
`description`	string 或 null	選擇性	助理的描述。最大長度為 512 個字元。
`instructions`	string 或 null	選擇性	助理所使用的系統指示。最大長度為 32768 個字元。
`tools`	陣列	選擇性	預設為 []。助理上啟用的工具清單。每個助理最多可以有 128 個工具。工具可以是類型code_interpreter或函式。描述 `function` 最多可以有 1,024 個字元。
`file_ids`	陣列	選擇性	預設為 []。附加至此小幫手的檔案標識符清單。最多可以附加至助理 20 個檔案。檔案的建立日期會依其建立日期依遞增順序排序。如果檔案先前已附加至清單，但未顯示在清單中，則會從助理中刪除該檔案。
`metadata`	map	選擇性	可附加至物件的16個索引鍵/值組集合。這對於以結構化格式儲存物件的其他資訊很有用。索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

傳回

修改過的小幫手物件。

修改小幫手範例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-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
  file_ids=["assistant-abc123", "assistant-abc456"],
)

print(my_updated_assistant)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "code-interpreter"}],
      "model": "gpt-4",
      "file_ids": ["assistant-abc123", "assistant-abc456"]
    }'

刪除小幫手

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}?api-version=2024-05-01-preview

刪除助理。

路徑參數

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

傳回

刪除狀態。

刪除小幫手範例

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

response = client.beta.assistants.delete("asst_abc123")
print(response)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant-id}?api-version=2024-05-01-preview  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

刪除小幫手檔案

DELETE https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview

刪除助理檔案。

路徑參數

參數	類型	必要	描述
`assistant_id`	string	必要	檔案所屬助理的標識碼。
`file_id`	字串	必要	要刪除之檔案的標識碼

傳回

檔案刪除狀態

範例刪除小幫手檔案

Python 1.x
REST

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-05-01-preview",
    azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    )

deleted_assistant_file = client.beta.assistants.files.delete(
    assistant_id="asst_abc123",
    file_id="assistant-abc123"
)
print(deleted_assistant_file)

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants/{assistant_id}/files/{file-id}?api-version=2024-05-01-preview
```  \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -X DELETE

檔案上傳 API 參考

助理會使用相同的 API 進行檔案上傳，就像微調一樣。上傳檔案時，您必須為目的參數指定適當的值。

Assistant 物件

欄位	類型	描述
`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 個字元。
`file_ids`	陣列	附加至此小幫手的檔案標識符清單。最多可以附加至助理 20 個檔案。檔案的建立日期會依其建立日期依遞增順序排序。
`metadata`	map	可附加至物件的16個索引鍵/值組集合。這對於以結構化格式儲存物件的其他資訊很有用。索引鍵長度上限為 64 個字元，且值長度上限為 512 個字元。

小幫手檔案物件

欄位	類型	描述
`id`	字串	標識碼，可在 API 端點中參考。
`object`	字串	物件類型，一律為 `assistant.file`
`created_at`	整數	建立小幫手檔案時的 Unix 時間戳（以秒為單位）。
`assistant_id`	字串	檔案所附加的助理標識碼。

共用方式為

小幫手 API （預覽）參考

建立助理

要求本文

傳回

建立助理要求的範例

建立小幫手檔案

傳回

建立小幫手檔案要求的範例

列出助理

傳回

範例清單助理

列出助理檔案

傳回

範例清單助理檔案

擷取

擷取小幫手

擷取小幫手

傳回

擷取小幫手檔案範例

修改小幫手

修改小幫手範例

刪除小幫手

刪除小幫手範例

刪除小幫手檔案

範例刪除小幫手檔案

檔案上傳 API 參考

Assistant 物件

小幫手檔案物件

意見反應

意見反應

其他資源

共用方式為

小幫手 API （預覽） 參考

建立助理

要求本文

傳回

建立助理要求的範例

建立小幫手檔案

傳回

建立小幫手檔案要求的範例

列出助理

傳回

範例清單助理

列出助理檔案

傳回

範例清單助理檔案

擷取

擷取小幫手

擷取小幫手

傳回

擷取小幫手檔案範例

修改小幫手

修改小幫手範例

刪除小幫手

刪除小幫手範例

刪除小幫手檔案

範例刪除小幫手檔案

檔案上傳 API 參考

Assistant 物件

小幫手檔案物件

意見反應

意見反應

其他資源

小幫手 API （預覽）參考