使用提示流程 SDK 在 Python 中建置自訂聊天應用程式

重要

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

在本快速入門中，我們會逐步引導您使用提示流程 SDK 設定本機開發環境。 我們會撰寫提示、在您的應用程式程式碼中執行它、追蹤要進行的 LLM 呼叫，以及在 LLM 的輸出上執行基本評估。

必要條件

您必須先建立應用程式所需的資源，才能遵循本快速入門：

• 用來 連線到外部資源的 AI Studio 中樞 。
• 用來組織專案成品並共用追蹤和評估執行的專案。
• 已部署的 Azure OpenAI 聊天模型 （gpt-35-turbo 或 gpt-4）

如果您還沒有這些資源，請完成 AI Studio 遊樂場快速入門即可建立。 您也可以遵循 SDK 指南來建立中樞和專案一文來建立這些資源。

此外，您必須具備在 Azure 訂用帳戶中新增儲存體帳戶角色指派的必要權限。 只有特定 Azure 資源的擁有者才被允許授與權限 (新增角色指派)。 您可能需要要求 IT 系統管理員協助授與存取權以使用您的身分識別來呼叫 Azure OpenAI 服務。

使用您的身分識別授與呼叫 Azure OpenAI 服務的存取權

若要使用安全性最佳做法，我們會使用 Microsoft Entra ID 來使用您的使用者身分識別向 Azure OpenAI 驗證，而不是使用 API 金鑰。

您或您的系統管理員必須為您的使用者身分識別授與您使用的 Azure AI 服務資源上的認知服務 OpenAI 使用者角色。 此角色可讓您使用您的使用者身分識別來呼叫 Azure OpenAI 服務。

若要為您自己授與使用的 Azure AI 服務資源的存取權：

1. 在 AI Studio 中，移至您的專案，然後從左窗格選取 [設定]。

2. 在 [連線的資源] 區段中，選取類型為 AIServices 的連線名稱。

   

   注意

   如果您沒有看到 AIServices 連線，請改用 Azure OpenAI 連線。

3. 在 [資源詳細資料] 頁面上，選取 [資源] 標題底下的連結，以在 Azure 入口網站中開啟 AI 服務資源。

   

4. 從 Azure 入口網站的左側頁面，選取 [存取控制 (IAM)]> [+ 新增]> [新增角色指派]。

5. 搜尋認知服務 OpenAI 使用者角色，然後加以選取。 然後選取下一步。

   

6. 選取 [使用者、群組或服務主體]。 然後，選取 [選取成員]。

7. 在開啟的 [選取成員] 窗格中，搜尋您要新增角色指派的使用者名稱。 選取使用者，然後選取 [選取]。

   

8. 繼續執行精靈，然後選取 [檢閱 + 指派] 以新增角色指派。

安裝 Azure CLI 並登入

現在，我們會安裝 Azure CLI 並從您的本機開發環境登入，讓您可以使用您的使用者認證來呼叫 Azure OpenAI 服務。

在大部分情況下，您可以使用下列命令，從終端機安裝 Azure CLI：

Windows

winget install -e --id Microsoft.AzureCLI

Linux

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

macOS

brew update && brew install azure-cli

如果這些命令不適合您的特定作業系統或設定，您可以遵循如何安裝 Azure CLI 的指示。

安裝 Azure CLI 之後，請使用 az login 命令登入並使用瀏覽器登入：

az login

現在，我們會建立應用程式，並從程式碼呼叫 Azure OpenAI 服務。

建立新的 Python 環境

首先，我們需要建立可用來安裝提示流程 SDK 套件的新 Python 環境。 請勿將套件安裝到您的全域 Python 安裝中。 安裝 Python 套件時，您應該一律使用虛擬或 conda 環境，否則您可能會破壞 Python 的全域安裝。

如有需要，請安裝 Python

我們建議使用 Python 3.10 或更新版本，但至少需要 Python 3.8。 如果您未安裝適當的 Python 版本，可以遵循 VS Code Python 教學課程中的指示，以了解在作業系統上安裝 Python 的最簡單方式。

建立虛擬環境

如果您已安裝 Python 3.10 或更高版本，您可以使用下列命令來建立虛擬環境：

