Azure OpenAI Assistants API （預覽版）

助理是 Azure OpenAI 服務的新功能，現在已公開預覽。 小幫手 API 可讓開發人員更輕鬆地建立具有複雜類似警覺體驗的應用程式，以篩選數據、建議解決方案，以及自動化工作。

• 助理可以使用特定指示來呼叫 Azure OpenAI 的 模型 ，以調整其個性和功能。
• 助理可以平行存取多個工具。 這些可以是 Azure OpenAI 裝載的工具，例如程式代碼解釋器和檔案搜尋，或您透過函式呼叫建置、裝載和存取的工具。
• 小幫手可以存取 持續性線程。 線程會藉由儲存訊息歷程記錄，並在對話變得太長而無法讓模型的內容長度過長時加以截斷，來簡化 AI 應用程式開發。 您只要在使用者回復時，就會建立線程一次，並直接將訊息附加至該線程。
• 助理可以存取數種格式的檔案。 無論是在其建立中，還是屬於小幫手與用戶之間的線程。 使用工具時，小幫手也可以建立檔案（例如影像或電子錶格），並在他們建立的訊息中引用檔案。

概觀

先前，即使對於有經驗的開發人員，建置自定義 AI 助理也需要繁重的工作。 雖然聊天完成 API 輕量且強大，但它本質上是無狀態，這表示開發人員必須管理交談狀態和聊天線程、工具整合、擷取檔和索引，以及手動執行程式代碼。

小幫手 API 是聊天完成 API 的具狀態演進，可提供這些挑戰的解決方案。 小幫手 API 支援持續性自動受控線程。 這表示身為開發人員，您不再需要開發對話狀態管理系統，並解決模型的內容窗口條件約束。 小幫手 API 會自動處理優化，以將線程保留在所選模型的最大內容視窗下方。 建立線程之後，只要在用戶回應時，即可將新訊息附加至該線程。 如有需要，小幫手也可以平行存取多個工具。 這些工具包括:

• 程式代碼解釋器
• 函式呼叫

提示

除非您使用程式代碼解釋器或檔案搜尋工具，否則使用小幫手沒有額外的定價或配額。

小幫手 API 是以支援 OpenAI GPT 產品的相同功能所建置。 某些可能的使用案例範圍從 AI 支援的產品推薦、銷售分析師應用程式、程式代碼助理、員工 Q&A 聊天機器人等。 在 Azure OpenAI Studio、AI Studio 的無程式代碼助理遊樂場上開始建置，或開始使用 API 進行建置。

重要

使用函式呼叫、程式代碼解釋器或具有檔案輸入的檔案搜尋來擷取不受信任的數據，以及小幫手線程功能可能會危害助理的安全性，或使用小幫手的應用程式。 在這裡了解風險降低方法。

助理遊樂場

我們在快速入門指南中 提供小幫手遊樂場的逐步解說。 這提供無程式代碼環境來測試助理的功能。

小幫手元件

元件	說明
小幫手	搭配工具使用 Azure OpenAI 模型的自定義 AI。
Thread	小幫手與用戶之間的交談會話。 線程會儲存訊息，並自動處理截斷，以將內容放入模型的內容中。
訊息	小幫手或使用者所建立的訊息。 訊息可以包含文字、影像和其他檔案。 訊息會儲存為線程上的清單。
執行	啟用小幫手，以根據線程的內容開始執行。 小幫手會使用其設定和線程的訊息，藉由呼叫模型和工具來執行工作。 在執行中，小幫手會將訊息附加至線程。
執行步驟	助理參與執行的詳細步驟清單。 助理可以在執行期間呼叫工具或建立訊息。 檢查執行步驟可讓您瞭解小幫手如何取得其最終結果。

助理數據存取

目前，針對小幫手建立的助理、線程、訊息和檔案的範圍在 Azure OpenAI 資源層級。 因此，有權存取 Azure OpenAI 資源或 API 金鑰存取權的任何人都可以讀取/寫入助理、線程、訊息和檔案。

強烈建議使用下列數據訪問控制：

• 實作授權。 在助理、線程、訊息和檔案上執行讀取或寫入之前，請確定終端使用者有權這樣做。
• 限制 Azure OpenAI 資源和 API 金鑰存取。 請仔細考慮誰可以存取正在使用助理的 Azure OpenAI 資源，以及相關聯的 API 密鑰。
• 定期稽核哪些帳戶/個人可以存取 Azure OpenAI 資源。 API 金鑰和資源層級存取可啟用各種作業，包括讀取和修改訊息和檔案。
• 啟用 診斷設定 ，以允許長期追蹤 Azure OpenAI 資源活動記錄的某些層面。

參數

Assistants API 支援數個參數，可讓您自定義小幫手的輸出。 參數 tool_choice 可讓您強制小幫手使用指定的工具。 您也可以使用 角色建立訊息， assistant 以在線程中建立自定義對話歷程記錄。 temperatureresponse_format，top_p可讓您進一步微調回應。 如需詳細資訊，請參閱參考文件。

內容視窗管理

小幫手會自動截斷文字，以確保它停留在模型的內容長度上限內。 您可以藉由指定要執行的最大令牌來利用和/或您想要包含在執行中的最近訊息數目上限，來自定義此行為。

最大完成和最大提示令牌

若要控制單一執行中的權杖使用方式，請在建立執行時設定 max_prompt_tokens 和 max_completion_tokens 。 這些限制適用於整個執行生命週期中所有完成中使用的令牌總數。

例如，起始設定為500且max_completion_tokens設定為1000的 Run max_prompt_tokens 表示第一次完成會將線程截斷為500個令牌，並將輸出上限為1000個令牌。 如果在第一次完成時只使用 200 個提示令牌和 300 個完成令牌，則第二個完成將有 300 個提示令牌和 700 個完成令牌的可用限制。

如果完成達到 max_completion_tokens 限制，Run 將會終止狀態不完整，而且會在 Run 物件的 欄位中提供 incomplete_details 詳細數據。

使用檔案搜尋工具時，建議將 設定 max_prompt_tokens 為不超過 20,000。 針對較長的交談或與檔案搜尋的多次互動，請考慮將此限制增加到 50,000，或理想情況下，移除 max_prompt_tokens 限制以取得最高質量的結果。

截斷策略

您也可以指定截斷策略，以控制線程應如何轉譯至模型的內容視窗。 使用類型的 auto 截斷策略將會使用 OpenAI 的預設截斷策略。 使用類型的 last_messages 截斷策略可讓您指定要包含在內容視窗中的最新訊息數目。

另請參閱

• 深入瞭解助理和 檔案搜尋
• 深入瞭解小幫手和 程式代碼解釋器
• 深入瞭解助理和 函式呼叫
• Azure OpenAI Assistants API 範例