Personalizando metadados semânticos

  • Versão de lançamento: Australia
  • Atualizado 17 de abr. de 2026
  • 5 min. de leitura

    • Os metadados semânticos (descrições, rótulos e instruções de uso) controlam como Geração de consultas interpreta perguntas de linguagem natural. Personalize esses metadados para melhorar a precisão da terminologia e dos dados da sua organização.

    As entidades (tabelas) e as dimensões (campos) na camada semântica têm três campos de metadados Geração de consultas usados ao processar uma pergunta:

    Rótulo semântico
    Um nome curto ou alias para a entidade ou dimensão. Funciona como uma palavra-chave de pesquisa que ajuda a Pesquisa com IA a identificar a tabela ou o campo correto quando a pergunta de um usuário não corresponde ao rótulo de campo padrão.
    Descrição semântica
    Uma descrição em linguagem natural do que a entidade ou dimensão representa em termos de negócios. Fornece contexto que ajuda o sistema a distinguir tabelas ou campos semelhantes.
    Instruções de uso de semântica
    Instruções injetadas diretamente no prompt do LLM quando a entidade ou dimensão é selecionada. Ensina o sistema como consultar os dados, por exemplo, quais operadores usar, como manipular abreviações ou como expandir valores hierárquicos.

    Quando personalizar

    Os metadados são gerados automaticamente e funcionam bem em seu estado de linha de base. Personalize-o somente quando observar problemas consistentes e repetíveis:

    • O sistema seleciona a tabela errada ou não consegue encontrar uma. Edite descrições e rótulos
    • O campo errado foi selecionado ou um campo está ausente. Edite descrições e rótulos
    • Sua organização usa terminologia diferente dos rótulos gerados automaticamente: Edite rótulos
    • A tabela ou o campo direito está selecionado, mas a consulta foi construída incorretamente. Edite as instruções de uso
    Nota:
    Existem milhares de dimensões. Não tente revisar todos eles. Foco nos campos que aparecem em consultas com falha.

    Dois métodos para personalizar metadados

    Há dois métodos disponíveis. A edição das tabelas de configuração é considerada a abordagem padrão.

    Tabela 1. Métodos de personalização de metadados
    Método Tabelas Quando usar
    Edite registros nas tabelas Configuração da tabela semântica e Configuração da coluna semântica Configuração da tabela semântica [sn_query_gen_table_config] e Configuração de coluna semântica [sn_query_gen_column_config] Conjunto de atualizações compatível. As personalizações podem ser incluídas em conjuntos de atualizações e transferidas entre instâncias. Substitui valores definidos nas tabelas Entidade e Dimensão. Suporta descrições de entidade e dimensão e instruções de uso de dimensão. Não é compatível com rótulos de entidade ou instruções de uso.
    Edite registros nas tabelas Entidade e Dimensão Entidade [sn_query_gen_entity] e Dimensão [sn_query_gen_dimension] Mais simples. Adequado para testes em uma única instância. Essas personalizações não podem ser transferidas entre instâncias. No entanto, este é o único método para mudar rótulos de entidade e instruções de uso no nível de entidade. Pode ser substituído por uma atualização da tabela a partir de um upgrade.
    Nota:
    Ambos os métodos exigem a função sn_query_gen.admin ou superior.

    Escrevendo descrições efetivas

    Siga estas diretrizes ao escrever descrições semânticas e rótulos:

    • Mantenha descrições de 1 a 2 frases focadas em como os usuários se referem a esses dados
    • Inclua sinônimos e abreviações comuns que seus usuários diriam
    • Evite parágrafos completos. Descrições concisas correspondem melhor do que as detalhadas

    Escrever instruções de uso eficazes

    Siga estas diretrizes ao escrever instruções de uso semântico:

    • Seja específico e estruturado. Incluir regras, exemplos e casos de borda
    • Use etapas numeradas ou seções rotuladas se a lógica for complexa
    • Inclua exemplos de perguntas do usuário e como a consulta deve ser
    • Para campos de texto livre, especifique a estratégia de correspondência (CONTÉM, correspondência exata) e as regras de expansão
    • Mantenha as instruções focadas nas necessidades de uma entidade ou campo

    Instruções de uso versus Segmentos

    As instruções de uso ensinam o LLM a consultar um campo dinamicamente, permitindo que o LLM lide com muitos cenários com base em suas regras. Valores de filtro específicos de código fixo de segmentos. Para campos como local de texto livre, as instruções de uso são a abordagem correta porque você não pode predefinir todas as consultas de local possíveis. Os segmentos são melhores para a terminologia de negócios fixa, como "Sev1": Prioridade 1.

    Descrição semântica

    Para uma entidade de incidente, em vez de usar apenas "Tabela de incidentes", use uma descrição como "Incidentes DE TI, indisponibilidades, interrupções de serviço e tíquetes de suporte de TI" para incluir a terminologia que os usuários realmente dizem.

    Convenções de dados nas instruções de uso

    Para um campo Estado que armazena abreviações:

    "Values in this field may be full state names or two-letter abbreviations (for example, 'California' or 'CA'). Always query for both forms. For country names, also include common aliases (for example, 'United Kingdom' OR 'UK')."

    Lógica de consulta complexa nas instruções de uso

    Estas instruções de uso são para um campo Local aproximado de texto livre com expansão hierárquica e manipulação de sinônimos:

    Campo: Local aproximado - Instrução de uso
    O campo Local aproximado é uma cadeia de caracteres de texto livre não normalizada. Todas as consultas devem usar diferenciação entre maiúsculas e minúsculas, CONTÉM correspondência e lida com expansão hierárquica.
    Lógica de consulta principal
    1. Identifique a entidade geográfica (bairro, cidade, estado, país, região, ou continente).
    2. Expanda entidades mais amplas em listas explícitas de subentidades antes de consultar.
    3. Use a lógica OR para todos os termos e sinônimos expandidos.
    Regras de expansão
    • Continentes: Expanda para uma lista de todos os principais países desse continente.
    • Regiões: Expanda para estados ou países relevantes (por exemplo, "Costa do Atlântico" -> NC, VA, FL etc.).
    • Estados/províncias: Inclua nomes completos e abreviações padrão (por exemplo, "Carolina do Norte" OU "NC").
    • Países: Inclua aliases comuns (por exemplo, "Reino Unido" OU "Reino Unido").
    Padrão de implementação
    1. Extrair intenção geográfica.
    2. Nível de entidade de classificação.
    3. Expanda para baixo (Continente > País) ou inclua sinônimos (Estado > Abreviação).
    4. Crie uma única cadeia de caracteres de consulta usando filtros de CONTÉM baseados EM OR.

    Observe o padrão: A instrução define regras e exemplos, e o LLM pode lidar com muitas consultas relacionadas dinamicamente com base nas regras fornecidas. Você ensina a lógica uma vez e o modelo a aplica a qualquer entrada.

    Exemplos de perguntas do usuário convertidas em consultas
    • Usuário: "Mostre-me coisas no Japão" → Consulta: O local CONTÉM "Japão"

    • Usuário: "Mostre-me coisas em países asiáticos" → Decomposição: Ásia -> [Japão, China, Indonésia...] → Consulta: O local CONTÉM "Japão" OU o local CONTÉM "China" OU o local CONTÉM "Indonésia"...

    • Usuário: "Mostre-me coisas na Carolina do Norte" → Consulta: O local CONTÉM "Carolina do Norte" OU o local CONTÉM "nc"
    • Usuário: "Mostre-me tudo na Europa" → Decomposição: Europa > [Reino Unido, Espanha, França, Alemanha...] → Consulta: O local CONTÉM "Reino Unido" OU o local CONTÉM "Reino Unido" OU o local CONTÉM "Espanha" OU o local CONTÉM "França"...