共用方式為


快速入門: 開始使用 Azure OpenAI Assistants (預覽版)

Azure OpenAI Assistants (預覽版) 可讓您使用自訂指示以根據您的需求量身打造 AI 助理,並透過程式碼解釋器和自訂函式等進階工具進行擴增。

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶

  • 在所需的 Azure 訂用帳戶中授與 Azure OpenAI 的存取權。

    目前只有應用程式會授予此服務的存取權。 您可以填妥 https://aka.ms/oai/access 的表單,以申請 Azure OpenAI 的存取權。 如有問題,請在此存放庫中提出問題來與我們連絡。

  • 在支持區域中具有相容模型的 Azure OpenAI 資源。

  • 建議您檢閱負責任 AI 透明度注意事項和其他負責任 AI 資源,以熟悉 Azure OpenAI 服務的功能和限制。

移至 Azure OpenAI Studio

https://oai.azure.com/ 瀏覽至 Azure OpenAI Studio,並使用可存取 OpenAI 資源的認證登入。 在登入工作流程期間 (或之後),選取適當的目錄、Azure 訂用帳戶和 Azure OpenAI 資源。

從 Azure OpenAI Studio 登入頁面的左側導覽啟動 Assistant 的遊樂場,[遊樂場]> [Assistants (預覽版) ]

Azure OpenAI Studio 登陸頁面的螢幕擷取畫面。

遊樂場

Assistants 遊樂場可讓您在無須執行任何程式碼的情況下探索、原型及測試 AI Assistants。 透過此頁面,您可以快速逐一查看並實驗各種功能。

Assistant 設定畫面的螢幕擷取畫面,其中所有的值尚未被填入。

Assistant 設定

使用 [Assistant 設定] 窗格來建立新的 AI 助理,或選取現有的助理。

名稱 說明
Assistant 名稱 與特定模型相關的部署名稱。
指示 指示和系統訊息相似,並且提供模型關於其行為方式的指引,以及產生回應時應該參考的任何內容。 您可以描述助理的特質、告訴其應該和不應該回答的內容,以及如何格式化回應。 您也可以提供答覆回應時應採取的步驟範例。
[部署] 您可以在此設定要與助理搭配使用的模型部署。
函數 為模型建立自訂函式定義,以根據您的規格制定 API 呼叫和結構資料輸出。
程式碼解譯器 程式碼解釋器可讓您存取 Python 沙箱環境,並用於允許模型測試和執行程式碼。
檔案 您可以上傳最多 20 個檔案,檔案大小限制為 512 MB,以便與工具搭配使用。

工具

個別助理最多可以存取 128 個工具,包含 code interpreter,以及您透過函式所建立的任何自訂工具。

聊天工作階段

聊天工作階段,也就是 Assistant's API 中的執行緒,是使用者與助理之間進行交談的地方。 不同於傳統的聊天完成呼叫,執行緒中的訊息數量沒有限制。 助理會自動壓縮要求,以符合模型的輸入權杖限制。

這也表示在每個交談回合內,您不會控制有多少權杖傳遞至模型。 管理權杖會被分離出來,並完全由 Assistants API 處理。

選取 [清除聊天] 按鈕,以刪除目前的交談歷程記錄。

在文字輸入方塊下方有兩個按鈕:

  • 在不執行的情況下新增訊息。
  • 新增並執行。

記錄

記錄會提供助理 API 活動的詳細快照集。

顯示面板

根據預設,有三個面板: 助理設定、聊天工作階段和記錄。 [顯示面板] 可讓您新增、移除和重新排列面板。 如果關閉面板後您需要將其還原,請使用 [顯示面板] 來還原遺失的面板。

建立您的第一個助理

  1. 從助理設定的下拉式清單中,選取 [新增]

  2. 為您的助理命名

  3. 輸入下列指示: 「您是協助回答數學問題的可撰寫程式碼 AI 助理」

  4. 選取 gpt-4 (1106-preview) 的部署。 下拉式清單會顯示您的自訂部署名稱,因此如果您的模型/部署名稱不同,您應該選擇一個基礎模型與 1106 預覽模型相同的部署。

  5. 選取啟用程式碼解釋器的切換。

  6. 選取 [儲存]。

    已輸入設定詳細資料的助理螢幕擷取畫面。

  7. 輸入您想讓助理回答的問題: 「我需要解決 3x + 11 = 14 此方程式。 可以請您提供協助嗎?」

  8. 選取 [新增並執行] 按鈕

    The solution to the equation (3x + 11 = 14) is (x = 1).
    

    雖然我們可以看到答案為正確,但若要確認模型是使用程式碼解釋器取得此答案,且所撰寫的程式碼有效,而非重複來自模型訓練資料的答案,我們會另外詢問一個問題。

  9. 輸入後續問題: 「顯示您在取得此解決方案時所執行的程式碼。」

    Certainly! Here's the Python code I ran to find the solution for the equation (3x + 11 = 14):
    
    from sympy import symbols, Eq, solve  
    
    # Define the variable  
    x = symbols('x')  
    
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
    
    # Solve the equation  
    solution = solve(equation, x)  
    solution  
    

