埋め込み空間

埋め込みプロバイダーは EmbeddingSpaceProvider を実装します。各エンコーダーを EMBEDDER 機能として宣言し、それらが構成する完全な空間を定義します。create() はその一つに対する VectorEncoder を返します。encode_one() は独自コードを表します。パッケージ化とインストールは概要の手順に従います。

from collections.abc import Sequence
from typing import Any

from indx_interfaces import (
    CapabilityDescriptor,
    CapabilityId,
    CapabilityKind,
    Device,
    DistanceMetric,
    EmbedderConfig,
    EmbedderId,
    EmbedderModality,
    EmbedderRole,
    EmbeddingSpace,
    EmbeddingSpaceId,
    VectorNormalization,
    embedder_fingerprint,
)

CAPABILITY_ID = CapabilityId("acme-text-embedder")
EMBEDDER_ID = EmbedderId("acme-text-embedder")
SPACE_ID = EmbeddingSpaceId("acme-text")
DIMENSION = 384
PREPROCESSING: dict[str, Any] = {"lowercase": True}

class Encoder:
    def encode(
        self, inputs: Sequence[str | bytes]
    ) -> tuple[tuple[float, ...], ...]:
        return tuple(tuple(encode_one(value)) for value in inputs)

class Provider:
    def descriptors(self) -> tuple[CapabilityDescriptor, ...]:
        return (
            CapabilityDescriptor(
                id=CAPABILITY_ID,
                version="1",
                kind=CapabilityKind.EMBEDDER,
                devices=(Device.CPU,),
                available=True,
            ),
        )

    def embedding_spaces(self) -> tuple[EmbeddingSpace, ...]:
        revision = "model-revision-1"
        config = EmbedderConfig(
            id=EMBEDDER_ID,
            provider="acme",
            model="acme-text-model",
            revision=revision,
            roles=(EmbedderRole.DOCUMENT, EmbedderRole.QUERY),
            modalities=(EmbedderModality.TEXT,),
            preprocessing=PREPROCESSING,
            fingerprint=embedder_fingerprint(
                "acme", "acme-text-model", revision, PREPROCESSING
            ),
        )
        return (
            EmbeddingSpace(
                id=SPACE_ID,
                version="1",
                dimension=DIMENSION,
                metric=DistanceMetric.COSINE,
                normalization=VectorNormalization.L2,
                embedders=(config,),
            ),
        )

    def create(self, capability_id: CapabilityId) -> Any:
        if capability_id != CAPABILITY_ID:
            raise ValueError(f"unknown capability: {capability_id}")
        return Encoder()

入力ごとに一つ、各ベクトルに正確に dimension 個の値を返します。一つのプロバイダーが空間全体を所有します。ベクトルを直接比較できることをテストしたエンコーダーだけを同じ空間へ入れてください。

実行時に文書用エンベッダーへ渡される入力は indx-interfaces の DOCUMENT_EMBEDDING_MODALITIES が唯一の定義で、優先順に (text, image) です。テキストを持つチャンクにはテキストを、テキストとして誰も読めなかったページの代わりに立つチャンクには indx-chunker-pdf がレンダリングしたページを渡します。このリストの外のモダリティを document ロールで宣言したエンベッダーは呼ばれることがなく、リストが覆う文書レーンを一つも宣言しない空間は、その空間を指定したプランが unsatisfied として返ります。document ロールで image を宣言することは可能で、同梱の clip-vit-b32 空間がそうしています。呼ばれるのはレンダリングされたページに対してだけです。ページが両方を持つ場合はテキストが優先されるからです。クエリ側にこれらの制約はありません。

チェックリスト

• エンコーダーの件数、次元、フィンガープリント変更、文書・クエリ間の互換性をテストする。

参考

• 埋め込み空間
• 動く拡張の例