注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。
このガイドのステップに沿って、Python 環境の作成時によく発生する問題をデバッグします。
以下のチェックの失敗については、コードリポジトリ内の「チェック」タブでチェックログを表示できます。これらのログを使って、チェックが失敗した理由を確認できます。
Palantir は、環境の初期化エラーメッセージの書式を改善することで、オープンソースの Mamba コミュニティに貢献しました ↗。2023年2月以降、Foundry サービスでは、環境の失敗時に満たせなかった依存関係ツリーを、エラーメッセージでより正確に表現できるようになりました。
次の例では、
packageA
├─ packageB
└─ packageC
└─ packageD
パッケージ packageB と packageC は、packageA の直接的依存関係です。packageD は packageC の直接的依存関係ですが、packageA の推移的依存関係です。packageA は packageD に直接制約を課していませんが、packageC に対する packageA の直接の要件によって、packageD に間接的に制約が課されます。以下に、この概念の実例を示します。
statsmodels
├─ numpy
├─ scipy
├─ matplotlib
│ │ ├─ libpng
│ │ ├─ setuptools
│ │ ├─ cycler
│ │ ├─ dateutil
│ │ └─ kiwisolver
statsmodels が libpng に制約を課すことは、一見わかりにくいかもしれません。しかし、matplotlib に制約を課すことで、推移的に制約を課しています。
直接の競合は、同じ環境で同じパッケージの異なるバージョンが要求された場合に発生します。python 3.7 と python 3.8 の両方を含む単純な環境を要求する場合を考えてみます。これは直接の競合であり、環境の作成に失敗します。新しいエラーメッセージには、次の情報が表示されます。
Could not solve for environment specs
The following packages are incompatible
├─ python 3.7** is requested and can be installed;
└─ python 3.8** is uninstallable because it conflicts with any installable
versions previously reported.
上記のメッセージは、python 3.7 をインストールできることを正しく説明しています。ただし、そのバージョンをインストールした場合、さらに別のバージョンをインストールしようとすると競合が発生します。この環境の依存関係は、Python のいずれかのバージョン制約を環境から削除することで解決できます。
ただし、直接の競合は、依存関係や推移的依存関係によって生じる競合に比べると、非常にまれです。
NumPy のドキュメント ↗には、numpy >=1.22.0 には python >=3.8 が必要であると明記されています。そのため、python 3.7.* と numpy 1.22.0 の両方を要求する環境を作成しようとすると、直接的依存関係の競合が発生します。その結果、次のエラーメッセージが表示されます。
Could not solve for environment specs
The following packages are incompatible
├─ numpy 1.22.0** is installable with the potential options
│ ├─ numpy 1.22.0 would require
│ │ ├─ python >=3.9,<3.10.0a0 , which can be installed;
│ │ └─ python_abi 3.9.* *_cp39, which can be installed;
│ ├─ numpy 1.22.0 would require
│ │ ├─ python >=3.10,<3.11.0a0 , which can be installed;
│ │ └─ python_abi 3.10.* *_cp310, which can be installed;
│ └─ numpy 1.22.0 would require
│ ├─ python >=3.8,<3.9.0a0 , which can be installed;
│ └─ python_abi 3.8.* *_cp38, which can be installed;
└─ python 3.7** is uninstallable because there are no viable options
├─ python [3.7.10|3.7.11|...|3.7.9] conflicts with any installable versions previously reported;
├─ python [3.7.0|3.7.1|3.7.2|3.7.3|3.7.6] would require
│ └─ python_abi * *_cp37m, which conflicts with any installable versions previously reported;
└─ python [3.7.10|3.7.12|...|3.7.9] would require
└─ python_abi 3.7.* *_cp37m, which conflicts with any installable versions previously reported.
このエラーメッセージは、numpy 1.22.0 が Python 3.8、3.9、3.10 のいずれかでインストール可能であるものの、要求されたバージョン 3.7.* と競合することを示しています。この環境の依存関係は、Python または NumPy のいずれかの制約を緩和することで解決できます。たとえば、python 3.8.* と numpy 1.22.0、または python 3.7.* と numpy 1.* のどちらの組み合わせでも、環境を正常に作成できます。
環境のトラブルシューティングでは、python と python_abi のバージョンは連動すると考えてかまいません。環境で python_abi を指定する代わりに、python のバージョンを調整することで、python_abi のバージョンを調整できます。
同様に、推移的依存関係によってパッケージの競合が発生することもあります。推移的依存関係の性質上、数個のパッケージを要求するだけで、環境の依存関係解決処理に数百個の制約が追加される可能性があります。statsmodels パッケージを例に考えてみます。
statsmodels
├─ numpy
├─ scipy
├─ matplotlib
│ │ ├─ libpng
│ │ ├─ setuptools
│ │ ├─ cycler
│ │ ├─ dateutil
│ │ └─ kiwisolver
特定のバージョンの statsmodels を要求すると、このパッケージが matplotlib に依存しているため、許容される setuptools のバージョンに制約が課されます。そのため、互換性のないバージョンの statsmodels と setuptools を環境で要求すると、statsmodels 自体が setuptools に課す制限によって、推移的依存関係の競合が発生する可能性があります。
たとえば、huggingface-adapter 0.1.1* と transforms 1.645.0 を要求する次の環境を考えてみます。
The following packages are incompatible
├─ huggingface-adapter 0.1.1** * is installable and it requires
│ └─ palantir_models >=0.551.0 *, which requires
│ └─ pyspark-src >=3.2.1,<3.3.0a0 *, which can be installed;
└─ transforms 1.645.0 * is uninstallable because it requires
└─ pyspark-src 3.2.1_palantir.36 *, which conflicts with any installable versions previously reported
この2個のパッケージに互換性がない理由は、一見わかりにくいかもしれません。エラーメッセージから、huggingface-adapter の推移的依存関係が、transforms の pyspark-src に対する直接的依存関係と競合していることが問題の原因だとわかります。この環境の依存関係は、transforms または huggingface-adapter のいずれかの制約を緩和することで解決できます。これにより、Mamba は、pyspark-src に対する要件に互換性があるバージョンの組み合わせを特定できます。
新しい mamba エラーメッセージに表示される可能性のあるすべての表現と、その解釈方法および修正方法のガイダンスを以下に示します。
The following packages are incompatible または The following package could not be installed:通常、詳細なエラーメッセージの最初の文として、いずれかが表示されます。これは、問題の全体像が、互換性のないバージョンに起因するパッケージの競合なのか、必要なパッケージ自体のインストールの問題なのかを示します。
can be installed:この文は通常、依存関係ツリーの最上部に表示され、そのパッケージ自体は追加の制約なしでインストールできることを意味します。ただし、この特定のバージョンがインストールされたと仮定すると、ほかのパッケージの依存関係がそのインストール済みバージョンと競合し、競合が発生する可能性があります。たとえば、python 3.7** is requested and can be installed は、Python 3.7 をその環境にインストールできることを意味します。この文のすぐ下に記載されているほかの競合はすべて、Python 3.7 が環境にインストールされていることを前提としています。no viable options:インストール可能なバージョンのいずれも、要求された環境のほかの指定によって課される制約を満たせません。たとえば、python 3.7** is uninstallable because there are no viable options というメッセージは、別のパッケージや制約が異なる Python バージョンを明示的に要求していなければ、python 3.7.* のバージョンをインストールできることを示します。
does not exist, perhaps a (typo or a) missing channel:インストールするパッケージが見つかりませんでした。これは、パッケージの指定が間違っているか、設定されたどのチャネル(Code Repositories の設定 > ライブラリ、または Code Workbook の環境設定)にもパッケージが含まれていないことを意味すると考えられます。たとえば、python 3.423.*(存在しないバージョン)と pthon 3.8.*(明らかな入力ミス)を含む環境を要求すると、次のエラーメッセージが表示されます。 Could not solve for environment specs
The following packages are incompatible
├─ pthon 3.8** does not exist (perhaps a typo or a missing channel);
└─ python 3.423** does not exist (perhaps a typo or a missing channel).
修正方法:パッケージの指定に入力ミスがないこと、または要求されたすべてのパッケージを環境で利用できることを確認してください。Foundry でパッケージの存在を検索する方法については、Python ライブラリを探すを参照してください。
is installable and it requires:そのパッケージと指定されたバージョンは環境にインストールできますが、環境に追加の制約が生じます。
is uninstallable because it requires:依存関係の一部が環境内で競合を引き起こすため、そのパッケージと指定されたバージョンをインストールできません。
is installable with the potential options:このパッケージには、環境にインストールできる、競合しないバージョンの候補があります。これらのバージョンのいずれかを選択すると、さらに制約が生じる可能性があります。
conflicts with any installable versions previously reported:通常、上の行に記載されているバージョンと対比して表示されます。これは、そのパッケージについて、can be installed とされる前提のバージョンがすでに別の箇所で決まっているため、このバージョンでは要件を満たせないことを示します。
is missing on the system:これは具体的には、仮想パッケージ ↗がないことを指します。一部のパッケージは、特定の OS 環境でのみ実行できます。たとえば、cudatoolkit ↗ パッケージでは、既存のアーキテクチャでパッケージを実行できるようにするため、システムレベルの機能である __cuda の特定のバージョンが、仮想パッケージとして環境に存在する必要があります。
which cannot be installed (as previously explained):すでに説明された競合があるか、別のパッケージにすでに説明されたものとまったく同じ制約が含まれているため、このパッケージをインストールできません。
新しい Mamba エラーメッセージが導入される前のレガシーエラーメッセージのうち、よくあるものを以下に示します。
この場合、設定済みのどのチャネルも、依存関係であるパッケージ A を提供していません。
Copied!1Problem: nothing provides requested A.a.a.a
これは、固定したバージョンのパッケージが存在しない場合に発生することがあります。その場合は、meta.yml 内のパッケージのバージョン指定を緩めるか削除してみてください。たとえば、matplotlib 1.1.1 を matplotlib に変更します。
外部リポジトリは Conda のラベル ↗に対応していないため、ラベル内のパッケージは Palantir リポジトリから発見可能ではありません。
このエラーが発生した場合は、以下のアプリケーション別の手順に従ってパッケージを追加できます。