Assistant 遊樂場中交談工作階段的螢幕擷取畫面。

您也可以參閱右側面板中的記錄,確認已使用過程式碼解釋器,並驗證產生回應所執行的程式碼。 請務必記住,雖然程式碼解釋器讓模型能夠藉由將問題轉換成程式碼並在 Python 沙盒環境中執行,以回應更複雜的數學問題,但您仍然需要驗證回應,以確認模型正確地將您的問題轉譯成程式碼中的有效表示法。

清除資源

如果您想要清除和移除 Azure OpenAI 資源,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

另請參閱

重要

本文所述的部分功能可能僅適用於預覽版。 此預覽版本沒有服務等級協定,不建議將其用於生產工作負載。 可能不支援特定功能,或可能已經限制功能。 如需詳細資訊,請參閱 Microsoft Azure 預覽版增補使用條款

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶

  • 在所需的 Azure 訂用帳戶中授與 Azure OpenAI 的存取權。

    目前只有應用程式會授予此服務的存取權。 您可以填妥 https://aka.ms/oai/access 的表單,以申請 Azure OpenAI 的存取權。 如有問題,請在此存放庫中提出問題來與我們連絡。

  • 內含已部署模型的 Azure AI 中樞資源。 如需模型部署的詳細資訊,請參閱資源部署指南

  • Azure AI Studio 中的 Azure AI 專案

前往 Azure AI Studio (預覽版)

  1. 登入 Azure AI Studio

  2. 移至專案,或在 Azure AI Studio 中建立新專案

  3. 在您的專案概觀中,選取位於 [專案遊樂場] 底下的[Assistants]

    Assistants 遊樂場可讓您在無須執行任何程式碼的情況下探索、原型及測試 AI Assistants。 透過此頁面,您可以快速逐一查看並實驗各種功能。

    遊樂場提供數種設定 Assistant 的選項。 在下列步驟中,您將使用 [Assistant 設定] 窗格來建立新的 AI 助理。

    名稱 說明
    Assistant 名稱 與特定模型相關的部署名稱。
    指示 指示和系統訊息相似,並且提供模型關於其行為方式的指引,以及產生回應時應該參考的任何內容。 您可以描述助理的特質、告訴其應該和不應該回答的內容,以及如何格式化回應。 您也可以提供答覆回應時應採取的步驟範例。
    [部署] 您可以在此設定要與助理搭配使用的模型部署。
    函數 為模型建立自訂函式定義,以根據您的規格制定 API 呼叫和結構資料輸出。 不在本快速入門中使用。
    程式碼解譯器 程式碼解釋器可讓您存取 Python 沙箱環境,並用於允許模型測試和執行程式碼。
    檔案 您可以上傳最多 20 個檔案,檔案大小限制為 512 MB,以便與工具搭配使用。 不在本快速入門中使用。

    Assistant 設定畫面的螢幕擷取畫面,其中所有的值尚未被填入。

建立您的第一個 Assistant

  1. 從 [部署] 下拉式功能表中選取部署。

  2. 從 Assistant 設定的下拉式清單中,選取 [新增]

  3. 為您的 Assistant 命名

  4. 輸入下列指示: 「您是協助回答數學問題的可撰寫程式碼 AI 助理」

  5. 選取模型部署。 我們建議使用其中一個最新的 gpt-4 模型進行測試。

  6. 選取啟用程式碼解釋器的切換。

  7. 選取 [儲存]。

    已輸入設定詳細資料的助理螢幕擷取畫面。

  8. 輸入您想讓助理回答的問題: 「我需要解決 3x + 11 = 14 此方程式。 可以請您提供協助嗎?」

  9. 選取 [新增並執行] 按鈕

    The solution to the equation (3x + 11 = 14) is (x = 1).
    

    雖然我們可以看到答案為正確,但若要確認模型是使用程式碼解釋器取得此答案,且所撰寫的程式碼有效,而非重複來自模型訓練資料的答案,我們會另外詢問一個問題。

  10. 輸入後續問題: 「顯示您在取得此解決方案時所執行的程式碼。」

    Sure. The code is very straightforward
    
    # calculation
    x = (14 - 11) / 3
    x
    
    
    First, we subtract 11 from 14, then divide the result by 3. This gives us the value of x which is 1.0.
    

    Assistant 遊樂場中交談工作階段的螢幕擷取畫面。

