Укажите путь к обогащенным узлам, используя контекст и свойства источника в наборе навыков поиска AI Azure

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

В этой статье используются примеры для иллюстрации различных сценариев. Полный синтаксис см. в разделе "Контекст навыка" и "Язык заметок ввода".

Базовые понятия

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

Пути для различных сценариев

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

Пример на снимке экрана иллюстрирует путь к элементу в коллекции Azure Cosmos DB.

• context путь /document/HotelId потому, что коллекция разделена на документы по полю /HotelId.

• source путь является /document/Description, потому что это навык перевода, и поле, которое необходимо перевести, является полем Description в каждом документе.

Все пути начинаются с /document. Обогащенный документ создается на этапе "взлома документов" выполнения индексатора, когда индексатор открывает документ или считывает строку из источника данных. Изначально единственным узлом в обогащенном документе является корневой узел (/document), и это узел, из которого происходят все другие обогащения.

В следующем списке приведено несколько распространенных примеров:

• /document является корневым узлом и указывает на объект BLOB в службе хранилища Azure или строку в таблице SQL.
• /document/{key} — это синтаксис документа или элемента в коллекции Azure Cosmos DB, где {key} находится фактический ключ, например /document/HotelId в предыдущем примере.
• /document/content указывает свойство "content" JSON-объекта.
• /document/{field} — это синтаксис операции, выполняемой в определенном поле, например перевод /document/Description поля, показанный в предыдущем примере.
• /document/pages/* или /document/sentences/* становятся контекстом, если вы разбиваете большой документ на небольшие блоки для обработки. Если "контекст" имеет значение /document/pages/*, навык выполняется один раз на каждой странице в документе. Поскольку может быть несколько страниц или предложений, можно добавить /* в конец, чтобы учесть всё.
• /document/normalized_images/* создается во время взлома документа, если документ содержит изображения. Все пути к изображениям начинаются с normalized_images. Так как в документе часто встроено несколько изображений, добавьте /*.

Примеры в оставшейся части этой статьи основаны на поле "содержимое", созданном автоматически индексаторами BLOB-объектов Azure в рамках этапа взлома документов. При обращении к документам из контейнера Blob используйте такой формат, как "/document/content", где поле "content" является частью документа.

Пример 1. Ссылка на простую аннотацию

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

Так как по умолчанию для context задано значение "/document", в качестве ссылки на список пользователей можно указать "/document/people". В этом случае "/document/people" представляет собой аннотацию, которую теперь можно сопоставить с полем в индексе или использовать в другом навыке из того же набора навыков.

  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "categories": [ "Person"],
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "persons",
        "targetName": "people"
      }
    ]
  }

Пример 2. Ссылка на массив в документе

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

Чтобы вызвать нужное количество итераций, задайте для параметра context значение "/document/people/*", где символ звездочки ("*") представляет все узлы в обогащенном документе в качестве потомков "/document/people". Хотя этот навык определен только один раз в массиве навыков, он вызывается для каждого элемента в документе до тех пор, пока все члены не будут обработаны.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the last name from a full name",
    "uri": "http://names.azurewebsites.net/api/GetLastName",
    "context" : "/document/people/*",
    "defaultLanguageCode": "en",
    "inputs": [
      {
        "name": "fullname",
        "source": "/document/people/*"
      }
    ],
    "outputs": [
      {
        "name": "lastname",
        "targetName": "last"
      }
    ]
  }

Если аннотации представляют собой массивы или коллекции строк, может потребоваться выполнить операции над определенными элементами, а не над массивом в целом. В предыдущем примере создается аннотация, называемая "last", для каждого узла, представленного контекстом. Если потребуется добавить ссылку на это семейство аннотаций, используйте синтаксис "/document/people/*/last". Если потребуется добавить ссылку на определенную аннотацию, используйте явный индекс: "/document/people/1/last" для ссылки на фамилию первого пользователя, определенного в документе. Обратите внимание, что в этом синтаксисе массивы индексируются начиная с 0.

Пример 3. Ссылка на элементы в массиве

Иногда необходимо сгруппировать все аннотации определенного типа для их передачи определенному навыку. Рассмотрим предполагаемый настраиваемый навык, который определяет наиболее распространенную фамилию среди всех фамилий, извлеченных в примере 2. Чтобы предоставить настраиваемому навыку только фамилии, укажите для параметра context значение "/document", а для входных данных — "/document/people/*/lastname".

Обратите внимание, что кардинальность "/document/people/*/lastname" больше, чем у документа. Может быть 10 узлов с фамилиями, но для этого документа существует только один узел документа. В этом случае система автоматически создаст массив "/document/people/*/lastname" , содержащий все элементы в документе.

  {
    "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
    "description": "Fictitious skill that gets the most common string from an array of strings",
    "uri": "http://names.azurewebsites.net/api/MostCommonString",
    "context" : "/document",
    "inputs": [
      {
        "name": "strings",
        "source": "/document/people/*/lastname"
      }
    ],
    "outputs": [
      {
        "name": "mostcommon",
        "targetName": "common-lastname"
      }
    ]
  }

Советы по устранению неполадок пути аннотации

Если у вас возникли проблемы с указанием входных данных навыка, эти советы могут помочь вам перейти вперед:

• Запустите мастер импорта данных по данным, чтобы просмотреть определения набора навыков и сопоставления полей, создаваемые мастером.

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

См. также

• Контекст навыка и язык заметок ввода
• Как интегрировать пользовательский навык в конвейер обогащения
• Определение набора навыков
• Создание набора навыков (REST)
• How to map enriched fields to an index (Как сопоставить обогащенные поля с индексом)