Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Из этой статьи вы узнаете, как использовать набор навыков для блокировки и векторизации содержимого из поддерживаемого источника данных. Набор навыков вызывает навык разделения текста или навык макета документов для фрагментирования, а также навык внедрения, связанный с поддерживаемой моделью внедрения, для векторизации фрагментов. Вы также узнаете, как хранить фрагментированные и векторизованные содержимое в векторном индексе.
В этой статье описывается комплексный рабочий процесс интегрированной векторизации с помощью REST. Для инструкций, основанных на портале, см. раздел Quickstart: Vectorize text and images in the Azure portal.
Предпосылки
Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .
Служба Azure AI Search. Мы рекомендуем уровень "Базовый" или "Выше".
Завершение Краткое руководство: Подключение без ключей и Настройка управляемого удостоверения, назначаемого системой. Хотя для операций уровня данных можно использовать проверку подлинности на основе ключей, в этой статье предполагается использование ролей и управляемых удостоверений, которые являются более безопасными.
Visual Studio Code с расширением REST Client.
Поддерживаемые источники данных
Встроенная векторизация работает со всеми поддерживаемыми источниками данных. Однако в этой статье рассматриваются наиболее часто используемые источники данных, описанные в следующей таблице.
| Источник данных | Описание |
|---|---|
| Хранилище BLOB-объектов Azure | Этот источник данных работает с объектами Blob и таблицами. Необходимо использовать учетную запись стандартной производительности (общего назначения версии 2). Уровни доступа могут быть горячими, прохладными или холодными. |
| Azure Data Lake Storage (ADLS) 2-го поколения | Это учетная запись Azure Storage с включенным иерархическим пространством имен. Чтобы подтвердить наличие Data Lake Storage, перейдите на вкладку Properties на странице Overview.
|
| Microsoft OneLake | Этот источник данных подключается к файлам и сочетаниям клавиш OneLake. |
Поддерживаемые модели внедрения
Используйте одну из следующих моделей внедрения для интегрированной векторизации. Инструкции по развертыванию приведены в следующем разделе.
| Поставщик | Поддерживаемые модели |
|---|---|
| Ресурс Azure OpenAI1, 2 | text-embedding-ada-002 Встраивание текста - версия 3 - малая текст-встраивание-3-большой |
| Ресурс Microsoft Foundry3 | Для текста и изображений: Azure Vision Multimodal4 |
1 Конечная точка вашего ресурса Azure OpenAI должна иметь пользовательский поддомен, например https://my-unique-name.openai.azure.com. Если вы создали ресурс на портале Azure, этот поддомен был автоматически создан во время настройки ресурса.
2 ресурса OpenAI Azure (с доступом к моделям встраивания), созданные на портале Microsoft Foundry, не поддерживаются. На портале Azure необходимо создать ресурс OpenAI Azure.
3 Для выставления счетов необходимо подключить ресурс Microsoft Foundry к набору навыков Azure AI Search. Если для создания набора навыков не используется подключение без ключа (предварительная версия), оба ресурса должны находиться в одном регионе.
4 Модель многомодальной интеграции «Azure Vision» доступна в некоторых регионах .
Ролевой доступ
Вы можете использовать Microsoft Entra ID с назначениями ролей или проверкой подлинности на основе ключей со строками подключения с полным доступом. Для Azure AI Search подключений к другим ресурсам рекомендуется назначать роли.
Чтобы настроить доступ на основе ролей для интегрированной векторизации:
В службе поиска включите роли и настройте управляемое удостоверение, назначаемое системой.
На платформе источника данных и поставщике моделей внедрения создайте назначения ролей, которые позволяют службе поиска получать доступ к данным и моделям. См. статью "Подготовка данных " и "Подготовка модели внедрения".
Замечание
Бесплатные службы поиска поддерживают подключения на основе ролей к Azure AI Search. Однако они не поддерживают управляемые идентификаторы для исходящих подключений к Azure Storage и Azure Vision. Это отсутствие поддержки требует использования проверки подлинности на основе ключей для подключений между бесплатными службами поиска и другими ресурсами Azure.
Для более безопасных подключений используйте базовый уровень или более высокий. Затем можно включить роли и настроить управляемое удостоверение для авторизованного доступа.
Получение сведений о подключении для Azure AI Search
В этом разделе вы получите конечную точку и токен Microsoft Entra для вашей службы Azure AI Search. Оба значения необходимы для установления подключений в REST запросах.
Подсказка
В следующих шагах предполагается, что вы используете доступ на основе ролей для проверки концепции. Если вы хотите использовать интегрированную векторизацию для разработки приложений, см. статью Connect your app to Azure AI Search using идентификаций.
Перейдите в службу поиска в портал Azure.
Чтобы получить конечную точку поиска, скопируйте URL-адрес на странице обзора . Пример конечной точки поиска.
https://my-service.search.windows.netЧтобы получить маркер Microsoft Entra, выполните следующую команду в локальной системе. Для выполнения этого шага необходимо завершить краткое руководство: подключение без ключей.
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
Подготовка данных
В этом разделе описана подготовка данных для интегрированной векторизации путем отправки файлов в поддерживаемый источник данных, назначение ролей и получение сведений о подключении.
Перейдите к учетной записи хранения Azure на портале Azure.
В левой области выберитеконтейнеры> данных.
Создайте контейнер или выберите существующий контейнер, а затем отправьте файлы в контейнер.
Назначить роли:
В левой области выберите Access Control (IAM).
Выберите Добавить>Добавить назначение ролей.
В разделе Роли функций задач выберите Storage Blob Data Reader, а затем нажмите Далее.
В разделе "Участники" выберите управляемое удостоверение и выберите "Выбрать участников".
Выберите подписку и управляемое удостоверение службы поиска.
Чтобы получить строку подключения, следуйте этим шагам.
В левой области выберите Безопасность и сеть>Ключи доступа.
Скопируйте любую строку подключения, которую вы укажете позже в настройках Set variables.
(Необязательно) Синхронизация удалений в контейнере с удалением в индексе поиска. Чтобы настроить индексатор для обнаружения удаления:
Включите мягкое удаление в учетной записи хранения. Если вы используете собственное мягкое удаление, следующий шаг не требуется.
Добавьте настраиваемые метаданные, которые индексатор может сканировать, чтобы определить, какие блобы помечены для удаления. Присвойте пользовательскому свойству описательное имя. Например, можно присвоить свойству IsDeleted имя и задать для него значение false. Повторите этот шаг для каждого блоба в контейнере. Если вы хотите удалить объект blob, установите значение свойства на true. Дополнительные сведения см. в разделе Обнаружение изменений и удаления при индексировании из Azure Storage.
Подготовка модели внедрения
В этом разделе описана подготовка ресурса Azure ИИ для интегрированной векторизации путем назначения ролей, получения конечной точки и развертывания поддерживаемой модели встраивания.
Azure AI Search поддерживает text-embedding-ada-002, text-embedding-3-small и text-embedding-3-large. В Azure AI Search используется навык Azure OpenAI Embedding для подключения к Azure OpenAI.
Перейдите к ресурсу Azure OpenAI на портале Azure.
Назначить роли:
В левой области выберите элемент управления доступом (IAM).
Выберите Добавить>Добавить назначение ролей.
В разделе Роли функции задания выберите Пользователь Cognitive Services OpenAI, а затем нажмите Далее.
В разделе "Участники" выберите управляемое удостоверение и выберите "Выбрать участников".
Выберите подписку и управляемое удостоверение службы поиска.
Чтобы получить конечную точку, выполните приведенные действия.
В левой области выберите ключи управления> ресурсамии конечную точку.
Скопируйте точку входа для ресурса Azure OpenAI. Этот URL-адрес можно указать позже в параметре Set переменных.
Чтобы развернуть модель внедрения:
Войдите на портал Foundry и выберите ресурс OpenAI Azure.
Разверните поддерживаемую модель внедрения.
Скопируйте имена развертывания и модели, которые будут указаны далее в переменных Set. Имя развертывания — это пользовательское имя, которое вы выбрали, а имя модели — это название модели, которую вы развернули, например
text-embedding-ada-002.
Установка переменных
В этом разделе вы указываете информацию о подключении для вашей службы Azure AI Search, вашего поддерживаемого источника данных и вашей поддерживаемой модели встраивания.
В Visual Studio Code вставьте следующие шаблоны в файл
.restили.http.@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HEREЗамените
@baseUrlна конечную точку поиска и@tokenна токен Microsoft Entra, который вы получили в Получить информацию о подключении для Azure AI Search.В зависимости от источника данных добавьте следующие переменные.
Источник данных Переменные Введите эти сведения Azure Blob Storage @storageConnectionStringи@blobContainer.Строка подключения и имя контейнера, созданного в Prepare your data. ADLS 2-го поколения @storageConnectionStringи@blobContainer.Строка подключения и имя контейнера, созданного в Prepare your data. OneLake @workspaceIdи@lakehouseId.Идентификаторы рабочей области и lakehouse, полученные в разделе "Подготовка данных". В зависимости от поставщика модели внедрения добавьте следующие переменные.
Поставщик модели внедрения Переменные Введите эти сведения Azure OpenAI @aoaiEndpoint,@aoaiDeploymentNameи@aoaiModelNameКонечная точка, имя развертывания и имя модели, полученные в подготовке модели внедрения. Azure Vision (служба компьютерного зрения) @AiFoundryEndpointКонечная точка, полученная в подготовке модели внедрения. Чтобы проверить переменные, отправьте следующий запрос.
### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2025-09-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}Ответ должен отображаться в соседней области. Если у вас уже существуют индексы, они перечислены. В противном случае список пуст. Если http-код имеет значение
200 OK, вы готовы продолжить работу.
Подключение к данным
В этом разделе описано, как подключиться к поддерживаемму источнику данных для индексации на основе индексатора. Для indexer в Azure AI Search требуется источник данных, указывающий тип, учетные данные и контейнер.
Создание источника данных позволяет определить источник данных, предоставляющий сведения о подключении во время индексирования.
### Create a data source POST {{baseUrl}}/datasources?api-version=2025-09-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 }Установите
typeдля вашего источника данных:azureblobилиadlsgen2.Чтобы создать источник данных, нажмите кнопку "Отправить запрос".
Если вы используете OneLake, установите
credentials.connectionStringнаResourceId={{workspaceId}}иcontainer.nameна{{lakehouseId}}.
Создание набора навыков
В этом разделе вы создаете набор навыков, включающий встроенный навык для фрагментирования содержимого и навык встраивания для создания векторных представлений фрагментов. Набор навыков выполняется во время индексирования в следующем разделе.
Вызовите встроенный навык для разбиения вашего контента на части
Секционирование содержимого на блоки помогает удовлетворить требования модели внедрения и предотвратить потерю данных из-за усечения. Дополнительные сведения о фрагментации см. в разделе "Блоки больших документов" для решений поиска векторов.
Для встроенной обработки фрагментов данных Azure AI Search предлагает навык Text Split и навык Document Layout. Навык разделения текста разбивает текст на предложения или страницы определенной длины, а навык макета документа разбивает содержимое на основе границ абзаца.
Используйте Создать набор навыков для определения или создания набора навыков.
### Create a skillset POST {{baseUrl}}/skillsets?api-version=2025-09-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "my-skillset", "skills": [] }В массиве
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.
Вызов функции встраивания для векторизации блоков
Чтобы векторизировать фрагментированное содержимое, набор навыков нуждается в навыке внедрения, который указывает на поддерживаемую модель внедрения.
После встроенного навыка фрагментирования в массиве
skillsвызовите Встраивающий навык Azure OpenAI или Навык 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" } ] }Замечание
Навык многомодальных эмбеддингов Azure Vision находится в общедоступной предварительной версии. Если вы хотите вызвать этот навык, используйте последнюю предварительную версию API.
Если вы используете навык встраивания Azure OpenAI, задайте для параметра
dimensionsзначение числа встраиваний, созданных моделью встраивания.Если вы используете навык многомодального встраивания Azure Vision, подключите свой ресурс Microsoft Foundry после
skillsмассива. Это вложение предназначено для выставления счетов."skills": [ ... ], "cognitiveServices": { "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity", "subdomainUrl": "{{AiFoundryEndpoint}}" }Чтобы создать набор навыков, нажмите кнопку "Отправить запрос".
Создание векторного индекса
В этом разделе описана настройка структур физических данных в службе Azure AI Search путем создания индекса vector. Для схемы векторного индекса требуется следующее:
- Имя
- Ключевое поле (строка)
- Одно или несколько векторных полей
- Конфигурация вектора
Векторные поля хранят числовые представления фрагментированных данных. Они должны быть доступны для поиска и извлечения, но они не могут быть фильтруемыми, фасетными или сортируемыми. Они также не могут иметь анализаторы, нормализаторы или назначения отображения синонимов.
В дополнение к полям векторов пример индекса в следующих шагах содержит невекторные поля для читаемого пользователем содержимого. Обычно включают эквиваленты простого текста для содержимого, которое требуется векторизовать. Дополнительные сведения см. в разделе "Создание векторного индекса".
Используйте create Index для определения схемы векторного индекса.
### Create a vector index POST {{baseUrl}}/indexes?api-version=2025-09-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "my-vector-index", "fields": [], "vectorSearch": [] }Добавьте конфигурацию векторного поиска в
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связывает конфигурацию алгоритма с профилем, который можно назначить векторным полям.В зависимости от вашей модели встраивания обновите
vectorSearch.algorithms.metric. Допустимые значения для метрик расстояния:cosine,dotproducteuclideanиhamming.Добавьте поля в
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" } ]В зависимости от навыка внедрения задайте
dimensionsдля каждого поля вектора следующее значение.Навык встраивания Введите это значение Azure OpenAI Количество встраиваний, созданных вашей моделью встраивания. Azure Vision (служба компьютерного зрения) 1024
Добавление векторизатора в индекс
В этом разделе описано, как включить векторизацию во время запроса, определив векторизатор в индексе. Векторизатор использует модель векторного представления, которая индексирует ваши данные, чтобы декодировать строку поиска или изображение в вектор для поиска по векторам.
Добавьте векторизатор 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 предварительной версии, например
2025-03-01-preview.Укажите векторизатор в
vectorSearch.profiles."profiles": [ { "name": "vector-profile-hnsw", "algorithm": "hnsw-algorithm", "vectorizer": "my-openai-vectorizer" } ]Чтобы создать векторный индекс, выберите "Отправить запрос".
Создать индексатор
В этом разделе вы создадите индексатор для управления всей системой векторизации, от извлечения данных и выполнения набора навыков до индексирования. Мы рекомендуем запустить индексатор по расписанию для обработки изменений или документов, пропущенных из-за ограничения.
Создайте индексатор для определения индексатора, выполняющего конвейер векторизации.
### Create an indexer POST {{baseUrl}}/indexers?api-version=2025-09-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 } }Чтобы создать индексатор, выберите "Отправить запрос".
Выполнение векторного запроса для подтверждения индексирования
В этом разделе вы убедитесь, что содержимое успешно индексировано путем создания векторного запроса. Так как вы настроили векторизатор в предыдущем разделе, поисковая система может декодировать обычный текст или изображение в вектор для выполнения запроса.
Используйте Documents - Search Post, чтобы определить запрос, который векторизуется во время выполнения запроса.
### Run a vector query POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2025-09-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указать текстовую строку. Эта строка передается в векторизатор, назначенный полю вектора. Дополнительные сведения см. в статье "Запрос" с интегрированной векторизацией.Чтобы запустить векторный запрос, выберите "Отправить запрос".