您也可以參閱右側面板中的記錄,確認已使用過程式碼解釋器,並驗證產生回應所執行的程式碼。 請務必記住,雖然程式碼解釋器讓模型能夠藉由將問題轉換成程式碼並在 Python 沙盒環境中執行,以回應更複雜的數學問題,但您仍然需要驗證回應,以確認模型正確地將您的問題轉譯成程式碼中的有效表示法。

重要概念

使用 Assistant 遊樂場時,請記住下列概念。

工具

個別助理最多可以存取 128 個工具,包含 code interpreter,以及您透過函式所建立的任何自訂工具。

聊天工作階段

聊天工作階段,也就是 Assistant's API 中的執行緒,是使用者與助理之間進行交談的地方。 不同於傳統的聊天完成呼叫,執行緒中的訊息數量沒有限制。 助理會自動壓縮要求,以符合模型的輸入權杖限制。

這也表示在每個交談回合內,您不會控制有多少權杖傳遞至模型。 管理權杖會被分離出來,並完全由 Assistants API 處理。

選取 [清除聊天] 按鈕,以刪除目前的交談歷程記錄。

在文字輸入方塊下方有兩個按鈕:

  • 在不執行的情況下新增訊息。
  • 新增並執行。

記錄

記錄會提供助理 API 活動的詳細快照集。

顯示面板

根據預設,有三個面板: 助理設定、聊天工作階段和記錄。 [顯示面板] 可讓您新增、移除和重新排列面板。 如果關閉面板後您需要將其還原,請使用 [顯示面板] 來還原遺失的面板。

清除資源

如果您想要清除和移除 Azure OpenAI 資源,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

或者,您也可以透過 [Assistant 的 API]來刪除 [助理] 或 [執行緒]

另請參閱

參考文件 | 程式庫原始程式碼 | 套件 (PyPi) |

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶

  • 在所需的 Azure OpenAI 訂用帳戶中授與服務的存取權

    目前只有應用程式會授予此服務的存取權。 您可以填妥 https://aka.ms/oai/access 的表單,以申請 Azure OpenAI 的存取權。 如有問題,請在此存放庫中提出問題來與我們連絡。

  • Python 3.8 或較新版本

  • 下列 Python 連結庫:os、openai(需要 1.x 版)

  • Azure CLI 用於本地開發環境中的無密碼驗證,請使用 Azure CLI 登入以建立必要內容。

  • 在支持區域中具有相容模型的 Azure OpenAI 資源。

  • 建議您檢閱負責任 AI 透明度注意事項和其他負責任 AI 資源,以熟悉 Azure OpenAI 服務的功能和限制。

  • 在測試此範例時,使用了已部署 gpt-4 (1106-preview) 模型的 Azure OpenAI 資源。

若要設定無密碼驗證,您必須:

  1. 使用 azure-identity 套件。
  2. Cognitive Services User 角色指派給您的使用者帳戶。 這可以在 Azure 入口網站底下的 [存取控制 (IAM)]> [新增角色指派] 中完成。
  3. 使用 Azure CLI 登入,例如 az login

設定

  1. 使用下列項目安裝 OpenAI Python 用戶端程式庫:
pip install openai
  1. 若要設定建議的無密碼驗證:
pip install azure-identity

注意

  • 檔案搜尋 可以擷取每個助理最多 10,000 個檔案 - 比之前多 500 倍。 其速度很快,可透過多線程搜尋支援平行查詢,以及增強重新撰寫和查詢重寫的功能。
    • 向量存放區是 API 中的新物件。 一旦檔案新增至向量存放區,它就會自動剖析、區塊化和內嵌,準備好進行搜尋。 向量存放區可以跨助理和線程使用,簡化檔案管理和計費。
  • 我們已新增參數的支援 tool_choice ,可用來強制在特定執行中使用特定工具(例如檔案搜尋、程式代碼解釋器或函式)。

注意

程式庫是由 OpenAI 進行維護。 參照版本歷程記錄來追蹤程式庫的最新更新。

擷取金鑰和端點

若要成功對 Azure OpenAI 服務發出呼叫,您將需要下列項目:

變數名稱
ENDPOINT 在 Azure 入口網站查看資源時,您可以在 [金鑰和端點] 區段中找到此值。 或者,您可以在 [Azure OpenAI Studio]>[遊樂場]>[檢視程式碼] 中找到該值。 範例端點為:https://docs-test-001.openai.azure.com/
API-KEY 在 Azure 入口網站查看資源時,您可以在 [金鑰和端點] 區段中找到此值。 您可以使用 KEY1KEY2
DEPLOYMENT-NAME 此值會對應至您在部署模型時為部署選擇的自訂名稱。 此值可以在 Azure 入口網站中的 [資源管理模型]>[部署] 底下找到,也可以在 Azure OpenAI Studio 的 [管理]>[部署]下找到。

