LangChain・LlamaIndex のバージョン不一致エラーを完全解決する方法

AI開発の現場で急速に普及した LangChain と LlamaIndex ですが、バージョンアップが非常に速いため「昨日まで動いていたコードが突然エラーになった」という経験をした方は多いのではないでしょうか。ここではよくある依存関係エラーのパターンを整理し、それぞれの根本原因と具体的な解決手順をご説明します。

よくある症状と再現パターン

LangChain・LlamaIndex 関連のエラーは、主に以下の場面で発生します。

pip install 時に依存関係が競合する

ERROR: pip's dependency resolver does not currently take into account
all the packages that are installed. This behaviour is the source of
the following dependency conflicts.
langchain 0.1.x requires openai>=1.6.1, but you have openai 0.28.0
which is incompatible.

ImportError / ModuleNotFoundError が発生する

from langchain.llms import OpenAI  # 旧API
# → ImportError: cannot import name 'OpenAI' from 'langchain.llms'

LangChain は v0.1 以降でパッケージ構造が大きく変わったため、古いチュートリアルのコードをそのまま実行するとこのエラーが頻発します。

LlamaIndex で AttributeError が出る

from llama_index import GPTSimpleVectorIndex  # 旧クラス名
# → AttributeError: module 'llama_index' has no attribute 'GPTSimpleVectorIndex'

LlamaIndex も v0.10 前後で命名規則が刷新され、旧クラス名が使えなくなりましました。

原因の分析：5つのパターン

パターン1：旧バージョンの API を参照している

LangChain は v0.1（2024年初頭）、v0.2（2024年後半）と立て続けに破壊的変更を加えましました。古いブログ記事や書籍のサンプルコードは旧APIを前提にしている場合が多く、最新環境では動作しません。

パターン2：openai ライブラリのメジャーバージョン不一致

LangChain の多くのバージョンは openai>=1.x を要求しますが、古い環境には openai==0.x が入っていることがあります。openai 1.x と 0.x では API の呼び出し方が根本的に異なるため、単純に LangChain だけ更新しても解決しません。

パターン3：仮想環境が混在している

グローバル Python 環境と仮想環境（venv / conda）が混在し、どちらのパッケージが使われているか把握できていないケースです。pip install しても効果がない、というときはほぼこのパターンです。

パターン4：llama_index のサブパッケージ分割に対応していない

LlamaIndex は v0.10 からモノリシックな llama_index パッケージが廃止され、llama-index-core と各種インテグレーションパッケージに分割されましました。pip install llama-index だけでは不十分で、使いたい機能に応じて追加パッケージが必要です。

パターン5：キャッシュや .egg-info の残骸

古い開発インストール（pip install -e .）の残骸や .egg-info ディレクトリが残っていると、新しいバージョンをインストールしても古いコードが読み込まれることがあります。

解決手順：パターン別の対処法

ステップ1：現在のバージョンと環境を確認する

まず状況を正確に把握する点が肝心です。

# 現在の Python 環境を確認
which python
python --version
 
# インストール済みの関連パッケージを確認
pip show langchain langchain-core langchain-community openai
pip show llama-index llama-index-core
 
# 仮想環境が有効かどうか確認
echo $VIRTUAL_ENV  # 何も表示されなければ仮想環境外

ステップ2：専用の仮想環境を作成する（推奨）

既存環境の汚染を避けるため、プロジェクトごとに仮想環境を作成することを強くお勧めします。

# venv で新しい仮想環境を作成
python -m venv .venv
source .venv/bin/activate  # Mac / Linux
# .venv\Scripts\activate   # Windows
 
# または uv を使う（高速・推奨）
pip install uv
uv venv
source .venv/bin/activate

ステップ3：LangChain を正しくインストールする

LangChain v0.2 以降は用途別にパッケージが分離されています。

# 最小構成（LLM連携のみ）
pip install langchain-core langchain-openai
 
# OpenAI + Community ツールを使う場合
pip install langchain langchain-openai langchain-community
 
# インストール後にバージョン確認
python -c "import langchain; print(langchain.__version__)"
# → 期待値: 0.2.x 以上

