> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 連携

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

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

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

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

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

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4)

### Toolkit の設定

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

```dotenv theme={null}
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 キーはデプロイ環境のファイルに保存し、バージョン管理には含めないでください。上記の値はプレースホルダーであり、有効な認証情報ではありません。

> [!NOTE]
>
> AI による提案の品質は、選択したモデルによって異なります。すでに Codex または ChatGPT のサブスクリプションをお持ちの場合は、[CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) の OpenAI 互換エンドポイント経由で接続できます。

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

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

```sh theme={null}
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 使用量の上限を有効にするには次のようにします。

```dotenv theme={null}
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 行に表示されます。使用量はタブを開いたときに読み込まれ、継続的には更新されません。チャットやエラー提案が完了した後に最新の数値を確認するには、タブを開き直してください。リセットは即座に反映され、そのユーザーの現在の期間のカウンターのみがクリアされ、表示中の使用量が再読み込みされます。アカウントフォームの他の項目を保存する必要はありません。

![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b)

チャットとエラー提案の使用量は 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` | ドキュメント検索のエンドポイント。空文字列を設定するとドキュメント検索が無効になります。 |

例:

```dotenv theme={null}
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 サーバー](https://ayakaleaf-pro.mintlify.site/ja/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)を参照してください。

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

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

### Q\&A

> [accordion] エディターに AI アシスタントが表示されない
>
> **回答：** AI アシスタントは、`AI_ENABLED=true` で、かつ `AI_BASE_URL`、`AI_API_KEY`、`AI_MODEL` がすべて設定されている場合にのみ、エディターの左レールに表示されます。いずれかが欠けている場合、AI アシスタントはすべてのユーザーに対して非表示になります。
>
> `config/variables.env` を変更した後は、`bin/up -d` でコンテナを再作成してください。ブラウザを再読み込みするだけでは新しい変数は適用されません。管理パネルの **Enable AI features** スイッチは AI アシスタントの表示・非表示を切り替えるものではなく、ユーザーがメッセージを送信できるかどうかのみを決定します。

> [accordion] メッセージを送信しても AI アシスタントが応答しない
>
> **回答：** まず、ユーザーが AI アシスタントに表示される AI 同意カードを承諾していることを確認してください。承諾するまではメッセージを送信できません。
>
> 次に、web サービスのログでエラーを確認します。
>
> ```sh theme={null}
> 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 ではない。
>
> プロバイダー側にリクエストが表示されているのにチャットが失敗する場合は、モデルがストリーミング形式のチャット補完と関数ツールをサポートしているか確認してください。

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.