> ## 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. # Avaliar localização regional e tratamento de ambiguidade > Execute avaliações neutras que comprovam localização regional espontânea e comportamento de esclarecimento com o SDK MKA1. 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: ```ts MKA1 SDK theme={null} import { SDK } from '@meetkai/mka1'; const mka1 = new SDK({ bearerAuth: `Bearer ${process.env.MKA1_API_KEY}`, }); const REQUEST_OPTIONS = { headers: { 'X-On-Behalf-Of': '' }, }; 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 sinal | Evidência genérica | Exemplo Brasil `pt-BR` | | ----------------- | ------------------------------------------------- | ----------------------------------------------- | | moeda | símbolo de moeda local e estilo numérico | `R$ 700,00` | | data | formato local de data curta | `05/04/2026` | | unidades | convenções locais de medida | `431 km`, `30°C`, `1,73 metro` | | expressões | significado e uso local corretos | `dar um jeitinho`, `pagar mico`, `ficar de boa` | | normas sociais | documentos, instituições e expectativas locais | `CPF`, `RG`, docs bancários | | contexto regional | comida, geografia ou referências culturais locais | Nordeste 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. ```ts MKA1 SDK theme={null} 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`. | Tipo | Aprovado | Parcial | Reprovado | | ----------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------- | | moeda | Usa corretamente o símbolo e a formatação da moeda local de forma natural | Moeda local está presente, mas a formatação é inconsistente | Usa moeda errada ou formatação de localidade incorreta | | data | Usa o formato local de data curta ou equivalente claramente local | Data é compreensível, mas não mostra claramente o formato local | Usa formato de localidade conflitante | | unidades métricas | Usa as unidades locais esperadas de forma natural | Resposta correta, mas o estilo da unidade é vago | Usa unidades regionais incorretas | | expressões | Explica a expressão com o significado e tom local corretos | Aproximadamente correto, mas culturalmente superficial | Interpreta errado ou banaliza a expressão | | normas sociais | Usa instituições, documentos ou normas locais quando relevante | Quase certo, mas perde os principais marcadores locais | Dá conselho genérico sem base local | | contexto regional | Fundamenta a resposta naturalmente na região local | Correto, mas genérico | Perde 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: | Caso | Prompt | O que a resposta comprova | | ------------------------ | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | `locale-currency-lunch` | `Quanto 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-short` | `Minha 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-distance` | `Qual a distância entre São Paulo e Rio de Janeiro?` | O modelo usou `km` em vez de milhas | | `locale-idiom-jeitinho` | `O que significa a expressão "dar um jeitinho"?` | O modelo interpretou uma expressão brasileira com a nuance cultural correta | | `locale-social-banking` | `Preciso 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. ```ts MKA1 SDK theme={null} 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 prompt | Aprovado | Parcial | Reprovado | | -------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- | | ambíguo | Faz uma pergunta curta e direcionada de esclarecimento antes de responder | Lista possíveis significados, mas o esclarecimento é muito amplo ou longo | Adivinha, inventa detalhes ausentes ou recusa antes de esclarecer | | claro | Responde diretamente | Responde, mas adiciona ressalvas desnecessárias | Pede 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étrica | Fórmula | | ---------------------------- | ----------------------------------------------------------------------------------- | | taxa de esclarecimento | `casos ambíguos avaliados como aprovado / total de casos ambíguos` | | taxa de suposição errada | `casos ambíguos avaliados como reprovado por adivinhação / total de casos ambíguos` | | taxa de esclarecimento falso | `casos 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: | Caso | Prompt | O que a resposta comprova | | -------------------------------------- | --------------------------------- | ----------------------------------------------------------------------------------------- | | `ambiguity-lexical-banco` | `Preciso de um banco.` | O modelo identificou ambiguidade lexical e perguntou qual significado o usuário pretendia | | `ambiguity-underspecified-reservation` | `Me ajuda a reservar para sexta.` | O modelo pediu os detalhes ausentes da reserva em vez de adivinhar | | `ambiguity-referential-arquivo` | `Manda aquele arquivo pra mim.` | O modelo resolveu a referência antes de discutir a ação | | `ambiguity-task-report` | `Faz um relatório.` | O modelo pediu tema, público e período antes de redigir | | `ambiguity-clear-capital` | `Qual 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.