本文へスキップ
`Ctrl`+`K`

# 7.8.12. `TokenLanguageModelKNN`

Added in version 15.1.8.

注釈

これは実験的な機能です。現時点ではまだ安定しきっていません。

## 7.8.12.1. 概要

`TokenLanguageModelKNN`はセマンティックサーチをサポートするトークナイザーです。

セマンティックサーチはk近傍法（k-Nearest Neighbors）を使います。

このトークナイザーを有効にするには次のコマンドで`language_model/knn`プラグインを有効にしてください。

    plugin_register language_model/knn

## 7.8.12.2. 構文

`TokenLanguageModelKNN`には必須の引数が2つあります。

    TokenLanguageModelKNN("model", "hf:///path/to", "code_column", "column_name")

`TokenLanguageModelKNN`には省略可能なオプションがあります。

    TokenLanguageModelKNN("model", "hf:///path/to", \
                          "code_column", "column_name", \
                          "n_clusters", N_CLUSTERS)

    TokenLanguageModelKNN("model", "hf:///path/to", \
                          "code_column", "column_name", \
                          "passage_prefix", "passage: ", \
                          "query_prefix", "query: ")

    TokenLanguageModelKNN("model", "hf:///path/to", \
                          "code_column", "column_name", \
                          "centroid_column", "centroid_column_name")

Added in version 15.1.9: passage_prefixとquery_prefixを追加。

Added in version 15.2.1: centroid_columnを追加

## 7.8.12.3. 使い方

注釈

このトークナイザーはtokenizeコマンドで実行できません。

`default_tokenizer`として設定する使い方で示します。

最初に`language_model/knn`プラグインを登録する必要があります。

実行例：

    plugin_register language_model/knn
    # [[0,1337566253.89858,0.000355720520019531],true]

スキーマ定義とサンプルデータは次のとおりです。

サンプルスキーマ：

実行例：

    table_create --name Memos --flags TABLE_NO_KEY
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create \
      --table Memos \
      --name content \
      --flags COLUMN_SCALAR \
      --type ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]

サンプルデータ：

実行例：

    load --table Memos
    [
    {"content": "I am a boy."},
    {"content": "This is an apple."},
    {"content": "Groonga is a full text search engine."}
    ]
    # [[0,1337566253.89858,0.000355720520019531],3]

各レコードごとにエンべディングの情報を保存しておく必要があります。そのカラムの作成は次のとおりです。

実行例：

    column_create Memos embedding_code COLUMN_SCALAR ShortBinary
    # [[0,1337566253.89858,0.000355720520019531],true]

セマンティックサーチ用のインデックスを作成します。

トークナイザーに`TokenLanguageModelKNN`を指定します。

実行例：

    table_create Centroids TABLE_HASH_KEY ShortBinary \
      --default_tokenizer \
        'TokenLanguageModelKNN("model", "hf:///groonga/all-MiniLM-L6-v2-Q4_K_M-GGUF", \
                               "code_column", "embedding_code")'
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Centroids data_content COLUMN_INDEX Memos content
    # [[0,1337566253.89858,0.000355720520019531],true]

`Memos`テーブルを取得するとエンベディングが作成されたことが確認できます。生成されたバイトコードが保存されます。

実行例：

    select Memos
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         3
    #       ],
    #       [
    #         [
    #           "_id",
    #           "UInt32"
    #         ],
    #         [
    #           "content",
    #           "ShortText"
    #         ],
    #         [
    #           "embedding_code",
    #           "ShortBinary"
    #         ]
    #       ],
    #       [
    #         1,
    #         "I am a boy.",
    #         "tW+IbgJ0dH9MM0nTOzt9ojKuwbfFnkUSCQHEh2X4l4ijXm03SpYrJHcLT+EbYFFUJPfyvim6bT8="
    #       ],
    #       [
    #         2,
    #         "This is an apple.",
    #         "utwX20mQL4h7XU/4OiMXRJnxJgg6QLP1lT3WehOKMZVlgSzowGRgeqd0GN7Y5E4G6mPzvoXhZD8="
    #       ],
    #       [
    #         3,
    #         "Groonga is a full text search engine.",
    #         "RLLyELYP2GC1grQNxMSK/+8OXE0W+3qJ+sY7wO4Hzmacv9NNv5vXjYjTsRBnH6b5Dpqrvu0hgT8="
    #       ]
    #     ]
    #   ]
    # ]

