分析代码工作簿Environment故障排除指南

注意:以下翻译的准确性尚未经过验证。这是使用 AIP ↗ 从原始英文文本进行的机器翻译。

故障排除指南

我的自定义环境初始化缓慢

初始化缓慢通常表明环境定义过大或过于复杂。初始化时间往往随着环境中包的数量呈超线性增长。此外,Foundry 通常会预先初始化常用环境,因此如果您基于默认配置文件创建了自定义环境,缓慢可能是因为您不再获得预先初始化的环境,而必须等待创建新环境。有关环境创建过程的更多详细信息,请参阅环境创建简介

尝试以下操作:

  1. 撤销 - 如果环境在其配置更改后开始缓慢初始化,请尝试恢复更改。在某些情况下,即使是添加一个包也可能显著增加初始化时间。
  2. 简化 - 从环境定义中移除任何不需要的包。小型、专用的环境比大型、通用的环境性能更佳。
  3. 固定版本 - 在环境配置面板中为部分包添加版本限制,如选择环境中所述。这对于具有许多可能版本的包(如python)和具有复杂依赖图的包(如scipy)最为有效。如果添加某个特定包导致环境变慢,尝试为该包固定一个版本。
    • 警告:添加版本限制可能导致环境不可满足。如果环境初始化失败,尝试放宽限制。例如,python=3.6.10将仅匹配该版本,而python=3.6将匹配任何python 3.6.x,因此更可能被满足。
    • 一种选择是等待您的环境(无限制)解析,然后检查选择了哪些版本(参见查看已解析的环境)。然后您可以为这些特定版本添加限制,直到初始化性能足够快。通常,最优的做法是为具有许多依赖项的包固定版本,而将其他所有包保持不固定。

环境初始化失败

如果您的环境初始化失败,您可以查看环境启动出错日志,以了解出错的详细信息。

environment_error_dialog

日志的第一行将显示Execution failed with non-zero exit code:,后跟一个整数出错代码。此出错代码指示具体的失败模式。

代码 1 - 环境解析出错

此出错表明某些指定包(和/或其依赖项)不兼容或无法安装。如果环境配置面板中的最近更改导致初始化开始失败,请尝试恢复更改。以下是常见环境解析出错的列表。

新的 Mamba 出错信息

Palantir 贡献 ↗ 给开源 Mamba 社区,通过提供更好的环境初始化出错信息格式化。自 2023 年 2 月以来,Foundry 服务受益于更接近于被环境失败侵犯的依赖树的出错信息。

有关理解这些新信息的指导,如何解释它们,以及如何补救的建议,请参阅新的出错信息

旧的 Mamba 出错信息

以下是引入新的 Mamba 出错信息之前的旧版出错信息中的常见出错信息列表。

找不到包

在这种情况下,没有配置的渠道提供包 A 的依赖。

Copied!
1 2 3 // 问题: 没有提供请求的 A.a.a.a // 此问题通常意味着在代码中请求了一个不存在或未定义的属性、方法或模块。 // 需要检查代码中是否有拼写错误或者确保所有必要的库和模块都已正确导入。

如果您的包的固定版本不存在,就可能发生这种情况。如果是这种情况,请尝试在meta.yml中放宽或删除包的版本限制;例如,matplotlib 1.1.1可以变为matplotlib。或者,这也可能意味着环境管理器无法找到安装指定版本所需的包。

未找到依赖

在这种情况下,包A包含一个所需的依赖B,但没有任何渠道提供该依赖。

Copied!
1 // 问题: A-a.a.a 需要 B-b.b.b,但没有提供 B-b.b.b

请注意,B 可以是用户在 meta.yml/foundry-ml/vector 配置文件中明确请求的包,也可以是传递依赖项。

如果 B 无法在您的注册中安装,则可能会发生这种情况;例如,B 可能已被召回,因此无法安装。

如果是这种情况,请尝试删除 A 的固定版本,以防存在一个版本的 A 具有所有可用的依赖项,或者联系您的 Palantir 代表以将必要的软件包导入 Foundry。

重复包出错
Copied!
1 // 无法同时安装 X.a.b.c 和 X.d.e.f

如果您尝试安装相同的包 X 并且为两者设置了两个不同的版本固定,则会发生此出错。例如,如果您尝试在 meta.yml 中同时固定 python 3.6.*python 3.7.*,您可能会收到此出错。您可以通过删除其中一个重复的包固定来解决此问题。

