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，因為系統會在內部自動附加。閘道與模型必須支援串流聊天補全（streaming chat completions）與函式工具（function tools）。這兩項功能都會將文件上下文傳送至此閘道；使用支援圖片的模型時，聊天功能也可以傳送上傳的圖片。

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_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。

例如，若要啟用圖片模型並設定每週 AI 額度：

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

使用者存取權與同意

執行個體的可用性與使用者權限是分開的。AI_ENABLED 與閘道設定控制執行個體的可用性。已登入的使用者還必須通過現有的帳號檢查：

• aiFeatures.enabled 不得為 false。這個既有的資料庫欄位同時控制聊天與 LaTeX 錯誤建議。
• 使用者有效的 features.aiUsageQuota 必須符合所設定的無限制層級（預設為 unlimited），或必須啟用既有的舊版 features.aiErrorAssistant 權限。有效功能包含適用的帳號功能覆寫。

單獨勾選核取方塊並不會變更使用者的方案。aiUsageQuota 欄位是權限層級，而非數值型的 token 額度。AI_TOKEN_QUOTA 是平均套用於每位獲准使用者的獨立上限；目前的模組不提供針對個別帳號的數值上限。

在管理員使用者清單中，選取一位使用者並開啟 Update account info → AI features。儲存帳號變更時，Enable AI features 會更新 aiFeatures.enabled。伺服器會在新的 AI 請求中檢查目前的權限，包括來自已開啟編輯器的請求。權限變更後，請重新整理編輯器以更新其可見的控制項。

​

用量與重設

管理員的 AI features 分頁會在同一列顯示目前週期的 Usage、Limit 以及 Reset 按鈕。用量會在開啟分頁時讀取，不會持續重新整理。聊天或錯誤建議完成後，請重新開啟分頁以查看最新的計數。重設會立即生效，且僅清除該使用者目前週期的計數器，然後重新載入顯示的用量。此操作不需要儲存帳號表單的其他部分。

聊天與錯誤建議的用量共用同一個 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	文件搜尋端點。設為空字串即可停用文件搜尋。

例如：

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 用戶端；這些模組不會將專案檔案公開為 MCP 伺服器，也不提供通用的 MCP 伺服器登錄。

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