Windows

py -3 -m venv .venv
.venv\scripts\activate

Linux

python3 -m venv .venv
source .venv/bin/activate

macOS

python3 -m venv .venv
source .venv/bin/activate

啟用 Python 環境表示，當您命令列執行 python 或 pip，將會使用應用程式的 .venv 資料夾中所包含的 Python 解譯器。

注意

您可以使用 deactivate 命令來結束 Python 虛擬環境，並可以稍後視需要重新啟用它。

安裝提示流程 SDK

在本節中，我們會使用提示流程來建置應用程式。 [https://microsoft.github.io/promptflow/](提示流程) 是一套開發工具，旨在簡化 LLM 型 AI 應用程式的端對端開發週期，從構想、原型設計、測試、評估到生產部署和監視。

使用 pip 將提示流程 SDK 安裝到您所建立的虛擬環境中。

pip install promptflow
pip install azure-identity

提示流程 SDK 會相依於多個套件，如果您不想安裝所有套件，您可以選擇個別安裝：

• promptflow-core：包含用於執行 LLM 程式碼的核心提示流程執行階段
• promptflow-tracing：用於在標準中發出 OpenTelemetry 追蹤的輕量型程式庫
• promptflow-devkit：包含用於本機開發環境的提示流程測試台和追蹤檢視器工具
• openai：使用 Azure OpenAI 服務的用戶端程式庫
• python-dotenv：用來從 .env 檔案讀取以設定環境變數

設定環境變數

需要您的 AI 服務端點和部署名稱，才能從程式碼呼叫 Azure OpenAI 服務。 在本快速入門中，您會將這些值儲存在 .env 檔案中，這是一個檔案，其中包含應用程式可以讀取的環境變數。 您可以在 AI Studio 聊天遊樂場中找到這些值。

1. 建立 .env 檔案，並貼上下列程式碼：

   AZURE_OPENAI_ENDPOINT=endpoint_value
   AZURE_OPENAI_DEPLOYMENT_NAME=deployment_name
   AZURE_OPENAI_API_VERSION=2024-02-15-preview
   

2. 瀏覽至 AI Studio 專案內的聊天遊樂場。 首先，傳送訊息給 LLM，以驗證聊天是否正與您的模型搭配運作。

3. 在聊天遊樂場中尋找 Azure OpenAI 部署名稱。 選取下拉式清單中的部署，並將滑鼠停留在部署名稱上以檢視它。 在此範例中，部署名稱為 gpt-35-turbo-16k。

   

4. 在 .env 檔案中，將 deployment_name 取代為上一個步驟中的部署名稱。 在此範例中，我們使用部署名稱 gpt-35-turbo-16k。

5. 選取 [<> 檢視程式碼] 按鈕並複製端點值。

   

6. 在 .env 檔案中，將 endpoint_value 取代為從上一個步驟的對話方塊中複製的端點值。

警告

支援金鑰型驗證，但 Microsoft 不建議。 如果您想要使用金鑰，可以將金鑰新增至 .env，但請確定您的 .env 位於您的 .gitignore 檔案中，以免不小心簽入 Git 存放庫。

建立基本聊天提示和應用程式

先建立提示範本檔案，為此我們將使用 Prompty，這是提示流程支援的提示範本格式。

建立 chat.prompty 檔案，並將下列程式碼複製到其中：

---
name: Chat Prompt
description: A basic prompt that uses the chat API to answer questions
model:
    api: chat
    configuration:
        type: azure_openai
    parameters:
        max_tokens: 256
        temperature: 0.2
inputs:
    chat_input:
        type: string
    chat_history:
        type: list
        is_chat_history: true
        default: []
outputs:   
  response:
    type: string
sample:
    chat_input: What is the meaning of life?
---
system:
You are an AI assistant who helps people find information.

{% for item in history %}
{{item.role}}:
{{item.content}}
{% endfor %}

user:
{{chat_input}}

現在，讓我們建立使用此提示範本的 Python 檔案。 建立 chat.py 檔案，並將以下程式碼貼入其中：

import os
from dotenv import load_dotenv
load_dotenv()

from promptflow.core import Prompty, AzureOpenAIModelConfiguration

model_config = AzureOpenAIModelConfiguration(
    azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT")
)

prompty = Prompty.load("chat.prompty", model={'configuration': model_config})
result = prompty(
    chat_history=[
        {"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},
        {"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."}
    ],
    chat_input="Do other Azure AI services support this too?")

print(result)

現在，從您的主控台執行 Python 程式碼：

python chat.py

您現在應該會看到執行提示的輸出：

Yes, other Azure AI services also support various capabilities and features. Some of the Azure AI services include Azure Cognitive Services, Azure Machine Learning, Azure Bot Service, and Azure Databricks. Each of these services offers different AI capabilities and can be used for various use cases. If you have a specific service or capability in mind, feel free to ask for more details.

追蹤聊天程式碼的執行

現在，我們來看看提示流程追蹤如何提供 Python 指令碼中所發生各種 LLM 呼叫的深入解析。

在 chat.py 檔案開頭，新增下列程式碼以啟用提示流程追蹤：

from promptflow.tracing import start_trace
start_trace()

重新執行 chat.py 一次：

python chat.py

這次您會在輸出中看到連結，用來檢視執行的提示流程追蹤：

Starting prompt flow service...
Start prompt flow service on port 23333, version: 1.10.1.
You can stop the prompt flow service with the following command:'pf service stop'.
Alternatively, if no requests are made within 1 hours, it will automatically stop.
You can view the trace detail from the following URL:
http://localhost:23333/v1.0/ui/traces/?#collection=aistudio-python-quickstart&uiTraceId=0x59e8b9a3a23e4e8893ec2e53d6e1e521

如果您選取該連結，則會看到追蹤顯示程式執行的步驟、傳遞至 LLM 的項目和回應輸出。

提示流程追蹤也可讓您追蹤特定函式呼叫，並將追蹤記錄至 AI Studio，如需詳細資訊，請務必查看如何在提示流程 SDK中使用追蹤。

評估您的提示

現在讓我們示範如何使用提示流程評估工具來產生計量，以從 0 到 5 的刻度針對交談品質評分。 我們再次執行提示，但這次會將結果儲存到包含完整對話的陣列中，然後將結果傳遞至 ChatEvaluator 以評分。

首先，安裝 promptflow-evals package：

pip install promptflow-evals

現在，將下列程式碼複製到 evaluate.py 檔案：

import os
from dotenv import load_dotenv
load_dotenv()

from promptflow.core import Prompty, AzureOpenAIModelConfiguration
from promptflow.evals.evaluators import ChatEvaluator

model_config = AzureOpenAIModelConfiguration(
    azure_deployment=os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION"),
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT")
)

chat_history=[
    {"role": "user", "content": "Does Azure OpenAI support customer managed keys?"},
    {"role": "assistant", "content": "Yes, customer managed keys are supported by Azure OpenAI."}
]
chat_input="Do other Azure AI services support this too?"

prompty = Prompty.load("chat.prompty", model={'configuration': model_config})
response = prompty(chat_history=chat_history, chat_input=chat_input)

conversation = chat_history
conversation += [
    {"role": "user", "content": chat_input},
    {"role": "assistant", "content": response}
]

chat_eval = ChatEvaluator(model_config=model_config)
score = chat_eval(conversation=conversation)

print(score)

執行 evaluate.py 指令碼：

python evaluate.py

您應該會看到類似以下的輸出：

{'gpt_coherence': 5.0, 'gpt_fluency': 5.0, 'evaluation_per_turn': {'gpt_coherence': {'score': [5.0, 5.0]}, 'gpt_fluency': {'score': [5.0, 5.0]}}}

看起來我們就此對話 LLM 回應的一致性和流暢性獲得 5 分！

如需如何使用提示流程評估工具的詳細資訊，包括如何將您自己的自訂評估工具和記錄評估結果記錄至 AI Studio，請務必查看使用提示流程 SDK 評估您的應用程式。

相關內容

• 快速入門：在 Azure AI Studio 中建立專案並使用聊天遊樂場
• 在 VS Code 中使用專案
• Azure AI SDK 概觀