> ## 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 错误建议、用户访问权限、配额以及可选的搜索服务。

<Info>
  此功能由 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/overleaf-pro) 提供，自 v6.3.0 起可用。如果你遇到任何问题，欢迎向我们反馈。
</Info>

## AI 助手和 LaTeX 错误助手

Ayakaleaf Pro 通过两种方式将 AI 功能引入编辑器。

* AI 助手可以将你的项目文档和当前选中内容作为上下文来回答问题，并提出修改建议供你审阅。
* 当你选中某个 LaTeX 编译错误时，错误助手会给出有针对性的修复方案。

<Frame>
  <img src="https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/image-48.png?fit=max&auto=format&n=x9kfDjtWlyyhG_mR&q=85&s=107b27f8843a326269b5e3711ccf2616" alt="" width="2844" height="1710" data-path="images/on-premises/image-48.png" />
</Frame>

### 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 密钥保存在部署环境文件中，不要纳入版本控制。上面的值只是占位符，并非可用的凭据。

<Info>
  AI 建议的质量取决于你所选择的模型。如果你已经订阅了 Codex 或 ChatGPT，可以通过 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) 提供的 OpenAI 兼容端点进行连接。
</Info>

`AI_BASE_URL` 是 OpenAI 兼容 API 的基础 URL，在需要时应包含服务提供商的版本前缀。不要在末尾追加 `/chat/completions`，因为我们会在内部自动追加。网关和模型必须支持流式聊天补全（streaming chat completions）和函数工具（function tools）。这两项功能都会将文档上下文发送到该网关；在使用支持图像的模型时，聊天还可以发送上传的图片。

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_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 额度：

```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 错误建议。
* 用户的有效 `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**（重置）按钮。用量在打开标签页时读取，不会持续刷新。在聊天或错误建议完成后，请重新打开该标签页以查看最新计数。重置会立即生效，仅清除该用户当前周期的计数器，然后重新加载显示的用量。重置无需保存账户表单的其他部分。

<Frame>
  <img src="https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max&auto=format&n=x9kfDjtWlyyhG_mR&q=85&s=3c52c12aa1551cda22f218ec2dfda63b" alt="" width="563" data-path="images/on-premises/img-2f5a5399.png" />
</Frame>

聊天和错误建议的用量共享同一个 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 客户端；这些模块不会将项目文件作为 MCP 服务器对外暴露，也不提供通用的 MCP 服务器注册表。

搜索查询会发送到所配置的搜索服务，然后搜索结果可能会被包含在发往 AI 网关的请求中。用户可以通过聊天的 **Tools** 菜单为自己的请求启用或禁用 **Web** 和 **Documentation**；工具还必须在服务器上完成配置，才能供模型使用。


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