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

As projeções são o componente de uma definição de armazenamento 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 seu conteúdo.

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

• Projeções de tabelas
• Projeções de objetos
• Projeções de arquivos

Lembre-se de que as projeções são definidas sob a 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 informações antes de começar, revise esta lista de verificação para obter dicas e fluxo de trabalho.

Gorjeta

Ao desenvolver projeções, habilite o cache de enriquecimento (visualização) para que você possa reutilizar enriquecimentos existentes ao editar 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 em uma projeção resultarão em um reprocesso completo de conteúdo enriquecido. Ao armazenar em cache os enriquecimentos, você pode iterar sobre projeções sem incorrer em quaisquer encargos de 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.

Com exceção das projeções de arquivos, que só aceitam imagens binárias, a fonte deve ser:

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

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

As habilidades de Shaper são favorecidas porque produz JSON, onde como 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 Shaper pode ser usada igualmente por projeções de tabela e objeto.

Dados os requisitos de entrada de origem, saber como moldar dados torna-se 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 exigem 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ê deseja projetar.

Para definir uma projeção de tabela, use a tables matriz na propriedade 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 Tabela do Azure.
generatedKeyName	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 "chave" como a convenção de nomenclatura.
origem	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.

Em projeções de tabela, "fonte" é geralmente a saída de uma habilidade Shaper que define a forma da tabela. As tabelas têm linhas e colunas, e a modelagem é o mecanismo pelo qual as linhas e colunas são especificadas. Você pode usar uma habilidade Shaper ou formas embutidas. A habilidade Shaper produz JSON válido, mas a fonte pode ser a saída de qualquer habilidade, se JSON válido.

Nota

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 em parte 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 "fonte". A seguinte forma de dados contendo 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 tabela múltipla (fatiamento)

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

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

Quando você projeta para 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 é filho de uma projeção existente resulta no nó filho sendo cortado para fora do nó pai e projetado na nova tabela ainda relacionada. Esta técnica permite que você defina um único nó em uma habilidade Shaper que pode ser a fonte para todas as suas projeções.

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

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

Por exemplo, suponha que uma habilidade Shaper produza um "EnrichedShape" que contenha 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 frases-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/*" }
    ]
  }
]

Nomeando relações

As generatedKeyName propriedades 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 para o pai. O nome da coluna ou propriedade no filho é o referenceKeyName do pai. Quando o não é fornecido, o serviço assume como padrão o referenceKeyNamegeneratedKeyName do pai.

O Power BI depende dessas chaves geradas para descobrir relações dentro das tabelas. Se você precisar da coluna na tabela filho com nome diferente, defina a referenceKeyName propriedade na tabela pai. Um exemplo seria definir o como ID na tabela tblDocument e o generatedKeyNamereferenceKeyName como DocumentID. Isso resultaria na coluna nas tabelas tblEntities e tblKeyPhrases contendo a ID do documento sendo chamada DocumentID.

Definir uma projeção de objeto

As projeções de objeto são representações JSON da árvore de enriquecimento que podem ser originadas de qualquer nó. Em comparação com projeções de tabela, as projeções de objetos são mais simples de definir e são usadas ao projetar documentos inteiros. As projeções de objetos 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 objects matriz na propriedade projections. 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	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 "chave" como a convenção de nomenclatura.
origem	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 de hotel individuais, um documento de 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 fonte é 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 arquivos são sempre imagens binárias e normalizadas, onde a normalização se refere ao potencial redimensionamento e rotação 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 (em oposição a JSON).

Para definir uma projeção de arquivo, use a files matriz na propriedade projections. 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	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 "chave" como a convenção de nomenclatura.
origem	Um caminho para um nó em uma árvore de enriquecimento que é a raiz da projeção. Para arquivos de imagens, a fonte é sempre /document/normalized_images/*. As projeções de arquivo atuam apenas na normalized_images coleção. Nem indexadores nem um conjunto de habilidades passarão pela imagem original não normalizada.

O destino é sempre um contêiner de blob, com um prefixo de pasta do valor codificado 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 do repositório de conhecimento como uma cadeia de conexão de conta de storageConnectionString armazenamento de uso geral V2 válida.

2. Atualize o conjunto de habilidades emitindo uma solicitação PUT com sua 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 detetar erros.

5. Use o portal do Azure para verificar a criação de objetos no Armazenamento do 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 descobrirá automaticamente as relações entre tabelas.

Problemas comuns

Omitir qualquer uma das etapas a seguir pode resultar em resultados inesperados. Verifique as seguintes condições se a sua saída não estiver correta.

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

• Omissão de 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 para /document/projectionShape/keyPhrases/* produzir 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 à falta de avisos de entrada se você não usar o caso exato para o seletor.

Próximos passos

O próximo passo orienta você através da modelagem e projeção de resultados de um rico conjunto de habilidades. Se o seu conjunto de habilidades for complexo, o artigo a seguir fornece exemplos de formas e projeções.

Exemplo detalhado de formas e projeções