重要

このページは英語版のページを機械翻訳しています。原文はこちらからご覧ください。

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

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

注記
TiDB Vector Search は、TiDB Self-Managed (TiDB >= v8.4) およびTiDB Cloudサーバーレスでのみ使用できます。 TiDB Cloud専用では使用できません。

前提条件

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

Python 3.8以上インストールされました。
ギットインストールされました。
TiDB Cloud Serverless クラスター。TiDB Cloud クラスターがない場合は、 TiDB Cloud Serverless クラスターの作成に従って独自のTiDB Cloudクラスターを作成してください。

サンプルアプリを実行する

以下の手順に従って、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 Vector Search など) をサポートし、TiDB と Django 間の互換性の問題を解決します。

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

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

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

クラスターページに移動し、ターゲットクラスターの名前をクリックして概要ページに移動します。
右上隅の「接続」をクリックします。接続ダイアログが表示されます。
接続ダイアログの構成が動作環境と一致していることを確認します。
- 接続タイプはPublicに設定されています
- ブランチはmainに設定されています
- 接続先はGeneralに設定されています
- オペレーティングシステムは環境に適合します。
ヒント：
プログラムが Windows Subsystem for Linux (WSL) で実行されている場合は、対応する Linux ディストリビューションに切り替えます。
接続ダイアログから接続パラメータをコピーします。
ヒント：
まだパスワードを設定していない場合は、「パスワードの生成」をクリックしてランダムなパスワードを生成します。
Python プロジェクトのルートディレクトリに.envファイルを作成し、接続パラメータを対応する環境変数に貼り付けます。
- TIDB_HOST : TiDB クラスターのホスト。
- TIDB_PORT : TiDB クラスターのポート。
- TIDB_USERNAME : TiDB クラスターに接続するためのユーザー名。
- TIDB_PASSWORD : TiDB クラスターに接続するためのパスワード。
- TIDB_DATABASE : 接続するデータベース名。
- TIDB_CA_PATH : ルート証明書ファイルへのパス。
以下は macOS の例です。
```
TIDB_HOST=gateway01.****.prod.aws.tidbcloud.com
TIDB_PORT=4000
TIDB_USERNAME=********.root
TIDB_PASSWORD=********
TIDB_DATABASE=test
TIDB_CA_PATH=/etc/ssl/cert.pem
```

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

データベーススキーマを移行します。

python manage.py migrate

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

python manage.py runserver

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

APIパス	説明
`POST: /insert_documents`	埋め込みのあるドキュメントを挿入します。
`GET: /get_nearest_neighbors_documents`	3 つの最も近い近傍ドキュメントを取得します。
`GET: /get_documents_within_distance`	一定の距離内の文書を取得します。

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

次のサンプルコードスニペットを参照して、独自のアプリケーション開発を完了することができます。

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,
    }

プロジェクトTIDB_CA_PATHルートディレクトリに.envファイルTIDB_USERNAME TIDB_HOSTおよびTIDB_DATABASE TIDB_PORT TiDB クラスターの実際TIDB_PASSWORD値で設定できます。

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

ベクトル列を定義する

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

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

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]