この場合、パッケージ A には必須の依存関係 B がありますが、どのチャネルもそれを提供していません。
Copied!1Problem: nothing provides B-b.b.b needed by A-a.a.a:
B は、ユーザーが明示的に要求したパッケージ(meta.yml/foundry-ml/vector プロファイル内)の場合も、推移的依存関係の場合もあります。
これは、エンロールメントで B をインストールできない場合に発生することがあります。たとえば、B の公開が停止されたために、インストールできなくなっている可能性があります。
その場合は、すべての依存関係が利用可能な A のバージョンが存在する可能性があるため、A のバージョン固定を解除してみてください。または、Palantir の担当者に連絡し、必要なパッケージを Foundry にインポートするよう依頼してください。
Copied!1cannot install both X.a.b.c and X.d.e.f
このエラーは、同じパッケージ X をインストールしようとして、2つの異なるバージョンに固定している場合に発生します。たとえば、meta.yml で python 3.9.* と python 3.10.* の両方を固定しようとすると、このエラーが発生することがあります。重複しているパッケージの固定指定のいずれかを削除すると、この問題を解決できます。
Copied!1CondaService:ReadRepositoryPermissionDenied
このエラーが発生する場合、必要なアセットとパッケージの一部がエンロールメントで利用できない可能性があります。それらがすべてエンロールメントにインストールされたら、必ず再デプロイしてください。
この場合、パッケージ A にはパッケージ B のバージョンに関する要件がありますが、そのバージョンの B がほかのパッケージと競合しています。
Copied!1Problem: package A-a.a.a requires B >=2.2.5,<2.3.0a0, but none of the providers can be installed
パッケージ B は、meta.yaml ファイルに要件として明示的に記載していない、A の推移的依存関係を指している可能性があります。推移的依存関係について詳しくは、環境作成の概要を参照してください。
依存関係の解決に失敗する最小限の例を作成します。環境の依存関係が正常に解決されるまでパッケージを削除し、その後、原因となっているパッケージを特定できるまでパッケージを追加し直します。
制約を緩めてみます(パッケージの固定を解除します)。
Code Workbook では、pandas、matplotlib、numpy に最小バージョンを指定して、デフォルトの pandas=0、matplotlib=2、numpy<1.20 が使用されるのを防ぐことができます。これらのデフォルトよりも新しいバージョンが必要な場合は、環境 > Spark 環境をカスタマイズ > プロファイルをカスタマイズに移動し、バージョン要件を満たすように、各パッケージのドロップダウンメニューからバージョンを選択します。

