Создайте компетенции для поисковой системы ИИ Azure

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

В этой статье объясняется, как создать набор навыков с помощью REST API, но те же понятия и шаги применяются к другим языкам программирования.

Ниже указаны правила определения набора навыков:

• Должен иметь уникальное имя в коллекции наборов навыков. Набор навыков — это ресурс верхнего уровня, который может использоваться любым индексатором.
• Должен иметь по крайней мере один навык. Три–пять навыков являются типичными. Максимальное значение — 30.
• Набор навыков может повторять навыки одного типа. Например, набор навыков может включать несколько навыков Shaper.
• Набор функций поддерживает последовательные операции, циклические и разветвляющиеся операции.

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

Добавление определения набора навыков

Создание набора навыков добавляет его в службу поиска. Обновление набора навыков полностью перезаписывает существующий набор навыков с содержимым полезных данных запроса. Рекомендуется получить определение набора навыков с помощью GET, изменить его, а затем обновить с помощью PUT.

Начните с базовой структуры. В REST API создания набора навыков текст запроса создается в ФОРМАТЕ JSON и содержит следующие разделы:

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"A Microsoft Foundry resource in the same region as Azure AI Search",
      "key":"<Your-Azure-AI-Foundry-Resource-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

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

• skills массив, неупорядоченная коллекция навыков. Навыки либо изолированы, либо связаны друг с другом через связи ввода-вывода, где выходные данные одного преобразования становятся входными. Навыки могут быть служебными (например, разделение текста), трансформационными (на основе ИИ из Azure OpenAI или Foundry Tools) или пользовательскими навыками, которые вы предоставляете. Пример массива навыков представлен в следующем разделе.

• cognitiveServices используется для оплачиваемых навыков, которые вызывают API средств Foundry. Удалите этот раздел, если вы не используете навыки, по которым можно выставлять счета, или пользовательский поиск сущностей. Если это так, подключите ресурс Foundry.

• knowledgeStore (необязательно) указывает учетную запись службы хранилища Azure и параметры для проецирования набора навыков в таблицы, BLOB-объекты и файлы в службе хранилища Azure. Удалите этот раздел, если он вам не нужен. в противном случае укажите хранилище знаний.

• encryptionKey(необязательно) указывает на Azure Key Vault и ключи, управляемые клиентом, используемые для шифрования конфиденциального содержимого (описания, строки подключения, ключи) в определении набора навыков. Удалите это свойство, если вы не используете шифрование, управляемое клиентом.

Добавление навыков

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

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

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

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

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

Настройка контекста навыка

Каждый навык имеет свойство контекста, определяющее уровень, на котором выполняются операции. Если свойство context не задано явно, по умолчанию используется "/document", где контекстом является весь документ (навык вызывается один раз для каждого документа).

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

Свойство context обычно устанавливается на одно из следующих значений:

Контекст также определяет, где выходные данные создаются в дереве обогащения. Например, навык распознавания сущностей возвращает свойство с именем organizations, записанное как orgs. Если контекст "/document", то узел organizations добавляется в качестве дочернего элемента "/document". Если вы хотите ссылаться на этот узел в последующих навыках, путь — это "/document/orgs".

Определение входных данных

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

Справочная документация по навыкам для каждого навыка описывает входные данные, которые он может использовать. Каждый вход имеет name, который идентифицирует конкретный вход, и source, который указывает расположение данных в обогащенном документе. Ниже приведен пример навыка распознавания сущностей:

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

• Навыки могут иметь несколько входных данных. Это конкретные входные данные для name. Для распознавания сущностей определенные входные данные — текст и языковой код.

• Свойство source указывает, какое поле или строка предоставляет обрабатываемое содержимое. Для навыков на основе текста источник — это поле в документе или строке, предоставляющей текст. Для навыков на основе изображений входные данные предоставляются узлом, нормализующим изображения.

  Пример источника	Description
  source: /document	Для табличного набора данных документ соответствует строке.
  source: /document/content	Для BLOB-объектов источником обычно является свойство содержимого BLOB.
  source: /document/some-named-field	Для навыков на основе текста, таких как распознавание сущностей или извлечение ключевых фраз, источник должен быть полем, которое содержит достаточно текста для анализа, например описание или сводку.
  source: /document/normalized_images/*	Для содержимого изображения источник — это изображение, нормализуемое во время взлома документа.

Если навык выполняет итерацию по массиву, контекст и источник входных данных должны включать /* в правильных позициях. Дополнительные сведения о полном синтаксисе см. в разделе Контекст навыка и язык заметок ввода.

Определение выходных данных

Каждый навык предназначен для генерации определённых типов выходных данных, на которые ссылаются по имени в наборе навыков. Выходные данные навыка имеют name и необязательный targetNameатрибут.

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

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

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

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

В некоторых ситуациях требуется ссылаться на каждый элемент массива отдельно. К примеру, предположим, вы хотите отдельно передать каждый элемент"/document/orgs" в другое умение. Для этого добавьте звездочку в путь: "/document/orgs/*"

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

Добавление настраиваемого навыка

В этом разделе приведен пример пользовательского навыка. URI указывает на функцию Azure, которая, в свою очередь, вызывает предоставленную вами модель или преобразование. Дополнительные сведения см. в статье «Добавьте пользовательский навык в конвейер обогащения поиска ИИ Azure».

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

Выходные данные, такие как описание компании в этом примере, создаются для каждой организации, которая идентифицируется. При обращении к узлу на нижнем шаге (например, в извлечении ключевых фраз) вы будете использовать путь "/document/orgs/*/companyDescription" для этого.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

Отправка выходных данных в место назначения

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

• Чтобы отправить выходные данные в какое-либо поле в индексе поиска, создайте сопоставление поля выходных данных в индексаторе.

• Чтобы отправить выходные данные в хранилище знаний, создайте проекцию.

• Чтобы отправить выходные данные в подчиненный навык, ссылайтесь на эти данные по имени узла, например, "/document/organization", в свойстве исходного ввода подчиненного навыка. Примеры см. в статье "Ссылка на заметку ".

Советы по созданию первого набора навыков

• Попробуйте мастер импорта данных.

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

  После запуска мастера можно открыть каждый объект в портале Azure, чтобы просмотреть его определение JSON.

• Попробуйте Сеансы отладки для вызова комплекта навыков для целевого документа и изучения обогащенного документа, созданного этим комплектом навыков. Вы можете просматривать и изменять входные и выходные параметры и значения. Это руководство — хорошее место для начала: Руководство: отладка набора навыков с использованием сеансов отладки.

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

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