Руководство по устранению неполадок индексатора для поиска ИИ Azure

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

Лучшие практики

Ниже приведены некоторые основные практики и рекомендации при работе с индексаторами.

Индексаторы предназначены для запуска по расписанию

• Для надежного индексирования настройте индексаторы для выполнения в обычном расписании. Запланированные запуски автоматически собирают все документы, пропущенные в предыдущих запусках из-за временных ошибок, прерываний сети или временных проблем со службой. Этот подход помогает поддерживать согласованность данных и сводит к минимуму потребность в ручном вмешательстве.
• Для больших источников данных начальное перечисление и индексирование может занять несколько часов или даже дней. Запуск индексатора по расписанию позволяет обеспечить непрерывную работу, а ошибки будут автоматически обработаны повторно. Избегайте использования только ручных запусков индексатора или запусков по запросу, так как эти варианты не обеспечивают такой же надежности и восстановления после временных ошибок.

Индексаторы обеспечивают наилучшее возможное индексирование на протяжении времени.

• Встроенные индексаторы обрабатывают документы без постоянных ошибок и повторных попыток в запланированных запусках. Они предлагают удобный, низкокодовый или безкодовый способ индексировать данные для распространенных сценариев, что позволяет ускорить разработку и упростить обслуживание. Когда индексатор запускает набор навыков, каждый запуск имеет фиксированный предел времени выполнения. Индексаторы, выполняемые в мультитенантной среде выполнения , имеют двухчасовое максимальное время выполнения. Это ограничение является наиболее распространенным случаем, используемым, если наборы навыков не требуют общих закрытых ссылок. Индексаторы, настроенные для использования общих приватных ссылок, выполняются в приватной среде с максимальной продолжительностью 24 часа. Сведения о полной таблице см. в разделе "Ограничения индексатора". Если обработка набора навыков на уровне отдельных документов не позволяет индексатору завершить работу до истечения ограничения по времени, он останавливается, оставляя оставшиеся документы необработанными. Полная обработка не гарантируется, если объем документа, размер файла, сложность набора навыков или среда выполнения не позволяют индексатору завершить работу в течение максимального времени выполнения. Секционирование источника данных может снизить этот риск, но не устраняет его, особенно если в секцию добавляются большие объемы файлов. Это поведение является ожидаемым. Сведения о стратегиях управления большими наборами данных и поддержки инкрементного восстановления см. в разделах Индексирование больших наборов данных и Планирование индексаторов. Если для решения требуется строгий контроль над процессом индексатора документов, используйте альтернативу API push-отправки в этой статье.
• Если для решения требуется строгий контроль над временными шкалами индексирования, используйте API push-уведомлений вместо этого, например REST API индекса документов или метод IndexDocuments (Azure SDK для .NET). Эти параметры обеспечивают полный контроль над конвейером индексирования.
• Индексаторы иногда могут выпадать из расписания. Хотя это условие является редким и существуют механизмы автоматического восстановления, восстановление может занять некоторое время. Это поведение является ожидаемым.

Устранение проблем с подключением к ограниченным ресурсам

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

Ошибка при подключении к ресурсу Microsoft Foundry в частном подключении

Если вы получаете код ошибки 403 со следующим сообщением, может возникнуть проблема с тем, как конечная точка ресурса указана в наборе навыков:

• "A Virtual Network is configured for this resource. Please use the correct endpoint for making requests. Check https://aka.ms/cogsvc-vnet for more details."

