よくあるエラーと対処法（Index not trained, dimension mismatch など）

1. AssertionError: 'Index not trained'

切り分けポイント 内容
代表メッセージ Error: '!(this->is_trained)' failed: Index not trained github.com
典型的な発生条件 IVF 系列（IndexIVF* / IndexIVFPQ など）のインデックスを train せずに add／search を呼び出した場合
原因 インデックス内部にクラスタ重心や PQ コードブックが無く、データを受け入れられない
即時対処 1) 十分な代表サンプルで index.train(x_train) を実行
2) index.is_trained を確認してから add を呼び出す medium.com
再発防止ベストプラクティス – スキーマをコード化：assert not index.requires_training or index.is_trained
– 学習用サンプル数の経験則：nlist × 32 以上で IndexIVF*、min(1e5, 5×d) 以上で IndexIVFPQ を目安

2. AssertionError: d == self.d など 次元不一致（dimension mismatch）

切り分けポイント 内容
代表メッセージ AssertionError: d == self.d ／ Dimension mismatch: 768 != 1536 など github.com
典型的な発生条件 – 既存インデックスに 異なる埋め込みモデルで生成したベクトルを追加
– faiss.IndexFlatL2(d) の d を誤設定
原因 インデックス作成時に固定される d（次元数）が、add／search に与えた配列の列数と一致しない
即時対処 1) ベクトルの shape[1] をログ出力し、インデックスの index.d と照合
2) 異なるモデルを使う場合は 新しいインデックスを作成
再発防止ベストプラクティス – 埋め込みモデル → インデックスの d を 自動取得 (d = embeddings.shape[1])
– CI で「学習→追加→検索」のスモークテストを実施（小規模データで OK）

3. AttributeError: module 'faiss' has no attribute 'StandardGpuResources'

（GPU モジュール読み込み失敗）

切り分けポイント 内容
代表メッセージ AttributeError: module 'faiss' has no attribute 'StandardGpuResources' github.com
原因 – pip install faiss-cpu で CPU 版を入れたのに GPU API を呼び出した
– CUDA ランタイム (libcudart.so) のバージョン不整合
即時対処 1) 正しいバイナリを再インストール pip uninstall faiss-* && pip install faiss-gpu==<ver>
2) from faiss import _swigfaiss_gpu で詳細な ImportError を確認し、欠落ライブラリをインストール
再発防止ベストプラクティス – コンテナ内で CUDA ver ↔ faiss-gpu ver を固定 (requirements.txt + nvidia/cuda:<tag>)
– GPU 機能呼び出しをオプション化し、CPU フォールバックを用意

4. NumPy dtype 不一致 (np.int64 が渡される)

切り分けポイント 内容
代表メッセージ TypeError: in method 'search', argument 2 of type 'int' （np.int64 を渡したとき） github.com
原因 SWIG ラッパが Python int のみ受け取り、np.int64 は別型として扱われる
即時対処 k = int(k_np) のように 明示キャストしてから search/add を呼ぶ
再発防止ベストプラクティス – API ラッパーで int(x) へ自動変換
– mypy/pytest で dtype チェックを追加

共通デバッグ手順 (チェックリスト)

  1. 前処理・検証

    python
    assert x.dtype == np.float32 and x.flags['C_CONTIGUOUS']
assert x.shape[1] == index.d
assert not index.requires_training or index.is_trained

  2. 最小再現スクリプトを別プロセスで実行し、再現の有無を確認

  3. 環境情報を固定

    • Python, Faiss, CUDA のバージョンを poetry.lock / requirements.txt に明示

  4. エラー全文を保管し、Issue 登録時に貼り付け

  5. メモリ・GPU の使用量を監視（大量追加時は OOM が別の Assertion となることがある）

まとめ

  • Index not trained と dimension mismatch は データ準備フェーズ で検出できる

  • GPU ランタイム/バイナリ不整合 は インストール手順 をスクリプト化して撲滅

  • dtype の暗黙差は 静的型チェック と CI テスト で自動検出を推奨

これらをチェックリスト化して開発フローに組み込むことで、Faiss 利用時のトラブルを大幅に低減できます。

ChatGPT4o 生成日：2025/06/18