重要

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

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

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

注記
TiDB Vector Search は現在ベータ版であり、 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 ORM を拡張して TiDB 固有の機能 (たとえば、Vector Search) をサポートし、TiDB と Django 間の互換性の問題を解決する、Django 用の TiDB 方言です。

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

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

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

ベクトル列を定義する

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

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

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

インデックスで最適化されたベクトル列を定義する

3 次元ベクトル列を定義し、ベクトル検索インデックス (HNSW インデックス) で最適化します。

class DocumentWithIndex(models.Model):
   content = models.TextField()
   # Note:
   #   - Using comment to add hnsw index is a temporary solution. In the future it will use `CREATE INDEX` syntax.
   #   - Currently the HNSW index cannot be changed after the table has been created.
   #   - Only Django >= 4.2 supports `db_comment`.
   embedding = VectorField(dimensions=3, db_comment="hnsw(distance=cosine)")

TiDB はこのインデックスを使用して、コサイン距離関数に基づくベクトル検索クエリを高速化します。

埋め込み付きドキュメントを保存する

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]