Antes de o modelo correr
O utilizador fornece um prompt e um alias como cheap, fast ou smart. O servidor de produção verifica autenticação, propriedade do workspace e permissão antes de aceitar a tarefa. IDs de modelo e segredos de fornecedor ficam atrás dessa fronteira — o alias amigável é o único vocabulário de modelo que o cliente precisa, porque o mapeamento para um modelo real de fornecedor é configuração, não contrato.
Um registo de tarefa durável dá ao pedido uma identidade antes de a execução em segundo plano começar. Essa identidade liga submissão, worker, registos de utilização e resultado. Também dá ao utilizador uma forma de recuperar o trabalho depois de navegar para outro lado.
A ordem importa: o trabalho caro só começa depois de as verificações baratas passarem. Verificar autenticação, propriedade e permissão antes de qualquer coisa ser enfileirada impede que pedidos não autenticados ou não pagos cheguem sequer a um fornecedor — e torna a falha explicável ao utilizador. O guia do módulo de AI documenta onde vivem essas verificações; o post sobre limites de workspace explica porque a propriedade é derivada no servidor em vez de confiada pelo cliente.
Decide de quem são as chaves e os limites
Uma funcionalidade de AI é uma decisão de gasto. O supastack permite aos workspaces trazer as suas próprias chaves de fornecedor — guardadas encriptadas, nunca expostas a clientes — ou correr com chaves da plataforma, e aplica orçamentos por workspace contra um catálogo de preços de modelos. Seja qual for a tua implementação, as perguntas são as mesmas: quem paga, e onde o limite é aplicado?
A aplicação pertence ao workflow do servidor, não a uma estimativa do lado do browser. Um orçamento verificado depois da geração apenas regista o excesso; verificado antes do dispatch, previne-o. A configuração de chaves de fornecedor cobre o lado da configuração.
Torna a execução explícita
O Trigger.dev executa o workflow ai.generate. O router consciente de capacidades escolhe um modelo conforme a política configurada e os requisitos do pedido. Trata essa política como uma entrada operacional: um alias indisponível não deve aparecer como uma escolha funcional na interface.
Uma falha de rede durante a submissão pode deixar o cliente incerto sobre se o trabalho foi enfileirado. O caminho de produção usa uma chave de idempotência delimitada à tarefa e uma submissão guardada para que a recuperação reutilize o pedido original. Enviar uma nova tarefa após cada timeout arrisca trabalho e custo duplicados.
A durabilidade é também o que mantém a interface simples: o ecrã lê o estado da tarefa e renderiza-o em vez de orquestrar retries. Quando a geração atravessa chamadas de modelo, passos de ferramentas ou agendamentos, o contrato explícito de workflow — enqueue, status, cancel — é o que mantém «em progresso» honesto.
Nomeia os modos de falha
Entre o pedido e o resultado há um conjunto específico e finito de coisas que correm mal. Desenha para cada uma pelo nome em vez de para «erros» no abstrato — cada tarefa deve terminar num estado explicável: em fila, a correr, falhada com uma razão, ou completa com um resultado. A recuperação de tarefas é a referência do kit para o lado da recuperação.
O requisito de interface por baixo é que nenhum estado pode mentir. Um spinner que sobrevive ao trabalho, ou uma mensagem de sucesso para uma tarefa que nunca correu, é um ticket de suporte e uma disputa de faturação à espera de acontecer.
- Submissão com timeout — recupera através da submissão guardada e da chave de idempotência delimitada à tarefa em vez de reenfileirar.
- Fornecedor falhou a meio da tarefa — marca a tarefa como falhada com uma razão que a interface consiga mostrar.
- Orçamento esgotado — rejeita antes do dispatch, não depois do gasto.
- Utilizador navegou para outro lado — o registo durável e o URL de recuperação restauram estado e resultado.
Acompanha o que aconteceu
A geração produz mais do que texto. A aplicação regista a utilização e um resultado de tarefa, e a interface lê o estado através da API autenticada. O registo de utilização é o que torna o orçamento aplicável — é escrito antes de o resultado ser devolvido, não estimado depois.
O email de conclusão é um passo separado com registos de entrega separados. Uma resposta de modelo bem-sucedida não estabelece que um email foi entregue. Manter estes resultados distintos torna as falhas mais fáceis de explicar e repetir sem voltar a executar o modelo desnecessariamente.
O resultado também precisa de um lar a que o utilizador possa voltar: uma página de tarefa, uma lista de histórico, um URL de recuperação entregue nesse email de conclusão. Uma geração que só existe numa notificação transitória é trabalho que te vão pedir para produzir duas vezes.
Verifica cada fronteira
Usa adaptadores fake deterministas para testar primeiro as decisões da aplicação: acesso recusado, aliases desativados, submissões duplicadas, recuperação de resultado e erros genéricos. Estes testes devem correr sem credenciais de fornecedor.
Usa depois o processo de smoke de fornecedor explicitamente opt-in para integrações reais. Exige a configuração sandbox documentada e uma aprovação para fazer chamadas externas. A distinção mantém o desenvolvimento comum rápido enquanto torna as provas de produção específicas e rastreáveis.
Mantém essa divisão estável à medida que o produto muda: cobertura determinista perto de cada decisão de fronteira, para que uma troca de fornecedor, uma mudança de política do router ou um alias novo falhe um teste em vez de falhar um cliente.
Perguntas frequentes sobre funcionalidades de AI em SaaS
Algumas perguntas surgem em cada conversa sobre pôr AI atrás de um paywall.
- Onde deve acontecer a autorização para funcionalidades de AI? — Antes de qualquer coisa ser enfileirada: autentica, resolve o workspace, verifica a permissão, depois cria a tarefa. Verificações corridas após a geração apenas documentam o abuso.
- Preciso de suporte bring-your-own-key? — Se os teus clientes têm as suas próprias relações com fornecedores, sim: decide quem paga e quem detém os limites de taxa. Guarda as chaves encriptadas e mantém-nas fora dos clientes — o guia de configuração de AI cobre o modelo.
- Como impeço que retries cobrem em duplicado? — Delimita a chave de idempotência à tarefa e reutiliza a submissão guardada durante a recuperação, para que um timeout não possa criar uma segunda execução faturável.
- Que dados de utilização devo registar? — Por tarefa: modelo, unidades consumidas, custo contra o catálogo de preços e o workspace — o suficiente para aplicar orçamentos e responder a perguntas de gasto sem repetir jobs.
- Quando pertence a geração a um job em segundo plano? — Sempre que puder sobreviver a um pedido. A latência do modelo, os retries e o trabalho em vários passos pedem execução durável; só as chamadas instantâneas e baratas pertencem ao inline.