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 carregadas ao usar um modelo com suporte a imagens.

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

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 pelas verificações de conta existentes:

• 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.
• O features.aiUsageQuota efetivo do usuário deve corresponder ao nível ilimitado configurado (unlimited por padrão), ou a permissão legada existente features.aiErrorAssistant deve estar habilitada. Os recursos efetivos incluem as substituições de recursos aplicáveis à conta.

Marcar apenas a caixa de seleção não altera o plano do usuário. O campo aiUsageQuota é um nível de permissão, não uma cota numérica de tokens. AI_TOKEN_QUOTA é um limite separado 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. Atualize o editor para que seus controles visíveis reflitam uma mudança de permissão.

​

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; esses módulos não expõem os arquivos do projeto como um servidor MCP nem fornecem um registro de servidores MCP de uso geral.

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.