この`embedding_code`に対してユーザが何か操作をすることはありません。Groongaがセマンティックサーチをするときに内部的に使います。

## 7.8.12.4. 引数

### 7.8.12.4.1. 必須引数

#### 7.8.12.4.1.1. `model`

使う言語モデルを指定します。Hugging FaceのURIが指定できます。

最初のインデックス作成のタイミングで自動でダウンロードしGroongaのデータベースがあるディレクトリに配置します。その後はローカルに配置されたモデルを利用します。

URIの例: `https://huggingface.co/groonga/all-MiniLM-L6-v2-Q4_K_M-GGUF`のモデルを指定したいときは`hf:///groonga/all-MiniLM-L6-v2-Q4_K_M-GGUF`を指定します。

言語モデルについては言語モデルを参照してください。

#### 7.8.12.4.1.2. `code_column`

エンべディングを保存するためのカラムを指定します。

検索対象のテキストを保存しているテーブルにカラムを作成して、そのカラム名を指定してください。

### 7.8.12.4.2. 省略可能引数

#### 7.8.12.4.2.1. `passage_prefix`

Added in version 15.1.9.

multilingual-e5のような一部のモデルでは、検索対象テキストや検索クエリにプレフィックスが必要です。

`passage_prefix`は、検索対象テキストのプレフィックスを指定するために使います。

検索対象テキストにプレフィックスとして`passage:` を、検索クエリクエリには`query:` を設定する例は次のとおりです。

    TokenLanguageModelKNN("model", "hf:///groonga/multilingual-e5-base-Q4_K_M-GGUF", \
                          "code_column", "embedding_code", \
                          "passage_prefix", "passage: ", \
                          "query_prefix", "query: ")

#### 7.8.12.4.2.2. `query_prefix`

Added in version 15.1.9.

multilingual-e5のような一部のモデルでは、検索対象テキストや検索クエリにプレフィックスが必要です。

`query_prefix`は、検索クエリのプレフィックスを指定するために使います。

#### 7.8.12.4.2.3. `centroid_column`

Added in version 15.2.1.

このオプションは、1025次元（4100バイト）以上の大きなエンベディング向けです。Groongaのテーブルキーは4KiB以下でなければなりません。4KiBを超えるエンベディングはキーとして保存できません。

このオプションを使うと、大きなエンベディングをテーブルのキーではなく指定したカラムに保存します。

実行例：

    table_create LargeCentroids TABLE_HASH_KEY UInt32 \
      --default_tokenizer \
          'TokenLanguageModelKNN("model", "hf:///groonga/multilingual-e5-base-Q4_K_M-GGUF", \
                                 "centroid_column", "centroid", \
                                 "code_column", "embedding_code", \
                                 "passage_prefix", "passage: ", \
                                 "query_prefix", "query: ")'

    column_create LargeCentroids centroid COLUMN_VECTOR Float32
    column_create LargeCentroids data_content COLUMN_INDEX Memos content

エンべディングを保存するためのカラムを指定し、インデックス用のテーブルにそれを追加します。

#### 7.8.12.4.2.4. `n_clusters`

インデックスとして利用するクラスタ数を指定します。省略すると自動で適切な値を設定します。

多くの場合、明示的にこのオプションを設定する必要はありません。

#### 7.8.12.4.2.5. `n_gpu_layers`

Added in version 15.2.1.

言語モデルが利用するGPUレイヤー数を指定します。省略すると、可能な限りのGPUを使用します。

多くの場合、明示的にこのオプションを設定する必要はありません。

`n_gpu_layers`の`0`を設定することで、GPUを無効にすることができます。

## 7.8.12.5. 参考

- 言語モデル

- tokenize

- language_model_knn