权限出错
Copied!
1 2 3 4 CondaService:ReadRepositoryPermissionDenied // 这是一个错误信息,表示在尝试读取仓库时权限被拒绝。 // "CondaService" 可能是一个与 Conda 相关的服务或模块。 // 确保你的账户具有访问该仓库的适当权限。

如果您收到此出错信息,可能是因为您的注册中某些资产和软件包不可用。

软件包冲突

在这种情况下,软件包A对软件包B的版本有要求,但此版本的B与其他软件包冲突:

Copied!
1 2 3 4 5 6 7 问题:包 A-a.a.a 需要 B 版本在 >=2.2.5 且 <2.3.0a0 之间,但没有提供者可以安装 // 这通常意味着依赖包 B 的版本要求无法在当前环境中满足。 // 可能的解决方法包括: // 1. 检查其他已安装包对 B 的版本要求,确保没有冲突。 // 2. 尝试更新包管理器以获取最新的包版本信息。 // 3. 如果可能,调整 A-a.a.a 或其他依赖项的版本要求以解决冲突。

请注意,包B可能是A的传递依赖项,您并未在环境中明确列为需求。有关传递依赖项的更多信息,请参阅已解决的环境文档。

修复代码1出错

要修复环境失败,请考虑以下步骤:

  1. 检查环境启动日志中的STDOUT
  2. 创建一个失败解决的最小示例。移除包直到环境初始化成功,然后逐个添加包,直到确定哪些包是阻碍因素。
  3. 通过移除包锁定来尝试放松约束。
    • 您可以在不同窗口中打开多个工作簿或相同工作簿的多个分支,以加快此过程。
    • 我们建议使用二分搜索来发现问题。尝试在一个工作簿中移除所有约束,在另一个工作簿中移除一半约束,然后在另一个工作簿中移除另一半约束,依此类推。

代码137 - 模块内存不足

此出错通常表示环境初始化所需的内存超过了Spark模块的可用内存。如果最近在环境配置面板中的更改导致初始化开始出错,请尝试恢复更改。否则,请尝试以下一个或多个建议:

  • 从环境中移除不需要的包。内存使用量随着环境中包的数量超线性增加,因此即使移除几个包也可能足以解决问题。
  • 为某些包添加版本约束,如环境初始化缓慢部分的步骤3中所述。固定每个包的版本将减少环境解决的复杂性,从而减少初始化环境所需的内存量。

如果在移除所有不需要的包并将剩余的一些包锁定到特定版本后,您的环境仍然无法初始化,请联系您的Palantir代表,并附上您尝试的所有调试步骤的详细信息。

其他代码

如果您的环境初始化失败并出现未列出的出错代码且重试后仍失败,请联系您的Palantir代表并附上出错日志的全文。

默认环境初始化速度不一致

我们预期默认配置有时会快速初始化,有时会花费更长时间。在后一种情况下,您需要等待Mamba解析您的环境规范并将其安装到支持您工作簿的Spark模块上。这是默认行为。在前一种情况下,要么您获得了预初始化模块,要么您的环境规范与缓存中可以立即安装的已解决环境匹配。如果许多用户同时打开工作簿,您不太可能获得预初始化模块,需要等待一个新的模块启动。

需要同时具备Conda包和JAR的包

有些包需要同时具备Conda包和JAR才能可用。一个常见的例子是graphframes包。此类包需要特殊的设置过程,如果此包之前未为您的实例配置,您可能会在搭建时遇到以下出错:

Copied!
1 2 3 4 5 o257.loadClass.: java.lang.ClassNotFoundException:<Class> // 出现了 java.lang.ClassNotFoundException 异常 // 这通常意味着程序试图加载某个类,但找不到该类。 // 可能的解决办法包括:检查类名是否正确,确保类路径设置正确,或者确认所需的库是否已添加到项目中。

JAR 文件可以在控制面板的 Conda 环境配置选项卡的高级部分中添加到配置文件的配置中(请参阅配置 Code Workbook 配置文件)。如果您在配置此类软件包时需要帮助,请联系您的 Palantir 代表。

其他问题

如果上述指导不足以解决您的问题,或者如果您遇到本指南范围之外的问题,请联系您的 Palantir 代表,并包括您尝试过的任何调试步骤的详细信息。