株式会社ホコサキ

zvecを実装レベルで読む――インプロセスベクターDBの設計とPython最小実装

天京祐輔
天京祐輔
zvecを実装レベルで読む――インプロセスベクターDBの設計とPython最小実装

外部サーバーを立てずにベクター検索を使いたい。そういう要件は意外と多い。PoC段階でDockerを持ち込みたくない、CLIツールに検索機能を組み込みたい、Lambda関数の中でRAGを完結させたい――そんなときに「インプロセスで動くベクターDB」という選択肢が浮かび上がる。

Alibaba Groupが2026年にオープンソース化したzvecは、まさにその用途に応えるライブラリだ。pip install zvec の一行でインストールでき、外部デーモンもRPCレイヤーも不要。プロセス内でベクター検索が完結する。zvecの設計思想を実装レベルで読み解きながら、Pythonバインディングによる最小実装を動かし、FAISS・ChromaDBとの使い分けを整理していく。

zvecとは何か――Proximaエンジンを包んだインプロセスDB

zvecの正体を一言で表すなら、「Alibaba Groupの本番ベクター検索エンジンをライブラリとして包んだもの」だ。コアにあるのはProximaと呼ばれるC++製の高性能ベクター検索エンジンで、Alibaba Group内の本番環境で長年使われてきた実績を持つ。zvecはそのProximaをシンプルなAPIと組み込みランタイムで包み、Pythonから直接呼び出せる形にしたプロジェクトだ。ライセンスはApache 2.0。

「インプロセス」という言葉が何を意味するかを正確に押さえておきたい。ChromaDBのサーバーモードやQdrant、MilvusといったベクターDBは、別プロセスとして起動したサーバーに対してHTTPやgRPCで問い合わせる構成を取る。zvecはそうではなく、あなたのPythonプロセスの中でDBエンジンが直接動く。ネットワークホップが存在しない。

このアーキテクチャを理解するのに一番わかりやすいアナロジーはSQLiteだ。SQLiteは「DBサーバー不要のSQL」として知られているが、zvecはその立ち位置のベクター検索版と考えるとほぼ正確に伝わる。アプリケーションにリンクするだけで動く、という設計思想が共通している。

GitHubのREADMEによると、v0.4.0時点でのサポート環境はPython 3.10〜3.14、Linux x86_64/ARM64、macOS ARM64。Windows向けのバイナリは現時点では提供されていない。Node.jsバインディングも存在するが、この記事ではPythonに絞る。

C++実装が生む設計上の特性――なぜ速く、なぜ軽いのか

zvecの速度と軽量さは「C++で書いてあるから」という単純な話ではなく、採用しているアルゴリズムとリソース管理の設計から来ている。

インデックス構造の中心にあるのは**HNSW（Hierarchical Navigable Small World）**グラフだ。HNSWは階層的なグラフ構造を使って近似最近傍探索を行うアルゴリズムで、探索時に全ベクトルを線形スキャンするのではなく、グラフ上のショートカットを辿ることで探索パスを大幅に短縮できる。精度と速度のトレードオフを調整しやすく、大規模データでも実用的なレイテンシを維持できるのがHNSWの強みだ。

Proximaエンジンの性能については、VectorDBBenchのCohere 10Mデータセットで8,000 QPS超を記録し、当時のリーダーボード1位だったZillizCloudの2倍以上を達成したとRedditの紹介記事で報告されている。ただしこれはベンチマーク上の数値であり、実際のワークロードでの性能は環境やデータ特性によって変わる。「Alibaba Group内の本番環境で長年使われてきた実績がある」という事実の方が、採用判断の根拠としては堅実だろう。

Pythonバインディングのオーバーヘッドが小さい理由も設計に根ざしている。PythonからC++ライブラリを呼ぶ際の典型的なボトルネックはデータのコピーコストだが、zvecはFFI（Foreign Function Interface）経由でC++コアを直接呼び出し、データコピーを最小化する構造を取っている。Pythonオブジェクトを何度もシリアライズしてHTTPで送るような構成とは根本的に異なる。

リソース制御の面では、以下のオプションが用意されている。

  • mmapモード: インデックスをメモリマップトファイルとして扱い、OSのページキャッシュを活用する。物理メモリが少ない環境でも大きなインデックスを扱える
  • ストリーミング書き込み: 大量ドキュメントの挿入時にメモリを一括確保せず、逐次書き込みで処理する
  • メモリ上限設定: 使用メモリの上限を明示的に指定でき、エッジデバイスや制約のある環境での動作を現実的にする
  • スレッド設定: 検索・インデックス構築に使うスレッド数を制御でき、CPUリソースの競合を避けられる

