快速入门#

本指南将引导您完成使用 prompt flow 代码优先体验的第一步。

先决条件 - 要充分利用本教程，您需要

了解如何使用 Python 编程 :)
对机器学习有基本的了解会很有帮助，但不是强制性的。

学习目标 - 完成本教程后，您应该学会如何

设置您的 Python 环境以运行 prompt flow
克隆一个示例流并理解什么是流
了解如何使用可视化编辑器或 YAML 编辑流
使用您喜欢的体验测试流：CLI、SDK 或 VS Code 扩展。

设置您的开发环境#

一个 Python 版本为 python=3.9 或更高版本（如 3.10）的 Python 环境。建议使用 Python 环境管理器 miniconda。安装 miniconda 后，运行以下命令创建一个 Python 环境

conda create --name pf python=3.9
conda activate pf

安装 promptflow 和 promptflow-tools。

pip install promptflow promptflow-tools

检查安装。

# should print promptflow version, e.g. "0.1.0b3"
pf -v

理解什么是流#

流，表示为一个 YAML 文件，是函数的 DAG（有向无环图），通过输入/输出依赖项连接，并由 prompt flow 执行器根据拓扑结构执行。有关更多详细信息，请参阅流。

获取流示例#

克隆示例仓库并检查 examples/flows 文件夹中的流。

git clone https://github.com/microsoft/promptflow.git

理解流目录#

本教程中使用的示例是 web-classification 流，它将 URL 分类为几个预定义的类别。分类是传统的机器学习任务，此示例说明了如何使用 GPT 和提示执行分类。

cd promptflow/examples/flows/standard/web-classification

流目录是包含流所有内容的目录。流文件夹的结构

flow.dag.yaml：流定义，包含用于创作目的的输入/输出、节点、工具和变体。
.promptflow/flow.tools.json：包含 flow.dag.yaml 中引用的工具元数据。
源代码文件 (.py, .jinja2)：用户管理，由工具引用的代码脚本。
requirements.txt：此流的 Python 包依赖项。

flow_dir

为了运行此特定流，您需要首先安装其要求。

pip install -r requirements.txt

理解流 YAML#

流目录的入口文件是 flow.dag.yaml，它描述了流的 DAG(有向无环图)。以下是流 DAG 的一个示例

flow_dag

此图由 VS Code 扩展渲染，将在下一节中介绍。

使用 VS Code 扩展可视化流#

注意：强烈建议使用 Prompt flow VS Code 扩展进行流开发和调试。

VS Code 扩展的先决条件。
- 安装最新稳定版 VS Code
- 安装 VS Code Python 扩展
安装 Prompt flow for VS Code 扩展
选择 Python 解释器
在 vscode 中打开 dag。您可以将 flow.dag.yaml 作为 yaml 文件打开，也可以在 visual editor 中打开。

开发和测试您的流#

如何编辑流#

要使用不同的输入数据测试您的流，您可以选择修改默认输入。如果您熟悉结构，您还可以添加或删除节点以更改流的排列。

$schema: https://azuremlschemas.azureedge.net/promptflow/latest/Flow.schema.json
inputs:
  url:
    type: string
    # change the default value of input url here
    default: https://play.google.com/store/apps/details?id=com.twitter.android
...

有关此主题的更多详细信息，请参阅开发流。

创建必要的连接#

注意

如果您正在使用 WSL 或其他没有默认密钥环存储后端的操作系统，您可能会遇到 StoreConnectionEncryptionKeyError，请参阅常见问题获取解决方案。

连接 有助于安全地存储和管理与 LLM 和其他外部工具（例如 Azure 内容安全）交互所需的密钥或其他敏感凭据。

示例流 web-classification 内部使用连接 open_ai_connection，例如 classify_with_llm 节点需要使用该连接与 llm 通信。

如果之前没有添加连接，我们需要设置连接。创建后，连接将存储在本地数据库中，并可在任何流中使用。

CLI

首先我们需要一个连接 YAML 文件 connection.yaml

如果您正在使用 Azure OpenAI，请按照此说明准备您的资源，如果没有 api_key，请获取一个。

$schema: https://azuremlschemas.azureedge.net/promptflow/latest/AzureOpenAIConnection.schema.json
name: open_ai_connection
type: azure_open_ai
api_key: <test_key>
api_base: <test_base>
api_type: azure
api_version: <test_version>

如果您正在使用 OpenAI，请通过 OpenAI 网站注册帐户，登录并找到个人 API 密钥，然后使用此 YAML

$schema: https://azuremlschemas.azureedge.net/promptflow/latest/OpenAIConnection.schema.json
name: open_ai_connection
type: open_ai
api_key: "<user-input>"
organization: "" # optional

然后我们可以使用 CLI 命令创建连接。

pf connection create -f connection.yaml

可以在 CLI 参考中找到更多命令详细信息。

SDK

在 SDK 中，可以使用 PFClient 创建和管理连接。

from promptflow.client import PFClient
from promptflow.entities import AzureOpenAIConnection

# PFClient can help manage your runs and connections.
pf = PFClient()

try:
    conn_name = "open_ai_connection"
    conn = pf.connections.get(name=conn_name)
    print("using existing connection")
except:
    connection = AzureOpenAIConnection(
        name=conn_name,
        api_key="<test_key>",
        api_base="<test_base>",
        api_type="azure",
        api_version="<test_version>",
    )

    # use this if you have an existing OpenAI account
    # from promptflow.entities import OpenAIConnection
    # connection = OpenAIConnection(
    #     name=conn_name,
    #     api_key="<user-input>",
    # )

    conn = pf.connections.create_or_update(connection)
    print("successfully created connection")

print(conn)

VS Code 扩展

点击 promptflow 图标进入 promptflow 控制面板
创建您的连接。

了解更多关于删除连接等操作的信息：管理连接。

测试流#

注意

测试流不会创建批处理运行记录，因此无法使用 pf run show-details 等命令获取运行信息。如果您想保留运行记录，请参阅运行和评估流

假设您在工作目录 promptflow/examples/flows/standard/ 中

CLI

将默认输入更改为您要测试的值。

q_0

pf flow test --flow web-classification  # "web-classification" is the directory name

flow-test-output-cli

SDK

test 函数的返回值是流/节点的输出。

from promptflow.client import PFClient

pf = PFClient()

flow_path = "web-classification"  # "web-classification" is the directory name

# Test flow
flow_inputs = {"url": "https://www.youtube.com/watch?v=o5ZQyXaAv1g", "answer": "Channel", "evidence": "Url"}  # The inputs of the flow.
flow_result = pf.test(flow=flow_path, inputs=flow_inputs)
print(f"Flow outputs: {flow_result}")

# Test node in the flow
node_name = "fetch_text_content_from_url"  # The node name in the flow.
node_inputs = {"url": "https://www.youtube.com/watch?v=o5ZQyXaAv1g"}  # The inputs of the node.
node_result = pf.test(flow=flow_path, inputs=node_inputs, node=node_name)
print(f"Node outputs: {node_result}")