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.

Este recurso é fornecido por 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.

​

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:

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.

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.

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:

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:

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.

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:

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.

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 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

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.

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:

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.

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.