移至您在 Azure 入口網站中的資源。 您可以在 [資源管理] 區段中找到 [金鑰和端點]。 複製您的端點和存取金鑰,因為您需要這兩者才能驗證 API 呼叫。 您可以使用 KEY1KEY2。 隨時持有兩個金鑰可讓您安全地輪替和重新產生金鑰,而不會造成服務中斷。

Azure 入口網站中 OpenAI 資源的概觀刀鋒視窗螢幕擷取畫面,畫面中端點和存取金鑰位置以紅色圓圈強調。

為您的金鑰和端點建立及指派永續性環境變數。

環境變數

為您的金鑰和端點建立及指派永續性環境變數。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

建立助理

在程式碼中,我們將指定下列值:

名稱 說明
Assistant 名稱 與特定模型相關的部署名稱。
指示 指示和系統訊息相似,並且提供模型關於其行為方式的指引,以及產生回應時應該參考的任何內容。 您可以描述助理的特質、告訴其應該和不應該回答的內容,以及如何格式化回應。 您也可以提供答覆回應時應採取的步驟範例。
模型 您可以在此設定要與助理搭配使用的模型部署。 擷取工具需要 gpt-35-turbo (1106)gpt-4 (1106-preview) 模型。 將此值設定為部署名稱,而不是模型名稱,除非兩者名稱相同。
程式碼解譯器 程式碼解釋器可讓您存取 Python 沙箱環境,並用於允許模型測試和執行程式碼。

工具

個別助理最多可以存取 128 個工具,包含 code interpreter,以及您透過函式所建立的任何自訂工具。

建立 Python 應用程式

使用 來登入 Azure az login ,然後使用下列 建議 的無密碼 Python 範例建立並執行小幫手:

import os
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import AzureOpenAI

token_provider = get_bearer_token_provider(DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default")

client = AzureOpenAI(
    azure_ad_token_provider=token_provider,
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    api_version="2024-05-01-preview",
)

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

若要使用服務 API 金鑰進行驗證,您可以使用下列 Python 範例來建立並執行小幫手:

import os
from openai import AzureOpenAI

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

# Create an assistant
assistant = client.beta.assistants.create(
    name="Math Assist",
    instructions="You are an AI assistant that can write code to help answer math questions.",
    tools=[{"type": "code_interpreter"}],
    model="gpt-4-1106-preview" # You must replace this value with the deployment name for your model.
)

# Create a thread
thread = client.beta.threads.create()

# Add a user question to the thread
message = client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="I need to solve the equation `3x + 11 = 14`. Can you help me?"
)

# Run the thread and poll for the result
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
    instructions="Please address the user as Jane Doe. The user has a premium account.",
)

print("Run completed with status: " + run.status)

if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    print(messages.to_json(indent=2))

輸出

執行已完成,狀態為:已完成

{
  "data": [
    {
      "id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
      "assistant_id": "asst_cYqL1RuwLyFV3HU1gkaE2k0K",
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
          },
          "type": "text"
        }
      ],
      "created_at": 1716397091,
      "metadata": {},
      "object": "thread.message",
      "role": "assistant",
      "run_id": "run_hFgBPbUtO8ZNTnNPC8PgpH1S",
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    },
    {
      "id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
      "assistant_id": null,
      "attachments": [],
      "content": [
        {
          "text": {
            "annotations": [],
            "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
          },
          "type": "text"
        }
      ],
      "created_at": 1716397025,
      "metadata": {},
      "object": "thread.message",
      "role": "user",
      "run_id": null,
      "thread_id": "thread_isb7spwRycI5ueT9E7357aOm"
    }
  ],
  "object": "list",
  "first_id": "msg_4SuWxTubHsHpt5IlBTO5Hyw9",
  "last_id": "msg_Z32w2E7kY5wEWhZqQWxIbIUB",
  "has_more": false
}

瞭解瞭解您的結果

在此範例中,我們會建立已啟用程式碼解釋器的助理。 當我們詢問數學問題時,助理會將問題轉譯為 Python 程式碼,並在沙盒環境中執行程式碼,以判斷問題的答案。 由模型所建立並測試以取得答案的程式碼為:

from sympy import symbols, Eq, solve  
  
# Define the variable  
x = symbols('x')  
  
# Define the equation  
equation = Eq(3*x + 11, 14)  
  
# Solve the equation  
solution = solve(equation, x)  
solution  

請務必記住,雖然程式碼解釋器讓模型能夠藉由將問題轉換成程式碼,並在 Python 沙盒環境中反覆執行直到取得解決方案,以回應更複雜的查詢,但您仍然需要驗證回應,以確認模型正確地將您的問題轉譯成程式碼中的有效表示法。

清除資源

如果您想要清除和移除 Azure OpenAI 資源,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

另請參閱

