Поделиться через

Подробный пример фигур и проекций в хранилище знаний

  • Статья

В этой статье представлен подробный пример, который дополняет высокоуровневые концепции и статьи на основе синтаксиса, пройдя по этапу формирования и проекции, необходимые для полного выражения выходных данных набора навыков в хранилище знаний.

Если требования к приложению вызывают несколько навыков и проекций, в этом примере можно лучше понять, как фигуры и проекции пересекаются.

Настройка примеров данных

Примеры документов не включены в коллекцию проекций, но демонстрационные файлы данных обогащения ИИ содержат текст и изображения, которые работают с проекциями, описанными в этом примере.

Создайте контейнер BLOB-объектов в служба хранилища Azure и отправьте все 14 элементов.

В служба хранилища Azure скопируйте строка подключения.

Этот файл можно использовать projections.rest для выполнения примеров в этой статье.

Пример набора навыков

Чтобы понять зависимость между фигурами и проекциями, просмотрите следующий набор навыков, который создает обогащенное содержимое. Этот набор навыков обрабатывает как необработанные изображения, так и текст, создавая выходные данные, на которые будут ссылаться фигуры и проекции.

Обратите внимание на выходные данные навыка (targetNames). Выходные данные, записанные в обогащенное дерево документов, ссылаются на проекции и фигуры (с помощью навыков фигуры).

{
    "name": "projections-demo-ss",
    "description": "Skillset that enriches blob data found in "merged_content". The enrichment granularity is a document.",
    "skills": [
        {
            "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
            "name": "#1",
            "description": null,
            "context": "/document/merged_content",
            "categories": [
                "Person",
                "Quantity",
                "Organization",
                "URL",
                "Email",
                "Location",
                "DateTime"
            ],
            "defaultLanguageCode": "en",
            "minimumPrecision": null,
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                },
                {
                    "name": "languageCode",
                    "source": "/document/language"
                }
            ],
            "outputs": [
                {
                    "name": "persons",
                    "targetName": "people"
                },
                {
                    "name": "organizations",
                    "targetName": "organizations"
                },
                {
                    "name": "locations",
                    "targetName": "locations"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.KeyPhraseExtractionSkill",
            "name": "#2",
            "description": null,
            "context": "/document/merged_content",
            "defaultLanguageCode": "en",
            "maxKeyPhraseCount": null,
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                },
                {
                    "name": "languageCode",
                    "source": "/document/language"
                }
            ],
            "outputs": [
                {
                    "name": "keyPhrases",
                    "targetName": "keyphrases"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
            "name": "#3",
            "description": null,
            "context": "/document",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/merged_content"
                }
            ],
            "outputs": [
                {
                    "name": "languageCode",
                    "targetName": "language"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Text.MergeSkill",
            "name": "#4",
            "description": null,
            "context": "/document",
            "insertPreTag": " ",
            "insertPostTag": " ",
            "inputs": [
                {
                    "name": "text",
                    "source": "/document/content"
                },
                {
                    "name": "itemsToInsert",
                    "source": "/document/normalized_images/*/text"
                },
                {
                    "name": "offsets",
                    "source": "/document/normalized_images/*/contentOffset"
                }
            ],
            "outputs": [
                {
                    "name": "mergedText",
                    "targetName": "merged_content"
                }
            ]
        },
        {
            "@odata.type": "#Microsoft.Skills.Vision.OcrSkill",
            "name": "#5",
            "description": null,
            "context": "/document/normalized_images/*",
            "textExtractionAlgorithm": "printed",
            "lineEnding": "Space",
            "defaultLanguageCode": "en",
            "detectOrientation": true,
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                }
            ],
            "outputs": [
                {
                    "name": "text",
                    "targetName": "text"
                },
                {
                    "name": "layoutText",
                    "targetName": "layoutText"
                }
            ]
        }
    ],
    "cognitiveServices": {
        "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
        "description": "An Azure AI services resource in the same region as Search.",
        "key": "<Azure AI services All-in-ONE KEY>"
    },
    "knowledgeStore": null
}

Пример навыка формирования

Навык фигуры — это программа для работы с существующим обогащенным содержимым вместо создания нового обогащенного содержимого. Добавление фигуры в набор навыков позволяет создать настраиваемую фигуру, которую можно проецировать в таблицу или хранилище BLOB-объектов. Без пользовательской фигуры проекции ограничены ссылкой на один узел (по одной проекции на выход), что не подходит для таблиц. Создание пользовательской фигуры объединяет различные элементы в новое логическое единство, которое может быть спроецировано в виде одной таблицы или фрагментировано и распределено по коллекциям таблиц.