これらのオプションが揃っているのは、Alibaba Group内でモバイル・デスクトップ・エッジといった多様な環境での動作を想定して設計されているからだ。「組み込み用途」を後付けで対応したのではなく、最初からその用途を中心に据えている点が他のライブラリと異なる。

Pythonバインディングで動かす最小実装

まずインストールから。pip install zvec だけで完結する。依存関係の解決に特別な手順は不要だが、対応プラットフォームに注意が必要だ。Linux x86_64/ARM64とmacOS ARM64のみサポートされているため、Windows環境やmacOS Intel（x86_64）では動作しない。Dockerを使うか、対応環境のCIで動かすことを前提にしよう。

以下は、sentence-transformersでエンベディングを生成し、zvecでインデックスを構築・検索する実装例だ。APIのシグネチャはGitHubの公式ドキュメントとQuickstartを参照して構成しているが、バージョンによって変わる可能性があるため、実際に動かす前に公式ドキュメントで最新のAPIを確認してほしい。

import zvec
from sentence_transformers import SentenceTransformer

# エンベディングモデルの準備
model = SentenceTransformer("all-MiniLM-L6-v2")

# コレクションのオープン（ディレクトリを指定して永続化）
db = zvec.open("./my_collection")

# スキーマ定義：ベクトル次元数と距離関数を指定
if "docs" not in db.list_collections():
    collection = db.create_collection(
        name="docs",
        dimension=384,          # all-MiniLM-L6-v2 の出力次元
        distance="cosine",
    )
else:
    collection = db.get_collection("docs")

# ドキュメントの挿入
documents = [
    {"id": 1, "text": "Pythonは汎用プログラミング言語です"},
    {"id": 2, "text": "ベクター検索は意味的な類似度で検索します"},
    {"id": 3, "text": "zvecはインプロセスで動作する軽量なベクターDBです"},
    {"id": 4, "text": "HNSWは近似最近傍探索のアルゴリズムです"},
]

texts = [doc["text"] for doc in documents]
vectors = model.encode(texts).tolist()

collection.upsert(
    ids=[doc["id"] for doc in documents],
    vectors=vectors,
    payloads=[{"text": doc["text"]} for doc in documents],
)

# 類似検索
query = "組み込みデータベースの仕組みを知りたい"
query_vector = model.encode(query).tolist()

results = collection.search(vector=query_vector, top_k=2)
for result in results:
    print(f"score: {result.score:.4f} | {result.payload['text']}")

APIの設計はMongoDBに近いドキュメント指向で、スキーマ定義→コレクション作成→ドキュメント操作という流れに慣れていれば迷わず使える。zvec.open() にディレクトリパスを渡すことでデータが永続化され、プロセスを再起動してもインデックスが残る。

もう一点ハマりやすいのが、Python 3.9以下での動作だ。pip install zvec 自体は通ることがあるが、実行時にバイナリの互換性エラーが出る。Python 3.10以上を使っていることを事前に確認しておこう。

FAISS・ChromaDBとの比較――どの構成で何を選ぶか

「zvecはFAISSやChromaDBより優れているか」という問いの立て方はあまり有用ではない。それぞれが異なる設計判断をしており、ユースケースによって最適解が変わる。

比較軸FAISSChromaDBzvec
サーバー有無不要（ライブラリ）不要/あり（両モード）不要（ライブラリ）
永続化手動（save/load）組み込み対応組み込み対応
スケーラビリティ高（大規模向け）中（〜1000万件）中（単一プロセス）
APIの使いやすさ低レベル・ML寄り高（開発体験重視）中〜高（ドキュメント指向）
セットアップコスト低（pip install）低（pip install）低（pip install）
LangChain連携ありネイティブ対応v0.4.0時点では未確認

FAISSはMeta AI Research製で、大規模な近似最近傍探索に特化した低レベルライブラリだ。インデックスの種類が豊富で細かい制御ができる反面、永続化は自前で実装する必要があり、APIは研究者・MLエンジニア向けの色が強い。「GPUで10億件のベクトルを検索したい」という用途では今でも第一選択肢になる。

