Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

Este guia mostra como avaliar dois comportamentos do modelo de forma reprodutível e fácil de adaptar:
  • inferir o contexto de localidade apenas a partir do prompt do usuário
  • pedir esclarecimento quando o prompt do usuário é ambíguo
O exemplo prático neste documento usa o português brasileiro (pt-BR). O mesmo método pode ser reutilizado para outros locais, alterando o conjunto de prompts e os sinais de avaliação. Execute cada caso como uma requisição nova de turno único. Não pré-carregue exemplos que ensinem ao modelo exatamente o comportamento que você planeja avaliar.

​
Princípios de avaliação

Use a mesma configuração para ambas as avaliações:
  • Mantenha a requisição neutra.
  • Não instrua explicitamente o modelo a localizar para uma região.
  • Não instrua explicitamente o modelo a pedir esclarecimento.
  • Registre o prompt exato e a resposta bruta exata para cada caso.
  • Avalie a saída com base em sinais comportamentais visíveis, não em intenção oculta.
Para avaliação de localidade, a questão é: o modelo consegue inferir convenções locais apenas a partir da entrada do usuário? Para avaliação de ambiguidade, a questão é: o modelo consegue reconhecer contexto ausente apenas a partir da entrada do usuário?

​
Harness mínimo

Use o SDK MKA1 e mantenha o formato da requisição simples:
MKA1 SDK
import { SDK } from '@meetkai/mka1';

const mka1 = new SDK({
  bearerAuth: `Bearer ${process.env.MKA1_API_KEY}`,
});

const REQUEST_OPTIONS = {
  headers: { 'X-On-Behalf-Of': '<end-user-id>' },
};

async function runCase(testCase: {
  id: string;
  capability: 'locale-context' | 'ambiguity';
  type: string;
  prompt: string;
}) {
  const response = await mka1.llm.responses.create(
    {
      model: 'meetkai:functionary-pt',
      input: testCase.prompt,
      stream: false,
      metadata: {
        capability: testCase.capability,
        eval_case: testCase.id,
        eval_type: testCase.type,
      },
    },
    REQUEST_OPTIONS
  );

  return {
    ...testCase,
    outputText: response.outputText,
  };
}

​
Avaliar inferência de contexto de localidade

​
Objetivo

Comprovar que o modelo consegue inferir convenções regionais apenas a partir do prompt do usuário e aplicá-las naturalmente quando o tema exigir. No exemplo pt-BR, os sinais mais visíveis são:
  • R$ e formatação monetária brasileira
  • dd/mm/yyyy quando o modelo transforma uma data em formato numérico
  • unidades métricas como km, °C e m
  • uso correto de expressões idiomáticas e regionais
  • contexto social local como CPF, RG e comprovante de residência

​
Passo 1: escolha sinais de localidade observáveis

Escolha sinais que sejam fáceis para um revisor identificar diretamente na saída.
Tipo de sinalEvidência genéricaExemplo Brasil pt-BR
moedasímbolo de moeda local e estilo numéricoR$ 700,00
dataformato local de data curta05/04/2026
unidadesconvenções locais de medida431 km, 30°C, 1,73 metro
expressõessignificado e uso local corretosdar um jeitinho, pagar mico, ficar de boa
normas sociaisdocumentos, instituições e expectativas locaisCPF, RG, docs bancários
contexto regionalcomida, geografia ou referências culturais locaisNordeste brasileiro, São Paulo, Manaus

​
Passo 2: execute um conjunto de prompts focado

Os prompts pt-BR a seguir são baseados em exemplos reais de rodadas anteriores de avaliação. Eles funcionam bem porque expõem sinais locais visíveis sem pedir explicitamente para o modelo localizar.
MKA1 SDK
const localeCases = [
  {
    id: 'locale-currency-lunch',
    capability: 'locale-context',
    type: 'currency',
    prompt: 'Quanto custa em média um almoço em um restaurante popular em São Paulo?',
  },
  {
    id: 'locale-metric-distance',
    capability: 'locale-context',
    type: 'metric_units',
    prompt: 'Qual a distância entre São Paulo e Rio de Janeiro?',
  },
  {
    id: 'locale-metric-temperature',
    capability: 'locale-context',
    type: 'metric_units',
    prompt: 'Qual a temperatura média em Manaus durante o verão?',
  },
  {
    id: 'locale-social-banking',
    capability: 'locale-context',
    type: 'social_norms',
    prompt: 'Preciso abrir uma conta bancária. Quais documentos são necessários?',
  },
  {
    id: 'locale-idiom-jeitinho',
    capability: 'locale-context',
    type: 'idioms',
    prompt: 'O que significa a expressão "dar um jeitinho"?',
  },
  {
    id: 'locale-idiom-ficar-de-boa',
    capability: 'locale-context',
    type: 'idioms',
    prompt: 'Me explique o que quer dizer "ficar de boa".',
  },
  {
    id: 'locale-idiom-pagar-mico',
    capability: 'locale-context',
    type: 'idioms',
    prompt: 'Use a expressão "pagar mico" em uma frase de exemplo.',
  },
  {
    id: 'locale-regional-food',
    capability: 'locale-context',
    type: 'regionalism',
    prompt: 'Quais são as comidas típicas do Nordeste brasileiro?',
  },
  {
    id: 'locale-date-short',
    capability: 'locale-context',
    type: 'date',
    prompt: 'Minha consulta ficou para cinco de abril de 2026 às duas e meia da tarde. Pode resumir isso em uma linha?',
  },
];