В этом примере пользовательская фигура сочетает метаданные BLOB-объекта и идентифицированные сущности с ключевыми фразами. Пользовательская фигура называется projectionShape, и родительским для нее является /document.

Одна из целей формирования — обеспечить выражение всех узлов обогащения в JSON с правильным форматом, что необходимо для проецирования в хранилище знаний. Это особенно верно, если дерево обогащения содержит узлы, которые не хорошо сформированы JSON (например, если обогащение является родительским для примитива, например строки).

Обратите внимание на два последних узла: KeyPhrases и Entities. Они переносятся в допустимый объект JSON с помощью sourceContext. Это необходимо, так как keyphrases и entities являются обогащениями для примитивов и должны быть преобразованы в допустимые JSON, прежде чем их можно будет спроецировать.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "ShaperForTables",
    "description": null,
    "context": "/document",
    "inputs": [
        {
            "name": "metadata_storage_content_type",
            "source": "/document/metadata_storage_content_type",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_storage_name",
            "source": "/document/metadata_storage_name",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_storage_path",
            "source": "/document/metadata_storage_path",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "metadata_content_type",
            "source": "/document/metadata_content_type",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "keyPhrases",
            "source": null,
            "sourceContext": "/document/merged_content/keyphrases/*",
            "inputs": [
                {
                    "name": "KeyPhrases",
                    "source": "/document/merged_content/keyphrases/*"
                }

            ]
        },
        {
            "name": "Entities",
            "source": null,
            "sourceContext": "/document/merged_content/entities/*",
            "inputs": [
                {
                    "name": "Entities",
                    "source": "/document/merged_content/entities/*/name"
                }

            ]
        }
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "projectionShape"
        }
    ]
}

Добавление фигур в набор навыков

Пример набора навыков, представленный в начале этой статьи, не включал навык фигуры, но навыки фигуры принадлежат в наборе навыков и часто помещаются в конец.

В наборе навыков навык фигуры может выглядеть следующим образом:

{
    "name": "projections-demo-ss",
    "skills": [
        {
            <Shaper skill goes here>
            }
        ],
    "cognitiveServices":  "A key goes here",
    "knowledgeStore": []
}

Проецирование в таблицы

На основе приведенных выше примеров существует известное количество обогащений и фигур данных, на которые можно ссылаться в табличных проекциях. В проекции таблиц ниже три таблицы определяются путем задания свойств tableName, source и generatedKeyName.

Все три таблицы будут связаны через созданные ключи и общий родительский элемент /document/projectionShape.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [
                {
                    "tableName": "tblDocument",
                    "generatedKeyName": "Documentid",
                    "source": "/document/projectionShape"
                },
                {
                    "tableName": "tblKeyPhrases",
                    "generatedKeyName": "KeyPhraseid",
                    "source": "/document/projectionShape/keyPhrases/*"
                },
                {
                    "tableName": "tblEntities",
                    "generatedKeyName": "Entityid",
                    "source": "/document/projectionShape/Entities/*"
                }
            ],
            "objects": [],
            "files": []
        }
    ]
}

Проверка результатов своих действий

Вы можете проверка определения проекции, выполнив следующие действия.

  1. Установите свойство storageConnectionString хранилища знаний для допустимой строки подключения учетной записи хранения общего назначения V2.

  2. Обновите набор навыков, отправив запрос PUT.

  3. После обновления набора навыков запустите индексатор.

Теперь у вас есть рабочая проекция с тремя таблицами. Импорт этих таблиц в Power BI должен привести к обнаружению связей Power BI .

Прежде чем перейти к следующему примеру, повторно рассмотрим аспекты проекции таблицы, чтобы понять механизм фрагментирования и создания отношений данных.

Фрагментирование таблицы на несколько дочерних таблицах

Фрагментирование — это метод разделения целой объединенной фигуры на составные части. В результате получаются отдельные, но связанные таблицы, с которыми можно работать по отдельности.

Например, projectionShape является объединенной фигурой (или узлом обогащения). В определении проекции projectionShape фрагментирована на дополнительные таблицы, что позволяет извлекать части фигуры, keyPhrases и Entities. В Power BI это полезно, так как несколько сущностей и ключевых фраз связаны с каждым документом, и вы получите дополнительные сведения, если можно увидеть сущности и ключевые фразы как классифицированные данные.

Фрагментирование неявным образом создает связь между родительской и дочерней таблицами с помощью generatedKeyName в родительской таблице для создания столбца с тем же именем в дочерней таблице.

Именование связей

Свойства generatedKeyName и referenceKeyName используются, чтобы связать данные между таблицами или даже между типами проекций. Каждая строка дочерней таблицы имеет свойство, указывающее на родительский элемент. Имя столбца или свойства дочернего элемента — referenceKeyName из родительского элемента. referenceKeyName Если этот параметр не указан, служба по умолчанию используется generatedKeyName для родительского элемента.