Mamba が生成するログをさらに詳細にすることもできます。これは、依存関係ツリーのさらに下位にある推移的依存関係を追跡する際に役立ちます(注:これによりチェックが遅くなります)。ログを詳細にするには、CI ログで Execution failed for task ':transforms-python:<task-name>'. という行を探し、チェックが失敗したタスクを特定します。たとえば、失敗したタスクが condaPackRun の場合は、内側の transforms-python/build.gradle ファイルの末尾に以下のブロックを追加します。
Copied!1 2 3tasks.condaPackRun { additionalArguments "-vvv" }
制約を完全に緩めても、要件リストに必要なパッケージやパッケージのバージョンが、以下のいずれかに該当する場合があります。
meta.yml 内の Python のバージョンと互換性がない。このシナリオに該当するかを確認するには、成功したチェックに関連する Conda ロックファイルと、失敗したチェックに関連するファイルを比較します。Conda ロックファイルにアクセスするには、設定の歯車アイコンで隠しファイル・フォルダを表示するオプションを選択し、transforms-python/conda-versions.run.linux-64.lock に移動します。成功した実行と失敗した実行の間で変更されたライブラリについて、meta.yaml ファイルで別のバージョンに固定します。
これが発生する主な理由は2つあります。
meta.yml に変更がない場合の処理の遅さをデバッグするCode Repositories では、以下を実行します。
@transform_df タグの外側のコードを変更した場合、そのコードがチェックを遅くしている可能性があります。該当する場合は、このコードのパフォーマンスを評価します。meta.yml に変更があった場合にジョブがタイムアウトする長時間実行されるジョブでメモリー不足(OOM)エラーが発生する場合、パッケージのバージョンに互換性がないために、環境の依存関係を解決できなくなっている可能性があります。これを解決するには、まずこのブランチをアップグレードし、その後、上記のデバッグ手順を実行します。
Copied!1CondaEnvironmentSetupError
ビルドエラーが発生した場合の解決手順は次のとおりです。
meta.yml に変更を加えた場合(変更の確認にはジョブ比較ツールを使用します)、変更を元に戻し、ビルドが正常に実行されるか確認します。meta.yml の変更を元に戻すことで問題が解決する場合は、パッケージの競合が発生している可能性が高く、上記の方法でデバッグできます。meta.yml を変更していない場合は、ビルドの Python モジュールのバージョンを確認します(次のステップを参照)。それでもビルドの問題が解決しない場合は、ブランチのアップグレードまたは基盤のアップグレード(アップグレード PR を参照)に伴う依存関係の解決によって、依存関係を解決できない環境になった可能性があります。その場合は、上記のデバッグ手順を確認してください。