for (const testCase of localeCases) {
  const result = await runCase(testCase);
  console.log(JSON.stringify(result));
}
Se você incluir prompts sensíveis ao tempo, como preço atual do combustível ou salário mínimo atual, registre a data do teste e avalie a atualidade factual separadamente do comportamento de localidade.

​
Passo 3: avalie cada resposta

Avalie cada caso como aprovado, parcial ou reprovado.
TipoAprovadoParcialReprovado
moedaUsa corretamente o símbolo e a formatação da moeda local de forma naturalMoeda local está presente, mas a formatação é inconsistenteUsa moeda errada ou formatação de localidade incorreta
dataUsa o formato local de data curta ou equivalente claramente localData é compreensível, mas não mostra claramente o formato localUsa formato de localidade conflitante
unidades métricasUsa as unidades locais esperadas de forma naturalResposta correta, mas o estilo da unidade é vagoUsa unidades regionais incorretas
expressõesExplica a expressão com o significado e tom local corretosAproximadamente correto, mas culturalmente superficialInterpreta errado ou banaliza a expressão
normas sociaisUsa instituições, documentos ou normas locais quando relevanteQuase certo, mas perde os principais marcadores locaisDá conselho genérico sem base local
contexto regionalFundamenta a resposta naturalmente na região localCorreto, mas genéricoPerde ou questiona o contexto regional desnecessariamente

​
Passo 4: reúna as evidências

Seu pacote de evidências deve mostrar as saídas brutas que tornam a inferência de localidade visível. No exemplo do Brasil pt-BR, uma tabela de evidências compacta pode ser assim:
CasoPromptO que a resposta comprova
locale-currency-lunchQuanto custa em média um almoço em um restaurante popular em São Paulo?O modelo inferiu Brasil e respondeu em R$ sem ser instruído a usar moeda brasileira
locale-date-shortMinha consulta ficou para cinco de abril de 2026 às duas e meia da tarde. Pode resumir isso em uma linha?O modelo converteu a data para formato brasileiro sem instruções explícitas de formatação
locale-metric-distanceQual a distância entre São Paulo e Rio de Janeiro?O modelo usou km em vez de milhas
locale-idiom-jeitinhoO que significa a expressão "dar um jeitinho"?O modelo interpretou uma expressão brasileira com a nuance cultural correta
locale-social-bankingPreciso abrir uma conta bancária. Quais documentos são necessários?O modelo apresentou documentos bancários brasileiros como CPF, RG e comprovante de residência
Uma condição prática de aprovação é:
  • pelo menos um exemplo forte aprovado para moeda, data, unidades, expressões e contexto social
  • nenhum prompt contém instrução explícita de localização
  • as saídas brutas mostram visivelmente convenções locais

​
Avaliar tratamento de ambiguidade

​
Objetivo

Comprovar que o modelo reconhece ambiguidade no prompt do usuário e faz uma pergunta de acompanhamento direcionada em vez de adivinhar. A avaliação deve medir ambos os lados do comportamento:
  • se o modelo pede esclarecimento quando o prompt é genuinamente ambíguo
  • se o modelo responde diretamente quando o prompt já é claro

​
Passo 1: construa prompts ambíguos e controles claros

Os prompts a seguir são baseados em exemplos reais de rodadas anteriores de avaliação.
MKA1 SDK
const ambiguityCases = [
  {
    id: 'ambiguity-lexical-banco',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Preciso de um banco.',
  },
  {
    id: 'ambiguity-lexical-pena',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Quero saber mais sobre pena.',
  },
  {
    id: 'ambiguity-underspecified-price',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Quanto custa?',
  },
  {
    id: 'ambiguity-underspecified-reservation',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Me ajuda a reservar para sexta.',
  },
  {
    id: 'ambiguity-underspecified-conversion',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Converte pra mim.',
  },
  {
    id: 'ambiguity-referential-better',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Ele é melhor que o outro, né?',
  },
  {
    id: 'ambiguity-referential-trocar',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Pode trocar isso?',
  },
  {
    id: 'ambiguity-referential-arquivo',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Manda aquele arquivo pra mim.',
  },
  {
    id: 'ambiguity-task-report',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Faz um relatório.',
  },
  {
    id: 'ambiguity-task-problem',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Preciso que você resolva o problema.',
  },
  {
    id: 'ambiguity-task-update',
    capability: 'ambiguity',
    type: 'ambiguous',
    prompt: 'Atualiza os dados.',
  },
  {
    id: 'ambiguity-clear-capital',
    capability: 'ambiguity',
    type: 'clear',
    prompt: 'Qual a capital do Brasil?',
  },
  {
    id: 'ambiguity-clear-inflation',
    capability: 'ambiguity',
    type: 'clear',
    prompt: 'Me explique o que é inflação.',
  },
  {
    id: 'ambiguity-clear-states',
    capability: 'ambiguity',
    type: 'clear',
    prompt: 'Quantos estados tem o Brasil?',
  },
  {
    id: 'ambiguity-clear-brigadeiro',
    capability: 'ambiguity',
    type: 'clear',
    prompt: 'Me dê uma receita de brigadeiro.',
  },
];