Power BI использует эти созданные ключи для обнаружения связей в таблицах. Если столбцу в дочерней таблице необходимо присвоить другое имя, установите свойство referenceKeyName в родительской таблице. Одним из примеров является установка generatedKeyName как идентификатора в таблице tblDocument и referenceKeyName в качестве DocumentID. Это приведет к тому, что столбец в таблицах tblEntities и tblKeyPhrases, содержащий идентификатор документа, получит имя DocumentID.

Проектирование документов BLOB-объектов

Проекции объектов — это представления JSON дерева обогащения, которые могут быть источником из любого узла. В сравнении с табличными проекциями проекции объектов проще определить и использовать при проецации целых документов. Проекции объектов ограничены одной проекцией в контейнере и не могут быть срезаны.

Чтобы определить проекцию объекта, используйте objects массив в свойстве проекций.

Источником является путь к узлу дерева обогащения, который является корнем проекции. Хотя это не обязательно, путь к узлу обычно является выходным результатом навыка фигуры. Это связано с тем, что большинство навыков не выводят допустимые объекты JSON самостоятельно, что означает, что требуется некоторая форма формирования. Во многих случаях для создания проекции объекта можно использовать тот же навык Формирователя,что создает табличные проекции. Кроме того, источник может быть установлен на узел с встроенным формированием для предоставления структуры.

Назначение всегда является контейнером BLOB-объектов.

В следующем примере проекты отдельных документов отеля, один документ отеля для каждого большого двоичного объекта в контейнер с именем hotels.

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

Источник — это выходные данные навыка фигуры с именем "objectprojection". Каждый большой двоичный объект будет иметь представление JSON для каждого входного поля.

    {
      "@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"
        }
      ]
    }

Проецирование файла изображения

Проекции файлов всегда являются двоичными, нормализованными изображениями, где нормализация относится к потенциальному размеру и повороту для использования в выполнении набора навыков. Проекции файлов, аналогичные проекциям объектов, создаются как большие двоичные объекты в служба хранилища Azure и содержат изображение.

Чтобы определить проекцию файла, используйте files массив в свойстве проекций.

Источник всегда /document/normalized_images/*. Проекции файлов действуют только в normalized_images коллекции. Ни индексаторы, ни набор навыков не будут проходить через исходный ненормализованный образ.

Назначение всегда является контейнером BLOB-объектов с префиксом папки в кодировке Base64 идентификатора документа. Проекции файлов не могут совместно использовать тот же контейнер, что и проекции объектов и должны быть проецированы в другой контейнер.

В следующем примере все нормализованные изображения, извлеченные из узла документа обогащенного документа, в контейнер с именем myImages.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [ ],
            "objects": [ ],
            "files": [
                {
                    "storageContainer": "myImages",
                    "source": "/document/normalized_images/*"
                }
            ]
        }
    ]
}

Проецирование в несколько типов

При более сложном сценарии может потребоваться спроецировать содержимое в проекции разных типов. Например, проецирование ключевых фраз и сущностей в таблицы, сохранение результатов распознавания текста и текста макета в виде объектов и последующее проецирование образов в виде файлов.

Действия при проецировании в несколько типов:

  1. Создание таблицы со строкой для каждого документа.
  2. Создание таблицы, связанной с таблицей документов, где каждая ключевая фраза идентифицируется как строка в этой таблице.
  3. Создание таблицы, связанной с таблицей документов, где каждая сущность идентифицируется как строка в этой таблице.
  4. Создание проекции объекта с текстом макета для каждого образа.
  5. Создание проекции файла, проецирующей каждый извлеченный образ.
  6. Создание таблицы перекрестных ссылок, содержащей ссылки на таблицу документов, проекцию объекта с текстом макета и проекцию файла.

Данные фигуры для перекрестной проекции

Чтобы получить фигуры, необходимые для этих проекций, начните с добавления нового навыка формирователя, который создает фигурный объект с именем crossProjection.

{
    "@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
    "name": "ShaperForCrossProjection",
    "description": null,
    "context": "/document",
    "inputs": [
        {
            "name": "metadata_storage_name",
            "source": "/document/metadata_storage_name",
            "sourceContext": null,
            "inputs": []
        },
        {
            "name": "keyPhrases",
            "source": null,
            "sourceContext": "/document/merged_content/keyphrases/*",
            "inputs": [
                {
                    "name": "KeyPhrases",
                    "source": "/document/merged_content/keyphrases/*"
                }

            ]
        },
        {
            "name": "entities",
            "source": null,
            "sourceContext": "/document/merged_content/entities/*",
            "inputs": [
                {
                    "name": "Entities",
                    "source": "/document/merged_content/entities/*/name"
                }

            ]
        },
        {
            "name": "images",
            "source": null,
            "sourceContext": "/document/normalized_images/*",
            "inputs": [
                {
                    "name": "image",
                    "source": "/document/normalized_images/*"
                },
                {
                    "name": "layoutText",
                    "source": "/document/normalized_images/*/layoutText"
                },
                {
                    "name": "ocrText",
                    "source": "/document/normalized_images/*/text"
                }
                ]
        }
 
    ],
    "outputs": [
        {
            "name": "output",
            "targetName": "crossProjection"
        }
    ]
}

