常见问题解答 (FAQ)#

一般#

稳定版与实验版#

Prompt flow 在同一 SDK 中提供稳定功能和实验性功能。

功能状态

描述

稳定功能

可用于生产

这些功能推荐用于大多数用例和生产环境。它们的更新频率低于实验性功能。

实验性功能

开发中

这些功能是新开发的功能和更新，可能尚未准备好或未经过充分测试以供生产使用。虽然这些功能通常是可用的，但它们可能包含一些重大更改。实验性功能用于解决 SDK 中的重大错误，并且只会在测试期间接收更新。实验性功能也称为预览功能。
顾名思义，实验性（预览）功能用于实验，不被认为是无 bug 或稳定的。因此，我们只推荐实验性功能给希望试用早期版本功能和更新，并打算参与 bug 和故障报告的高级用户。

OpenAI 1.x 支持#

请使用以下命令升级 Promptflow 以支持 OpenAI 1.x

pip install promptflow>=1.1.0
pip install promptflow-tools>=1.0.0

请注意，上述命令会将您的 openai 包升级到 1.0.0 以后的版本，这可能会对自定义工具代码引入重大更改。

请参阅OpenAI 迁移指南了解更多详情。

Promptflow 1.8.0 升级指南#

在升级到 Promptflow 1.8.0 或更高版本之前，首先卸载任何现有安装的 Promptflow 及其子包非常重要。这确保了新版本的干净安装，没有任何冲突。

pip uninstall -y promptflow promptflow-core promptflow-devkit promptflow-azure # uninstall promptflow and its sub-packages
pip install 'promptflow>=1.8.0' # install promptflow version 1.8.0 or later

‘pip install promptflow>=1.8.0’ 或 ‘pf upgrade’ 直接不起作用的原因

promptflow 包已被拆分为多个包。安装 promptflow 时，您将获得以下包

  • promptflow:

    • promptflow-tracing: Promptflow 的跟踪功能。

    • promptflow-core: 运行流的核心功能。

    • promptflow-devkit: Promptflow 的开发工具包。

    • promptflow-azure: Promptflow 与 Azure 集成的 Azure 额外要求 (promptflow[azure])。

将 Promptflow 从现有版本升级到 Promptflow 1.8.0 时，pip 会在安装 Promptflow 子包后删除旧的 Promptflow，这导致子包文件被错误删除。

upgrade-wrongly-remove

故障排除#

连接创建失败并出现 StoreConnectionEncryptionKeyError#

Connection creation failed with StoreConnectionEncryptionKeyError: System keyring backend service not found in your operating system. See https://pypi.org/project/keyring/ to install requirement for different operating system, or 'pip install keyrings.alt' to use the third-party backend.

此错误是由于 keyring 找不到可用的后端来存储密钥而引起的。例如，macOS 钥匙串和Windows 凭据锁是有效的 keyring 后端。

要解决此问题，请安装第三方 keyring 后端或编写您自己的 keyring 后端，例如：pip install keyrings.alt

有关 keyring 第三方后端的更多详细信息，请参阅 keyring 中的“第三方后端”。

Pf visualize 显示错误：“tcgetpgrp failed: Not a tty”#

如果您正在使用 WSL，这是 webbrowser 在 WSL 下的一个已知问题；有关更多信息，请参阅此问题。请尝试将您的 WSL 升级到 22.04 或更高版本，此问题应该会得到解决。

如果您在使用 WSL 22.04 或更高版本时仍然面临此问题，或者您根本没有使用 WSL，请向我们提出问题。

安装的工具未显示在 VSCode 扩展工具列表中#

通过 pip install [tool-package-name] 安装工具包后，新工具可能不会立即出现在 VSCode 扩展的工具列表中，如下所示

VSCode Extension tool list

这通常是由于缓存过时造成的。要刷新工具列表并使新安装的工具可见

  1. 打开 VSCode 扩展窗口。

  2. 按“Ctrl+Shift+P”调出命令面板。

  3. 键入并选择“开发人员：重新加载 Web 视图”命令。

  4. 等待片刻，直到工具列表刷新。

重新加载会清除以前的缓存，并使用任何新安装的工具填充工具列表。这样，缺失的工具现在就可见了。

设置日志级别#

