AI 集成

配置 AI 聊天、LaTeX 错误建议、用户访问权限、配额以及可选的搜索服务。

此功能由 ayaka-notes/ayakaleaf-pro 提供，自 v6.3.0 起可用。如果你遇到任何问题，欢迎向我们反馈。

​

AI 助手和 LaTeX 错误助手

Ayakaleaf Pro 通过两种方式将 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	未设置	可选，用于调用 AI 网关的 HTTP 代理 URL。它不会配置网页搜索或文档搜索客户端。
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；工具还必须在服务器上完成配置，才能供模型使用。