Определение проекций таблицы, объекта и файла

Из консолидированного объекта crossProjection выполните фрагментирование объекта на несколько таблиц, запишите выходные данные OCR как BLOB-объекты, а затем сохраните образ в виде файлов (также в хранилище BLOB-объектов).

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
            {
            "tables": [
                {
                    "tableName": "crossDocument",
                    "generatedKeyName": "Id",
                    "source": "/document/crossProjection"
                },
                {
                    "tableName": "crossEntities",
                    "generatedKeyName": "EntityId",
                    "source": "/document/crossProjection/entities/*"
                },
                {
                    "tableName": "crossKeyPhrases",
                    "generatedKeyName": "KeyPhraseId",
                    "source": "/document/crossProjection/keyPhrases/*"
                },
                {
                    "tableName": "crossReference",
                    "generatedKeyName": "CrossId",
                    "source": "/document/crossProjection/images/*"
                }
                    
            ],
            "objects": [
                {
                    "storageContainer": "crossobject",
                    "generatedKeyName": "crosslayout",
                    "source": null,
                    "sourceContext": "/document/crossProjection/images/*/layoutText",
                    "inputs": [
                        {
                            "name": "OcrLayoutText",
                            "source": "/document/crossProjection/images/*/layoutText"
                        }
                    ]
                }
            ],
            "files": [
                {
                    "storageContainer": "crossimages",
                    "generatedKeyName": "crossimages",
                    "source": "/document/crossProjection/images/*/image"
                }
            ]
        }
    ]
}

Для каждой проекции объектов требуется имя контейнера. Проекции объектов и проекции файлов не могут совместно использовать контейнер.

Связи между проекциями таблицы, объекта и файла

В этом примере освещается другая функция проекций. Определив несколько типов проекций в одном объекте проекции, существует связь между различными типами (таблицами, объектами, файлами). Это позволяет начать со строки таблицы для документа и найти весь текст OCR для образов в этом документе в проекции объекта.

Если данные не нужны, определите проекции в разных группах проекций. Например, следующий фрагмент приведет к тому, что таблицы будут связаны, но связь между таблицами и проекциями объекта (текстом OCR) будет отсутствовать.

Группы проекций полезны в тех случаях, когда необходимо спроецировать одни и те же данные в разные фигуры для различных нужд. Например, группа проекций для панели мониторинга Power BI и другая группа проекций для записи данных, которые используются для развития модели машинного обучения, заключенной в пользовательский навык.

При построении проекций разных типов сначала создаются проекции файла и объекта, а в таблицы добавляются пути.

"knowledgeStore" : {
    "storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<Acct Name>;AccountKey=<Acct Key>;",
    "projections": [
        {
            "tables": [
                {
                    "tableName": "unrelatedDocument",
                    "generatedKeyName": "Documentid",
                    "source": "/document/projectionShape"
                },
                {
                    "tableName": "unrelatedKeyPhrases",
                    "generatedKeyName": "KeyPhraseid",
                    "source": "/document/projectionShape/keyPhrases"
                }
            ],
            "objects": [
                
            ],
            "files": []
        }, 
        {
            "tables": [],
            "objects": [
                {
                    "storageContainer": "unrelatedocrtext",
                    "source": null,
                    "sourceContext": "/document/normalized_images/*/text",
                    "inputs": [
                        {
                            "name": "ocrText",
                            "source": "/document/normalized_images/*/text"
                        }
                    ]
                },
                {
                    "storageContainer": "unrelatedocrlayout",
                    "source": null,
                    "sourceContext": "/document/normalized_images/*/layoutText",
                    "inputs": [
                        {
                            "name": "ocrLayoutText",
                            "source": "/document/normalized_images/*/layoutText"
                        }
                    ]
                }
            ],
            "files": []
        }
    ]
}

Следующие шаги

В примере в этой статье показаны распространенные шаблоны создания проекций. Теперь, когда у вас есть хорошее понимание концепций, вы лучше оснащены для создания проекций для конкретного сценария.

Настройка кэширования для добавочного обогащения