AIチャットの設定¶

Info

AIチャットにはGramps Web APIバージョン2.5.0以上が必要です。

Gramps Web APIは、リトリーバル拡張生成（RAG）と呼ばれる技術を介して、大規模言語モデル（LLM）を使用して系譜データベースに関する質問をすることをサポートしています。

RAGは次のように機能します。まず、ベクトル埋め込みモデルを使用して、Grampsデータベース内のすべてのオブジェクトのインデックスを、オブジェクトの意味をエンコードした数値ベクトルの形式で作成します。このプロセスは、フルテキスト検索インデックスの作成に似ていますが、計算コストが高くなります。

次に、ユーザーがチャットエンドポイントを介して質問をすると、その質問も同じ埋め込みモデルによってベクトルに変換され、Grampsデータベース内のオブジェクトと比較されます。このセマンティック検索は、質問に最も意味的に類似したデータベース内のオブジェクトを返します。

最後のステップでは、質問と取得したオブジェクトがLLMに送信され、提供された情報に基づいて回答が形成されます。このようにして、チャットボットは事前に存在する知識に依存するのではなく、系譜データベースの内容に関する詳細情報にアクセスできます。

Gramps Web APIでチャットエンドポイントを有効にするには、3つのステップが必要です。

必要な依存関係のインストール、
セマンティック検索の有効化、
LLMプロバイダーの設定。

この3つのステップについては、以下で順に説明します。最後に、オーナーまたは管理者はどのユーザーがチャット機能にアクセスできるかを設定する必要があります。

必要な依存関係のインストール¶

AIチャットには、Sentence TransformersおよびPyTorchライブラリがインストールされている必要があります。

Gramps Webの標準Dockerイメージには、amd64（例：64ビットデスクトップPC）およびarm64（例：64ビットRaspberry Pi）アーキテクチャ用にこれらが事前にインストールされています。残念ながら、AIチャットは、PyTorchサポートがないため、armv7（例：32ビットRaspberry Pi）アーキテクチャではサポートされていません。

pipを介してGramps Web APIをインストールする際（Dockerイメージを使用する場合は必要ありません）、必要な依存関係は次のコマンドでインストールされます。

pip install gramps_webapi[ai]

セマンティック検索の有効化¶

必要な依存関係がインストールされている場合、セマンティック検索の有効化は、VECTOR_EMBEDDING_MODEL構成オプションを設定すること（例：GRAMPSWEB_VECTOR_EMBEDDING_MODEL環境変数を設定すること）と同じくらい簡単です。詳細についてはサーバー構成を参照してください。これは、Sentence Transformersライブラリによってサポートされているモデルの任意の文字列にすることができます。このプロジェクトのドキュメントで詳細と利用可能なモデルを確認してください。

Warning

デフォルトのDockerイメージには、GPUサポートのあるPyTorchバージョンが含まれていないことに注意してください。GPUにアクセスできる場合（これによりセマンティックインデックス作成が大幅に高速化されます）、GPU対応のPyTorchバージョンをインストールしてください。

モデルを選択する際には、いくつかの考慮事項があります。

モデルを変更する場合は、ツリー（またはマルチツリーセットアップのすべてのツリー）のセマンティック検索インデックスを手動で再作成する必要があります。そうしないと、エラーや無意味な結果が発生します。
モデルは、一方で精度/一般性と、他方で計算時間/ストレージスペースとのトレードオフです。強力なGPUにアクセスできないシステムでGramps Web APIを実行している場合、通常、大きなモデルは実際には遅すぎます。
データベース全体が英語であり、すべてのユーザーが英語でチャットの質問をすることが期待されている場合を除き、多言語埋め込みモデルが必要です。これは、純粋な英語モデルよりも珍しいです。

モデルがローカルキャッシュに存在しない場合、新しい構成でGramps Web APIが初めて起動されるときにダウンロードされます。モデルsentence-transformers/distiluse-base-multilingual-cased-v2は、標準Dockerイメージを使用する際にすでにローカルで利用可能です。このモデルは良い出発点であり、多言語入力をサポートしています。

異なるモデルに関する学びをコミュニティと共有してください！

Info

Sentence Transformersライブラリは、かなりの量のメモリを消費するため、ワーカープロセスが終了する可能性があります。一般的な目安として、セマンティック検索が有効になっている場合、各Gunicornワーカーは約200MBのメモリを消費し、各Celeryワーカーはアイドル時でも約500MBのメモリを消費し、埋め込みを計算しているときは最大1GBに達します。メモリ使用量を制限する設定についてはCPUとメモリの使用制限を参照してください。さらに、一時的なメモリ使用量のスパイクによるOOMエラーを防ぐために、十分に大きなスワップパーティションを用意することをお勧めします。

LLMプロバイダーの設定¶

LLMとの通信は、openai-pythonライブラリを使用したOpenAI互換APIを介して行われます。これにより、Ollamaを介してローカルにデプロイされたLLM（Ollama OpenAI互換性を参照）や、OpenAIやHugging Face TGI（テキスト生成推論）などのAPIを使用できます。LLMは、構成パラメータLLM_MODELおよびLLM_BASE_URLを介して設定されます。

OpenAI APIを介したホストされたLLMの使用¶

OpenAI APIを使用する場合、LLM_BASE_URLは設定しなくてもよく、LLM_MODELはOpenAIモデルの1つ（例：gpt-4o-mini）に設定する必要があります。RAGアプローチのため、LLMはセマンティック検索結果から適切な情報を選択し、回答を形成するために「のみ」使用され、深い系譜学的または歴史的知識は必要ありません。したがって、小さな/安価なモデルが十分かどうかを試すことができます。

また、アカウントにサインアップし、APIキーを取得して、OPENAI_API_KEY環境変数に保存する必要があります。

Info

LLM_MODELは構成パラメータです。環境変数を介して設定する場合は、GRAMPSWEB_LLM_MODELを使用してください（構成を参照）。OPENAI_API_KEYは構成パラメータではなく、openai-pythonライブラリによって直接使用される環境変数であるため、プレフィックスを付けるべきではありません。

Ollamaを介したローカルLLMの使用¶

Ollamaは、LLMをローカルで実行する便利な方法です。詳細についてはOllamaのドキュメントを参照してください。LLMはかなりの計算リソースを必要とし、最小のモデルを除いて、GPUサポートなしではおそらく遅すぎることに注意してください。tinyllamaがニーズに合うかどうかを試してみてください。合わない場合は、より大きなモデルを試してください。コミュニティと経験を共有してください！

Docker Composeを使用してGramps Webをデプロイする際には、Ollamaサービスを追加できます。

services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

volumes:
    ollama_data:

その後、LLM_BASE_URL構成パラメータをhttp://ollama:11434/v1に設定します。LLM_MODELをOllamaがサポートするモデルに設定し、ollama pull <model>でコンテナ内にプルダウンします。最後に、OPENAI_API_KEYをollamaに設定します。

Ollamaに関する問題をトラブルシューティングするには、Ollamaサービス環境で環境変数OLLAMA_DEBUG=1を設定してデバッグログを有効にできます。

Info

Gramps Web AIチャットにOllamaを使用している場合は、コミュニティをサポートするために、欠落している詳細をこのドキュメントに追加してください。

その他のプロバイダーの使用¶

他のプロバイダーに関するドキュメントを提出し、コミュニティと経験を共有してください！