ChromaDBはデフォルトでインプロセス動作する組み込みDBであり、サーバーを立てなくても使える。開発体験を最優先に設計されており、LangChainとのネイティブ統合が強みだ。LLMアプリのプロトタイピングで「とにかく動くものを作りたい」という場面では最も摩擦が少ない。ただし本番スケールでの性能は専用DBには及ばず、1000万件を超えてくるとQdrantやMilvusへの移行が現実的な選択になる。

zvecの立ち位置は「インプロセス動作＋Proximaエンジン由来の性能特性」という組み合わせだ。FAISSと同様にサーバー不要だが、永続化が組み込まれており、APIがより扱いやすい。ChromaDBと比べると開発体験の洗練度や周辺エコシステムは現時点でやや劣るが、リソース制御の細かさとエッジ環境への適性はzvecの方が上だ。

アーキテクチャ上の近傍としてLanceDBも挙げておきたい。LanceDBはApache Arrow列指向フォーマットをベースにしたディスクネイティブ設計で、IVF-PQインデックスを採用している。zvecがHNSWとmmapを組み合わせるのに対し、LanceDBは列指向ストレージとの統合を強みにしており、分析ワークロードとの親和性が高い。どちらを選ぶかはデータアクセスパターンによる。

採用すべき場面と、見送るべき場面

zvecが最もよく機能するのは、「サーバーを立てるコストが価値に見合わない」場面だ。

典型的なのはPoCや社内ツールの文脈だ。新しいRAGのアイデアを検証したいとき、ChromaDBもzvecも pip install だけで始められる点は同じだが、zvecはリソース制御オプションが最初から揃っており、「PoC後にそのまま制約のある環境へ持ち込む」という流れがスムーズだ。検証フェーズから本番環境の条件を意識した実装ができる。

CLIツールへの組み込みも相性がいい。たとえばローカルのMarkdownファイルを意味検索するツールを作るとき、バックエンドにサーバーが必要な設計は配布の障壁になる。zvecなら単一のPythonパッケージとして配布でき、ユーザーは別途サービスを起動する必要がない。

サーバーレス関数（AWS LambdaやGoogle Cloud Functions）への組み込みも現実的な選択肢になる。コールドスタート時にサーバーへの接続を確立する必要がなく、関数のコンテナ内でインデックスを保持できる。エッジ推論環境でも同様で、ARM64対応があることでRaspberry PiやApple Siliconのような環境でも動作する。

一方で、zvecを見送るべき場面も明確にある。最も重要な制約から順に挙げると、こうなる。

  • マルチプロセス・マルチサービスからの共有アクセス: 複数のワーカープロセスや異なるマイクロサービスが同一のベクターインデックスを読み書きする構成には向かない。この制約が当てはまる時点で、外部サーバー型のDBを選ぶべきだ
  • 大規模データへのスケールアウト: zvecは単一プロセス内で動作するため、データが増えてもプロセスを横に並べることができない。数億件を超えるベクトルを複数サーバーで分散処理したい場合はMilvusやQdrantが適切だ
  • 耐障害性が求められる本番環境: zvecの永続化機能は存在するが、WAL（Write-Ahead Logging）やレプリケーションといった本番DBが当然持つ耐障害性の仕組みは現時点では限定的だ。データロストが許容できないクリティカルな用途では慎重に評価すること
  • LangChainを中心に据えたアーキテクチャ: v0.4.0時点では公式のLangChain統合は確認できていない。ChromaDBやFAISSのような既成のインテグレーションがなければ、接着コードを自前で書く必要がある

エコシステムの成熟度という観点では、zvecはまだ若いプロジェクトだ。GitHubのドキュメントは整備されており、DeepWikiやDiscordも用意されているが、Stack Overflowの回答やサードパーティのチュートリアルはChromaDBやFAISSに比べて圧倒的に少ない。トラブルシューティングで詰まったときに頼れるリソースが少ないことは、採用判断の現実的な考慮点になる。

まとめると、zvecは「サーバー管理コストを払いたくない」「でもFAISSの低レベルAPIは扱いたくない」「組み込み用途でリソース制御が必要」という条件が重なる場面でよく機能する。その条件から外れるなら、ChromaDB・FAISS・Qdrantのいずれかの方が成熟したエコシステムの恩恵を受けられる。

株式会社ホコサキは山口県宇部を拠点に、AI活用支援・業務システム開発・DX推進に取り組んでいます。RAGシステムの構成選定や実装支援に関心がある方は、お問い合わせページからご連絡ください。

    zvecを実装レベルで読む――インプロセスベクターDBの設計とPython最小実装 | 株式会社ホコサキ