> ## 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. # Integração com IA > Configure o chat com IA, as sugestões para erros de LaTeX, o acesso dos usuários, as cotas e os serviços de pesquisa opcionais. > [!NOTE] > > Este recurso é fornecido por [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro) e está disponível a partir da v6.3.0. Seu feedback é bem-vindo caso encontre algum problema. ## Assistente de IA e assistente de erros de LaTeX O Ayakaleaf Pro traz recursos de IA para o editor de duas formas. * O assistente de IA pode usar os documentos do projeto e a seleção atual como contexto para responder perguntas e sugerir edições para você revisar. * O assistente de erros propõe uma correção direcionada quando você seleciona um erro de compilação 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) ### Configuração do Toolkit Adicione o seguinte ao `config/variables.env` da sua implantação do Toolkit, substituindo a URL, a chave e o modelo de exemplo pelos valores do seu provedor: ```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 ``` Mantenha as chaves de API reais no arquivo de ambiente da implantação e fora do controle de versão. Os valores acima são apenas marcadores, não credenciais válidas. > [!NOTE] > > A qualidade das sugestões de IA depende do modelo escolhido. Se você já tiver uma assinatura do Codex ou do ChatGPT, poderá conectá-la por meio do endpoint compatível com OpenAI do [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI). `AI_BASE_URL` é a URL base da API compatível com OpenAI, incluindo o prefixo de versão do provedor quando necessário. Não acrescente `/chat/completions`, pois isso é feito internamente. O gateway e o modelo devem suportar chat completions com streaming e ferramentas de função (function tools). Ambos os recursos enviam contexto do documento para esse gateway; o chat também pode enviar imagens e arquivos PDF carregados ao usar um modelo que os aceite. O Toolkit encaminha o `config/variables.env` para o contêiner da aplicação. Mantenha os nomes de variáveis mostrados aqui; não adicione o prefixo `OVERLEAF_`. No diretório do Toolkit, recrie o contêiner da aplicação após alterar essas variáveis: ```sh theme={null} bin/up -d ``` ### Configurações do gateway | Variável | Padrão | Finalidade | | - | - | - | | `AI_ENABLED` | `false` | Defina exatamente `true` para habilitar o chat e as sugestões de erros na instância. Se não for definida ou tiver qualquer outro valor, eles permanecem desabilitados. Também é necessária uma configuração de gateway funcional. | | `AI_BASE_URL` | Nenhum; obrigatório | URL base da API compatível com OpenAI. | | `AI_API_KEY` | Nenhum; obrigatório | Chave de API desse gateway, usada pelo servidor. | | `AI_MODEL` | Nenhum; obrigatório | Modelo de texto usado pela configuração padrão do chat e pelas sugestões para erros de LaTeX. | | `AI_IMAGE_MODEL` | Não definido | Modelo opcional com suporte a imagens no mesmo gateway, usando a mesma chave de API. | | `AI_PDF_MODEL` | Não definido | Modelo opcional no mesmo gateway para chats com arquivos PDF, usando a mesma chave de API. A partir da v6.4.0. | | `AI_MAX_STEPS` | `20` | Número máximo de chamadas de ferramentas por mensagem do usuário no chat com IA, incluindo continuações automáticas. Use um inteiro positivo. | | `AI_PROXY_URL` | Não definido | URL opcional de proxy HTTP para as chamadas ao gateway de IA. Não configura os clientes de pesquisa na web ou na documentação. | | `AI_TOKEN_QUOTA` | `0` | Limite de tokens por usuário, compartilhado entre o chat e as sugestões de erros em cada período. Não definido ou `0` significa ilimitado; use um inteiro positivo para definir um limite. | | `AI_TOKEN_QUOTA_PERIOD` | `month` | `month` é redefinido no primeiro dia do mês às 00:00 UTC; `week` é redefinido às segundas-feiras às 00:00 UTC. Outros valores usam `month`. | Para uploads de imagens, defina `AI_IMAGE_MODEL` como um modelo que aceite entrada de imagens e suporte as ferramentas usadas pelo chat. Qualquer requisição de chat cujo histórico contenha uma imagem anexada usa esse modelo, incluindo mensagens posteriores dessa conversa. Sem essa configuração, as requisições com imagens usam o modelo de chat normal, que precisa suportar imagens. As sugestões para erros de LaTeX continuam usando `AI_MODEL`. Os anexos em PDF foram introduzidos a partir da v6.4.0. Os usuários podem anexar arquivos PDF de até 2 MB, assim como imagens. O chat envia cada arquivo PDF como está, como uma parte `file` do Chat Completions, então o gateway e o modelo precisam aceitar entrada em PDF: os modelos de visão da OpenAI aceitam, enquanto muitos gateways auto-hospedados, como o vLLM, aceitam imagens mas recusam arquivos PDF. Defina `AI_PDF_MODEL` como um modelo que leia arquivos PDF; qualquer chat cujo histórico contenha um arquivo PDF usa esse modelo, incluindo mensagens posteriores e quaisquer imagens dessa conversa, por isso ele também deve aceitar imagens. Sem essa configuração, os chats com PDF usam `AI_MODEL`. Quando o modelo recusa um arquivo PDF, o chat orienta o usuário a pedir ao administrador que defina `AI_PDF_MODEL`. Por exemplo, para habilitar um modelo de imagens e uma cota semanal de IA: ```dotenv theme={null} AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID AI_TOKEN_QUOTA=100000 AI_TOKEN_QUOTA_PERIOD=week ``` ### Acesso dos usuários e consentimento A disponibilidade na instância e a permissão do usuário são independentes. `AI_ENABLED` e a configuração do gateway controlam a disponibilidade na instância. Um usuário conectado também precisa passar pela verificação de conta existente: `aiFeatures.enabled` não pode ser `false`. Esse campo existente do banco de dados controla tanto o chat quanto as sugestões para erros de LaTeX. Quando ele não está definido, os recursos de IA ficam habilitados para o usuário. `AI_TOKEN_QUOTA` é um limite aplicado igualmente a cada usuário autorizado; o módulo atual não oferece um limite numérico individual por conta. Na lista de usuários do painel de administração, selecione um usuário e abra **Update account info → AI features**. **Enable AI features** atualiza `aiFeatures.enabled` quando as alterações da conta são salvas. O servidor verifica as permissões atuais em novas requisições de IA, incluindo requisições de um editor já aberto. Um usuário sem permissão continua vendo o assistente de IA no editor, mas não consegue enviar mensagens. ### Uso e redefinição A aba de recursos de IA do painel de administração mostra, em uma única linha, o **Usage** do período atual, o **Limit** e o botão **Reset**. O uso é lido quando a aba é aberta; ele não é atualizado continuamente. Reabra a aba após a conclusão de um chat ou de uma sugestão de erro para ver a contagem mais recente. A redefinição tem efeito imediato e limpa apenas o contador do período atual daquele usuário, recarregando em seguida o uso exibido. Não é necessário salvar o restante do formulário da conta. ![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b) O uso do chat e das sugestões de erros compartilha um único contador no Redis, atualizado com o total de tokens informado pelo provedor do modelo após a conclusão de uma requisição. Isso inclui tokens de entrada e de saída em todas as etapas do modelo. A entrada pode incluir o histórico da conversa, o contexto do documento e os resultados das ferramentas, de modo que uma mensagem de acompanhamento pode consumir mais tokens do que apenas a nova mensagem. O uso é registrado mesmo quando o limite é **Unlimited**. Requisições sem total de tokens informado não são somadas ao contador; o uso histórico não registrado não pode ser reconstruído pelo módulo. As verificações de cota ocorrem antes do streaming. Uma requisição, ou várias requisições simultâneas, podem exceder a cota restante antes que as requisições seguintes sejam bloqueadas. Trata-se de uma cota de uso, e não de um limite rígido de gastos com o provedor. Se a consulta da cota falhar, a requisição é permitida e a falha é registrada em log. Ambos os recursos usam `AI_TOKEN_QUOTA`; as sugestões de erros não têm um limite separado de número de requisições. Redefinir o contador não altera a permissão, o consentimento, o limite configurado nem os registros de cobrança do próprio provedor. Os contadores usam chaves de período em UTC e expiram após 40 dias; manter os dados do Redis preserva o uso atual entre reinicializações da aplicação. ### Serviços de pesquisa opcionais A pesquisa na web usa uma API compatível com Tavily. Ela fica disponível quando uma chave de API de pesquisa está configurada. Essas configurações são independentes do gateway de IA: | Variável | Padrão | Finalidade | | - | - | - | | `TAVILY_API_KEY` | Não definido | Chave da API de pesquisa. Tem precedência sobre `WEB_SEARCH_API_KEY`. | | `WEB_SEARCH_API_KEY` | Não definido | Nome alternativo para a chave da API de pesquisa. | | `WEB_SEARCH_URL` | `https://api.tavily.com/search` | Endpoint de pesquisa; endpoints personalizados devem aceitar o formato de requisição e resposta do Tavily. | | `WEB_SEARCH_MAX_RESULTS` | `5` | Resultados solicitados por pesquisa; use um inteiro positivo suportado pelo serviço. | | `WEB_SEARCH_DEPTH` | `basic` | Profundidade da pesquisa, normalmente `basic` ou `advanced`. | | `WEB_SEARCH_PROVIDER` | `tavily` | A implementação atual suporta apenas o protocolo compatível com Tavily; alterar esse valor não seleciona outro adaptador. | | `DOCS_MCP_URL` | `https://docs.overleaf.com/~gitbook/mcp` | Endpoint de pesquisa na documentação. Defina como string vazia para desabilitar a pesquisa na documentação. | Por exemplo: ```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 ``` A pesquisa na documentação chama a ferramenta `searchDocumentation` do endpoint GitBook MCP configurado e aceita respostas JSON ou SSE. Trata-se de um cliente MCP para pesquisa na documentação. Para permitir que clientes de IA fora do Ayakaleaf trabalhem em um projeto, consulte [Servidor MCP](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md). A leitura de páginas web foi introduzida a partir da v6.4.0. O chat pode ler uma página pela URL, como um link fornecido pelo usuário ou um resultado de pesquisa. Ele busca a página por meio do proxy de URLs vinculadas, o mesmo serviço que busca arquivos de URLs externas, então as restrições de rede descritas em [External URL](https://ayakaleaf-pro.mintlify.site/pt/on-premises/configuration/overleaf-toolkit/external-url.md) também se aplicam a ele. Nenhuma outra configuração é necessária. As consultas de pesquisa são enviadas ao serviço de pesquisa configurado. Os resultados podem então ser incluídos nas requisições ao gateway de IA. O menu **Tools** do chat permite que os usuários habilitem ou desabilitem **Web** e **Documentation** em suas requisições; uma ferramenta também precisa estar configurada no servidor para ficar disponível ao modelo. ### Perguntas e respostas > [accordion] O assistente de IA não aparece no editor > > **Resposta:** O assistente de IA aparece na barra lateral esquerda do editor somente quando `AI_ENABLED=true` e `AI_BASE_URL`, `AI_API_KEY` e `AI_MODEL` estão todos definidos. Se algum deles estiver faltando, o assistente de IA fica oculto para todos os usuários. > > Depois de alterar `config/variables.env`, recrie o contêiner com `bin/up -d`. Apenas atualizar o navegador não aplica as novas variáveis. A opção **Enable AI features** no painel de administração não mostra nem oculta o assistente de IA; ela apenas define se o usuário pode enviar mensagens. > [accordion] Envio uma mensagem, mas o assistente de IA não responde > > **Resposta:** Primeiro, verifique se o usuário aceitou o cartão de consentimento de IA exibido no assistente de IA. Não é possível enviar mensagens antes disso. > > Em seguida, procure erros no log do serviço web: > > ```sh theme={null} > bin/logs web > ``` > > | Mensagem de log | Significado | > | - | - | > | `workbench AI chat requested but no AI gateway is configured` | Uma das variáveis `AI_ENABLED`, `AI_BASE_URL`, `AI_API_KEY` ou `AI_MODEL` está faltando no contêiner em execução. Recrie-o com `bin/up -d`. | > | `workbench chat stream error` | O gateway retornou um erro. O usuário vê "The AI service returned an error". O erro registrado mostra o código de status e a mensagem do gateway. | > | `workbench chat failed` | A requisição falhou antes ou durante o streaming, por exemplo porque o gateway não pode ser alcançado. | > > Se o painel do seu provedor não mostrar nenhum uso, a requisição não chegou ao provedor. As causas comuns são: > > * `AI_BASE_URL` está incorreta, por exemplo com um `/v1` faltando ou sobrando, ou com `/chat/completions` acrescentado. > * O servidor não consegue alcançar o gateway. Se o tráfego de saída precisar passar por um proxy, defina `AI_PROXY_URL`. > * `AI_MODEL` não é um ID de modelo conhecido pelo gateway. > > Se o provedor mostrar as requisições, mas o chat continuar falhando, verifique se o modelo suporta chat completions com streaming e ferramentas de função. > [accordion] O histórico do chat é mantido? > > **Resposta:** Não. Um chat só é mantido na aba aberta do navegador. Atualizar ou fechar a página o apaga, e **Start new chat** substitui o chat atual. Não há uma lista de chats anteriores, e cada projeto mostra um chat por vez. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.