AI 連携

AI チャット、LaTeX エラーの修正提案、ユーザーアクセス、使用量の上限、および任意の検索サービスを設定します。

この機能は ayaka-notes/ayakaleaf-pro によって提供され、v6.3.0 から利用できます。問題が発生した場合は、ぜひフィードバックをお寄せください。

​

AI アシスタントと LaTeX エラーアシスタント

Ayakaleaf Pro は、2 つの方法で AI 機能をエディターに組み込みます。

• AI アシスタントは、プロジェクトのドキュメントと現在の選択範囲をコンテキストとして使用し、質問に回答したり、レビュー用の編集案を提示したりします。
• エラーアシスタントは、LaTeX のコンパイルエラーを選択すると、それに的を絞った修正案を提示します。

​

Toolkit の設定

Toolkit デプロイの config/variables.env に以下を追加し、例の URL、キー、モデルをプロバイダーの値に置き換えてください。

AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID

実際の API キーはデプロイ環境のファイルに保存し、バージョン管理には含めないでください。上記の値はプレースホルダーであり、有効な認証情報ではありません。

AI による提案の品質は、選択したモデルによって異なります。すでに Codex または ChatGPT のサブスクリプションをお持ちの場合は、CLIProxyAPI の OpenAI 互換エンドポイント経由で接続できます。

AI_BASE_URL は OpenAI 互換 API のベース URL で、必要に応じてプロバイダーのバージョンプレフィックスを含めます。/chat/completions は内部で付加されるため、末尾に追加しないでください。ゲートウェイとモデルは、ストリーミング形式のチャット補完と関数ツールをサポートしている必要があります。どちらの機能もドキュメントのコンテキストをこのゲートウェイに送信します。画像や PDF ファイルを受け付けるモデルを使用している場合、チャットではアップロードされた画像や PDF ファイルも送信されることがあります。

Toolkit は config/variables.env をアプリケーションコンテナに渡します。ここに示した変数名をそのまま使用し、OVERLEAF_ プレフィックスは付けないでください。これらの変数を変更した後は、Toolkit ディレクトリからアプリケーションコンテナを再作成します。

bin/up -d

​

ゲートウェイの設定

変数	デフォルト	用途
AI_ENABLED	false	インスタンスでチャットとエラー提案を有効にするには、正確に true を設定します。未設定またはその他の値の場合は無効のままです。有効なゲートウェイ設定も必要です。
AI_BASE_URL	なし（必須）	OpenAI 互換 API のベース URL。
AI_API_KEY	なし（必須）	サーバーが使用する、そのゲートウェイ用の API キー。
AI_MODEL	なし（必須）	デフォルトのチャット設定および LaTeX エラー提案で使用されるテキストモデル。
AI_IMAGE_MODEL	未設定	同じゲートウェイ上の画像対応モデル（任意）。同じ API キーを使用します。
AI_PDF_MODEL	未設定	PDF ファイルを含むチャットに使用する、同じゲートウェイ上のモデル（任意）。同じ API キーを使用します。v6.4.0 以降。
AI_MAX_STEPS	20	AI チャットでユーザーメッセージ 1 件あたりに実行できるツール呼び出しの最大数（自動継続を含む）。正の整数を指定します。
AI_PROXY_URL	未設定	AI ゲートウェイへの呼び出しに使用する HTTP プロキシ URL（任意）。Web 検索やドキュメント検索のクライアントには適用されません。
AI_TOKEN_QUOTA	0	期間ごとにチャットとエラー提案で共有される、ユーザーあたりのトークン上限。未設定または 0 は無制限を意味します。上限を設けるには正の整数を指定します。
AI_TOKEN_QUOTA_PERIOD	month	month は毎月 1 日の 00:00 UTC にリセットされ、week は毎週月曜日の 00:00 UTC にリセットされます。その他の値は month として扱われます。

画像のアップロードを利用するには、画像入力を受け付け、チャットで使用されるツールをサポートするモデルを AI_IMAGE_MODEL に設定します。履歴に画像の添付を含むチャットリクエストは、その会話の後続メッセージも含めてすべてこのモデルを使用します。この設定がない場合、画像を含むリクエストには通常のチャットモデルが使用されるため、そのモデル自体が画像をサポートしている必要があります。LaTeX エラー提案は引き続き AI_MODEL を使用します。