參考文件 | 原始程式碼 | 套件 (NuGet)

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶

  • 在所需的 Azure OpenAI 訂用帳戶中授與服務的存取權

    目前只有應用程式會授予此服務的存取權。 您可以填妥 https://aka.ms/oai/access 的表單,以申請 Azure OpenAI 的存取權。 如有問題,請在此存放庫中提出問題來與我們連絡。

  • .NET 8 SDK

  • 在支持區域中具有相容模型的 Azure OpenAI 資源。

  • 建議您檢閱負責任 AI 透明度注意事項和其他負責任 AI 資源,以熟悉 Azure OpenAI 服務的功能和限制。

  • 在測試此範例時,使用了已部署 gpt-4 (1106-preview) 模型的 Azure OpenAI 資源。

設定

建立新的 .NET Core 應用程式

在主控台視窗中 (例如 cmd、PowerShell 或 Bash),使用 dotnet new 命令建立名為 azure-openai-quickstart 的新主控台應用程式。 此命令會建立簡單的 "Hello World" 專案,內含單一 C# 來源檔案:Program.cs

dotnet new console -n azure-openai-assistants-quickstart

將目錄變更為新建立的應用程式資料夾。 您可以使用下列命令來建置應用程式:

dotnet build

建置輸出應該不會有警告或錯誤。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

使用下列項目安裝 OpenAI .NET 用戶端程式庫:

dotnet add package Azure.AI.OpenAI.Assistants --prerelease

擷取金鑰和端點

若要成功對 Azure OpenAI 進行呼叫,您需要端點金鑰

變數名稱
ENDPOINT 從 Azure 入口網站查看您的資源時,可以在 [金鑰與端點] 區段中找到此值。 或者,您可以在 [Azure OpenAI Studio]>[遊樂場]>[程式碼檢視] 中找到該值。 範例端點為:https://docs-test-001.openai.azure.com/
API-KEY 從 Azure 入口網站查看您的資源時,可以在 [金鑰與端點] 區段中找到此值。 您可以使用 KEY1KEY2

移至您在 Azure 入口網站中的資源。 您可以在 [資源管理] 區段中找到 [金鑰和端點] 區段。 複製您的端點和存取金鑰,因為您需要這兩者才能驗證 API 呼叫。 您可以使用 KEY1KEY2。 隨時持有兩個金鑰可讓您安全地輪替和重新產生金鑰,而不會造成服務中斷。

Azure 入口網站中某個 Azure OpenAI 資源,以紅色圓圈強調端點和存取金鑰位置的概觀使用者介面螢幕擷取畫面。

環境變數

為您的金鑰和端點建立及指派永續性環境變數。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

建立助理

在程式碼中,我們將指定下列值:

名稱 說明
Assistant 名稱 與特定模型相關的部署名稱。
指示 指示和系統訊息相似,並且提供模型關於其行為方式的指引,以及產生回應時應該參考的任何內容。 您可以描述助理的特質、告訴其應該和不應該回答的內容,以及如何格式化回應。 您也可以提供答覆回應時應採取的步驟範例。
模型 您可以在此設定要與助理搭配使用的模型部署。 擷取工具需要 gpt-35-turbo (1106)gpt-4 (1106-preview) 模型。 將此值設定為部署名稱,而不是模型名稱,除非兩者名稱相同。
程式碼解譯器 程式碼解釋器可讓您存取 Python 沙箱環境,並用於允許模型測試和執行程式碼。

工具

個別助理最多可以存取 128 個工具,包含 code interpreter,以及您透過函式所建立的任何自訂工具。

使用下列程式碼建立並執行助理:

using Azure;
using Azure.AI.OpenAI.Assistants;

string endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new ArgumentNullException("AZURE_OPENAI_ENDPOINT");
string key = Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY") ?? throw new ArgumentNullException("AZURE_OPENAI_API_KEY");
AssistantsClient client = new AssistantsClient(new Uri(endpoint), new AzureKeyCredential(key));

// Create an assistant
Assistant assistant = await client.CreateAssistantAsync(
    new AssistantCreationOptions("gpt-4-1106-preview") // Replace this with the name of your model deployment
    {
        Name = "Math Tutor",
        Instructions = "You are a personal math tutor. Write and run code to answer math questions.",
        Tools = { new CodeInterpreterToolDefinition() }
    });

// Create a thread
AssistantThread thread = await client.CreateThreadAsync();

// Add a user question to the thread
ThreadMessage message = await client.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "I need to solve the equation `3x + 11 = 14`. Can you help me?");

// Run the thread
ThreadRun run = await client.CreateRunAsync(
    thread.Id,
    new CreateRunOptions(assistant.Id)
);

// Wait for the assistant to respond
do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    run = await client.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued
    || run.Status == RunStatus.InProgress);

// Get the messages
PageableList<ThreadMessage> messagesPage = await client.GetMessagesAsync(thread.Id);
IReadOnlyList<ThreadMessage> messages = messagesPage.Data;

// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
foreach (ThreadMessage threadMessage in messages.Reverse())
{
    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
    foreach (MessageContent contentItem in threadMessage.ContentItems)
    {
        if (contentItem is MessageTextContent textItem)
        {
            Console.Write(textItem.Text);
        }
        Console.WriteLine();
    }
}

這會產生如下所示的輸出:

2024-03-05 03:38:17 -       user: I need to solve the equation `3x + 11 = 14`. Can you help me?
2024-03-05 03:38:25 -  assistant: The solution to the equation \(3x + 11 = 14\) is \(x = 1\).

在重新執行之前,您可以在執行緒上建立新訊息,助理會使用過去的訊息來做為執行緒中的內容。

清除資源

如果您想要清除和移除 Azure OpenAI 資源,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

另請參閱

參考文件 | 程式庫原始程式碼 | 套件 (npm) |

必要條件

若要設定無密碼驗證,您必須:

  1. 使用 @azure/identity 套件。
  2. Cognitive Services User 角色指派給您的使用者帳戶。 這可以在 Azure 入口網站底下的 [存取控制 (IAM)]> [新增角色指派] 中完成。
  3. 使用 Azure CLI 登入,例如 az login

設定

  1. 使用以下程式碼以安裝適用於 JavaScript 的 OpenAI Assistants 用戶端程式庫:

    npm install openai
    
  2. 若要設定建議的無密碼驗證:

    npm install @azure/identity
    

擷取金鑰和端點

若要成功對 Azure OpenAI 服務發出呼叫,您將需要下列項目:

變數名稱
ENDPOINT 在 Azure 入口網站查看資源時,您可以在 [金鑰和端點] 區段中找到此值。 或者,您可以在 [Azure OpenAI Studio]>[遊樂場]>[檢視程式碼] 中找到該值。 範例端點為:https://docs-test-001.openai.azure.com/
API-KEY 在 Azure 入口網站查看資源時,您可以在 [金鑰和端點] 區段中找到此值。 您可以使用 KEY1KEY2
DEPLOYMENT-NAME 此值會對應至您在部署模型時為部署選擇的自訂名稱。 此值可以在 Azure 入口網站中的 [資源管理模型]>[部署] 底下找到,也可以在 Azure OpenAI Studio 的 [管理]>[部署]下找到。

移至您在 Azure 入口網站中的資源。 您可以在 [資源管理] 區段中找到 [金鑰和端點]。 複製您的端點和存取金鑰,因為您需要這兩者才能驗證 API 呼叫。 您可以使用 KEY1KEY2。 隨時持有兩個金鑰可讓您安全地輪替和重新產生金鑰,而不會造成服務中斷。

Azure 入口網站中 OpenAI 資源的概觀刀鋒視窗螢幕擷取畫面,畫面中端點和存取金鑰位置以紅色圓圈強調。

為您的金鑰和端點建立及指派永續性環境變數。

環境變數

為您的金鑰和端點建立及指派永續性環境變數。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

為部署名稱和 API 版本新增其他環境變數:

  • AZURE_OPENAI_DEPLOYMENT_NAME:部署名稱,如 Azure 入口網站 所示。
  • OPENAI_API_VERSION:深入瞭解 API 版本

為您的金鑰和端點建立及指派永續性環境變數。

setx AZURE_OPENAI_DEPLOYMENT_NAME "REPLACE_WITH_YOUR_DEPLOYMENT_NAME" 
setx OPENAI_API_VERSION "REPLACE_WITH_YOUR_API_VERSION" 

建立助理

在程式碼中,我們將指定下列值:

名稱 說明
Assistant 名稱 與特定模型相關的部署名稱。
指示 指示和系統訊息相似,並且提供模型關於其行為方式的指引,以及產生回應時應該參考的任何內容。 您可以描述助理的特質、告訴其應該和不應該回答的內容,以及如何格式化回應。 您也可以提供答覆回應時應採取的步驟範例。
模型 這是部署名稱。
程式碼解譯器 程式碼解釋器可讓您存取 Python 沙箱環境,並用於允許模型測試和執行程式碼。

工具

個別助理最多可以存取 128 個工具,包含 code interpreter,以及您透過函式所建立的任何自訂工具。

使用 az login 登入 Azure,然後使用下列建議無密碼 TypeScript 模組以建立並執行助理 (index.ts):

import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Add `Cognitive Services User` to identity for Azure OpenAI resource
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from "@azure/identity";

// Get environment variables
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please ensure to set AZURE_OPENAI_DEPLOYMENT_NAME and AZURE_OPENAI_ENDPOINT in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const credential = new DefaultAzureCredential();
  const scope = "https://cognitiveservices.azure.com/.default";
  const azureADTokenProvider = getBearerTokenProvider(credential, scope);
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    azureADTokenProvider,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