新しい API の書き方に合わせてコードも修正します。

# ❌ 旧API（v0.1以前）
from langchain.llms import OpenAI
llm = OpenAI(temperature=0.7)
 
# ✅ 新API（v0.2以降）
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

ステップ4：LlamaIndex を正しくインストールする

LlamaIndex v0.10 以降はサブパッケージ制になっています。

# コアのみ（最小構成）
pip install llama-index-core
 
# OpenAI LLM を使う場合
pip install llama-index-core llama-index-llms-openai llama-index-embeddings-openai
 
# Gemini を使う場合
pip install llama-index-core llama-index-llms-gemini llama-index-embeddings-gemini

旧クラス名から新クラス名への移行例を示します。

# ❌ 旧API（v0.9以前）
from llama_index import GPTSimpleVectorIndex, Document
index = GPTSimpleVectorIndex([Document(text="hello")])
 
# ✅ 新API（v0.10以降）
from llama_index.core import VectorStoreIndex, Document
index = VectorStoreIndex.from_documents([Document(text="hello")])

ステップ5：openai ライブラリを更新する

LangChain v0.2 以降は openai>=1.6 が必要です。

pip install --upgrade openai
python -c "import openai; print(openai.__version__)"
# → 期待値: 1.x.x

解決できたかの確認方法

以下のスクリプトを実行し、エラーなく通過することを確認してください。

# verify_install.py
import sys
print(f"Python: {sys.version}")
 
try:
    import langchain
    print(f"✅ langchain: {langchain.__version__}")
except ImportError as e:
    print(f"❌ langchain import failed: {e}")
 
try:
    from langchain_openai import ChatOpenAI
    print("✅ langchain_openai: OK")
except ImportError as e:
    print(f"❌ langchain_openai import failed: {e}")
 
try:
    from llama_index.core import VectorStoreIndex
    print("✅ llama_index.core: OK")
except ImportError as e:
    print(f"❌ llama_index.core import failed: {e}")
 
try:
    import openai
    print(f"✅ openai: {openai.__version__}")
except ImportError as e:
    print(f"❌ openai import failed: {e}")

python verify_install.py
# 期待される出力:
# Python: 3.11.x
# ✅ langchain: 0.2.x
# ✅ langchain_openai: OK
# ✅ llama_index.core: OK
# ✅ openai: 1.x.x

予防策：再発防止のベストプラクティス

requirements.txt または pyproject.toml でバージョンを固定する

# requirements.txt（例）
langchain==0.2.16
langchain-openai==0.1.23
langchain-community==0.2.16
llama-index-core==0.10.68
llama-index-llms-openai==0.1.29
openai==1.51.0

バージョンを固定しておくことで、チームメンバーや CI 環境でも同じパッケージが使われることが保証されます。

Antigravity で依存関係の更新を自動検知する

Antigravity Lab の RAG パイプライン構築ガイドでも紹介しているように、Antigravity の AI エージェントを活用すると requirements.txt の古いバージョンを検知し、変更差分のレビューまで自動化できます。

変更履歴（CHANGELOG）を定期的に確認する

LangChain・LlamaIndex ともに GitHub 上で詳細な変更履歴を公開しています。マイナーバージョンアップでも破壊的変更が入ることがあるため、アップデート前に確認する習慣をつけましょう。

全体を振り返って

LangChain・LlamaIndex のバージョン不一致エラーは、主に以下の5点を確認することで解決できます。

専用の仮想環境を作成し、グローバル環境と分離する
LangChain v0.2 以降は langchain-core + langchain-openai のサブパッケージ構成を使う
LlamaIndex v0.10 以降は llama-index-core + 機能別パッケージを個別にインストールする
openai>=1.6 を確認し、旧 0.x 系が残っていれば更新する
requirements.txt にバージョンを固定して再発を防ぐ

Python の AI ライブラリは進化が速く、依存関係の管理が複雑になりがちです。Python・PyTorch・CUDA インストールエラーの解決方法も合わせてご参照いただくと、より安定した AI 開発環境を整えることができます。