Definir projeções em um repositório de conhecimento

  • Artigo

As projeções são o componente de uma definição de repositório de conhecimento que determina onde o conteúdo enriquecido com IA é armazenado no Armazenamento do Azure. As projeções determinam o tipo, a quantidade e a composição das estruturas de dados que contêm o conteúdo.

Neste artigo, aprenda a sintaxe para cada tipo de projeção:

Lembre-se de que as projeções são definidas na propriedade "knowledgeStore" de um conjunto de habilidades.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
      {
        "tables": [ ],
        "objects": [ ],
        "files": [ ]
      }
    ]
}

Se você precisar de mais contexto sobre assunto antes de iniciar, examine esta lista de verificações para dicas e fluxos de trabalho.

Dica

Ao desenvolver projeções, habilite o cache de enriquecimento (versão prévia) para que você possa reutilizar os enriquecimentos existentes ao editar as definições de projeção. O cache de enriquecimento é um recurso de visualização, portanto, certifique-se de usar a API REST de visualização (api-version=2020-06-30-preview ou posterior) na solicitação do indexador. Sem cache, edições simples para uma projeção resultarão em um reprocessamento completo de conteúdo enriquecido. Ao armazenar os enriquecimentos em cache, você pode iterar sobre projeções sem incorrer em encargos pelo processamento do conjunto de habilidades.

Requisitos

Todas as projeções têm propriedades de origem e destino. A fonte é sempre o conteúdo interno de uma árvore de enriquecimento criada durante a execução do conjunto de habilidades. O destino é o nome e o tipo de um objeto externo criado e preenchido no Armazenamento do Azure.

Exceto para projeções de arquivo, que aceitam apenas imagens binárias, a origem deve ser:

  • JSON válido
  • Um caminho para um nó na árvore de enriquecimento (por exemplo, "source": "/document/objectprojection")

Embora um nó possa ser resolvido para um único campo, uma representação mais comum é uma referência a uma forma complexa. Formas complexas são criadas por meio de uma metodologia de modelagem, seja uma habilidade de Shaper ou uma definição de modelagem embutida, mas é, geralmente, uma habilidade de Shaper. Os campos ou elementos da forma determinam os campos em contêineres e tabelas.

As habilidades de Shaper são favorecidas porque geram JSON, onde a maioria das habilidades não produz JSON válido por conta própria. Em muitos casos, a mesma forma de dados criada por uma habilidade de Shaper pode ser usada igualmente por projeções de tabela e objeto.

Dados os requisitos de entrada de origem, saber como moldar dados se torna um requisito prático para a definição de projeção, especialmente se você estiver trabalhando com tabelas.

Definir uma projeção de tabela

As projeções de tabela são recomendadas para cenários que chamam a exploração de dados, como análise com o Power BI ou cargas de trabalho que consomem quadros de dados. A seção de tabelas de uma matriz de projeções é uma lista de tabelas que você quer projetar.

Para definir uma projeção de tabela, use a matriz tables na propriedade das projeções. Uma projeção de tabela tem três propriedades necessárias:

Propriedade Descrição
tableName Determina o nome de uma nova tabela criada no Armazenamento de Tabelas do Azure.
generatedKeyName O nome da coluna para a chave que identifica exclusivamente cada linha. O valor é gerado pelo sistema. Se você omitir essa propriedade, uma coluna será criada automaticamente, que usa o nome da tabela e a "chave" como convenção de nomenclatura.
source Um caminho para um nó em uma árvore de enriquecimento. O nó deve ser uma referência a uma forma complexa que determina quais colunas são criadas na tabela.

Nas projeções de tabela, a “origem” é geralmente a saída de uma habilidade de Shaper que define a forma da tabela. Tabelas têm linhas e colunas, a formatação é o mecanismo pelo qual as linhas e colunas são especificadas. Você pode usar uma habilidade de shaper ou formas embutidas. A habilidade de Shaper produz um JSON válido, mas a origem pode ser a saída de qualquer habilidade, se for um JSON válido.

Observação

As projeções de tabela estão sujeitas aos limites de armazenamento impostos pelo Armazenamento do Azure. O tamanho da entidade não pode exceder 1 MB, e uma única propriedade não pode ser maior que 64 KB. Essas restrições tornam as tabelas uma boa solução para armazenar um grande número de pequenas entidades.

Exemplo de tabela única

O esquema de uma tabela é especificado parcialmente pela projeção (nome e chave da tabela) e também pela fonte que fornece a forma da tabela (colunas). Este exemplo mostra apenas uma tabela para que você possa se concentrar nos detalhes da definição.

"projections" : [
  {
    "tables": [
      { "tableName": "Hotels", "generatedKeyName": "HotelId", "source": "/document/tableprojection" }
    ]
  }
]

