Настройка интегрированной векторизации в поиске ИИ Azure с помощью REST

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

В этой статье описывается комплексный рабочий процесс интегрированной векторизации с помощью REST. Для получения инструкций в портале см. Краткое руководство: векторизация текста и изображений в портале Azure.

Предпосылки

• Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .

• Служба поиска ИИ Azure. Мы рекомендуем уровень "Базовый" или "Выше".

• Поддерживаемый источник данных.

• Поддерживаемая модель внедрения.

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

• Visual Studio Code с REST-клиентом.

Поддерживаемые источники данных

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

Поддерживаемый источник данных	Описание
Хранилище BLOB-объектов Azure	Этот источник данных работает с объектами Blob и таблицами. Необходимо использовать учетную запись стандартной производительности (общего назначения версии 2). Уровни доступа могут быть горячими, прохладными или холодными.
Azure Data Lake Storage (ADLS) 2-го поколения	Это учетная запись хранения Azure с включенным иерархическим пространством имен. Чтобы подтвердить наличие Data Lake Storage, перейдите на вкладку "Свойства " на странице обзора .

Поддерживаемые модели внедрения

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

^{1 Конечная} точка ресурса Azure OpenAI должна иметь настраиваемый поддомен, например https://my-unique-name.openai.azure.com. Если вы создали ресурс на портале Azure, этот поддомен был автоматически создан во время настройки ресурса.

² ресурса Azure OpenAI (с доступом к моделям внедрения), созданным на портале Azure AI Foundry , не поддерживаются. Только ресурсы Azure OpenAI, созданные на портале Azure, совместимы с навыком внедрения Azure OpenAI.

³ Для выставления счетов необходимо присоединить многосервисный ресурс Azure AI к набору навыков в службе поиска Azure AI. Если для создания набора навыков не используется подключение без ключа (предварительная версия), оба ресурса должны находиться в одном регионе.

⁴ Модель многомодального внедрения визуального распознавания ИИ Azure доступна в выборе регионов.

Ролевой доступ

Идентификатор Microsoft Entra можно использовать с назначением ролей или аутентификацией на основе ключей, используя строки подключения с полным доступом. Для подключений поиска ИИ Azure к другим ресурсам рекомендуется назначать роли.

Чтобы настроить доступ на основе ролей для интегрированной векторизации:

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

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

Получите информацию о подключении к ИИ поиску Azure

В этом разделе вы получаете конечную точку и токен Microsoft Entra для вашей службы поиска ИИ Azure. Оба значения необходимы для установления подключений в запросах REST .

1. Войдите на портал Azure и выберите службу поиска ИИ Azure.

2. Чтобы получить конечную точку поиска, скопируйте URL-адрес на странице обзора . Пример конечной точки поиска.https://my-service.search.windows.net

3. Чтобы получить маркер Microsoft Entra, выполните следующую команду в локальной системе. Для выполнения этого шага необходимо завершить краткое руководство: подключение без ключей.

   az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
   

Подготовка данных

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

Подготовка модели внедрения

В этом разделе описана подготовка ресурса ИИ Azure для интегрированной векторизации путем назначения ролей, получения конечной точки и развертывания поддерживаемой модели внедрения.

Установка переменных

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

1. В Visual Studio Code вставьте следующие заполнители в файл .rest или .http.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
   @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
   

2. Замените @baseUrl на конечную точку поиска и @token на токен Microsoft Entra, который вы получили в разделе «Получение информации о подключении для поиска Azure AI».

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

   Источник данных	Переменные	Введите эти сведения
   Azure Blob-хранилище	@storageConnectionString и @blobContainer.	Строка подключения и имя контейнера, созданного в разделе "Подготовка данных".
   ADLS 2-го поколения	@storageConnectionString и @blobContainer.	Строка подключения и имя контейнера, созданного в разделе "Подготовка данных".

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

   Поставщик модели внедрения	Переменные	Введите эти сведения
   Azure OpenAI	@aoaiEndpoint, @aoaiDeploymentName и @aoaiModelName	Конечная точка, имя развертывания и имя модели, полученные в подготовке модели внедрения.
   Визуальное распознавание искусственного интеллекта Azure	@aiMultiServiceEndpoint	Конечная точка, полученная в подготовке модели внедрения.