PDF の添付は v6.4.0 以降で導入されました。ユーザーは画像と同様に、最大 2 MB の PDF ファイルを添付できます。チャットは各 PDF ファイルをそのまま Chat Completions の file パートとして送信するため、ゲートウェイとモデルが PDF 入力を受け付ける必要があります。OpenAI の Vision モデルは対応していますが、vLLM など多くのセルフホスト型ゲートウェイは画像を受け付けても PDF ファイルは拒否します。PDF ファイルを読み取れるモデルを AI_PDF_MODEL に設定してください。履歴に PDF ファイルを含むチャットは、その会話の後続メッセージや画像も含めてこのモデルを使用するため、このモデルは画像も受け付ける必要があります。この設定がない場合、PDF を含むチャットには AI_MODEL が使用されます。モデルが PDF ファイルを拒否した場合、チャットはユーザーに対し、管理者に AI_PDF_MODEL の設定を依頼するよう案内します。

たとえば、画像モデルと週単位の AI 使用量の上限を有効にするには次のようにします。

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

ユーザーアクセスと同意

インスタンスでの利用可否とユーザーの権限は別々に管理されます。インスタンスでの利用可否は AI_ENABLED とゲートウェイの設定によって制御されます。さらに、サインインしたユーザーは既存のアカウントチェックにも合格する必要があります。aiFeatures.enabled が false であってはなりません。この既存のデータベースフィールドは、チャットと LaTeX エラー提案の両方を制御します。未設定の場合、そのユーザーの AI 機能は有効になります。

AI_TOKEN_QUOTA は許可されたすべてのユーザーに等しく適用される上限です。現在のモジュールでは、アカウントごとに個別の数値上限を設定することはできません。

管理者のユーザー一覧でユーザーを選択し、Update account info → AI features を開きます。Enable AI features は、アカウントの変更を保存したときに aiFeatures.enabled を更新します。サーバーは、すでに開いているエディターからのリクエストを含め、新しい AI リクエストごとに現在の権限をチェックします。権限のないユーザーにもエディターに AI アシスタントは表示されますが、メッセージを送信することはできません。

​

使用量とリセット

管理画面の AI features タブには、現在の期間の Usage、Limit、Reset ボタンが 1 行に表示されます。使用量はタブを開いたときに読み込まれ、継続的には更新されません。チャットやエラー提案が完了した後に最新の数値を確認するには、タブを開き直してください。リセットは即座に反映され、そのユーザーの現在の期間のカウンターのみがクリアされ、表示中の使用量が再読み込みされます。アカウントフォームの他の項目を保存する必要はありません。

チャットとエラー提案の使用量は 1 つの Redis カウンターを共有しており、リクエストの完了後にモデルプロバイダーが報告する合計トークン数に基づいて更新されます。これには、モデルの各ステップにおける入力トークンと出力トークンが含まれます。入力には会話履歴、ドキュメントのコンテキスト、ツールの結果が含まれることがあるため、フォローアップのメッセージでは、新しいメッセージ単体よりも多くのトークンを消費する場合があります。上限が Unlimited の場合でも使用量は記録されます。トークン合計が報告されないリクエストはカウンターに加算されません。過去に記録されなかった使用量をモジュールが再構築することはできません。

上限のチェックはストリーミングの前に行われます。1 つのリクエスト、または複数の同時リクエストによって、後続のリクエストがブロックされる前に残りの許容量を超えることがあります。これは厳密なプロバイダーの支出上限ではなく、使用量の許容枠です。上限の照会に失敗した場合、リクエストは許可され、その失敗がログに記録されます。

どちらの機能も AI_TOKEN_QUOTA を使用します。エラー提案にはリクエスト回数に基づく個別の上限はありません。カウンターをリセットしても、権限、同意、設定された上限、プロバイダー側の請求記録は変更されません。カウンターは UTC の期間キーを使用し、40 日後に失効します。Redis のデータを保持しておけば、アプリケーションを再起動しても現在の使用量は維持されます。

​

任意の検索サービス

Web 検索には Tavily 互換の API を使用します。検索 API キーが設定されている場合に利用できます。これらの設定は AI ゲートウェイとは独立しています。