As colunas são derivadas da "origem". A forma de dados a seguir que contém HotelId, HotelName, Category e Description resultará na criação dessas colunas na tabela.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "#3",
    "description": null,
    "context": "/document",
    "inputs": [
    {
        "name": "HotelId",
        "source": "/document/HotelId"
    },
    {
        "name": "HotelName",
        "source": "/document/HotelName"
    },
    {
        "name": "Category",
        "source": "/document/Category"
    },
    {
        "name": "Description",
        "source": "/document/Description"
    },
    ],
    "outputs": [
    {
        "name": "output",
        "targetName": "tableprojection"
    }
    ]
}

Exemplo de várias tabelas (divisão)

Um padrão comum para projeções de tabela é ter várias tabelas relacionadas, em que as colunas partitionKey e rowKey geradas pelo sistema são criadas para dar suporte a relações entre tabelas para todas as tabelas no mesmo grupo de projeção.

A criação de várias tabelas poderá ser útil se você quiser ter controle sobre como os dados relacionados são agregados. Se o conteúdo enriquecido tiver componentes não relacionados ou independentes – por exemplo, as palavras-chave extraídas de um documento poderão não estar relacionadas às entidades reconhecidas no mesmo documento – você poderá dividir esses campos em tabelas adjacentes.

Quando você está projetando em várias tabelas, a forma completa é projetada em cada tabela, a menos que um nó filho seja a origem de outra tabela dentro do mesmo grupo. Adicionar uma projeção com um caminho de origem que seja filho de uma projeção existente fará com que o nó filho seja dividido do nó pai e projetado para a nova tabela relacionada. Essa técnica permite definir um único nó em uma habilidade de shaper que pode ser a origem para todas as suas projeções.

O padrão para várias tabelas consiste em:

  • Uma tabela como a tabela pai ou principal
  • Tabelas adicionais para conter fragmentos do conteúdo enriquecido

Por exemplo, suponha que uma habilidade de Shaper produza um "EnrichedShape" que contém informações do hotel, além de conteúdo enriquecido, como frases-chave, locais e organizações. A tabela principal incluiria campos que descrevem o hotel (ID, nome, descrição, endereço, categoria). As frases-chave obteriam a coluna de frase-chave. As entidades obteriam as colunas de entidade.

"projections" : [
  {
    "tables": [
    { "tableName": "MainTable", "generatedKeyName": "HotelId", "source": "/document/EnrichedShape" },
    { "tableName": "KeyPhrases", "generatedKeyName": "KeyPhraseId", "source": "/document/EnrichedShape/*/KeyPhrases/*" },
    { "tableName": "Entities", "generatedKeyName": "EntityId", "source": "/document/EnrichedShape/*/Entities/*" }
    ]
  }
]

Relações nomeadas

As propriedades generatedKeyName e referenceKeyName são usadas para relacionar dados entre tabelas ou até mesmo entre tipos de projeção. Cada linha na tabela filho tem uma propriedade apontando de volta para o pai. O nome da coluna ou propriedade no filho é o referenceKeyName do pai. Quando o não é fornecido, o serviço o padroniza para o referenceKeyNamegeneratedKeyName do pai.

O Power BI conta com essas chaves geradas para descobrir relações dentro das tabelas. Se você precisar da coluna na tabela filho nomeada de modo diferente, defina a propriedade referenceKeyName na tabela pai. Um exemplo seria definir o generatedKeyName como a ID na tabela tblDocument e referenceKeyName como DocumentID. Isso resultaria na coluna nas tabelas tblEntities e tblKeyPhrases que contêm a ID do documento que está sendo nomeada como DocumentID.

Definir uma projeção de objeto

As projeções de objeto são representações de JSON da árvore de enriquecimento que podem ser originadas de qualquer nó. Em comparação com projeções de tabela, as projeções de objeto são mais simples de definir e são usadas ao projetar documentos inteiros. As projeções de objeto são limitadas a uma única projeção em um contêiner e não podem ser fatiadas.

Para definir uma projeção de objeto, use a matriz objects na propriedade das projeções. Uma projeção de objeto tem três propriedades necessárias:

Propriedade Descrição
storageContainer Determina o nome de um novo contêiner criado no Armazenamento do Azure.
generatedKeyName O nome da coluna para a chave que identifica exclusivamente cada linha. O valor é gerado pelo sistema. Se você omitir essa propriedade, uma coluna será criada automaticamente, que usa o nome da tabela e a "chave" como convenção de nomenclatura.
source Um caminho para um nó em uma árvore de enriquecimento que é a raiz da projeção. O nó é geralmente uma referência a uma forma de dados complexa que determina a estrutura do blob.

O exemplo a seguir projeta documentos individuais do hotel, um documento do hotel por blob, em um contêiner chamado hotels.

"knowledgeStore": {
  "storageConnectionString": "an Azure storage connection string",
  "projections" : [
    {
      "tables": [ ]
    },
    {
      "objects": [
        {
        "storageContainer": "hotels",
        "source": "/document/objectprojection",
        }
      ]
    },
    {
        "files": [ ]
    }
  ]
}