5. Чтобы проверить переменные, отправьте следующий запрос.

   ### List existing indexes by name
   GET {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   

   Ответ должен отображаться в соседней области. Если у вас есть индексы, они перечислены. В противном случае список пуст. Если http-код имеет значение 200 OK, вы готовы продолжить работу.

Подключение к данным

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

1. Создание источника данных позволяет определить источник данных, предоставляющий сведения о подключении во время индексирования.

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2024-07-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-data-source",
       "type": "azureblob",
       "subtype": null,
       "credentials": {
           "connectionString": "{{storageConnectionString}}"
       },
       "container": {
           "name": "{{blobContainer}}",
           "query": null
       },
       "dataChangeDetectionPolicy": null,
       "dataDeletionDetectionPolicy": null
     }
   

2. Установите type для вашего источника данных: azureblob или adlsgen2.

3. Чтобы создать источник данных, нажмите кнопку "Отправить запрос".

Создание набора навыков

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

Вызовите встроенный навык для разбиения вашего контента на части

Секционирование содержимого на блоки помогает удовлетворить требования модели внедрения и предотвратить потерю данных из-за усечения. Дополнительные сведения о фрагментации см. в разделе "Блоки больших документов" для решений поиска векторов.

Для встроенного фрагментирования данных служба "Поиск ИИ Azure" предлагает навык разделения текста и навык макета документов. Навык разделения текста разбивает текст на предложения или страницы определенной длины, а навык макета документа разбивает содержимое на основе границ абзаца.

1. Используйте Создать набор навыков для определения или создания набора навыков.

   ### Create a skillset
   POST {{baseUrl}}/skillsets?api-version=2024-07-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-skillset",
       "skills": []
     }
   

2. В массиве skills вызовите навык разделения текста или навык макета документов. Вы можете вставить одно из следующих определений.

       "skills": [
        {
          "@odata.type": "#Microsoft.Skills.Text.SplitSkill",
          "name": "my-text-split-skill",
          "textSplitMode": "pages",
          "maximumPageLength": 2000,
          "pageOverlapLength": 500,
          "maximumPagesToTake": 0,
          "unit": "characters",
          "defaultLanguageCode": "en",
          "inputs": [
           {
             "name": "text",
             "source": "/document/text",
             "inputs": []
           }
          ],
          "outputs": [
           {
             "name": "textItems"
           }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill",
          "name": "my-document-layout-skill",
          "context": "/document",
          "outputMode": "oneToMany",
          "markdownHeaderDepth": "h3",
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "markdown_document"
           }
          ]
        }
       ]
   

   Замечание

   Навык макета документов доступен в предварительной общедоступной версии. Если вы хотите вызвать этот навык, используйте API предварительной версии, например 2025-03-01-preview.

Вызов функции встраивания для векторизации блоков

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

1. После встроенного навыка фрагментирования в массиве skills вызовите навык внедрения Azure OpenAI или навык распознавания искусственного интеллекта Azure. Вы можете вставить одно из следующих определений.

        {
          "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
          "resourceUri": "{{aoaiEndpoint}}",
          "deploymentId": "{{aoaiDeploymentName}}",
          "modelName": "{{aoaiModelName}}",
          "dimensions": 1536,
          "inputs": [
            {
              "name": "text",
              "source": "/document/text"
            }
          ],
          "outputs": [
            {
              "name": "embedding"
            }
          ]
        },
        {
          "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill",
          "context": "/document",
          "modelVersion": "2023-04-15", 
          "inputs": [
            {
              "name": "url",
              "source": "/document/metadata_storage_path"
            },
            {
              "name": "queryString",
              "source": "/document/metadata_storage_sas_token"
            }
          ],
          "outputs": [
            {
              "name": "vector"
            }
          ]
        }
   

   Замечание

   Навык распознавания искусственного интеллекта Azure находится в общедоступной предварительной версии. Если вы хотите вызвать этот навык, используйте API предварительной версии, например 2025-03-01-preview.

2. Если вы используете навык встраивания Azure OpenAI, задайте dimensions значением количество встраиваний, созданных вашей моделью встраивания.

3. Если вы используете навык распознавания искусственного интеллекта Azure, подключите ресурс Azure AI с несколькими службами после массива skills . Это вложение предназначено для выставления счетов.

       "skills": [ ... ],
       "cognitiveServices": {
         "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
         "subdomainUrl": "{{aiMultiServiceEndpoint}}"
        }
   

4. Чтобы создать набор навыков, нажмите кнопку "Отправить запрос".

Создание векторного индекса

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

• Имя
• Ключевое поле (строка)
• Одно или несколько векторных полей
• Конфигурация вектора

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

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

1. Используйте create Index для определения схемы векторного индекса.

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-vector-index",
       "fields": [],
       "vectorSearch": []
     }
   