若要使用服務金鑰進行驗證,您可以使用下列 TypeScript 模組建立並執行助理 (index.ts):

import "dotenv/config";
import { AzureOpenAI } from "openai";
import {
  Assistant,
  AssistantCreateParams,
  AssistantTool,
} from "openai/resources/beta/assistants";
import { Message, MessagesPage } from "openai/resources/beta/threads/messages";
import { Run } from "openai/resources/beta/threads/runs/runs";
import { Thread } from "openai/resources/beta/threads/threads";

// Get environment variables
const azureOpenAIKey = process.env.AZURE_OPENAI_KEY as string;
const azureOpenAIEndpoint = process.env.AZURE_OPENAI_ENDPOINT as string;
const azureOpenAIDeployment = process.env
  .AZURE_OPENAI_DEPLOYMENT_NAME as string;
const openAIVersion = process.env.OPENAI_API_VERSION as string;

// Check env variables
if (!azureOpenAIKey || !azureOpenAIEndpoint || !azureOpenAIDeployment || !openAIVersion) {
  throw new Error(
    "Please set AZURE_OPENAI_KEY and AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT_NAME in your environment variables."
  );
}

// Get Azure SDK client
const getClient = (): AzureOpenAI => {
  const assistantsClient = new AzureOpenAI({
    endpoint: azureOpenAIEndpoint,
    apiVersion: openAIVersion,
    apiKey: azureOpenAIKey,
  });
  return assistantsClient;
};

const assistantsClient = getClient();

const options: AssistantCreateParams = {
  model: azureOpenAIDeployment, // Deployment name seen in Azure AI Studio
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run JavaScript code to answer math questions.",
  tools: [{ type: "code_interpreter" } as AssistantTool],
};
const role = "user";
const message = "I need to solve the equation `3x + 11 = 14`. Can you help me?";

// Create an assistant
const assistantResponse: Assistant =
  await assistantsClient.beta.assistants.create(options);
console.log(`Assistant created: ${JSON.stringify(assistantResponse)}`);

// Create a thread
const assistantThread: Thread = await assistantsClient.beta.threads.create({});
console.log(`Thread created: ${JSON.stringify(assistantThread)}`);

// Add a user question to the thread
const threadResponse: Message =
  await assistantsClient.beta.threads.messages.create(assistantThread.id, {
    role,
    content: message,
  });
console.log(`Message created:  ${JSON.stringify(threadResponse)}`);

// Run the thread and poll it until it is in a terminal state
const runResponse: Run = await assistantsClient.beta.threads.runs.createAndPoll(
  assistantThread.id,
  {
    assistant_id: assistantResponse.id,
  },
  { pollIntervalMs: 500 }
);
console.log(`Run created:  ${JSON.stringify(runResponse)}`);

// Get the messages
const runMessages: MessagesPage =
  await assistantsClient.beta.threads.messages.list(assistantThread.id);
for await (const runMessageDatum of runMessages) {
  for (const item of runMessageDatum.content) {
    // types are: "image_file" or "text"
    if (item.type === "text") {
      console.log(`Message content: ${JSON.stringify(item.text?.value)}`);
    }
  }
}

輸出

