Classificação de texto no Google Sheets: a função =AI() vs Apps Script → API Jev

Quase toda tarefa de classificação em planilha tem a mesma forma: uma coluna de texto livre (respostas de pesquisa, formulários, mensagens de suporte, avaliações), uma lista curta de categorias e uma coluna nova que deve conter exatamente uma delas por linha. Extras úteis: uma coluna de confiança, uma marca de “revisar” e uma coluna de rótulos manuais numa amostra para conferir o resultado. No Google Sheets há três caminhos realistas para preencher essa coluna: a função AI nativa, um Apps Script que chama uma API externa como o JevModel, ou exportar um CSV, classificar fora e colar os resultados de volta.

A ajuda do Google descreve a sintaxe AI("prompt", [intervalo opcional]); =Gemini() é um nome equivalente. Você seleciona as células e clica em Generate and Insert, ou Refresh and Insert para gerar de novo. Os exemplos do Google incluem classificar uma solicitação como elogio, pedido de troca ou pedido de devolução, e classificar e-mails como positivos, negativos ou neutros. Para classificação, os limites documentados importam: só retorna texto; a função vê apenas o intervalo passado, não a planilha inteira; não pode ser aninhada em outra fórmula (o exemplo não suportado do Google envolve AI() em IF); só as primeiras 350 células AI selecionadas são geradas por vez; há limites de geração de curto e longo prazo; e o acesso depende do plano, das configurações do administrador e do idioma. Pontos fortes: zero configuração em contas elegíveis e um prompt em linguagem natural que qualquer pessoa edita. Limites: a saída é texto livre, então o rótulo pode variar (“Return”, “return request”, “Returns”) se o prompt e uma limpeza não forçarem valores exatos, e não há coluna de probabilidade por rótulo para definir um limiar de revisão.

O Apps Script chama qualquer API HTTPS com UrlFetchApp, e o guia de funções personalizadas do Google confirma que o URL Fetch é um dos serviços permitidos. Ainda assim, não é o lugar para uma chamada de classificação cobrada por uso. Uma função personalizada precisa retornar em 30 segundos ou a célula mostra #ERROR!; cada uso é uma chamada separada ao servidor do Apps Script; e ela é recalculada quando uma célula referenciada muda, então uma edição pode reclassificar (e cobrar) a mesma linha sem você perceber. Um item de menu personalizado evita isso: o script roda uma vez ao clicar, lê as linhas selecionadas, chama o JevModel e grava rótulo e probabilidade como valores fixos que não recalculam. Planeje com os limites publicados pelo Google: 6 minutos por execução e cotas de URL Fetch de 20.000 chamadas/dia em contas pessoais e 100.000/dia no Google Workspace (o Google avisa que podem mudar). Trabalhe com seleções que terminem numa execução. Guarde a chave do JevModel em Project Settings → Script properties, não numa célula, e lembre que quem edita a planilha também edita o script vinculado: mantenha poucos editores.

A tabela compara a forma do fluxo e o contrato de saída, não a precisão. Nenhuma linha é benchmark; meça na sua própria amostra rotulada.

Abra Extensions → Apps Script, cole o código, crie uma propriedade de script chamada JEVMODEL_API_KEY com uma chave do JevModel Console → API keys e recarregue a planilha. Selecione as células de texto de uma coluna e escolha Jev → Classify selected rows; o rótulo e a probabilidade são gravados nas duas colunas seguintes. A requisição segue o contrato documentado: um state (o texto da célula) e perguntas nomeadas, aqui um Choice cujos criteria ligam IDs de rótulo a definições curtas. Definições claras, com um “other” explícito, importam mais que redação esperta. O site fixa o modelo typesafe/jev-1.13 via OpenRouter, então não há campo model. O JevModel é independente da TypeSafe AI, que desenvolve o Jev. Um code diferente de zero (por exemplo INSUFFICIENT_TOKENS) é gravado como ERROR para você reexecutar só essas linhas; a API não tem chave de idempotência, então não reexecute linhas que já têm rótulo.

// Illustrative only. Save the key as the script property JEVMODEL_API_KEY.
// Run from the menu, not as a custom function, so edits never re-bill rows.
const LABELS = {
  billing: "Charges, refunds, invoices or payment methods.",
  shipping: "Delivery status, delays or address changes.",
  product: "How the product works, or a defect report.",
  other: "Anything that fits none of the labels above.",
};

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu("Jev")
    .addItem("Classify selected rows", "classifySelection")
    .addToUi();
}

function classifySelection() {
  const key = PropertiesService.getScriptProperties().getProperty("JEVMODEL_API_KEY");
  const sheet = SpreadsheetApp.getActiveSheet();
  const range = sheet.getActiveRange(); // one column of text cells
  const rows = range.getValues().map(([text]) => {
    if (!text) return ["", ""];
    const res = UrlFetchApp.fetch("https://jevmodel.app/api/v1/systemone", {
      method: "post",
      contentType: "application/json",
      headers: { Authorization: "Bearer " + key },
      muteHttpExceptions: true,
      payload: JSON.stringify({
        state: String(text),
        questions: {
          route: {
            type: "choice",
            instructions: "Which support queue should handle this message?",
            criteria: LABELS,
          },
        },
      }),
    });
    const body = JSON.parse(res.getContentText());
    if (body.code !== 0) return ["ERROR", body.message];
    const answer = body.data.answers.route;
    const p = answer.probabilities ? answer.probabilities[answer.choice] : "";
    return [answer.choice, p];
  });
  // Plain values in the next two columns: label, probability.
  sheet.getRange(range.getRow(), range.getColumn() + 1, rows.length, 2).setValues(rows);
}

A planilha facilita a avaliação, então faça. Antes de classificar tudo, rotule à mão uma amostra aleatória de linhas em outra coluna, rode a mesma pergunta e compare com COUNTIFS ou uma tabela dinâmica: concordância por rótulo e quais rótulos se confundem. Depois defina uma regra de revisão a partir da amostra, por exemplo “probabilidade abaixo do nível onde houve mais discordâncias vai para revisão”, e adicione uma coluna como =IF(C2<0.7,"review","ok"); 0,7 é um exemplo, não uma recomendação. Mantenha o rótulo “other” e trate uma fatia alta de “other” como sinal de que a lista de rótulos precisa de ajuste, não como falha do modelo. A confiança de Choice descrita pela TypeSafe, (p − 1/n)/(1 − 1/n), corrige pelo número de rótulos, mas também não é precisão calibrada. Reconfira a amostra após mudar rótulos ou definições.

Escolha =AI() se você já tem um plano elegível, a planilha é uma exploração pontual e alguém vai ler os resultados de qualquer forma. Escolha o menu Apps Script → Jev se o mesmo conjunto de rótulos é reutilizado, se você quer uma coluna de probabilidade para decidir o que revisar, ou se os rótulos precisam bater com os de outra automação (Zapier, Make, n8n, Power Automate, Pipedream ou seu app) pela mesma API. Escolha CSV → Console → Batch para ter rótulos do Jev sem programar, ou testar uma pergunta num arquivo pequeno. Checklist para qualquer caminho: 1) defina rótulos com um “other” explícito; 2) rotule uma amostra à mão; 3) guarde rótulos aceitos como valores, não fórmulas vivas; 4) nada de chaves de API em células; 5) não afirme precisão que você não mediu nessa amostra. Se uma linha pode ter vários rótulos, veja multi-label-text-classification em vez de forçar um único Choice.