ベクトル検索

client.create_table()使用してテーブルを作成し、 VectorField使用してベクトル フィールドを定義できます。

次の例では、4 つの列を持つdocumentsテーブルを作成します。

• id : テーブルの主キー。
• text : ドキュメントのテキストコンテンツ。
• text_vec : テキスト コンテンツのベクトル埋め込み。
• meta : ドキュメントのメタデータ (JSON オブジェクト)。

from pytidb.schema import TableModel, Field, VectorField
from pytidb.datatype import TEXT, JSON

class Document(TableModel):
    __tablename__ = "documents"

    id: int = Field(primary_key=True)
    text: str = Field(sa_type=TEXT)
    text_vec: list[float] = VectorField(dimensions=3)
    meta: dict = Field(sa_type=JSON, default_factory=dict)

table = client.create_table(schema=Document, if_exists="overwrite")

VectorFieldクラスは次のパラメータを受け入れます。

• dimensions : ベクトルの次元。指定すると、このフィールドには指定した次元のベクトルのみが格納されます。
• index : ベクトルフィールドにベクトルインデックスを作成するかどうか。デフォルトはTrueです。
• distance_metric : ベクトルインデックスに使用する距離メトリック。サポートされる値:
  • DistanceMetric.COSINE （デフォルト）: コサイン距離メトリック。テキストの類似性を測定するのに適しています。
  • DistanceMetric.L2 : L2距離メトリック、全体的な差異を捉えるのに適しています

table.bulk_insert([
    Document(text="dog", text_vec=[1,2,1], meta={"category": "animal"}),
    Document(text="fish", text_vec=[1,2,4], meta={"category": "animal"}),
    Document(text="tree", text_vec=[1,0,0], meta={"category": "plant"}),
])

ベクトル検索を実行するにはtable.search()メソッドを使用します。デフォルトではsearch_mode="vector"が使用されます。

table.search([1, 2, 3]).limit(3).to_list()

[
    {"id": 2, "text": "fish", "text_vec": [1,2,4], "_distance": 0.00853986601633272},
    {"id": 1, "text": "dog", "text_vec": [1,2,1], "_distance": 0.12712843905603044},
    {"id": 3, "text": "tree", "text_vec": [1,0,0], "_distance": 0.7327387580875756},
]

結果によると、最も関連性の高いドキュメントは距離が0.00853986601633272のfishです。

table.search() API は次の距離メトリックをサポートしています。

ベクトル検索に使用する距離メトリックを変更するには、 .distance_metric()メソッドを使用します。

例: L2距離メトリックを使用する

from pytidb.schema import DistanceMetric

results = (
    table.search([1, 2, 3])
        .distance_metric(DistanceMetric.L2)
        .limit(10)
        .to_list()
)

.distance_threshold()メソッドを使用して、検索結果の最大距離を設定します。しきい値未満の距離を持つレコードのみが返されます。

例: 距離が 0.5 未満のドキュメントのみを返す

results = table.search([1, 2, 3]).distance_threshold(0.5).limit(10).to_list()

最小距離と最大距離の両方を設定するには、 .distance_range()メソッドを使用します。この範囲内の距離を持つレコードのみが返されます。

例: 距離が 0.01 から 0.05 までのドキュメントのみを返す

results = table.search([1, 2, 3]).distance_range(0.01, 0.05).limit(10).to_list()

フィルター辞書を持つ.filter()メソッドを使用して、ベクトル検索にフィルターを適用します。

デフォルトでは、 table.search() API はポストフィルタリング モードを使用して、ベクター インデックスによる検索パフォーマンスを最大化します。

例: ポストフィルタリングによるベクトル検索

results = (
    table.search([1, 2, 3])
        # The `meta` is a JSON field, and its value is a JSON object
        # like {"category": "animal"}
        .filter({"meta.category": "animal"})
        .num_candidate(50)
        .limit(10)
        .to_list()
)

注記：

ベクトルインデックスを使用する場合、最後のlimitが非常に小さいと結果の精度が低下する可能性があります。3 .num_candidate()の方法を使用すると、ベクトル検索フェーズでベクトルインデックスから取得する候補の数を、 limit番目のパラメータを変更せずに制御できます。

num_candidate値を大きくすると、一般的に再現率は向上しますが、クエリのパフォーマンスが低下する可能性があります。データセットと精度要件に応じてこの値を調整してください。

事前フィルタリングを有効にするには、 .filter()方法でprefilter=True設定します。

例: 事前フィルタリングによるベクトル検索

results = (
    table.search([1, 2, 3])
        .filter({"meta.category": "animal"}, prefilter=True)
        .limit(10)
        .to_list()
)

サポートされているフィルター演算子については、 フィルタリング参照してください。

スキーマ内に複数のベクトル フィールドを定義し、 .vector_column()メソッドを使用して指定されたベクトル フィールドに対してベクトル検索を実行できます。

例: 検索するベクトル場を指定する

# Create a table with multiple vector fields
class RichTextDocument(TableModel):
    __tablename__ = "rich_text_documents"
    id: int = Field(primary_key=True)
    text: str = Field(sa_type=TEXT)
    text_vec: list[float] = VectorField(dimensions=3)
    image_url: str
    image_vec: list[float] = VectorField(dimensions=3)

table = client.create_table(schema=RichTextDocument, if_exists="overwrite")

# Insert sample data ...

# Search using image vector field
results = (
    table.search([1, 2, 3])
        .vector_column("image_vec")
        .distance_metric(DistanceMetric.COSINE)
        .limit(10)
        .to_list()
)