変数	デフォルト	用途
TAVILY_API_KEY	未設定	検索 API キー。WEB_SEARCH_API_KEY より優先されます。
WEB_SEARCH_API_KEY	未設定	検索 API キーの別名。
WEB_SEARCH_URL	https://api.tavily.com/search	検索エンドポイント。カスタムエンドポイントは Tavily のリクエスト形式とレスポンス形式に対応している必要があります。
WEB_SEARCH_MAX_RESULTS	5	1 回の検索で要求する結果の数。サービスがサポートする正の整数を指定します。
WEB_SEARCH_DEPTH	basic	検索の深さ。通常は basic または advanced です。
WEB_SEARCH_PROVIDER	tavily	現在の実装は Tavily 互換プロトコルのみをサポートしています。この値を変更しても別のアダプターが選択されることはありません。
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	ドキュメント検索のエンドポイント。空文字列を設定するとドキュメント検索が無効になります。

例:

TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp

ドキュメント検索は、設定された GitBook MCP エンドポイントの searchDocumentation ツールを呼び出し、JSON または SSE のレスポンスを受け付けます。これはドキュメント検索用の MCP クライアントです。Ayakaleaf 外部の AI クライアントからプロジェクトを操作できるようにするには、MCP サーバーを参照してください。

Web ページの読み取りは v6.4.0 以降で導入されました。チャットは、ユーザーが指定したリンクや検索結果など、URL を使ってページを読み取ることができます。ページは、外部 URL からファイルを取得するのと同じサービスであるリンク URL プロキシを通じて取得されるため、外部 URL で説明されているネットワーク制限がこれにも適用されます。追加の設定は必要ありません。

検索クエリは設定された検索サービスに送信されます。その後、検索結果が AI ゲートウェイへのリクエストに含まれることがあります。チャットの Tools メニューでは、ユーザーが自分のリクエストに対して Web と Documentation を有効または無効にできます。モデルがツールを利用するには、サーバー側でもそのツールが設定されている必要があります。

​

Q&A

エディターに AI アシスタントが表示されない

回答： AI アシスタントは、AI_ENABLED=true で、かつ AI_BASE_URL、AI_API_KEY、AI_MODEL がすべて設定されている場合にのみ、エディターの左レールに表示されます。いずれかが欠けている場合、AI アシスタントはすべてのユーザーに対して非表示になります。

config/variables.env を変更した後は、bin/up -d でコンテナを再作成してください。ブラウザを再読み込みするだけでは新しい変数は適用されません。管理パネルの Enable AI features スイッチは AI アシスタントの表示・非表示を切り替えるものではなく、ユーザーがメッセージを送信できるかどうかのみを決定します。

メッセージを送信しても AI アシスタントが応答しない

回答： まず、ユーザーが AI アシスタントに表示される AI 同意カードを承諾していることを確認してください。承諾するまではメッセージを送信できません。

次に、web サービスのログでエラーを確認します。

bin/logs web

ログメッセージ	意味
workbench AI chat requested but no AI gateway is configured	実行中のコンテナで AI_ENABLED、AI_BASE_URL、AI_API_KEY、AI_MODEL のいずれかが欠けています。bin/up -d で再作成してください。
workbench chat stream error	ゲートウェイがエラーを返しました。ユーザーには “The AI service returned an error” と表示されます。ログに記録されたエラーには、ゲートウェイのステータスコードとメッセージが含まれます。
workbench chat failed	ストリーミングの前または途中でリクエストが失敗しました。たとえば、ゲートウェイに到達できない場合などです。

プロバイダーのダッシュボードに使用量が表示されない場合、リクエストはプロバイダーに届いていません。よくある原因は次のとおりです。

• AI_BASE_URL が誤っている。たとえば /v1 が欠けている、または余分に付いている、あるいは /chat/completions が末尾に付加されている。
• サーバーがゲートウェイに到達できない。送信トラフィックがプロキシを経由する必要がある場合は、AI_PROXY_URL を設定してください。
• AI_MODEL がゲートウェイの認識するモデル ID ではない。

プロバイダー側にリクエストが表示されているのにチャットが失敗する場合は、モデルがストリーミング形式のチャット補完と関数ツールをサポートしているか確認してください。

チャット履歴は保存されますか?

回答： いいえ。チャットは開いているブラウザタブ内にのみ保持されます。ページを再読み込みしたり閉じたりするとクリアされ、Start new chat は現在のチャットを置き換えます。過去のチャットの一覧はなく、各プロジェクトでは一度に 1 つのチャットが表示されます。