Copied!1RuntimeError: Multi-download failed
このエラーは、パッケージのダウンロード元のアーティファクトチャネルへのアクセス権がないか、エンロールメントでそのアーティファクトを利用できないことを意味します。実際の失敗はドライバーログで確認できます。
このリポジトリをテンプレート化しようとしている場合は、Conda チャネルの一覧に移動し、一覧内のチャネルに警告が表示されていないか確認します。警告が表示されているチャネルがある場合は、次の手順に従います。
Copied!1transforms._errors.EntryPointError: "Key {name} was not found, please check your repo's meta.yaml and setup.py files"
このエラーは、ビルドのトリガーに必要なルートファイルに、何らかの不足があることを意味します。データセットプレビューは使用できる場合がありますが、ビルドは失敗します。
この問題をデバッグするには、meta.yaml または setup.py に必要な情報が不足していないか確認します。参考として、新しい Python コードリポジトリを作成し、そのリポジトリ内の meta.yaml ファイルと setup.py ファイルを確認できます。
meta.yaml または setup.py(あるいはその両方)に不足している情報を追加したら、変更をコミットし、チェックが成功するのを待ってから、ビルドを再実行します。
一部のパッケージは、利用可能にするために Conda パッケージと JAR の両方が必要です。よくある例として graphframes パッケージがあります(Conda パッケージには Python API が含まれ、JAR には実際の実装が含まれています)。Conda パッケージのみを追加し、必要な JAR を追加しないと、次のエラーが発生する場合があります。
o257.loadClass.: java.lang.ClassNotFoundException:<Class>
または、次のエラーが発生する場合もあります。
Java のクラスパス(classpath)参照エラーです - 使用している Python の依存関係が、クラスパスに含まれていない Java jar を参照しようとしています。最近追加した Python の依存関係を確認し、必要な Java パッケージ(JAR)への依存関係を build.gradle ファイルに追加してください。
このようなパッケージを追加するには、次の2つのステップが必要です。
transforms-python/build.gradle ファイルを選択します。ファイルの末尾に、次のブロックを追加します。Copied!1 2 3dependencies { condaJars '<group_name>:<name>:<version>' }
これらのパッケージがユニットテストにも必要な場合は、テスト時にも利用可能にする必要があります。そのためには、gradle ファイルに次のブロックを追加します(testing プラグインは sparkJars の依存関係より前に宣言する必要があります)。
Copied!1 2 3 4 5 6 7// テスト用プラグインを適用します apply plugin: 'com.palantir.transforms.lang.pytest-defaults' dependencies { condaJars '<group_name>:<name>:<version>' sparkJars '<group_name>:<name>:<version>' }
Conda パッケージと JAR の両方が必要な外部ライブラリの別の例として、Spark-NLP ↗ パッケージがあります。このパッケージの JAR 依存関係は、build.gradle ファイルに追加する必要があります。
まず、Spark-NLP を外部ライブラリとして追加します。

