Criar um aprimoramento semântico

Antes de criar um aprimoramento

Considere o tipo de contexto que você deseja fornecer:

• Você está definindo um termo ou métrica de negócios?
• Você está explicando como calcular algo?
• Você está fornecendo orientação de qualidade de dados para um campo específico?
• Você está descrevendo um relacionamento entre objetos?
• Você está configurando um filtro ou condição padrão?

Isso ajuda a determinar o escopo certo (espaço de dados, objeto ou campo) e como frasear a instrução de aprimoramento.

Criar um aprimoramento

1. Navegue para o modo de exibição de lista Aprimoramentos semânticos.
2. Clique em Novo aprimoramento semântico.
3. Insira um Nome que identifique claramente o propósito do aprimoramento. Exemplo: "Definição de cliente ativa" ou "Orientação de campo de receita".
4. Selecione o escopo:
   • Objeto: Aplica-se a um Objeto de data lake (DLO) ou Objeto de modelo de dados (DMO) específico. Use para orientação específica do objeto.
   • Campo: Aplica-se a um campo específico em um objeto. Use para interpretação no nível do campo.
5. Se você selecionou o escopo Objeto ou Campo, escolha o objeto ou o campo de destino na lista suspensa.
6. No campo Declaração semântica, escreva seu aprimoramento em linguagem clara e simples. Seja específico sobre quando e como a regra é aplicada. Você pode escrever aprimoramentos de várias frases para regras de negócios complexas. Exemplos:
   • "Clientes ativos são aqueles com status = 'Ativo' e pelo menos um pedido nos últimos 90 dias."
   • "Use amount_usd__c para cálculos de receita. Esse campo representa o tamanho do negócio em dólares americanos."
   • "Ao filtrar email_address, sempre use comparações minúsculas, pois alguns dados legados têm valores de caso mistos."
   • "Oportunidades de alto valor são definidas como amount_usd__c maior que US$ 100.000 e o estágio é igual a 'Proposta' ou 'Negociação'. Para análise regional, use o campo region__c, não o estado do endereço de cobrança. Oportunidades de alto valor históricas anteriores a 2023 usavam um limite diferente de US$ 50.000 devido a ajustes de inflação."
7. (Opcional) Adicione marcas para organizar aprimoramentos relacionados. Use marcas consistentes como "receita", "segmentação de clientes" ou "qualidade de dados" para facilitar a localização e o gerenciamento de aprimoramentos mais tarde. As marcas são apenas para a organização e não afetam os aprimoramentos que o agente recupera.
8. (Opcional) Marque Crítico se esse aprimoramento sempre deve ser considerado pelo agente. Use-o para regras de negócios fundamentais ou restrições de qualidade de dados. Marcar muitos aprimoramentos como Críticos causa um aumento do contexto e desacelera as consultas, portanto, use-o com moderação.
9. (Opcional, mas recomendado) Adicione Resumos de pesquisa para melhorar a recuperação de enriquecimento semântico. Essas são palavras-chave ou frases que você espera que apareçam nas perguntas dos usuários. Por exemplo, se a declaração semântica definir o valor da vida útil do cliente, adicione resumos de pesquisa como "CLV" e "valor da vida útil do cliente".
10. Clique em Salvar.

Escrevendo instruções semânticas efetivas

Uma declaração semântica ensina ao agente como transformar uma pergunta em linguagem simples na consulta certa em relação aos seus dados. Cada instrução efetiva responde a três perguntas:

• Qual é a regra? A instrução que o agente deve seguir.
• Por que existe? O raciocínio por trás disso.
• O que acontece se ele for ignorado? A resposta incorreta que você está tentando evitar.

O "por quê" é mais importante. Uma regra sem raciocínio é seguida literalmente e interrompe qualquer pergunta que você não tenha previsto. Uma regra com raciocínio permite que o agente trate de casos que você nunca anotou. Compare uma instrução fraca que forneça apenas a regra com uma instrução forte que adicione o raciocínio e a consequência:

• Fracasso (apenas regra): "Sempre filtrar Status = 'Ativo'".
• Forte (regra, raciocínio e consequência): "Sempre filtre Status = 'Ativo' em todas as consultas. A tabela armazena registros de clientes ativos e arquivados. Sem esse filtro, os resultados se misturam em clientes arquivados que não são mais relevantes. Isso se aplica mesmo quando o usuário pergunta sobre um cliente nomeado."

Siga estas diretrizes ao escrever uma instrução:

Seja específico

Em vez de "Usar o campo de receita", escreva "Usar amount_usd__c para cálculos de receita porque representa o tamanho do negócio em dólares dos EUA e é preenchido de modo consistente".

Explique o porquê

Não diga apenas uma regra, explique o motivo. "Filtre por status = 'Ativo', pois os clientes inativos não devem aparecer nos relatórios."

Usar exemplos

Ao definir cálculos, mostre a fórmula ou a lógica. "Valor da vida útil do cliente = total_revenue / months_active * average_customer_lifespan_months."

Condições de estado claras

Se uma regra se aplicar apenas a determinados casos, digamos quando. "Para consultas de oportunidade, exclua estágio = 'Fechado e perdido', a menos que solicitado explicitamente."

Evitar jargão

Escreva em linguagem simples que o agente pode analisar. Se você precisar usar termos específicos do domínio, defina-os.

Práticas recomendadas para instruções semânticas

• Uma regra por instrução. Não combine regras não relacionadas. Quando o agente recupera uma instrução, ele captura tudo, de modo que uma instrução que abrange cinco tópicos adiciona quatro regras irrelevantes sempre que uma correspondência ocorre.
• Leve com a regra, então explique o porquê. Informe primeiro a instrução, depois o raciocínio e, em seguida, a consequência do erro.
• Diga o que não fazer. Se dois campos ou valores forem fáceis de confundir, dê um nome explícito ao errado. "Nunca use a data de envio para perguntas de receita" é tão valioso quanto dar um nome ao campo certo.
• Especifique valores que o agente não consegue adivinhar. O agente vê os nomes de campo, não os valores dentro deles. Lista o conjunto válido quando ele for curto e não óbvio.
• Esclareça os formatos e as unidades. Se um número for armazenado como um multiplicador, uma porcentagem ou em centavos, digamos que sim. Caso contrário, "menos de 2x" ou "mais de 50%" será interpretado incorretamente.
• Anexar cada instrução ao destino correto mais estreito. Uma regra sobre um campo pertence a esse campo. Uma regra que abrange vários campos pertence ao objeto. Isso mantém as perguntas não relacionadas limpas e revela a regra certa na hora certa.
• Usar Critical apenas para regras que se aplicam a quase todas as perguntas. Uma declaração crítica sempre é aplicada. As declarações não críticas são capturadas apenas quando a pergunta corresponde aos resumos de pesquisa. Reserve Critical para regras universais e mantenha a contagem pequena.
• Escreva resumos de pesquisa nas palavras que seus usuários realmente digitam. Estas são as frases de acionador que aparecem em uma instrução não crítica. Use frases reais, sinônimos e abreviações, não descrições técnicas.

Tipos de contexto que você pode adicionar

As declarações semânticas podem capturar muitos tipos de contexto de negócios. Os tipos comuns incluem:

Testar seu aprimoramento

Depois de criar um aprimoramento, teste-o fazendo ao agente uma pergunta que deve acioná-lo. Revise a resposta do agente e verifique a seção Exibir mais detalhes para verificar se o aprimoramento foi aplicado corretamente. Se o agente não usou o aprimoramento conforme esperado:

• Certifique-se de que o enriquecimento esteja ativo.
• Verifique se o escopo (espaço de dados, objeto ou campo) corresponde à sua pergunta.
• Revise a instrução semântica para ser mais específica ou adicione marcas relevantes.
• Se o aprimoramento for fundamental, marque-o como Crítico.

Próximas etapas

Consulte Gerenciar aprimoramentos semânticos para aprender a editar, desativar ou excluir aprimoramentos conforme seu modelo de dados evolui.