Эта ошибка возникает, если вы настроили общую приватную ссылку для подключений к ресурсу Azure Foundry, а конечная точка отсутствует настраиваемый поддомен. Настраиваемый поддомен является первой частью конечной точки (например, http://my-custom-subdomain.services.ai.azure.com). Если вы создали ресурс на портале Foundry, а не на портале Azure, может быть отсутствует личный домен.

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

Ошибка при использовании общей приватной ссылки

Если вы получаете код ошибки 403 со следующим сообщением, индексатор может подключаться через общедоступную конечную точку вместо утвержденной общей приватной ссылки:

Unexpected error validating provided resource. {"error":{"code":"403","message":"Public access is disabled. Please configure private endpoint."}}

Эта ошибка может возникать, если индексатор не настроен для использования частной среды выполнения. Убедитесь, что общая приватная ссылка одобрена, установите для индексатора executionEnvironment значение private и убедитесь, что подключение использует правильную конечную точку ресурса и идентификатор группы.

Правила брандмауэра

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

• The remote server returned an error: (403) Forbidden
• This request is not authorized to perform this operation
• Credentials provided in the connection string are invalid or have expired

Чтобы разрешить индексаторам доступ к этим ресурсам, используйте один из следующих вариантов:

• Настройте входящее правило для IP-адреса службы поиска и диапазона IP-адресов тега AzureCognitiveSearchслужбы. Дополнительные сведения о настройке ограничений диапазона IP-адресов для каждого типа источника данных см. в следующих ссылках:

  • Хранилище Azure
  • Azure Cosmos DB
  • Azure SQL

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

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

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

Правила группы безопасности сети (NSG)

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

Для внешних ресурсов, размещённых в виртуальной сети, настройте входящие правила NSG для тега AzureCognitiveSearch службы.

Дополнительные сведения о подключении к виртуальной машине см. в статье "Настройка подключения к SQL Server" на виртуальной машине Azure.

Ошибки сети.

Как правило, сетевые ошибки являются универсальными. Ниже перечислены некоторые распространенные ошибки.

• A network-related or instance-specific error occurred while establishing a connection to the server
• The server was not found or was not accessible
• Verify that the instance name is correct and that the source is configured to allow remote connections

При получении любой из этих ошибок:

• Убедитесь, что вы можете получить доступ к источнику, пытаясь подключиться к нему напрямую, а не через службу поиска.
• Проверьте ресурс на портале Azure для любых текущих ошибок или сбоев.
• Проверьте наличие сбоев сети в состоянии Azure.
• Убедитесь, что вы используете общедоступный DNS для разрешения имен, а не Azure Частная зона DNS.

Бессерверное индексирование в базе данных Azure SQL (код ошибки 40613)

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

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

Политики условного доступа Microsoft Entra

При создании индексатора SharePoint необходимо войти в приложение Microsoft Entra после предоставления кода устройства. Если вы получаете сообщение, которое говорится"Your sign-in was successful but your admin requires the device requesting access to be managed", политика условного доступа, вероятно, блокирует индексатор из библиотеки документов SharePoint.

Чтобы обновить политику и разрешить индексатору доступ к библиотеке документов:

1. Откройте портал Azure и найдите Условный доступ Microsoft Entra.

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

3. Определите, какая политика блокирует индексатор SharePoint для доступа к библиотеке документов. Политика, которая может блокировать индексатор, включает учетную запись пользователя, используемую для проверки подлинности во время этапа создания индексатора в разделе "Пользователи и группы ". Политика также может иметь Условия, которые:

   • Ограничить платформы Windows
   • Ограничьте мобильные приложения и настольные клиенты.
   • Установите состояние устройства на Да.

4. После подтверждения того, какая политика блокирует индексатор, сделайте исключение для индексатора. Начните с получения IP-адреса службы поиска.

   Сначала получите полностью квалифицированное доменное имя службы поиска. Полное доменное имя выглядит следующим образом <your-search-service-name>.search.windows.net. Полное доменное имя (FQDN) можно найти в портале Azure.

   

   Теперь, когда у вас есть полное доменное имя (FQDN), получите IP-адрес службы поиска, выполнив nslookup (или ping) с использованием этого полного доменного имени. В следующем примере вы добавляете 150.0.0.1 в правило входящего трафика в брандмауэре служба хранилища Azure. После обновления параметров брандмауэра может пройти до 15 минут, прежде чем индексатор службы поиска сможет получить доступ к учетной записи служба хранилища Azure.

   nslookup contoso.search.windows.net
   Server:  server.example.org
   Address:  10.50.10.50
   
   Non-authoritative answer:
   Name:    <name>
   Address:  150.0.0.1
   Aliases:  contoso.search.windows.net
   

5. Получите диапазоны IP-адресов для среды выполнения индексатора в вашем регионе.

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

   Диапазоны IP-адресов для тега AzureCognitiveSearch службы можно получить с помощью API обнаружения или скачиваемого JSON-файла.

   В этом упражнении, если служба поиска использует общедоступное облако Azure, скачайте JSON-файл Azure Public.

   

   Из JSON-файла, если предположить, что служба поиска находится в регионе West Central US, приведён список IP-адресов для среды выполнения мультитенантного индексатора.

       {
         "name": "AzureCognitiveSearch.WestCentralUS",
         "id": "AzureCognitiveSearch.WestCentralUS",
         "properties": {
           "changeNumber": 1,
           "region": "westcentralus",
           "platform": "Azure",
           "systemService": "AzureCognitiveSearch",
           "addressPrefixes": [
             "52.150.139.0/26",
             "52.253.133.74/32"
           ]
         }
       }
   

6. Вернитесь на страницу условного доступа на портале Azure, выберите Именованные расположения в меню слева, затем нажмите + расположение диапазона IP-адресов. Присвойте новому именованному расположению имя и добавьте диапазоны IP-адресов для сред выполнения индексатора и службы поиска, собранные в последних двух шагах. 1

   • Для IP-адреса службы поиска может потребоваться добавить "/32" в конец IP-адреса, так как он принимает только допустимые диапазоны IP-адресов.
   • Помните, что для диапазонов IP-адресов среды выполнения индексатора нужно добавить только диапазоны IP-адресов для региона, в котором находится служба поиска.

7. Исключите новое именованное местоположение из политики:

   1. В меню слева выберите Политики.
   2. Выберите политику, блокирующую индексатор.
   3. Выберите Условия.
   4. Выберите Расположения.
   5. Выберите Исключить, затем добавьте новое именованное расположение.
   6. Выберите Сохранить для сохранения изменений.

8. Подождите несколько минут, чтобы политика обновилась и применила новые правила политики.

9. Повторите попытку создать индексатор:

   1. Отправьте запрос изменения для созданного объекта источника данных.
   2. Повторно отправьте запрос на создание индексатора. Используйте новый код для входа, а затем отправьте другой запрос на создание индексатора.

Индексирование неподдерживаемых типов документов

Если вы индексируете содержимое из хранилища Хранилище BLOB-объектов Azure и контейнер содержит BLOB-объекты неподдерживаемого типа содержимого, индексатор пропускает этот документ. В других случаях могут возникнуть проблемы с отдельными документами.

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

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

Отсутствие документов

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

• Вы обновили документ после запуска индексатора. Если ваш индексатор работает по настройке, он в конечном итоге повторно запускается и подымает документ.
• Время ожидания индексатора истекло до того, как документ был обработан. Существует максимальное время обработки, после которого документы не обрабатываются. Вы можете проверить состояние индексатора на портале Azure или вызвать Получить состояние индексатора (REST API).
• Сопоставления полей или обогащение с помощью ИИ изменили документ, и его представление в поисковом индексе отличается от ожидаемого.
• Значения отслеживания изменений являются ошибочными или отсутствуют необходимые условия. Если значение высокого водяного знака — это дата, установленная на будущий момент времени, индексатор пропускает все документы с более ранней датой. Вы можете определить состояние отслеживания изменений индексатора с помощью initialTrackingStatefinalTrackingState полей в состоянии индексатора. Индексаторы для Azure SQL и MySQL должны иметь индекс в столбце высокой отметки исходной таблицы, или запросы, используемые индексатором, могут истечь.

Отсутствует содержимое хранилища блоб-объектов

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

• Документ содержит только отсканированные изображения. Двоичные объекты PDF, которые содержат нетекстовое содержимое, например, отсканированные изображения (JPG), не дают результатов в стандартном конвейере индексирования двоичных объектов. Если у вас есть содержимое изображения с текстовыми элементами, вы можете использовать анализ изображений или OCR для поиска и извлечения текста.

• Индексатор объектов настроен для индексирования только метаданных. Чтобы извлечь содержимое, необходимо настроить индексатор BLOB-объектов для извлечения содержимого и метаданных:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2026-04-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Отсутствует содержимое из Azure Cosmos DB

Поиск ИИ Azure имеет неявную зависимость от индексирования Azure Cosmos DB. Если вы отключите автоматическое индексирование в Azure Cosmos DB, поиск ИИ Azure возвращает успешное состояние, но не сможет индексировать содержимое контейнера. Процессы проверки параметров и включения индексирования описаны в статье Управление индексированием в Azure Cosmos DB.

Несоответствие количества документов между источником данных и индексом

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

• Индекс может отставать от фактического количества документов, особенно в портале Azure.
• Индексатор имеет политику для удаленных документов. Удаленные документы учитываются индексатором, если документы индексируются до их удаления.
• Если столбец идентификатора в источнике данных не является уникальным. Это условие относится к источникам данных, имеющим концепцию столбцов, таких как Azure Cosmos DB.
• Если определение источника данных имеет другой запрос, отличный от используемого для оценки количества записей. Например, в базе данных вы запрашиваете количество записей базы данных, а в запросе определения источника данных вы можете выбрать только подмножество записей для индексирования.
• Счетчики проверяются по разным интервалам для каждого компонента конвейера: источник данных, индексатор и индекс.
• Источник данных содержит файл, связанный со многими документами. Это условие может возникать при индексировании больших двоичных объектов, когда параметр "parsingMode" установлен на jsonArray и jsonLines.

Документы обрабатываются несколько раз

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

• Запросы к индексатору по требованию отправляются один за другим с небольшим интервалом.
• Топология источника данных включает несколько реплик и секций, таких как топология, описанная на уровнях согласованности в Azure Cosmos DB.
• Источник данных — база данных Azure SQL, а столбец, выбранный в качестве "верхней границы", имеет тип datetime2.

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

Пример повторяющейся обработки документов с 30-секундным буфером

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

На практике этот сценарий происходит только при ручном вызове индексаторов по запросу в течение нескольких минут друг от друга для определенных источников данных. Это может привести к несоответствию чисел (например, индексатор обработал всего 345 документов в соответствии со статистикой выполнения индексатора, но в источнике данных и индексе всего 340 документов) или потенциально увеличить затраты, если вы выполняете те же самые навыки для одного и того же документа несколько раз. Запуск индексатора с помощью расписания является предпочтительной рекомендацией.

Параллельное индексирование

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

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

Индексирование документов с метками конфиденциальности

Если вы устанавливаете метки конфиденциальности в документах, возможно, их не удастся индексировать. При возникновении ошибок удалите метки перед индексированием.

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

• Устранение распространенных неполадок с индексаторами и предупреждениями
• Контролировать индексирование на основе индексатора
• Индексирование больших наборов данных