上記で追加したライブラリのバージョンに対応する JAR を、サブプロジェクト内の build.gradle ファイル(通常は transforms-python/build.gradle)に追加します。たとえば、上記の Spark-NLP のライブラリバージョンは5.0.2なので、次のステップでは、そのバージョン要件を満たす JAR を追加します。<group_name>:<name>:<version> 形式を使用すると、次のコードで JAR を build.gradle スクリプトに追加できます。
dependencies {
condaJars 'com.johnsnowlabs.nlp:spark-nlp_2.12:5.0.2'
}
名前に指定された対象バージョンが不明な場合は、Maven ↗ にアクセスして目的のライブラリを検索し、Foundry で確認したライブラリバージョンに対応する対象バージョンを探します。
上記のエラーで最も多い原因は、依存関係の競合です。依存関係の競合を減らすには、次のベストプラクティスに従います。
Python のバージョン指定は major.minor 形式を維持します。
3.9.*、3.10.*、3.11.* が利用可能です。Python のバージョンは固定せず、パッケージ名 python のみを指定することを推奨します。ただし、コードを特定のバージョンの Python で実行する必要がある場合は、build セクションと run セクションの両方で、選択したバージョンに固定する必要があります。Python 3.8.* は現在非推奨です。引き続き使用できますが、2025年1月以降はサポート対象外となります。Python 3.6.* と 3.7.* のサポートは終了しています。
build セクションと run セクションの Python の依存関係が同一であることを必ず確認してください。Python の依存関係が一致していないと、意図しない結果や失敗につながる可能性があります。
Python のバージョン指定では、python >=3.9 や python >3.9,<=3.10.11 などの範囲は利用できません。サポート対象外の Python バージョンを使用すると、非推奨の Python 3.6.* がデフォルトで使用されるため、meta.yaml でサポート対象の Python バージョンが有効な形式で固定されていることを確認してください。

Python 3.9以降、Foundry は Python のサポート終了 ↗で定められたスケジュールに従います。つまり、サポート終了が宣言された Python バージョンは、プラットフォームでもサポート対象外となります。詳細については、Python バージョンのページを参照してください。
依存関係の競合を引き起こす可能性があるため、バージョンを明示的に固定することは避けます。major.minor 形式のバージョン指定でも、競合が発生する場合があります。
Code Workbook では、自動設定の場合、デフォルトは pandas=0、matplotlib=2、numpy<1.20 となるため、pandas、matplotlib、numpy に最小バージョンを指定できます。
上記のガイダンスで問題を解決できない場合、またはこのガイドの範囲外の問題が発生した場合は、試したデバッグ手順の詳細を添えて、Palantir の担当者にお問い合わせください。