> ## 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`，因為系統會在內部自動附加。閘道與模型必須支援串流聊天補全（streaming chat completions）與函式工具（function tools）。這兩項功能都會將文件上下文傳送至此閘道；使用可接受圖片與 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` | 未設定 | 選用的模型，位於同一閘道並使用相同的 API 金鑰，用於含有 PDF 檔案的聊天。自 v6.4.0 起提供。 |
| `AI_MAX_STEPS` | `20` | AI 聊天中每則使用者訊息的最大工具呼叫次數，包含自動接續。請使用正整數。 |
| `AI_PROXY_URL` | 未設定 | 選用的 HTTP 代理 URL，用於呼叫 AI 閘道。此設定不會影響網頁或文件搜尋用戶端。 |
| `AI_TOKEN_QUOTA` | `0` | 每位使用者在每個週期內由聊天與錯誤建議共用的 token 上限。未設定或 `0` 表示無限制；若要設定上限，請使用正整數。 |
| `AI_TOKEN_QUOTA_PERIOD` | `month` | `month` 會在每月第一天 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 的視覺模型可以接受，但許多自架閘道（例如 vLLM）雖接受圖片卻會拒絕 PDF 檔案。請將 `AI_PDF_MODEL` 設為可讀取 PDF 檔案的模型；任何歷史記錄中包含 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** 按鈕。用量會在開啟分頁時讀取，不會持續重新整理。聊天或錯誤建議完成後，請重新開啟分頁以查看最新的計數。重設會立即生效，且僅清除該使用者目前週期的計數器，然後重新載入顯示的用量。此操作不需要儲存帳號表單的其他部分。

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

聊天與錯誤建議的用量共用同一個 Redis 計數器，會在請求完成後依據模型供應商回報的總 token 數進行更新。這包含所有模型步驟中的輸入與輸出 token。輸入可能包含對話歷史、文件上下文與工具結果，因此後續提問消耗的 token 可能比新訊息本身更多。即使上限為 **Unlimited**，仍會記錄用量。未回報 token 總數的請求不會計入計數器；模組無法重建過去未記錄的用量。

配額檢查會在串流開始前進行。單一請求或多個並行請求可能會在後續請求被阻擋之前超出剩餘額度。這是一種用量額度，而非嚴格的供應商支出上限。如果配額查詢失敗，請求會被允許，並記錄該失敗。

兩項功能都使用 `AI_TOKEN_QUOTA`；錯誤建議沒有獨立的請求次數上限。重設計數器不會變更權限、同意狀態、已設定的上限或供應商本身的計費紀錄。計數器使用 UTC 週期鍵，並在 40 天後到期；保留 Redis 資料可在應用程式重新啟動後保留目前的用量。

### 選用的搜尋服務

網頁搜尋使用 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` | 每次搜尋請求的結果數；請使用服務支援的正整數。 |
| `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/zh-TW/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)。

讀取網頁功能自 v6.4.0 起推出。聊天可以透過 URL 讀取網頁，例如使用者提供的連結或搜尋結果。它會透過連結 URL 代理（與從外部 URL 擷取檔案的服務相同）擷取網頁，因此[外部 URL](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/external-url.md) 中所述的網路限制同樣適用。無需其他設定。

搜尋查詢會傳送至所設定的搜尋服務。搜尋結果隨後可能會包含在傳送給 AI 閘道的請求中。聊天的 **Tools** 選單讓使用者可以為其請求啟用或停用 **Web** 與 **Documentation**；工具也必須在伺服器上完成設定，模型才能使用。

### 問與答

> [accordion] AI 助理沒有出現在編輯器中
>
> \*\*答：\*\*只有在 `AI_ENABLED=true`，且 `AI_BASE_URL`、`AI_API_KEY` 與 `AI_MODEL` 皆已設定時，AI 助理才會出現在編輯器的左側欄。若缺少其中任何一項，所有使用者都將看不到 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** 會取代目前的聊天。系統沒有先前聊天的清單，且每個專案一次只會顯示一個聊天。


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