Promptflow 使用 logging 模块来记录消息。您可以通过环境变量 PF_LOGGING_LEVEL 设置日志级别，有效值包括 CRITICAL、ERROR、WARNING、INFO、DEBUG，默认为 INFO。下面是设置 PF_LOGGING_LEVEL 为 DEBUG 后的服务日志

img

与 WARNING 级别的服务日志进行比较

img

设置日志格式#

Promptflow 默认使用以下日志格式和日期时间格式

  • 日志格式: %(asctime)s %(process)7d %(name)-18s %(levelname)-8s %(message)s

  • 日期时间格式: %Y-%m-%d %H:%M:%S %z

您可以使用 PF_LOG_FORMAT 环境变量自定义日志格式，并使用 PF_LOG_DATETIME_FORMAT 自定义日期时间格式。这些变量也可以在流 yaml 文件中定义或直接在环境中设置。

设置环境变量#

目前，Promptflow 支持以下环境变量

PF_WORKER_COUNT

仅对批量运行有效，批量运行执行中的并行工作程序数量。

默认值为 4（当 promptflow<1.4.0 时为 16）

更改时请考虑以下几点

  1. 并发数不应超过总数据行数。否则，由于进程启动和关闭需要额外时间，执行可能会变慢。

  2. 高并行度可能会导致底层 API 调用达到 LLM 端点的速率限制。在这种情况下，您可以减少 PF_WORKER_COUNT 或增加速率限制。请参阅此文档了解配额管理。然后您可以参考此表达式来设置并发。

PF_WORKER_COUNT <= TPM * duration_seconds / token_count / 60

TPM：每分钟令牌数，LLM 端点的容量速率限制

duration_seconds：单个流运行持续时间（秒）

token_count：单个流运行令牌数

例如，如果您的端点 TPM（每分钟令牌数）为 50K，单个流运行需要 10k 令牌并运行 30 秒，请不要将 PF_WORKER_COUNT 设置为大于 2。这是一个粗略的估计。请同时考虑协作（同事同时使用同一个端点）以及部署的推理端点、操场和其他可能向您的 LLM 端点发送请求的场景中消耗的令牌。

PF_BATCH_METHOD

仅对批量运行有效。可选值：'spawn', 'fork'。

spawn

  1. 子进程不会继承父进程的资源，因此，每个进程都需要重新初始化流所需的资源，这可能会使用更多系统内存。

  2. 启动进程很慢，因为它需要一些时间来初始化必要的资源。

fork

  1. 使用写时复制机制，子进程将继承父进程的所有资源，从而使用更少的系统内存。

  2. 进程启动更快，因为它不需要重新初始化资源。

注意：Windows 仅支持 spawn，Linux 和 macOS 同时支持 spawn 和 fork。

如何配置环境变量#

  1. 在 flow.dag.yaml 中配置环境变量。例如

    inputs: []
    outputs: []
    nodes: []
    environment_variables:
      PF_WORKER_COUNT: 2
      PF_BATCH_METHOD: "spawn"
      MY_CUSTOM_SETTING: my_custom_value

  1. 提交运行时指定环境变量。

使用此参数：--environment-variable 来指定环境变量。例如：--environment-variable PF_WORKER_COUNT="2" PF_BATCH_METHOD="spawn"。

创建运行时指定环境变量。例如

    pf = PFClient(
        credential=credential,
        subscription_id="<SUBSCRIPTION_ID>",
        resource_group_name="<RESOURCE_GROUP>",
        workspace_name="<AML_WORKSPACE_NAME>",
    )

    flow = "web-classification"
    data = "web-classification/data.jsonl"

    environment_variables = {"PF_WORKER_COUNT": "2", "PF_BATCH_METHOD": "spawn"}

    # create run
    base_run = pf.run(
        flow=flow,
        data=data,
        environment_variables=environment_variables,
    )

VSCode 扩展仅支持在提交批量运行时指定环境变量。在 batch_run_create.yaml 中指定环境变量。例如

    name: flow_name
    display_name: display_name
    flow: flow_folder
    data: data_file
    column_mapping:
        customer_info: <Please select a data input>
        history: <Please select a data input>
    environment_variables:
        PF_WORKER_COUNT: "2"
        PF_BATCH_METHOD: "spawn"

优先级#

提交运行时指定的环境变量始终优先于 flow.dag.yaml 文件中的环境变量。