> ## 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 通过两种方式将 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 文件。

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 聊天中每条用户消息的最大工具调用次数，包括自动续写。请使用正整数。 |
| `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`。

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-CN/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)。

读取网页功能自 v6.4.0 起引入。聊天可以根据 URL 读取网页，例如用户提供的链接或搜索结果。它通过链接 URL 代理（即从外部 URL 获取文件的同一服务）获取页面，因此[外部 URL](https://ayakaleaf-pro.mintlify.site/zh-CN/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.