A origem é a saída de uma habilidade Shaper, chamada "objectprojection". Cada blob terá uma representação JSON de cada entrada de campo.

    {
      "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
      "name": "#3",
      "description": null,
      "context": "/document",
      "inputs": [
        {
          "name": "HotelId",
          "source": "/document/HotelId"
        },
        {
          "name": "HotelName",
          "source": "/document/HotelName"
        },
        {
          "name": "Category",
          "source": "/document/Category"
        },
        {
          "name": "keyPhrases",
          "source": "/document/HotelId/keyphrases/*"
        },
      ],
      "outputs": [
        {
          "name": "output",
          "targetName": "objectprojection"
        }
      ]
    }

Definir uma projeção de arquivo

As projeções de arquivo são sempre imagens binárias e normalizadas, nas quais a normalização refere-se ao redimensionamento e à rotação potenciais para uso na execução do conjunto de habilidades. As projeções de arquivo, semelhantes às projeções de objeto, são criadas como blobs no Armazenamento do Azure, e contêm dados binários (ao contrário do JSON).

Para definir uma projeção de arquivo, use a matriz files na propriedade das projeções. Uma projeção de arquivos tem três propriedades necessárias:

Propriedade Descrição
storageContainer Determina o nome de um novo contêiner criado no Armazenamento do Azure.
generatedKeyName O nome da coluna para a chave que identifica exclusivamente cada linha. O valor é gerado pelo sistema. Se você omitir essa propriedade, uma coluna será criada automaticamente, que usa o nome da tabela e a "chave" como convenção de nomenclatura.
source Um caminho para um nó em uma árvore de enriquecimento que é a raiz da projeção. Para arquivos de imagens, a origem é sempre /document/normalized_images/*. As projeções de arquivo somente agem na coleção normalized_images. Nenhum dos indexadores nem de um conjunto de habilidades passará pela imagem original não normalizada.

O destino é sempre um contêiner de blob, com um prefixo de pasta do valor codificado em Base64 da ID do documento. Se houver várias imagens, elas serão colocadas juntas na mesma pasta. As projeções de arquivo não podem compartilhar o mesmo contêiner que as projeções de objeto e precisam ser projetadas em um contêiner diferente.

O exemplo a seguir projeta todas as imagens normalizadas extraídas do nó do documento de um documento enriquecido, em um contêiner chamado myImages.

"projections": [
    {
        "tables": [ ],
        "objects": [ ],
        "files": [
            {
                "storageContainer": "myImages",
                "source": "/document/normalized_images/*"
            }
        ]
    }
]

Projeções de teste

Você pode processar projeções seguindo estas etapas:

  1. Defina a propriedade storageConnectionString do repositório de conhecimento como uma cadeia de conexão de conta de armazenamento de uso geral v2 válida.

  2. Atualize o conjunto de habilidades emitindo uma solicitação PUT com a definição de projeção no corpo do conjunto de habilidades.

  3. Execute o indexador para colocar o conjunto de habilidades em execução.

  4. Monitore a execução do indexador para verificar o progresso e detectar erros.

  5. Use o portal do Azure para verificar a criação do objeto no Armazenamento do Microsoft Azure.

  6. Se você estiver projetando tabelas, importe-as para o Power BI para manipulação e visualização de tabelas. Na maioria dos casos, o Power BI irá descobrir automaticamente as relações entre tabelas.

Problemas comuns

Omitir qualquer uma das etapas a seguir pode gerar resultados inesperados. Verifique as condições a seguir se a saída não parecer correta.

  • Os enriquecimentos de cadeia de caracteres não são moldados em JSON válido. Quando as cadeias de caracteres são aprimoradas, por exemplo, merged_content enriquecidas com frases-chave, a propriedade enriquecida é representada como um filho de merged_content dentro da árvore de enriquecimento. A representação padrão não é JSON bem formada. No momento da projeção, transforme o enriquecimento em um objeto JSON válido com um nome e um valor. Usar uma habilidade do Shaper ou definir formas embutidas ajudará a resolver esse problema.

  • Omitir /* no final de um caminho de origem. Se a origem de uma projeção for /document/projectionShape/keyPhrases, a matriz de frases-chave será projetada como um único objeto/linha. Em vez disso, defina o caminho de origem como /document/projectionShape/keyPhrases/* para gerar uma única linha ou objeto para cada uma das frases-chave.

  • Erros de sintaxe de caminho. Os seletores de caminho diferenciam maiúsculas de minúsculas e podem levar a avisos de entrada ausentes se você não usar o caso exato para o seletor.

Próximas etapas

A próxima etapa o orienta na formatação e na projeção da saída de um conjunto de habilidade enriquecido. Se seu conjunto de habilidades for complexo, o artigo a seguir fornecerá exemplos de formas e projeções.

Exemplo detalhado de formas e projeções