zvec

zvecとzvec-grepの概要：Docker Composeでローカル検索を試す 文書を意味で探したいとき、ベクトルDBに加えて、文書の分割や埋め込みモデルの呼び出しも必要になります。まず検索を試すなら、その処理をまとめたCLIから始めると全体像をつかみやすくなります。 この記事では、検索の保存・実行基盤である zvec と、それを使う検索ツール zvec-grep（コマンド名は zg） の役割を整理します。その後、英語のMarkdown文書3件をDocker Compose経由でインデックス化し、文字列検索・キーワード検索・ベクトル検索・ハイブリッド検索を試す構成を紹介します。LLMによる回答生成までは行いません。 ベクトル検索・RAG・zvecの技術的な関係 ベクトル検索は「情報を探す方法」、RAGは「探した情報を使って回答を生成する構成」、zvecは「検索を実装するためのDB」です。同じ階層の技術ではなく、RAGの検索部分でベクトル検索を採用し、その保存・検索基盤にzvecを使う、という関係になります。 要素 担当すること この構成での位置 埋め込みモデル 文書や質問を数値の並び（ベクトル）に変換する 検索前の変換処理 ベクトル検索 質問のベクトルに近い文書ベクトルを探す 関連する文書を選ぶ方法 zvec ベクトルや関連データを保存し、類似度に基づいて検索する 検索を支えるDB RAG 外部の情報を検索し、その内容を生成モデルに渡して回答を作る 検索と生成を組み合わせる全体構成 回答生成用LLM 質問と検索した文書を入力として回答を生成する 検索後の生成処理 ベクトル検索は、意味を数値で比較して文書を探す 文章を埋め込みモデルへ入力すると、内容を表すベクトルが得られます。文書と質問を対応する同じベクトル空間へ変換し、cosine類似度などで近いものを探すことで、表現が異なっても関連する文書を候補にできます。意味の近さをどれだけ捉えられるかは、埋め込みモデルや文書の分割方法にも依存します。 例えば「アカウントに入れなくなった」という質問から、「パスワード再設定」の文書を探す場面です。zvecは登録されたベクトルを保存・検索します。文書をベクトルへ変換する埋め込み処理と、検索結果から文章を生成する処理は、それぞれ別の役割です。 RAGは、検索した文書を回答生成につなぐ RAGはRetrieval-Augmented Generation（検索拡張生成）の略です。RAGの原論文では、文書の検索と生成モデルを組み合わせる手法が示されています。ここでは、その考え方を使った典型的な文書検索・回答生成の流れを示します。 文書側の分割・埋め込み・保存は、事前準備として行います。質問を受け取った後は、質問を埋め込み、関連文書を検索し、その文書と質問を回答生成用LLMへ渡します。埋め込みモデルと回答生成用LLMは、役割も必要な計算資源も異なります。 この説明ではベクトル検索を使いますが、RAGの検索部分はキーワード検索やハイブリッド検索で構成することもできます。zvecも選択肢の一つであり、RAG全体を自動的に完成させるものではありません。また、関連文書を渡しても回答の正確性が保証されるわけではなく、検索結果と生成結果をそれぞれ評価します。 この記事では、RAGの検索部分までを試す この後に使うzvec-grepは、文書の探索・抽出・埋め込み・zvecを使った検索をまとめて試す入口です。今回のサンプルは、関連する文書を検索して表示するところまでを扱います。回答生成用LLMは起動せず、RAG全体を動かす構成ではありません。 既存のOSSベクトルDBと比べたzvecの優位性 zvecの強みは、単一アプリやローカルツールへ、独立したDBサーバーを増やさずに検索機能を組み込めることです。特に、個人開発のRAG、デスクトップアプリ、CLIなど、データを利用するアプリの近くに置きたい用途で利点があります。 ただし、比較する製品の実行形態を揃える必要があります。QdrantやMilvusにはサーバー型だけでなく、ローカル実行向けの選択肢もあります。以下は公式資料にある構成の比較であり、処理速度やメモリ使用量の比較実験ではありません。 サーバー型DBに対して、導入・運用する構成を小さくできる 比較対象 公式資料にある実行形態 zvecを選ぶ利点・比較時の留意点 Qdrantのサーバー構成 DBコンテナを起動し、クライアントからAPIで接続 アプリ内で検索でき、DBサービスの起動・接続先・ポート管理を省ける Milvus Standaloneの公式Compose例 Milvus・etcd・MinIOの3コンテナを起動 この構成に比べ、別途管理するDB・メタデータ・オブジェクトストレージのサービスを減らせる Qdrant Python clientのLocal mode メモリ内またはローカルパスで動き、DBサーバー不要 サーバー不要という点は共通。利用言語、必要な機能、データ規模で選ぶ Milvus Lite Pythonアプリへ組み込み、ローカルファイルに保存 組み込み型という点は共通。Milvusの他構成とAPIを共有する点も比較する 根拠は、Qdrant Quickstart、MilvusのCompose手順、Qdrant clientのLocal mode、Milvus Liteの説明です。Milvusの3コンテナという記載は参照した公式Compose例を指し、すべてのMilvus構成に当てはめるものではありません。 この構成差から、zvecには次の設計上の利点があると考えられます。 管理するサービスを減らせる：検索のためだけにDBサーバーの起動・停止、接続設定、サービス監視を追加せずに済みます。単一アプリへ検索を追加するときの導入負担を抑えられます。 DBへのネットワーク往復を省ける：プロセス内の呼び出しで検索するため、DBクライアントとサーバー間の通信経路が不要です。これは通信に伴う処理を省けるという意味で、検索全体が必ず高速になるという測定結果ではありません。 アプリと一緒に配布・検証しやすい：SDKと保存先をアプリの構成へまとめられます。この記事でも、検索用サービス1個の中でzvecを利用します。バックアップや依存バージョンの管理は引き続き必要です。 組み込み型でも、検索機能を組み合わせられる zvec v0.7.0の公式READMEでは、Dense・Sparseベクトル、全文検索、構造化フィルター、それらを組み合わせるハイブリッド検索が案内されています。サーバーを立てずに、これらをアプリの検索基盤として使える点が魅力です。PythonとNode.jsのSDKがあり、本記事ではNode.js側から利用します。 文書の取り込みから検索までを早く試したい場合は、zvec-grepを入口にできます。ただし、そのファイル探索・抽出・CLI機能はzvec-grepが提供するものであり、zvec本体の機能とは区別します。また、ハイブリッド検索やローカル実行は他のOSSにもあるため、それらの存在だけでzvecが全面的に優位とは判断できません。 優位性が出る条件と、サーバー型を検討する条件 自分のPCや単一アプリで使う検索、まず小さく始めたいRAGでは、zvecの構成の少なさが利点になります。一方、複数アプリから同じデータをAPIで共有したい、DBをアプリと別に運用・増強したい、障害の影響範囲をプロセスごとに分けたい場合は、サーバー型DBの構成も比較対象になります。プロセス内で動くzvecでは、検索処理が使うCPU・メモリもアプリと同じプロセスに属するためです。 zvecは同一コレクションに対する複数プロセスの読み取りと、単一プロセスによる排他的な書き込みを区別しています。複数の書き込み元が必要なら、この制約を踏まえた設計が必要です。 本記事のサンプル3件の結果から、QdrantやMilvusより高速・省メモリ・高精度とは結論付けません。性能を比較する場合は、同じベクトル、検索条件、ハードウェア、同時実行数に加え、検索の再現率を揃えて、応答時間・スループット・インデックス作成時間・メモリ使用量を測る必要があります。 ! 検証範囲を先に示します。Linux x86_64・Node.js 24.19.0上で、配布版zvec-grep 0.2.1とzvec Node.js SDK 0.7.1を使い、同じ文書の登録、4種類の検索、再インデックスを実行しました。 執筆環境にはDockerがなく、以下のDockerイメージのビルドとCompose実行は未確認です。コンテナでの再現確認が必要なサンプルとして読んでください。 zvecとzvec-grepの役割 項目 zvec zvec-grep 主な役割 アプリに組み込むプロセス内ベクトルDB コードや文書を探すCLI・エージェント向け検索ツール 使い方 SDKでスキーマ・データ登録・検索を実装 zg index や zg query を実行 扱う処理 ベクトル・全文検索、構造化フィルターなど ファイル探索・抽出・埋め込み・検索結果の提示など 保存先 指定したローカルコレクション ワークスペースの .zvec-grep/ サーバー 独立したDBサーバーを必須としない 単発CLI実行とローカルの常駐Serverを選べる zvecの公式READMEでは、Dense・Sparseベクトル、全文検索、ハイブリッド検索などが案内されています。自作アプリに検索機能を組み込みたい場合は、このSDK側から設計します。文章からベクトルを作る埋め込み処理は、DBに保存する処理とは別に考える必要があります。 zvec-grepの公式READMEは、ripgrep、BM25、ベクトル検索をまとめるツールとして紹介しています。文書を用意して検索を試したい場合はこちらが入口になります。現行mainには別実装の案内もありますが、この記事はnpm配布のTypeScript／Node.js版を対象とします。 検索方法の使い分け 方法 入力の例 向いている場面 ripgrep password という文字列 既知の文字列・正規表現を漏れなく探す BM25／全文検索 password というキーワード キーワードに関連する文書を順位付きで探す ベクトル検索 recover access to an account 同じ単語がなくても近い意味の文書を探す ハイブリッド検索 自然文とキーワード 意味の近さと語句の手掛かりを併用する zvec-grepのインデックス検索は、抽出した文書断片の語句とベクトルから候補を探し、順位を統合できます。公式ArchitectureではRRF（Reciprocal Rank Fusion）が説明されています。対してripgrepは元ファイルを直接走査するため、インデックスも埋め込みモデルも不要です。 RAGへ進む場合は、この検索結果を根拠としてLLMに渡す処理を追加します。検索できることと、正確な回答を生成できることは別々に検証します。 前提条件 対象バージョン 要素 この記事の指定 コンテナ node:24-bookworm-slim（Debian・glibc系） zvec-grep @zvec/zvec-grep@0.2.1 zvec Node.js SDK @zvec/zvec@0.7.1（overrideで固定） 埋め込みモデル local/potion-retrieval-32m 実行方式 direct、CPU、単発コマンド コンテナの対象 linux/amd64 ホスト側 Docker EngineまたはDocker Desktop、Compose v2 公式mainのCLIガイドは変更が進んでいます。0.2.1では zg index・zg query を使用します。 mainにある zg --index などの構文を混ぜないでください。この記事の構文はv0.2.1のCLIガイドと、インストールしたパッケージのヘルプで確認しています。 Linux・Windows（Docker DesktopのLinuxコンテナ）などから実行できますが、記事のシェル例はBashを前提にします。ARM64ホストではamd64エミュレーションが必要になり、速度・互換性は別途確認してください。zvec本体が対応するプラットフォームと、CLIの依存パッケージが動く条件は同一ではありません。 小さな検証用として、Dockerへ2 vCPU・4 GiB程度のRAMと数GBの空きディスクを割り当てるところから始めます。これは公式の最低要件や実測による必要量ではありません。npm依存・モデル・イメージ・インデックスが容量を使い、対象文書が増えると追加のメモリと保存領域が必要です。GPUと外部LLM APIキーは使いません。 英語文書向けの軽量モデルを選ぶため、サンプルも英語です。日本語の検索品質をこの結果から判断しないでください。 手順 1. 作業ディレクトリを用意する zg-compose-demo を作り、その下に次のファイルを保存します。ファイル内容は後述の「コード例」にあります。 ファイル 用途 package.json zgとzvecのバージョン指定 Dockerfile CLIの実行イメージ compose.yaml 実行位置と永続化先 docs/password.md パスワード再設定の文書 docs/backup.md DBバックアップの文書 docs/cache.md 画像キャッシュの文書 mkdir -p zg-compose-demo/docs cd zg-compose-demo 構成はComposeサービス1個です。検索用コンテナの中でzvecも動きます。DBサーバーのサービスや公開ポートは追加しません。 2. ビルドとバージョン確認 ファイルを保存してから、以下を実行します。 docker compose config docker compose build docker compose run --rm zg --version docker compose run --rm zg index --help CLIのバージョンが 0.2.1 であることを確認します。config はCompose設定の確認であり、イメージのビルド成功や検索成功までは保証しません。 3. インデックスを作る docker compose run --rm zg index \ --embedding local/potion-retrieval-32m \ --mode direct \ --embedding-concurrency 1 docker compose run --rm zg status --mode direct コンテナの作業場所は /workspace で、ホストの docs/ をマウントします。その配下に .zvec-grep/ が作られます。 モデルは初回利用時にダウンロードされます。モデルキャッシュは ZVEC_GREP_MODEL_CACHE=/models に変更し、名前付きボリュームに保存します。今回の0.2.1のModel2Vec実装はHugging Faceからモデルを取得します。初回から完全オフラインでは動きません。ビルド時もコンテナレジストリとnpmへの接続が必要です。 4. 4種類の検索を比較する 既知の文字列を直接探します。この処理だけならモデルもインデックスも不要です。 docker compose run --rm zg query --rg -n password . 次は、作成したインデックスを使う検索です。 キーワード検索 docker compose run --rm zg query --fts password \ --mode direct --human --limit 3 ベクトル検索 docker compose run --rm zg query \ --vector "recover access to an account" \ --mode direct --human --limit 3 ハイブリッド検索 docker compose run --rm zg query \ "recover access to an account" \ --mode direct --human --limit 3 キーワードを明示して融合する場合は、次のようにも書けます。 docker compose run --rm zg query \ --hybrid "recover access to an account" \ --fts password --fuse \ --mode direct --human --limit 3 ネイティブ実行では3ファイルの登録に成功し、status は3件・512次元・cosineを表示しました。--fts password は password.md を返し、上記のベクトル検索とハイブリッド検索も同ファイルを1位に返しました。これはサンプル3件での確認であり、検索精度や性能のベンチマークではありません。 5. 文書の変更・再作成を確認する 文書を編集・追加した後は再インデックスします。direct の検索は既定では更新待ちをしないため、明示的な更新を基本にします。 docker compose run --rm zg index --mode direct \ --embedding-concurrency 1 変更なしで再実行したネイティブ検証では、3件が unchanged、失敗0件となりました。既存インデックスは保存したモデル設定を引き継ぎます。 モデルを変えるときは、ベクトル空間が変わるため再構築します。日本語などを扱う検証の出発点として、多言語モデルへ切り替える例です。 docker compose run --rm zg index --rebuild \ --embedding local/potion-multilingual-128m \ --mode direct --embedding-concurrency 1 この多言語モデルへの切り替えは未実行です。別モデルの取得容量、時間、品質を確認してください。 6. 終了・削除する run --rm は処理が終わると実行コンテナを削除します。インデックスはホストの docs/.zvec-grep/、モデルは名前付きボリュームに残るため、次の実行で再利用できます。 Composeが管理するコンテナやネットワークを片付ける docker compose down インデックスを削除する。原本のMarkdownは残る docker compose run --rm zg index --drop --yes --mode direct モデルキャッシュの名前付きボリュームも削除する docker compose down --volumes down --volumes だけでは、バインドマウント先の docs/.zvec-grep/ は削除されません。キャッシュ削除後は次回のモデル取得が必要です。ビルドしたイメージもこのコマンドでは削除しません。 コード例 package.json { "name": "zg-compose-demo", "version": "1.0.0", "private": true, "dependencies": { "@zvec/zvec-grep": "0.2.1" }, "overrides": { "@zvec/zvec": "0.7.1" } } zvec-grepが内部で使うzvecもoverrideで固定します。ただし、これだけでは間接依存の全バージョンは固定されません。継続利用するプロジェクトでは package-lock.json を生成・保存し、Dockerfileも npm ci を使う構成に変更します。 Dockerfile FROM node:24-bookworm-slim WORKDIR /opt/zg COPY package.json ./ RUN npm install --omit=dev \ && npm cache clean --force ENV PATH="/opt/zg/node_modules/.bin:${PATH}" WORKDIR /workspace ENTRYPOINT ["zg"] Debian系を使い、glibc向けネイティブバインディングを利用する構成です。--omit=optional は付けません。zvecやripgrepのプラットフォーム別バイナリもoptionalDependenciesとして配布されているためです。依存パッケージのインストールスクリプトが実行される点も含め、ビルドログを確認してください。 compose.yaml name: zg-compose-demo services: zg: platform: linux/amd64 build: context: . working_dir: /workspace environment: ZVEC_GREP_MODE: direct ZVEC_GREP_MODEL_CACHE: /models volumes: - ./docs:/workspace - model-cache:/models command: ["--help"] volumes: model-cache: /workspace は検索対象だけに絞ります。Dockerfileやnpm依存まで検索する必要はありません。モデルキャッシュを別のマウント先に置くことで、そのファイル群も検索対象から外します。 docs/password.md Password reset Send a time-limited reset link by email when a user forgets a password. docs/backup.md Database backup Create a daily database backup and test restoration regularly. docs/cache.md Image cache Cache resized images to reduce page loading time. 注意点 ローカルモデルと通信・保存を区別する 今回のモデルを使う埋め込み計算はローカルです。一方、初回のモデル取得は外部通信を伴います。原文・検索語の外部埋め込みAPIへの送信は、この構成では設定していません。 モデルキャッシュとインデックスは別のデータです。特にインデックスには検索用の情報が残るため、元文書と同じように扱ってください。モデルをキャッシュしても、完全オフラインでの初回起動や更新を検証したことにはなりません。 書き込みとファイル所有者に注意する この例はイメージの既定ユーザーで動くため、Linuxホストでは docs/.zvec-grep/ がroot所有になる場合があります。共有環境へ持ち込む際はUID／GIDと書き込み権限を調整します。 同じインデックスへ複数の index を同時実行しないでください。zvecの公式READMEでは、読み取りの並行実行と、単一プロセスによる排他的な書き込みが区別されています。 常駐サーバーが必要になる場面 今回は単発CLIを選びました。direct はコマンドごとにプロセスを終了するため、モデルの読み込みも繰り返します。頻繁に検索する場合やエージェントからMCPで利用する場合は、モデルを再利用できるServer構成を検討します。 zvec-grepのServerはローカルループバックでの利用を前提とします。今回のComposeへポート公開だけを足してリモート検索APIにする設計は扱いません。 実行済みと未確認を整理する 対象 確認状況 配布版0.2.1のヘルプとコマンド構文 ネイティブ実行で確認 3文書の登録・状態確認・4種類の検索 ネイティブ実行で確認 複数クエリの融合・変更なしの再インデックス ネイティブ実行で確認 Docker build・Compose起動・マウント先の永続化 未実行 インデックス削除・キャッシュ削除 手順掲載のみ、未実行 多言語モデル・日本語の検索品質 未実行 大量データの性能・最低必要スペック 未検証 ネイティブ検証では、インストールスクリプトを抑止して依存を配置した後、zvecのバイナリ準備処理を実行しています。Dockerfileの通常の npm install と同一のビルド経路を検証したものではありません。コンテナ側の依存解決・ネイティブバイナリ・保存先を確認する際は、「ビルドとバージョン確認」から順に進めてください。 参考資料 zvec v0.7.0 README：サンプルに近いリリース世代の組み込み型DBとしての構成と検索機能。 Qdrant Local Quickstart：サーバー構成の起動・接続方法。 Qdrant Python client Local mode：サーバー不要のローカル実行。 Milvus Docker Compose：Standaloneの公式Compose例。 Milvus Lite：Pythonへの組み込みと他のMilvus構成とのAPI共有。 Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks：検索と生成を組み合わせるRAGの原論文。 alibaba/zvec：プロセス内DB、検索機能、対応プラットフォーム、並行アクセスの説明。 zvec-ai/zvec-grep：検索CLIの概要とzvecとの関係。 zvec-grep v0.2.1 CLI guide：本文で使用したコマンドとオプション。 zvec-grep v0.2.1 Embedding models：モデル選択、キャッシュ、モデル変更の方針。 zvec-grep Architecture：インデックス検索とripgrepの経路、BM25・ベクトル・RRFの関係。 zvec-grep Server and execution modes：Direct／Serverの考え方。mainのCLI構文は配布版0.2.1と異なるため、実行時は配布版のヘルプも確認する。 資料と配布パッケージは2026年10月21日（日本時間）に確認しました。