コンテンツにスキップ

AIチャットの設定

Info

AIチャットにはGramps Web APIバージョン2.5.0以上が必要です。バージョン3.6.0では、よりインテリジェントなインタラクションのためのツール呼び出し機能が導入されました。

Gramps Web APIは、リトリーバル・オーグメンテッド・ジェネレーション（RAG）とツール呼び出しを組み合わせた技術を使用して、大規模言語モデル（LLM）を介して系譜データベースに関する質問をすることをサポートしています。

仕組み

AIアシスタントは、2つの補完的なアプローチを使用します。

リトリーバル・オーグメンテッド・ジェネレーション（RAG）: ベクトル埋め込みモデルが、Grampsデータベース内のすべてのオブジェクトのインデックスを、オブジェクトの意味をエンコードした数値ベクトルの形で作成します。ユーザーが質問をすると、その質問もベクトルに変換され、データベース内のオブジェクトと比較されます。このセマンティック検索は、質問に最も意味的に類似したオブジェクトを返します。

ツール呼び出し（v3.6.0+）: AIアシスタントは、系譜データを直接クエリするために専門のツールを使用できるようになりました。これらのツールにより、アシスタントはデータベースを検索し、特定の基準で人々/イベント/家族/場所をフィルタリングし、個人間の関係を計算し、詳細なオブジェクト情報を取得することができます。これにより、アシスタントは複雑な系譜の質問に正確に答える能力が大幅に向上します。

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

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

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

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

AIチャットには、Sentence TransformersおよびPyTorchライブラリのインストールが必要です。

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

Gramps Web APIをpipを介してインストールする場合（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互換APIをサポートするPydantic AIフレームワークを使用します。これにより、Ollamaを介してローカルにデプロイされたLLM（Ollama OpenAI互換性を参照）や、OpenAI、Anthropic、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）に設定する必要があります。LLMは、RAGとツール呼び出しの両方を使用して質問に答えます：セマンティック検索結果から関連情報を選択し、専門のツールを使用してデータベースに直接クエリを実行できます。系譜や歴史に関する深い知識は必要ありません。したがって、小型または安価なモデルで十分かどうかを試すことができます。

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

Info

LLM_MODELは設定パラメータです。環境変数を介して設定したい場合は、GRAMPSWEB_LLM_MODELを使用してください（設定を参照）。OPENAI_API_KEYは設定パラメータではなく、Pydantic AIライブラリで直接使用される環境変数であるため、プレフィックスを付けないでください。

Mistral AIの使用

Mistral AIのホストされたモデルを使用するには、LLM_MODELを設定する際にモデル名の先頭にmistral:を付けます。

Mistral AIのアカウントにサインアップし、APIキーを取得してMISTRAL_API_KEY環境変数に保存する必要があります。Pydantic AIは自動的に正しいMistral APIエンドポイントを使用するため、LLM_BASE_URLを設定する必要はありません。

環境変数を使用したDocker Composeの例設定： 

environment:
  GRAMPSWEB_LLM_MODEL: mistral:mistral-large-latest
  MISTRAL_API_KEY: your-mistral-api-key-here
  GRAMPSWEB_VECTOR_EMBEDDING_MODEL: sentence-transformers/distiluse-base-multilingual-cased-v2

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を使用している場合、コミュニティをサポートするために、欠落している詳細をこのドキュメントに追加してください。

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

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