2. Добавьте конфигурацию векторного поиска в vectorSearch раздел.

       "vectorSearch": {
         "algorithms": [
           {
             "name": "hnsw-algorithm",
             "kind": "hnsw",
             "hnswParameters": {
               "m": 4,
               "efConstruction": 400,
               "efSearch": 100,
               "metric": "cosine"
             }
           }
         ],
         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
           }
         ]
       }
   

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

3. В зависимости от вашей модели встраивания обновите vectorSearch.algorithms.metric. Допустимые значения для метрик расстояния: cosine, dotproducteuclideanи hamming.

4. Добавьте поля в fields массивы. Включите ключевое поле для идентификации документов, невекторных полей для содержимого, доступного для чтения человеком, и векторных полей для внедрения.

       "fields": [
         {
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "filterable": true
         },
         {
           "name": "title",
           "type": "Edm.String",
            "searchable": true,
            "filterable": true,
            "sortable": true,
            "retrievable": true
         },
         {
           "name": "titleVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": true,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         },
         {
           "name": "content",
           "type": "Edm.String",
            "searchable": true,
            "retrievable": true
         },
         {
           "name": "contentVector",
           "type": "Collection(Edm.Single)",
            "searchable": true,
            "retrievable": false,
            "stored": false,
            "dimensions": 1536,
            "vectorSearchProfile": "vector-profile-hnsw"
         }
       ]
   

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

   Навык внедрения	Введите это значение
   Azure OpenAI	Количество встраиваний, созданных вашей моделью встраивания.
   Визуальное распознавание искусственного интеллекта Azure	1024

Добавление векторизатора в индекс

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

1. Добавьте векторизатор Azure OpenAI или векторизатор Azure AI Vision после vectorSearch.profiles. Вы можете вставить одно из следующих определений.

         "profiles": [ ... ],
         "vectorizers": [
           {
             "name": "my-openai-vectorizer",
             "kind": "azureOpenAI",
             "azureOpenAIParameters": {
               "resourceUri": "{{aoaiEndpoint}}",
               "deploymentId": "{{aoaiDeploymentName}}",
               "modelName": "{{aoaiModelName}}"
             }
           },
           {
             "name": "my-ai-services-vision-vectorizer",
             "kind": "aiServicesVision",
             "aiServicesVisionParameters": {
               "resourceUri": "{{aiMultiServiceEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Замечание

   Векторизатор визуального распознавания Azure находится в общедоступной предварительной версии. Если вы хотите вызвать этот векторизатор, используйте API предварительной версии, например 2025-03-01-preview.

2. Укажите векторизатор в vectorSearch.profiles.

         "profiles": [
           {
             "name": "vector-profile-hnsw",
             "algorithm": "hnsw-algorithm",
             "vectorizer": "my-openai-vectorizer"
           }
         ]
   

3. Чтобы создать векторный индекс, выберите "Отправить запрос".

Создать индексатор

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

1. Создайте индексатор для определения индексатора, выполняющего конвейер векторизации.

   ### Create an indexer
   POST {{baseUrl}}/indexers?api-version=2024-07-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "name": "my-indexer",
       "dataSourceName": "my-data-source",
       "targetIndexName": "my-vector-index",
       "skillsetName": "my-skillset",
       "schedule": {
         "interval": "PT2H"
       },
       "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null
       }
     }
   

2. Чтобы создать индексатор, выберите "Отправить запрос".

Выполнение векторного запроса для подтверждения индексирования

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

1. Используйте Documents - Search Post, чтобы определить запрос, который векторизуется во время выполнения запроса.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2024-07-01  HTTP/1.1
     Content-Type: application/json
     Authorization: Bearer {{token}}
   
     {
       "count": true,
       "select": "title, content",
       "vectorQueries": [
           {
             "kind": "text",
             "text": "a sample text string for integrated vectorization",
             "fields": "titleVector, contentVector",
             "k": "3"
           }
       ]
     }
   

   Замечание

   Векторизатор визуального распознавания Azure находится в общедоступной предварительной версии. Если вы ранее использовали этот векторизатор, используйте предварительный API, например 2025-03-01-preview.

   Для запросов, вызывающих встроенную векторизацию, kind необходимо задать textзначение и text указать текстовую строку. Эта строка передается в векторизатор, назначенный полю вектора. Дополнительные сведения см. в статье "Запрос" с интегрированной векторизацией.

2. Чтобы запустить векторный запрос, выберите "Отправить запрос".

Связанный контент

• Встроенная векторизация в поиске ИИ Azure
• Краткое руководство. Векторизация текста и изображений на портале Azure
• Пример Python для интегрированной векторизации