Загрузка данных в индекс поиска в службе "Поиск ИИ Azure"

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

Предпосылки

• Служба поиска ИИ Azure (любой уровень). Создайте службу или найдите существующую.

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

• Разрешения для загрузки документов:

  • Проверка подлинности на основе ключей: ключ API администратора для службы поиска.
  • Проверка подлинности на основе ролей: роль участника данных индекса поиска в службе поиска.

• Для разработки пакета SDK установите клиентская библиотека поиска Azure:

  • .NET: Azure. Search.Documents
  • Python: azure-search-documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Использование портала Azure

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

1. Перейдите в службу поиска в портал Azure.

2. На странице "Обзор" выберите "Импорт данных " на панели команд, чтобы создать и заполнить индекс поиска.

   

   Чтобы просмотреть рабочий процесс, перейдите по следующим ссылкам: Краткое руководство: Создание индекса поиска Azure AI и Краткое руководство: Интегрированная векторизация.

3. После завершения работы мастера используйте обозреватель поиска для проверки результатов.

Используйте REST API

Документы — индекс — это REST API для импорта данных в индекс поиска.

Текст запроса содержит один или несколько документов для индексирования. Документы однозначно идентифицируются с помощью ключа с учетом регистра. Каждый документ связан с действием: "upload", "delete", "merge" или "mergeOrUpload". Запросы на отправку должны содержать данные документа в виде набора пар "ключ-значение".

REST API полезны для первоначальной проверки концепции, позволяя тестировать рабочие процессы индексирования без необходимости писать много кода. Параметр @search.action определяет, добавляются ли документы полностью или частично с точки зрения новых или заменяющих значений для определенных полей.

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

