zvec

使用方法

始める前に、以下の点を確認してください：

1. 開発言語：Python または Node.js

   • Python：pip install zvec を使用します
   • Node.js：npm install @zvec/zvec を使用します

2. ユースケース：

   • RAG ドキュメント検索システム
   • セマンティック検索
   • マルチモーダル検索（画像＋テキスト）
   • ハイブリッド検索（キーワード＋セマンティック検索）

3. データ規模：

   • < 100k：FLAT インデックスを使用します（正確な検索）
   • 100k-10M：HNSW インデックスを使用します（推奨されるデフォルト）

   • 10M：IVF インデックスを使用します（メモリを最適化）

選択ワークフロー

• ユーザーがベクトル検索機能を必要としている
  • 開発言語を選択します（Python/Node.js）
  • ユースケースを特定します
    • RAG システム → 単一ベクトル検索＋ドキュメントチャンク管理を使用します
    • E コマース検索 → ハイブリッド検索（ベクトル＋フィルター）を使用します
    • マルチモーダル → マルチベクトル検索＋重み付けランキングを使用します
  • スキーマを設計します（ベクトルフィールド＋スカラーフィールド）
  • インデックスの種類を選択します（HNSW/FLAT/IVF）
  • データ同期戦略を実装します

デフォルトの推奨事項

• create_and_open() / ZVecCreateAndOpen() を使用して Collection を作成します
• デフォルトの距離指標としてコサイン類似度（COSINE）を使用します
• 密ベクトルには FP32 型を使用します
• フィルターフィールドに InvertIndexParam インデックスを作成します

検証チェックリスト

• ベクトルの次元数が Schema の定義と一致している
• スカラーフィールドの型が正しい
• フィルター条件の構文が正しい
• 大量のデータを書き込んだ後に optimize() を呼び出す

クイックスタート

Python：

import zvec

# Create Collection
schema = zvec.CollectionSchema(
    name="my_collection",
    fields=[
        zvec.FieldSchema(name="title", data_type=zvec.DataType.STRING),
    ],
    vectors=[
        zvec.VectorSchema(
            name="embedding",
            data_type=zvec.DataType.VECTOR_FP32,
            dimension=768,
            index_param=zvec.HnswIndexParam(
                metric_type=zvec.MetricType.COSINE
            ),
        ),
    ],
)

collection = zvec.create_and_open("./my_data", schema)

# Insert document
collection.upsert(zvec.Doc(
    id="doc_1",
    vectors={"embedding": [0.1] * 768},
    fields={"title": "Hello World"},
))

# Search
results = collection.query(
    vectors=zvec.VectorQuery(
        field_name="embedding",
        vector=[0.1] * 768,
    ),
    topk=10,
)

Node.js：

import { ZVecCreateAndOpen, ZVecCollectionSchema, ZVecFieldSchema, ZVecVectorSchema, ZVecDataType, ZVecHnswIndexParams, ZVecMetricType } from "@zvec/zvec";

const schema = new ZVecCollectionSchema({
  name: "my_collection",
  fields: [new ZVecFieldSchema({ name: "title", dataType: ZVecDataType.STRING })],
  vectors: [new ZVecVectorSchema({
    name: "embedding",
    dataType: ZVecDataType.VECTOR_FP32,
    dimension: 768,
    indexParams: new ZVecHnswIndexParams({ metricType: ZVecMetricType.COSINE }),
  })],
});

const collection = ZVecCreateAndOpen("./my_data", schema);

コアコンセプト

データモデル

Collection

• リレーショナルデータベースのテーブルに似た、データを保存、整理、クエリするためのコンテナーです
• 各 Collection には、構造を定義する Schema があります
• 各 Collection は、ディスク上の専用ディレクトリに個別に永続化されます

Document

• リレーショナルテーブルの行に似た、データストレージの基本単位です
• 次の 3 つの主要な要素で構成されます：
  • id：一意の文字列識別子
  • vectors：名前付きベクトルのコレクション（密ベクトルと疎ベクトルをサポート）
  • fields：名前付きスカラーフィールドのコレクション

Schema

• 動的 Schema：スカラーフィールドとベクトルはいつでも追加または削除できます
• 厳密な型システム：各フィールドには DataType の宣言が必要です

ベクトルの種類

密ベクトル

• 固定長の実数値埋め込み
• 型：VECTOR_FP16、VECTOR_FP32、VECTOR_INT8
• 適した用途：セマンティック理解、コンテキストの把握

疎ベクトル

• ゼロ以外の次元が少数のみの高次元表現
• 型：SPARSE_VECTOR_FP32、SPARSE_VECTOR_FP16
• 適した用途：キーワードマッチング、BM25 スコアリング

インデックスの種類

インデックスの種類	特徴	ユースケース
FLAT	総当たり検索、正確な結果	小規模データ（<100k）
HNSW	近似最近傍探索、グラフ構造	大規模データ（推奨されるデフォルト）
IVF	転置ファイルインデックス	非常に大規模なデータ

利用可能なトピック

Python

• クイックスタート - Zvec Python API を使ったクイックスタート
• Collection 管理 - Collection の作成、オープン、管理
• データ操作 - ドキュメントの挿入、更新、削除
• ベクトル検索 - 単一ベクトル、マルチベクトル、ハイブリッド検索
• RAG システム - ドキュメント検索システムの構築
• ハイブリッド検索 - ベクトル類似度＋スカラーフィルタリング
• マルチモーダル検索 - 画像＋テキストの統合検索

Node.js

• クイックスタート - Zvec Node.js API のクイックスタート
• コレクション管理 - コレクションの作成、オープン、管理
• データ操作 - ドキュメントの挿入、更新、削除
• ベクトル検索 - 単一ベクトル、複数ベクトル、ハイブリッド検索
• RAG システム - ドキュメント検索システムの構築
• ハイブリッド検索 - ベクトル類似度＋スカラーによるフィルタリング
• マルチモーダル検索 - 画像とテキストの統合検索

全般

• 設定 - グローバル設定と初期化
• データモデル - Zvec データモデルの概要
• 埋め込み - テキスト埋め込み関数（Python のみ）
• リランキング - 検索結果の再ランキング関数（Python のみ）
• API チートシート - Python と Node.js API のクイックリファレンス
• トラブルシューティング - よくある問題と解決方法

利用可能なトピック

Python

• コレクション管理
• データ操作
• ハイブリッド検索
• マルチモーダル検索
• クイックスタート
• RAG システム
• ベクトル検索

Node.js

• コレクション管理
• データ操作
• ハイブリッド検索
• マルチモーダル検索
• クイックスタート
• RAG システム
• ベクトル検索

全般

• 設定
• データモデル
• 埋め込み
• リランキング
• API チートシート
• トラブルシューティング