PyODPS DataFrame 代码运行环境与执行方式详解

编写PyODPS DataFrame数据写入应用时，同一脚本内的代码可能分散执行于本地环境、MaxCompute Executor或DataWorks开发环境。这种多地点执行常引发意外状况。本文旨在解析代码实际执行位置的判定方法，并提供典型问题的解决策略。

执行逻辑概述

先观察以下示例代码：

from odps import ODPS, options
import numpy as np

o = ODPS(access_id, access_key, project, endpoint)
df = o.get_table('pyodps_iris').to_df()
coeffs = [0.1, 0.2, 0.4]

def handle(v):
    import numpy as np
    return float(np.cosh(v)) * sum(coeffs)

options.df.supersede_libraries = True
val = df.sepal_length.map(handle).sum().execute(libraries=['numpy.zip', 'other.zip'])
print(np.sinh(val))

需要明确：PyODPS本质上是一个Python包，并非经过特殊改造的解释器。它运行于标准Python环境，因此不会自动将单机代码转化为分布式执行——每条语句的行为与普通Python完全一致，不要期望自动魔法。

以下详细剖析该代码的执行流程。

上图展示了执行过程中可能涉及的系统。紫色标记的代码执行位置位于MaxCompute外部，下文统一称为“本地”。本地执行的代码是handle函数之外的部分（注意handle传入map时仅传递函数本身，尚未执行）。因此这些代码的行为与普通Python一致，导入第三方包时引用本地安装的版本。问题随之而来：代码中libraries=['numpy.zip', 'other.zip']指定的other.zip若未在本地安装，则本地代码一旦出现import other便会立即报错——即使other.zip已上传至MaxCompute资源，本地环境也无法找到。理论上，本地代码若不涉及PyODPS包，则与PyODPS无关，需用户自行排查。

handle函数的情况则完全不同。将handle传入map方法时（假设后端为MaxCompute），首先由cloudpickle模块打包——闭包和字节码一并序列化。随后PyODPS DataFrame利用这些内容生成Python UDF，提交至MaxCompute。作业以SQL形式执行时，会调用该UDF，在MaxCompute Executor中反序列化并运行。因此：

• handle函数体内的代码完全在MaxCompute Executor中执行，本地不参与。
• handle内部无法使用本地安装的包，仅Executor环境中存在的包有效。
• 上传的第三方包需兼容Executor的Python版本（当前为Python 2.7，UCS2）。
• 在handle中修改外部变量（如coeffs）不会影响本地环境中的值。
• 若在handle外部导入包，再在内部调用，可能出错——不同环境的包结构差异会导致cloudpickle将本地引用带入Executor。强烈建议将import语句置于handle内部。
• 由于使用了cloudpickle，若handle调用其他文件中的代码，则这些文件所在的包必须存在于Executor中。若不愿管理第三方包，可将所有自定义代码集中到同一文件。

上述关于handle的说明同样适用于自定义聚合、apply和map_reduce中调用的自定义方法或Agg类。若使用Pandas后端，所有代码均在本地执行，需预先安装相关包。不过Pandas后端调试完成后通常会切换至MaxCompute运行，因此建议在本地安装包的同时，遵循MaxCompute后端的开发规范。

第三方包集成与部署

本地环境（个人电脑/自有服务器）使用第三方包或外部代码

在对应的Python版本环境中直接安装即可。

DataWorks本地代码引用外部文件

此功能由DataWorks平台提供，具体操作请查阅DataWorks官方文档。

UDF内部（map/apply/map_reduce/自定义聚合）使用第三方包或外部代码

具体方法参考阿里云官方文档（https://yq.aliyun.com/articles/591508）。补充要点：在DataWorks上传资源后，务必点击“提交”以确保资源正确同步至MaxCompute。若需使用自定义Numpy版本，上传对应wheel包的同时，需配置odps.df.supersede_libraries = True，并将numpy包名置于libraries列表首位；若已设置options.df.libraries，则numpy包名须位于该配置列表最前端。

跨MaxCompute表数据引用

本地环境访问MaxCompute表

若Endpoint可达，直接通过PyODPS或DataFrame接口访问。

UDF内部访问其他MaxCompute表

MaxCompute Executor通常不支持直接访问Endpoint或Tunnel Endpoint，环境中也没有PyODPS包——因此不能直接使用ODPS入口对象或PyODPS DataFrame，也无法从自定义函数外部传入这些对象。若数据量较小，建议将DataFrame作为资源传入（参考PyODPS官方文档：https://pyodps.readthedocs.io/zh_CN/latest/df-element.html#function-resource）。数据量较大时，改用join更为合适。

外部服务访问

本地环境访问外部服务

确保本地环境具备访问相关服务的网络条件；生产服务器相关问题可联系PE（平台工程师）解决。

DataWorks本地代码访问外部服务

请直接咨询DataWorks技术支持团队。

UDF内部访问外部服务

参考前述文档启用Isolation隔离机制。若仍出现网络错误，请加入MaxCompute用户群联系售后支持处理。