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

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

В этой статье описывается комплексный рабочий процесс интегрированной векторизации с помощью REST. Инструкции для портала см. в разделе Quickstart: Vectorize text and images in the Azure portal.

Необходимые условия

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

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

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

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

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

• Visual Studio Code с расширением клиента REST.

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

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

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

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

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

¹ Конечная точка вашего ресурса Azure OpenAI должна иметь настроенный поддомен, например . Если вы создали ресурс на портале Azure, этот поддомен был автоматически создан во время настройки ресурса.

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

³ Для выставления счетов необходимо присоединить ресурс Microsoft Foundry к набору навыков Поиск с использованием ИИ Azure. Если для создания набора навыков не используется подключение без ключа , оба ресурса должны находиться в одном регионе.

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

Доступ на основе ролей

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

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

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

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

Получение сведений о подключении для Поиск с использованием ИИ Azure

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

1. Перейдите в службу поиска на портале 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.

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

   Источник данных	Переменные	Введите эти сведения
   Хранилище BLOB-объектов Azure	@storageConnectionString и @blobContainer	Строка подключения и имя контейнера, который вы создали в разделе Подготовка данных.
   ADLS 2-го поколения	@storageConnectionString и @blobContainer	Строка подключения и имя контейнера, который вы создали в разделе Подготовка данных.
   OneLake	@workspaceId и @lakehouseId	Идентификаторы рабочего пространства и lakehouse, полученные в разделе "Подготовка данных".

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

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

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

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

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

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

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

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

   ### Create a data source
   POST {{baseUrl}}/datasources?api-version=2026-04-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. Чтобы создать источник данных, нажмите кнопку "Отправить запрос".

4. Если вы используете OneLake, установите credentials.connectionString в ResourceId={{workspaceId}}, а container.name в {{lakehouseId}}.

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

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

Вызовите встроенное умение для разбиения содержимого на части

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

Для встроенного разбиения данных на фрагменты Поиск с использованием ИИ Azure предоставляет навык Text Split и навык Azure Content Understanding. Навык Text Split разбивает текст на предложения или страницы заданной длины, тогда как навык Azure Content Understanding выполняет семантическое разбиение на фрагменты с учётом макета документа и с соблюдением границ абзацев.

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

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

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

       "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.ContentUnderstandingSkill",
          "name": "my-content-understanding-skill",
          "context": "/document",
          "chunkingProperties": {
            "method": "semantic",
            "unit": "tokens",
            "maximumLength": 500
          },
          "inputs": [
           {
             "name": "file_data",
             "source": "/document/file_data"
           }
          ],
          "outputs": [
           {
             "name": "text_sections",
             "targetName": "text_sections"
           }
          ]
        }
       ]
   

Вызов навыка работы с эмбеддингами для векторизации блоков

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

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

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

   Примечание

   Навык многомодальных включений Vision в Azure доступен в тестовой версии. Если вы хотите вызвать этот навык, используйте последнюю предварительную версию API.

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

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

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

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

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

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

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

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

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

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

   ### Create a vector index
   POST {{baseUrl}}/indexes?api-version=2026-04-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 Vision	1024

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

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

1. Добавьте векторизатор Azure OpenAI или векторизатор Azure 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": "{{AiFoundryEndpoint}}",
               "modelVersion": "2023-04-15"
             }
           }
         ]
   

   Примечание

   Векторизатор визуального зрения Azure находится в предварительной версии. Если вы хотите вызвать этот векторизатор, используйте последнюю версию API предварительной версии.

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=2026-04-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. Используйте документы — поиск Post, чтобы определить векторизованный запрос во время выполнения запроса.

   ### Run a vector query
   POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2026-04-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 предварительной версии.

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

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

Связанное содержимое

• Встроенное внедрение вектора в Поиск с использованием ИИ Azure
• Quickstart: векторный поиск на портале Azure
• пример Python для интегрированной векторизации