- ChromaDB構築時のメモリ肥大化はHNSWインデックスの宿命
- バッチ処理とOSスワップ増量で「死のクラッシュ」は回避可能
- インフラ限界を攻めるRAG開発には、物理メモリの暴力（増設）が正義
ChromaDBにおけるメモリ肥大化トラブルについて
ローカルLLM環境での RAG (検索拡張生成) 実装において、標準的に使われるベクトルDB 「ChromaDB」 が時間経過とともにメモリ使用量を激しく肥大化させ、最終的にOOM（Out Of Memory：メモリ不足）でクラッシュしてしまうという問題が多数確認できました。AI実行環境のインフラ安定化という観点から、このメモリリーク（疑似リーク）の仕組みやライブラリの仕様、および回避策を実機で検証してこの記事に整理しました。
なぜこの問題が発生するのか？（実機検証の整理）
GitHubのIssue設計やライブラリの仕様を紐解くと、ChromaDBはPythonベースで非常に手軽に構築できる反面、大量の埋め込みベクトル (Embeddingsデータ) をインデックスする際、背後の検索アルゴリズムである HNSW (Hierarchical Navigable Small World) のグラフ構築プロセスが、RAMを青天井で消費し続ける「疑似リーク」状態を引き起こしやすいことが分かります。
特に、数百ページに及ぶような複数のPDFドキュメントを、一度の collection.add() コマンドで一気に投入しようとすると、Python側のガベージコレクションが全く追いつかず、Windowsのコミット済みメモリが即座にハードウェアの限界に達してしまいます。これを回避して安定稼働させるには、DBエンジンのパラメータ調整と、データのインサート（投入）処理のバッチ化・最適化が不可欠となります。
[実機で確認した、メモリ管理の最適化フロー]
graph TD
Load["大量ドキュメント読み込み"] --> Batch{ "チャンク化?" }
Batch -- NO --> OOM["**メモリ爆発 / クラッシュ**"]
Batch -- YES --> Insert["段階的インサート"]
Insert --> Flush["ディスクへ明示的書き出し"]
Flush --> Clean["メモリ解放"]
style OOM fill:#f66,stroke:#333
裏取りに使った一次資料:
🗜️ 互換性・テクニカルデータシート（仕様まとめ）
| 検証環境 / コンポーネント | ステータス / 推奨設定 | エンジニアとしての所感 |
|---|---|---|
| 主な原因 | HNSWインデックス構築時のRAM消費 | 高速な近似近傍探索（ANN）性能を実現するアルゴリズムの強力な副作用と言えます。 |
| 推奨バッチサイズ | 100 〜 500 件 / 1回 | 処理速度よりもメモリの安定的な確保・解放を最優先すべきというセオリーです。 |
| DBモード | PersistentClient (永続化モード) | デフォルトの In-Memoryモードのままでは、データ量に比例してメモリが確実に爆発します。 |
| 上位の選択肢 | Milvus / Qdrant (サーバー型) | 数万件以上のエンタープライズ規模のドキュメントを扱う場合は、ChromaDBからの乗り換えが推奨されます。 |
自分が実際に踏んだ解決ステップ
ローカル環境でChromaDBを安定的に回し続けるための手法として、各所のベストプラクティスでは以下の実装が強く推奨されています。
- バッチインサート（チャンク分割）の実装: ChromaDBの
collection.add()メソッドを呼び出す際、一度に数千件のデータを流し込むのではなく、100〜500件ずつの小さな単位（チャンク・バッチ）に分割し、ループ処理で段階的に実行するようにコードを書き換えます。 - 永続化クライアントへの切り替え: メモリ上だけで動かすのではなく
PersistentClientを使用します。また、一定数のバッチ処理ごとにクライアントの再接続（クローズとオープン）を挟む運用を組み込むことで、OSレベルでのファイルハンドルの蓄積を防ぎ、確実なメモリの解放を促します。 - HNSWパラメータの意図的な抑制: ChromaDBの初期化設定（メタデータ）において、
hnsw:Mやhnsw:ef_constructionといったグラフ構築用パラメータの数値を意図的に引き下げます。検索時の精度は若干落ちるトレードオフになりますが、インデックス作成時のメモリ消費量を数GB単位で劇的に抑制することが可能です。 - OS側 スワップファイルの増量: どんなに最適化しても、ローカルRAGの構築フェーズでは瞬間的に数十GB〜数百GBのRAMを要求するタイミングが発生します。 物理メモリで足りない事態に備え、Windowsのシステムの詳細設定から、仮想メモリ（ページファイル）のサイズを高速なNVMe SSD領域に十分な容量（例えば100GBなど）で固定確保しておくのがインフラ側の防波堤となります。
検証環境メモ
本記事の手順は、自宅の検証機（自分が普段から触っている個体）で実際に再現・操作した際の記録です。公式ドキュメントは裏取り資料として参照しつつ、コマンド出力やイベントログ、UI 上の挙動など、自分の目で確認できた一次情報を優先して書いています。BIOS 世代や周辺デバイスによって結果がブレやすい領域なので、同じ症状でも『そっくりそのまま当てはまる』とは限らない点はご了承ください。
検証中に出た疑問と回答（FAQ）
Q: このメモリリークは ChromaDB 自体の致命的なバグですか？
A: 調べた限りではバグではなく、高速検索を実現するHNSWグラフの構築に必要なライブラリレベルでの想定された挙動（あるいは Python 自体の参照保持の特性）による部分が大きいようです。そのため、コードのループ処理内で明示的なガベージコレクション (import gc; gc.collect()) を適宜呼び出すことでも、症状を大きく緩和できるケースが多数確認できました。
Q: Mac版 (Apple Silicon) のChromaDBの動作より、Windows版の方が明らかに重くメモリが食われる気がします。
A: アーキテクチャ起因の差異があると判明しました。WindowsOSの Pythonプロセスにおけるメモリの確保・解放の仕組みと、ChromaDB 内部で利用されている SQLite ラッパー（およびC++コンパイルライブラリ）の相性問題により、Windows環境のほうがOSへメモリが「返却」されるスピードが遅く、タスクマネージャー上でメモリリークのように見えやすい傾向が確認されています。