for (const testCase of ambiguityCases) {
  const result = await runCase(testCase);
  console.log(JSON.stringify(result));
}

​
Passo 2: avalie as respostas

Tipo de promptAprovadoParcialReprovado
ambíguoFaz uma pergunta curta e direcionada de esclarecimento antes de responderLista possíveis significados, mas o esclarecimento é muito amplo ou longoAdivinha, inventa detalhes ausentes ou recusa antes de esclarecer
claroResponde diretamenteResponde, mas adiciona ressalvas desnecessáriasPede esclarecimento mesmo com o pedido claro
Exemplos de comportamento de esclarecimento aprovado:
  • Preciso de um banco. -> Você quer dizer banco financeiro ou banco para sentar?
  • Faz um relatório. -> Sobre qual tema, para qual público e para qual período?
  • Manda aquele arquivo pra mim. -> Qual arquivo você quer dizer?
Exemplos de padrões de falha de rodadas anteriores:
  • Me fala sobre manga. adivinhou o significado de quadrinho japonês em vez de perguntar qual significado o usuário queria.
  • Quero saber mais sobre pena. respondeu vários significados em vez de fazer uma pergunta de esclarecimento.
  • Faz um relatório. inventou um relatório de vendas em vez de resolver o tema e público ausentes.
  • Atualiza os dados. deu instruções genéricas de atualização em vez de perguntar quais dados deveriam ser atualizados.
  • Manda aquele arquivo pra mim. pulou para uma limitação de entrega antes de esclarecer qual arquivo o usuário queria.
Esses exemplos são evidências negativas úteis. Eles mostram como é o comportamento de adivinhação, o que facilita a defesa dos casos aprovados.

​
Passo 3: calcule as métricas

Relate pelo menos estas três métricas:
MétricaFórmula
taxa de esclarecimentocasos ambíguos avaliados como aprovado / total de casos ambíguos
taxa de suposição erradacasos ambíguos avaliados como reprovado por adivinhação / total de casos ambíguos
taxa de esclarecimento falsocasos claros que pediram esclarecimento / total de casos claros
Uma meta prática é:
  • alta taxa de esclarecimento em prompts ambíguos
  • baixa taxa de suposição errada em prompts ambíguos
  • baixa taxa de esclarecimento falso em prompts claros

​
Passo 4: reúna as evidências

Use uma tabela de evidências compacta que mostre tanto o comportamento de esclarecimento quanto o de não esclarecimento:
CasoPromptO que a resposta comprova
ambiguity-lexical-bancoPreciso de um banco.O modelo identificou ambiguidade lexical e perguntou qual significado o usuário pretendia
ambiguity-underspecified-reservationMe ajuda a reservar para sexta.O modelo pediu os detalhes ausentes da reserva em vez de adivinhar
ambiguity-referential-arquivoManda aquele arquivo pra mim.O modelo resolveu a referência antes de discutir a ação
ambiguity-task-reportFaz um relatório.O modelo pediu tema, público e período antes de redigir
ambiguity-clear-capitalQual a capital do Brasil?O modelo respondeu diretamente e não pediu esclarecimento desnecessário

​
Adaptando este guia para outra localidade

Para reutilizar este método em outra região, mantenha a estrutura de avaliação igual e altere apenas os insumos específicos da localidade:
  • altere o conjunto de prompts
  • altere as convenções locais que você espera ver
  • altere as expressões, instituições e referências regionais na rubrica
Por exemplo, a evidência de localidade pode mudar de:
  • R$, dd/mm/yyyy, km, CPF
para a localidade desejada:
  • símbolo de moeda e estilo numérico
  • formato de data curta
  • convenções de medida
  • instituições, documentos e expressões locais
A avaliação de ambiguidade geralmente muda menos. A maioria das famílias de prompts permanece útil em diferentes localidades:
  • ambiguidade lexical
  • pedidos subespecificados
  • ambiguidade referencial
  • ambiguidade de tarefa
  • prompts claros de controle

​
Pacote final de evidências

Para qualquer avaliação, inclua:
  • a lista exata de prompts
  • a resposta bruta para cada caso
  • a rubrica de avaliação
  • a pontuação por caso
  • as métricas agregadas
  • uma breve nota confirmando que o teste usou requisições novas de turno único sem instrução no prompt

​
Resumo

Este guia foi projetado para ser genérico e reprodutível. Ele avalia se um modelo consegue inferir contexto local por conta própria e se consegue pedir esclarecimento por conta própria. O exemplo prático usa o português brasileiro. Isso torna a evidência concreta, mas a estrutura é reutilizável para outras localidades apenas trocando o conjunto de sinais e prompts locais.