传递大型DataFrame至Prefect Flow时出现创建失败问题

问题背景 #

用Prefect编排机器学习流水线时，小批量数据处理完全正常，但处理10000行左右的单列文本清洗后DataFrame时，负责预测的Flow无法创建，抛出两类异常：

1. ReadTimeout关联的SSL读取超时错误
2. LocalProtocolError关联的h2流关闭错误

即使把Flow简化为仅打印DataFrame信息的逻辑，问题依然存在，且程序从未进入Flow函数内部。

解决方向 #

1. 延长Prefect API请求超时 #

这类超时/协议错误大多是因为大数据量DataFrame作为参数传递时，Prefect序列化并传输数据的时间超过了默认超时限制。
在代码开头添加超时配置：

from prefect.settings import PREFECT_API_REQUEST_TIMEOUT
import prefect.settings

# 调整超时时间为300秒（可按需修改）
prefect.settings.set_settings({PREFECT_API_REQUEST_TIMEOUT: 300})

如果用的是自建Prefect Server，也要同步检查服务器端的API超时配置，确保能处理大请求。

2. 别直接传大型DataFrame当Flow参数 #

Prefect不推荐直接把大DataFrame作为参数传递——序列化+网络传输的过程很容易触发超时或协议问题。换个思路：

• 先把DataFrame存到本地/云存储（比如Parquet文件），Flow只接收文件路径，内部再读取数据：

  from prefect import flow
  import pandas as pd
  
  @flow()
  def predictions(data_path):
      df = pd.read_parquet(data_path)
      print(df.info())
  
  # 先保存数据
  df_test.to_parquet("./test_data.parquet")
  # 传路径而非DataFrame
  test = predictions("./test_data.parquet")
  

3. 禁用HTTP/2协议 #

错误里的h2.exceptions.StreamClosedError指向HTTP/2兼容性问题，强制用HTTP/1.1试试：

from prefect.settings import PREFECT_API_USE_HTTP2
import prefect.settings

prefect.settings.set_settings({PREFECT_API_USE_HTTP2: False})

4. 排查网络与SSL配置 #

• 检查本地代理、防火墙是否拦截了Prefect的API请求
• 如果是自建Server用了自签名证书，测试环境可以临时关闭SSL验证：

  from prefect.settings import PREFECT_API_VERIFY_SSL
  import prefect.settings
  
  prefect.settings.set_settings({PREFECT_API_VERIFY_SSL: False})
  

5. 升级依赖版本 #

旧版Prefect、httpx、httpcore可能存在已知的超时或HTTP/2 bug，升级到最新稳定版：

pip install --upgrade prefect httpx httpcore

内容的提问来源于stack exchange，提问作者emilenebd