Assistant created: {"id":"asst_zXaZ5usTjdD0JGcNViJM2M6N","createdAt":"2024-04-08T19:26:38.000Z","name":"Math Tutor","description":null,"model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"fileIds":[],"metadata":{}}
Thread created: {"id":"thread_KJuyrB7hynun4rvxWdfKLIqy","createdAt":"2024-04-08T19:26:38.000Z","metadata":{}}
Message created:  {"id":"msg_o0VkXnQj3juOXXRCnlZ686ff","createdAt":"2024-04-08T19:26:38.000Z","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","role":"user","content":[{"type":"text","text":{"value":"I need to solve the equation `3x + 11 = 14`. Can you help me?","annotations":[]},"imageFile":{}}],"assistantId":null,"runId":null,"fileIds":[],"metadata":{}}
Created run
Run created:  {"id":"run_P8CvlouB8V9ZWxYiiVdL0FND","object":"thread.run","status":"queued","model":"daisy","instructions":"You are a personal math tutor. Write and run JavaScript code to answer math questions.","tools":[{"type":"code_interpreter"}],"metadata":{},"usage":null,"assistantId":"asst_zXaZ5usTjdD0JGcNViJM2M6N","threadId":"thread_KJuyrB7hynun4rvxWdfKLIqy","fileIds":[],"createdAt":"2024-04-08T19:26:39.000Z","expiresAt":"2024-04-08T19:36:39.000Z","startedAt":null,"completedAt":null,"cancelledAt":null,"failedAt":null}
Message content: "The solution to the equation \\(3x + 11 = 14\\) is \\(x = 1\\)."
Message content: "Yes, of course! To solve the equation \\( 3x + 11 = 14 \\), we can follow these steps:\n\n1. Subtract 11 from both sides of the equation to isolate the term with x.\n2. Then, divide by 3 to find the value of x.\n\nLet me calculate that for you."
Message content: "I need to solve the equation `3x + 11 = 14`. Can you help me?"

請務必記住,雖然程式碼解釋器讓模型能夠藉由將問題轉換成程式碼,並在 JavaScript 中反覆執行直到取得解決方案,以回應更複雜的查詢,但您仍然需要驗證回應,以確認模型正確地將您的問題轉譯成程式碼中的有效表示法。

清除資源

如果您想要清除和移除 Azure OpenAI 資源,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

範例指令碼

另請參閱

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶

  • 在所需的 Azure OpenAI 訂用帳戶中授與服務的存取權

    目前只有應用程式會授予此服務的存取權。 您可以填妥 https://aka.ms/oai/access 的表單,以申請 Azure OpenAI 服務的存取權。 如有問題,請在此存放庫中提出問題來與我們連絡。

  • Python 3.8 或較新版本

  • 在支持區域中具有相容模型的 Azure OpenAI 資源。

  • 建議您檢閱負責任 AI 透明度注意事項和其他負責任 AI 資源,以熟悉 Azure OpenAI 服務的功能和限制。

  • 在測試此範例時,使用了已部署 gpt-4 (1106-preview) 模型的 Azure OpenAI 資源。

設定

擷取金鑰和端點

若要成功對 Azure OpenAI 發出呼叫,您將需要下列項目:

變數名稱
ENDPOINT 從 Azure 入口網站查看您的資源時,可以在 [金鑰與端點] 區段中找到此值。 或者,您可以在 [Azure OpenAI Studio]>[遊樂場]>[程式碼檢視] 中找到該值。 範例端點為:https://docs-test-001.openai.azure.com/
API-KEY 從 Azure 入口網站查看您的資源時,可以在 [金鑰與端點] 區段中找到此值。 您可以使用 KEY1KEY2
DEPLOYMENT-NAME 此值會對應至您在部署模型時為部署選擇的自訂名稱。 此值可以在 Azure 入口網站中的 [資源管理]>[部署] 底下找到,也可以在 Azure OpenAI Studio 的 [管理]>[部署]下找到。

移至您在 Azure 入口網站中的資源。 您可以在 [資源管理] 區段中找到 [端點和金鑰]。 複製您的端點和存取金鑰,因為您需要這兩者才能驗證 API 呼叫。 您可以使用 KEY1KEY2。 隨時持有兩個金鑰可讓您安全地輪替和重新產生金鑰,而不會造成服務中斷。

Azure 入口網站中 OpenAI 資源的概觀刀鋒視窗螢幕擷取畫面,畫面中端點和存取金鑰位置以紅色圓圈強調。

為您的金鑰和端點建立及指派永續性環境變數。

環境變數

為您的金鑰和端點建立及指派永續性環境變數。

setx AZURE_OPENAI_API_KEY "REPLACE_WITH_YOUR_KEY_VALUE_HERE" 
setx AZURE_OPENAI_ENDPOINT "REPLACE_WITH_YOUR_ENDPOINT_HERE" 

REST API

建立助理

注意

使用 Azure OpenAI 時,model 參數需要模型部署名稱。 如果您的模型部署名稱與基礎模型名稱不同,您可以將程式碼調整為 "model": "{your-custom-model-deployment-name}"

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.",
    "name": "Math Assist",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-1106-preview"
  }'

工具

個別助理最多可以存取 128 個工具,包含 code interpreter,以及您透過函式所建立的任何自訂工具。

建立執行緒

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d ''

新增使用者問題至執行緒

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

執行執行緒

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

擷取執行狀態

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_abc123 \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

Assistant 回應

curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/messages \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \

瞭解瞭解您的結果

在此範例中,我們會建立已啟用程式碼解釋器的助理。 當我們詢問數學問題時,助理會將問題轉譯為 Python 程式碼,並在沙盒環境中執行程式碼,以判斷問題的答案。 由模型所建立並測試以取得答案的程式碼為:

    from sympy import symbols, Eq, solve  
      
    # Define the variable  
    x = symbols('x')  
      
    # Define the equation  
    equation = Eq(3*x + 11, 14)  
      
    # Solve the equation  
    solution = solve(equation, x)  
    solution  

請務必記住,雖然程式碼解釋器讓模型能夠藉由將問題轉換成程式碼,並在 Python 沙盒環境中反覆執行直到取得解決方案,以回應更複雜的查詢,但您仍然需要驗證回應,以確認模型正確地將您的問題轉譯成程式碼中的有效表示法。

清除資源

如果您想要清除和移除 Azure OpenAI 資源,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

另請參閱