你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

使用提示流 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 而不是 API 密钥，通过你的用户标识向 Azure OpenAI 进行身份验证。

你或你的管理员需要为你的用户标识授予你正在使用的 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 环境

首先，我们需要创建新的 Python 环境，以便用于安装提示流 SDK 包。 请勿将包安装到你的全局 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

在本部分中，我们将使用提示流来生成应用程序。 提示流是一套开发工具，旨在从构思、原型制作、测试、评估到生产部署和监视，简化基于 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 文件中读取环境变量以设置它们

配置环境变量

从代码调用 Azure OpenAI 服务需要 AI 服务终结点和部署名称。 在本快速入门中，请将这些值保存在 .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

你现在应会看到运行 prompty 的输出：

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 概述