Определение проекций в хранилище знаний

Статья
09/01/2024

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

В этой статье описаны синтаксис для каждого типа проекции:

Проекции таблиц
Проекции объектов
Проекции файлов

Помните, что проекции определяются в свойстве "knowledgeStore" набора навыков.

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

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

Совет

При разработке проекций включите кэширование обогащения (предварительная версия), чтобы можно было повторно использовать существующие обогащения при редактировании определений проекции. Кэширование обогащения — это предварительная версия функции, поэтому обязательно используйте rest API предварительной версии в запросе индексатора. Без кэширования простые изменения в проекции приведет к полной повторной обработке обогащенного содержимого. Кэширование обогащений позволяет выполнять итерацию по проекциям без каких-либо расходов на обработку набора навыков.

Требования

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

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

Допустимый JSON
Путь к узлу в дереве обогащения (например, "source": "/document/objectprojection")

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

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

Учитывая требования к входным данным источника, зная, как формировать данные , становится практическим требованием для определения проекции, особенно если вы работаете с таблицами.

Определение проекции таблицы

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

Чтобы определить проекцию таблицы, используйте tables массив в свойстве проекций. Проекция таблицы имеет три обязательных свойства:

Свойство	Description
tableName	Определяет имя новой таблицы, созданной в службе хранилища таблиц Azure.
generatedKeyName	Имя столбца для ключа, который однозначно идентифицирует каждую строку. Значение создается системой. Если опустить это свойство, будет автоматически создан столбец, в котором в качестве соглашения об именовании используются имя таблицы и "ключ".
source	Путь к узлу в дереве обогащения. Узел должен быть ссылкой на сложную фигуру, которая определяет, какие столбцы создаются в таблице.

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

Примечание.

Табличные проекции применяются к ограничениям хранения, введенным служба хранилища Azure. Размер сущности не может превышать 1 МБ, а одно свойство не может превышать 64 КБ. Эти ограничения делают таблицы хорошим решением для хранения большого количества небольших сущностей.

Пример одной таблицы

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

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

Столбцы являются производными от источника. Следующая фигура данных, содержащая HotelId, HotelName, Category и Description, приведет к созданию этих столбцов в таблице.

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

Пример нескольких таблиц (срезов)

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

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

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

Шаблон для нескольких таблиц состоит из следующих элементов:

Одна таблица в качестве родительской или основной таблицы
Дополнительные таблицы, содержащие срезы обогащенного содержимого

Например, предположим, что навык фигуры выводит элемент "EnrichedShape", содержащий сведения о отеле, а также обогащенное содержимое, например ключевые фразы, расположения и организации. Основная таблица содержит поля, описывающие отель (идентификатор, имя, описание, адрес, категория). Ключевые фразы получат столбец ключевой фразы. Сущности получат столбцы сущностей.

"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/*" }
    ]
  }
]

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

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

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

Определение проекции объекта

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

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

Свойство	Description
storageContainer	Определяет имя нового контейнера, созданного в служба хранилища Azure.
generatedKeyName	Имя столбца для ключа, который однозначно идентифицирует каждую строку. Значение создается системой. Если опустить это свойство, будет автоматически создан столбец, в котором в качестве соглашения об именовании используются имя таблицы и "ключ".
source	Путь к узлу в дереве обогащения, который является корнем проекции. Узел обычно является ссылкой на сложную фигуру данных, которая определяет структуру 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 и содержат двоичные данные (в отличие от JSON).

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

Свойство	Description
storageContainer	Определяет имя нового контейнера, созданного в служба хранилища Azure.
generatedKeyName	Имя столбца для ключа, который однозначно идентифицирует каждую строку. Значение создается системой. Если опустить это свойство, будет автоматически создан столбец, в котором в качестве соглашения об именовании используются имя таблицы и "ключ".
source	Путь к узлу в дереве обогащения, который является корнем проекции. Для файлов изображений источник всегда `/document/normalized_images/*`находится. Проекции файлов действуют только в `normalized_images` коллекции. Ни индексаторы, ни набор навыков не будут проходить через исходный ненормализованный образ.

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

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

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

Тестовые проекции

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

Установите свойство storageConnectionString хранилища знаний для допустимой строки подключения учетной записи хранения общего назначения V2.
Обновите набор навыков путем выдачи запроса PUT с определением проекции в тексте набора навыков.
Запустите индексатор , чтобы поместить набор навыков в выполнение.
Мониторинг выполнения индексатора для проверки хода выполнения и перехвата ошибок.
Используйте портал Azure для проверки создания объектов в служба хранилища Azure.
Если вы проектируете таблицы, импортируйте их в Power BI для обработки таблиц и визуализации. В большинстве случаев Power BI автоматически обнаруживает связи между таблицами.

Распространенные проблемы

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

Строковые обогащения не формируются в допустимый JSON. Если строки обогащены, например merged_content обогащена ключевыми фразами, обогащенное свойство представляется как дочерний элемент merged_content в дереве обогащения. Представление по умолчанию не является хорошо сформированным JSON. Во время проекции обязательно преобразуйте обогащение в допустимый объект JSON с именем и значением. Использование навыка фигуры или определения встроенных фигур поможет устранить эту проблему.
Упущение /* в конце исходного пути. Если источником проекции является /document/projectionShape/keyPhrases, то массив ключевых фраз проецируется как одиночный объект или строка. Вместо этого укажите /document/projectionShape/keyPhrases/* для пути к источнику, чтобы получить одну строку или объект для каждой из ключевых фраз.
Синтаксические ошибки в пути. Селекторы путей чувствительны к регистру и могут привести к отсутствующим предупреждениям ввода, если вы не используете точный вариант для селектора.

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

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

Подробный пример фигур и проекций

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