TiDBベクトル検索をDjango ORMと統合する

このチュートリアルではジャンゴORM を使用してTiDB ベクトル検索と対話し、エンベディングを保存し、ベクトル検索クエリを実行する方法を説明します。

注記：

• ベクター検索機能はベータ版です。予告なく変更される場合があります。バグを発見した場合は、GitHubで問題を報告してください。
• ベクトル検索機能は、 TiDBセルフマネージドTiDB Cloud Starter 、 TiDB Cloud Essential 、およびTiDB Cloud Dedicatedで利用できます。TiDB Self-ManagedおよびTiDB Cloud Dedicatedの場合、TiDBのバージョンはv8.4.0以降である必要があります（v8.5.0以降を推奨）。

前提条件

このチュートリアルを完了するには、以下が必要です。

• Python 3.8以降インストールされています。
• Gitがインストールされました。
• TiDBクラスタ。

TiDBクラスタをお持ちでない場合は、以下の手順で作成できます。

• (推奨) TiDB Cloud Starterインスタンスを作成する。
• ローカルテスト用のTiDBセルフマネージドクラスタをデプロイ。または本番本番のTiDBセルフマネージドクラスタをデプロイ。

サンプルアプリを実行します

以下の手順に従うことで、TiDB Vector SearchをDjango ORMに統合する方法をすぐに習得できます。

ステップ1. リポジトリをクローンする

tidb-vector-pythonリポジトリをローカルマシンにクローンします。

git clone https://github.com/pingcap/tidb-vector-python.git

ステップ2. 仮想環境を作成する

プロジェクト用の仮想環境を作成する：

cd tidb-vector-python/examples/orm-django-quickstart
python3 -m venv .venv
source .venv/bin/activate

ステップ3. 必要な依存関係をインストールします

デモプロジェクトに必要な依存関係をインストールします。

pip install -r requirements.txt

または、プロジェクトに以下のパッケージをインストールすることもできます。

pip install Django django-tidb mysqlclient numpy python-dotenv

mysqlclientのインストールで問題が発生した場合は、mysqlclientの公式ドキュメントを参照してください。

django-tidbとは何ですか？

django-tidbは Django 用の TiDB 方言であり、Django ORM を拡張して TiDB 固有の機能 (例えば、ベクトル検索) をサポートし、TiDB と Django 間の互換性の問題を解決します。

django-tidbをインストールするには、お使いの Django のバージョンに合ったバージョンを選択してください。例えば、 django==4.2.*を使用している場合は、 django-tidb==4.2.*をインストールしてください。マイナーバージョンは同じである必要はありませんが、最新のマイナーバージョンを使用することをお勧めします。

詳細については、 django-tidbリポジトリを参照してください。

ステップ4．環境変数を設定する

選択したTiDBのデプロイオプションに応じて、環境変数を設定してください。

TIDB_HOST=127.0.0.1
TIDB_PORT=4000
TIDB_USERNAME=root
TIDB_PASSWORD=
TIDB_DATABASE=test

ステップ5．デモを実行する

データベーススキーマを移行する：

python manage.py migrate

Django開発サーバーを実行します。

python manage.py runserver

ブラウザを開いてhttp://127.0.0.1:8000にアクセスし、デモアプリケーションをお試しください。利用可能なAPIパスは以下のとおりです。

サンプルコードスニペット

以下のサンプルコードスニペットを参考に、独自のアプリケーション開発を完成させてください。

TiDBに接続する

ファイルsample_project/settings.pyに、以下の設定を追加します。

dotenv.load_dotenv()

DATABASES = {
    "default": {
        # https://github.com/pingcap/django-tidb
        "ENGINE": "django_tidb",
        "HOST": os.environ.get("TIDB_HOST", "127.0.0.1"),
        "PORT": int(os.environ.get("TIDB_PORT", 4000)),
        "USER": os.environ.get("TIDB_USERNAME", "root"),
        "PASSWORD": os.environ.get("TIDB_PASSWORD", ""),
        "NAME": os.environ.get("TIDB_DATABASE", "test"),
        "OPTIONS": {
            "charset": "utf8mb4",
        },
    }
}

TIDB_CA_PATH = os.environ.get("TIDB_CA_PATH", "")
if TIDB_CA_PATH:
    DATABASES["default"]["OPTIONS"]["ssl_mode"] = "VERIFY_IDENTITY"
    DATABASES["default"]["OPTIONS"]["ssl"] = {
        "ca": TIDB_CA_PATH,
    }

プロジェクトのルート ディレクトリに.envファイルを作成し、環境変数TIDB_HOST 、 TIDB_PORT 、 TIDB_USERNAME 、 TIDB_PASSWORD 、 TIDB_DATABASE 、およびTIDB_CA_PATH TiDB の実際の値で設定できます。

ベクターテーブルを作成する

ベクトル列を定義する

tidb-djangoは、ベクトル埋め込みをテーブルに格納するためのVectorFieldを提供します。

embeddingという名前の列を持つテーブルを作成し、その列に3次元ベクトルを格納します。

class Document(models.Model):
   content = models.TextField()
   embedding = VectorField(dimensions=3)

埋め込みを含むドキュメントを保存する

Document.objects.create(content="dog", embedding=[1, 2, 1])
Document.objects.create(content="fish", embedding=[1, 2, 4])
Document.objects.create(content="tree", embedding=[1, 0, 0])

近隣住民の文書を検索

TiDB Vectorは以下の距離関数をサポートしています。

• L1Distance
• L2Distance
• CosineDistance
• NegativeInnerProduct

コサイン距離関数に基づいて、クエリベクトル[1, 2, 3]に意味的に最も近い上位 3 つのドキュメントを検索します。

results = Document.objects.annotate(
   distance=CosineDistance('embedding', [1, 2, 3])
).order_by('distance')[:3]

一定距離内の文書を検索

クエリベクトル[1, 2, 3]からのコサイン距離が 0.2 未満の文書を検索します。

results = Document.objects.annotate(
   distance=CosineDistance('embedding', [1, 2, 3])
).filter(distance__lt=0.2).order_by('distance')[:3]

関連項目

• ベクトルデータ型
• ベクトル検索インデックス