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）。这两项功能都会将文档上下文发送到该网关；在使用支持相应输入的模型时，聊天还可以发送上传的图片和 PDF 文件。

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

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

聊天和错误建议的用量共享同一个 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 客户端。如需让 Ayakaleaf 之外的 AI 客户端处理项目，请参阅 MCP 服务器。

读取网页功能自 v6.4.0 起引入。聊天可以根据 URL 读取网页，例如用户提供的链接或搜索结果。它通过链接 URL 代理（即从外部 URL 获取文件的同一服务）获取页面，因此外部 URL 中描述的网络限制同样适用。无需额外设置。

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

​

问答

编辑器中没有出现 AI 助手

回答：只有当 AI_ENABLED=true 且 AI_BASE_URL、AI_API_KEY 和 AI_MODEL 均已设置时，AI 助手才会出现在编辑器的左侧栏中。如果缺少其中任何一项，AI 助手将对所有用户隐藏。

修改 config/variables.env 后，请使用 bin/up -d 重新创建容器。仅刷新浏览器不会应用新的变量。管理面板中的 Enable AI features 开关不会显示或隐藏 AI 助手；它只决定用户能否发送消息。

我发送了消息，但 AI 助手没有回复

回答：首先，确认用户已接受 AI 助手中显示的 AI 授权卡片。在此之前无法发送消息。

然后在 web 服务日志中查找错误：

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。

如果服务提供商显示收到了请求但聊天仍然失败，请检查该模型是否支持流式聊天补全和函数工具。

聊天记录会被保留吗？

回答：不会。聊天仅保留在当前打开的浏览器标签页中。刷新或关闭页面会将其清除，Start new chat 会替换当前聊天。没有历史聊天列表，每个项目一次只显示一个聊天。