1. Сформулируйте вызов POST, указывающий имя индекса, конечную точку docs/index и текст запроса, включающий @search.action параметр.

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2026-04-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "HotelName": "Stay-Kay City Hotel",
       "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
       "Category": "Boutique",
       "Tags": [ "pool", "air conditioning", "concierge" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. Установите параметр @search.action в значение upload для создания или перезаписи документа. Задайте для него merge значение или uploadOrMerge если вы нацелены на обновления для определенных полей в документе. В предыдущем примере показаны оба действия.

   Действие	Действие
   загрузить	Аналогично "upsert", где документ вставляется, если этот документ новый, и обновляется или заменяется, если он существует. Если в документе отсутствуют значения, необходимые индексу, значение поля документа устанавливается в null.
   объединить	Обновляет документ, который уже существует, и не удается найти документ. Слияние заменяет существующие значения. По этой причине обязательно проверьте поля коллекции, содержащие несколько значений, таких как поля типа Collection(Edm.String). Например, если tags поле начинается со значения ["budget"] и выполняется слияние с ["economy", "pool"], конечное значение tags поля равно ["economy", "pool"]. Это не ["budget", "economy", "pool"].
   объединитьИлиЗагрузить	Ведет себя как слияние, если документ существует, и отправляется, если документ является новым. Это наиболее распространенное действие для добавочных обновлений.
   delete	Удаляет указанный документ из индекса. Любое поле, указанное в операции удаления, отличное от ключевого поля, игнорируется. Если вы хотите удалить отдельное поле из документа, используйте слияние и явно установите для поля значение null. Дополнительные сведения см. в разделе "Удаление документов в индексе поиска".

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

   В примитивных коллекциях, если документ содержит поле тегов типа Collection(Edm.String) со значением ["бюджет"], и выполняется слияние со значением ["экономика", "пул"] для тега, окончательное значение поля "Теги" будет ["экономика", "пул"]. Это не ["бюджет", "экономика", "пул"].

   В сложных коллекциях, если документ содержит сложное поле коллекции с именем "Комнаты" со значением [{ "Type": "Бюджетная комната", "BaseRate": 75.0 }], и вы выполняете слияние со значением [{ "Type": "Стандартный номер" }, { "Type": "Бюджетная комната", "BaseRate": 60.5 }], окончательное значение поля "Комнаты" будет [{ "Type": "Стандартный номер" }, { "Type": "Бюджетная комната", "BaseRate": 60.5 }]. Это не будет ни одно из следующих действий:

   • [{ "Тип": "Бюджетная комната", "BaseRate": 75.0 }, { "Тип": "Стандартный номер" }, { "Тип": "Бюджетная комната", "BaseRate": 60.5 }] (добавление элементов)

   • [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Бюджетный номер", "BaseRate": 60.5 }] (объедините элементы в указанном порядке, затем добавьте любые дополнительные элементы)

   Замечание

   При отправке значений DateTimeOffset с данными часового пояса в индекс поиск Azure AI нормализует эти значения в формате UTC. Например, 2025-01-13T14:03:00-08:00 будет храниться как 2025-01-13T22:03:00Z. Если вам нужно хранить сведения часового пояса, добавьте дополнительный столбец в индекс.

3. Отправьте запрос.

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

   Код состояния	Meaning	Повторная попытка	Примечания.
   200	Документ был успешно изменен или удален.	n/a	Операции удаления являются идемпотентными. То есть, даже если ключ документа не существует в индексе, попытка удаления с этим ключом приводит к коду состояния 200.
   201	Документ был успешно создан.	n/a
   400	В документе произошла ошибка, которая препятствовала индексации.	нет	Сообщение об ошибке в ответе указывает, что неправильно с документом.
   404	Документ не удалось объединить, так как заданный ключ не существует в индексе.	нет	Эта ошибка не возникает для отправки, так как они создают новые документы, и она не возникает для удаления, так как они идемпотентны.
   409	Конфликт версии обнаружен при попытке индексировать документ.	Да	Это может произойти при нескольких одновременных попытках индексирования одного документа.
   422	Индекс временно недоступен, так как он был обновлен с флагом AllowIndexDowntime с значением true.	Да
   429	Указывает, что превышена квота на количество документов на индекс.	нет	Необходимо создать новый индекс или обновить индекс для увеличения пределов емкости.
   503 (Сервис временно недоступен)	Служба поиска временно недоступна, возможно, из-за тяжелой нагрузки.	Да	Ваш код должен подождать, прежде чем предпринимать повторную попытку, иначе вы рискуете только увеличить время недоступности службы.

   Замечание

   Если клиентский код часто встречает ответ 207, одна из возможных причин заключается в том, что система находится под нагрузкой. Это можно подтвердить, проверив statusCode свойство 503. В этом случае рекомендуется ограничивать запросы индексирования. В противном случае, если индексирование трафика не утихает, система может начать отклонять все запросы с ошибками 503.

4. Просмотрите только что добавленные документы в качестве шага проверки:

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2026-04-01
   

Справочник:Документы — индекс, документы — получение

Успешный запрос индекса возвращает HTTP 200 (ОК) для пакета, в котором все документы успешно выполнены, или HTTP 207 (multi-Status) в случае сбоя некоторых документов. Текст ответа содержит состояние для каждого документа:

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Когда ключ документа или идентификатор является новым, значение NULL становится значением для любого поля, которое не указано в документе. Для действий в существующем документе обновленные значения заменяют предыдущие значения. Все поля, которые не были указаны в "merge" или "mergeUpload", остаются нетронутыми в индексе поиска.

использование пакетов SDK Azure;

Программируемость предоставляется в следующих пакетах SDK Azure.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Проверка загрузки данных

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

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2026-04-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Принцип работы импорта данных

Служба поиска принимает документы JSON, соответствующие схеме индекса. Служба поиска может импортировать и индексировать текстовое содержимое и векторное содержимое в документах JSON.

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

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

Эти документы можно подготовить самостоятельно, но если содержимое находится в поддерживаемом источнике данных, выполнение индексатора или использование мастера импорта может автоматизировать извлечение документов, сериализацию JSON и индексирование.

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

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

Дополнительные сведения см. в стратегиях импорта данных.

Устранение распространенных ошибок