Azure AI 검색에 대한 인덱서 문제 해결 지침

아티클
09/03/2024

경우에 따라 인덱서에는 오류가 생성되지 않거나 다른 Azure 서비스에서 발생하는 문제(예: 인증 중 또는 연결 중에)가 발생합니다. 이 문서에서는 안내해 주는 메시지가 없는 경우 인덱서 문제를 해결하는 데 중점을 둡니다. 또한 인덱싱 중에 사용되는 검색 대상이 아닌 리소스에서 발생하는 오류에 대한 문제 해결을 제공합니다.

참고 항목

조사해야 할 Azure AI 검색 오류가 있는 경우 대신 일반적인 인덱서 오류 및 경고 문제 해결을 참조하세요.

제한된 리소스에 대한 연결 문제 해결

Azure 네트워크 보안이 적용되는 데이터 원본의 경우 인덱서는 연결 방법이 제한됩니다. 현재 인덱서는 공유 프라이빗 링크를 사용하여 IP 방화벽 뒤 또는 프라이빗 엔드포인트를 통해 가상 네트워크에서 제한된 데이터 원본에 액세스할 수 있습니다.

방화벽 규칙

Azure Storage, Azure Cosmos DB 및 Azure SQL은 구성 가능한 방화벽을 제공합니다. 방화벽이 요청을 차단할 때 구체적인 오류 메시지는 없습니다. 일반적으로 방화벽 오류는 일반적입니다. 일반적인 오류는 다음과 같습니다.

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 주소 및 AzureCognitiveSearch 서비스 태그의 IP 주소 범위에 대한 인바운드 규칙을 구성합니다. 각 데이터 원본 유형에 대한 IP 주소 범위 제한 구성에 대한 자세한 내용은 다음 링크에서 확인할 수 있습니다.
최후의 수단으로 또는 임시 조치로, 모든 네트워크에서의 액세스를 허용하여 방화벽을 사용하지 않도록 설정합니다.

제한: IP 주소 범위 제한은 검색 서비스와 스토리지 계정이 서로 다른 지역에 있는 경우에만 작동합니다.

인덱서는 데이터 검색 외에도 기술 세트 및 사용자 지정 기술을 통해 아웃바운드 요청을 보냅니다. Azure 함수를 기반으로 하는 사용자 지정 기술의 경우 Azure 함수에도 IP 주소 제한이 있다는 점에 유의하세요. 사용자 지정 기술 실행을 허용할 IP 주소 목록에는 검색 서비스의 IP 주소 및 AzureCognitiveSearch 서비스 태그의 IP 주소 범위가 포함됩니다.

NSG(네트워크 보안 그룹) 규칙

인덱서가 SQL 관리되는 인스턴스의 데이터에 액세스하거나 Azure VM이 사용자 지정 기술에 대한 웹 서비스 URI로 사용되는 경우 네트워크 보안 그룹은 요청이 허용되는지 여부를 결정합니다.

가상 네트워크에 있는 외부 리소스의 경우 AzureCognitiveSearch 서비스 태그에 대한 인바운드 NSG 규칙을 구성합니다.

가상 머신 연결에 대한 자세한 내용은 Azure VM에서 SQL Server 연결 구성을 참조하세요.

네트워크 오류

일반적으로 네트워크 오류는 일반적입니다. 일반적인 오류는 다음과 같습니다.

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 Portal의 리소스에서 현재 오류 또는 중단이 있는지 확인합니다.
Azure 상태에서 네트워크 중단을 확인합니다.
이름 확인에 Azure 프라이빗 DNS가 아닌 공용 DNS를 사용하고 있는지 확인합니다.

Azure SQL 데이터베이스 서버리스 인덱싱(오류 코드 40613)

SQL 데이터베이스가 서버리스 컴퓨팅 계층에 있는 경우 인덱서가 연결될 때 데이터베이스가 실행 중이고 일시 중지되지 않았는지 확인합니다.

데이터베이스가 일시 중지된 경우 검색 서비스에서 처음 로그인하면 데이터베이스가 자동으로 다시 시작되어야 하지만 대신 데이터베이스를 사용할 수 없다는 오류가 반환되고 오류 코드 40613이 표시됩니다. 데이터베이스가 실행된 후 로그인을 다시 시도하여 연결을 설정합니다.

Microsoft Entra 조건부 액세스 정책

SharePoint Online 인덱서를 만들 때 디바이스 코드를 제공한 후 Microsoft Entra 앱에 로그인해야 하는 단계가 있습니다. "Your sign-in was successful but your admin requires the device requesting access to be managed" 메시지가 표시되면 조건부 액세스 정책으로 인해 인덱서가 SharePoint 문서 라이브러리에서 차단되었을 수 있습니다.

정책을 업데이트하고 문서 라이브러리에 대한 인덱서 액세스를 허용하려면 다음을 수행합니다.

Azure Portal을 열고 Microsoft Entra 조건부 액세스를 검색합니다.
왼쪽 메뉴에서 정책을 선택합니다. 이 페이지를 볼 수 있는 액세스 권한이 없는 경우 액세스 권한이 있는 사용자를 찾거나 액세스 권한을 받아야 합니다.
SharePoint Online 인덱서에서 문서 라이브러리에 액세스하지 못하도록 차단하는 정책을 확인합니다. 인덱서를 차단할 수 있는 정책에는 사용자 및 그룹 섹션의 인덱서 만들기 단계에서 인증하는 데 사용한 사용자 계정이 포함됩니다. 정책에는 다음과 같은 조건도 있을 수 있습니다.
- Windows 플랫폼을 제한합니다.
- 모바일 앱 및 데스크톱 클라이언트를 제한합니다.
- 디바이스 상태를 예로 구성합니다.
인덱서를 차단하는 정책을 확인했으면 인덱서에 대해 예외를 적용합니다. 검색 서비스 IP 주소를 검색하여 시작합니다.

먼저 검색 서비스의 FQDN(정규화된 도메인 이름)을 가져옵니다. FQDN은 <your-search-service-name>.search.windows.net과 같습니다. Azure Portal에서 FQDN을 찾을 수 있습니다.

이제 FQDN이 있으므로 FQDN의 nslookup(또는 ping)을 수행하여 검색 서비스의 IP 주소를 가져옵니다. 다음 예제에서는 Azure Storage 방화벽의 인바운드 규칙에 "150.0.0.1"을 추가합니다. 검색 서비스 인덱서에서 Azure Storage 계정에 액세스할 수 있도록 방화벽 설정이 업데이트될 때까지 최대 15분이 걸릴 수 있습니다.
```
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
```
해당 지역의 인덱서 실행 환경에 대한 IP 주소 범위를 가져옵니다.

추가 IP 주소는 인덱서의 다중 테넌트 실행 환경에서 발생하는 요청에 사용됩니다. 이 IP 주소 범위는 서비스 태그에서 가져올 수 있습니다.

AzureCognitiveSearch 서비스 태그의 IP 주소 범위는 검색 API 또는 다운로드 가능한 JSON 파일을 통해 가져올 수 있습니다.

이 연습에서는 검색 서비스가 Azure 퍼블릭 클라우드라고 가정하여 Azure 퍼블릭 JSON 파일을 다운로드해야 합니다.

검색 서비스가 미국 중서부에 있다고 가정하면 JSON 파일에서 다중 테넌트 인덱서 실행 환경에 대한 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"
        ]
      }
    }
```
Azure Portal의 조건부 액세스 페이지로 돌아가서 왼쪽 메뉴에서 명명된 위치를 선택한 다음, + IP 범위 위치를 선택합니다. 새로 명명된 위치의 이름을 지정하고, 마지막 두 단계에서 수집한 검색 서비스 및 인덱서 실행 환경에 대한 IP 범위를 추가합니다. 1
- 검색 서비스 IP 주소의 경우 유효한 IP 범위만 허용하므로 "/32"를 IP 주소 끝에 추가해야 할 수 있습니다.
- 인덱서 실행 환경 IP 범위의 경우 검색 서비스가 있는 지역의 IP 범위만 추가하면 됩니다.
정책에서 새 명명된 위치를 제외합니다.
1. 왼쪽 메뉴에서 정책을 선택합니다.
2. 인덱서를 차단하는 정책을 선택합니다.
3. 조건을 선택합니다.
4. 위치를 선택합니다.
5. 제외를 선택한 다음, 새 명명된 위치를 추가합니다.
6. 변경 내용을 저장합니다.
정책에서 새 정책 규칙을 업데이트하고 적용할 때까지 몇 분 정도 기다립니다.
인덱서 만들기를 다시 시도합니다.
1. 만든 데이터 원본 개체에 대한 업데이트 요청을 보냅니다.
2. 인덱서 만들기 요청을 다시 보냅니다. 새 코드를 사용하여 로그인한 다음, 다른 인덱서 만들기 요청을 보냅니다.

지원되지 않는 문서 형식 인덱싱

Azure Blob Storage의 콘텐츠를 인덱싱하고 컨테이너에 지원되지 않는 콘텐츠 형식의 Blob이 포함된 경우 인덱서가 해당 문서를 건너뜁니다. 다른 경우에는 개별 문서에 문제가 있을 수 있습니다.

이러한 상황에서는 개별 문서에 문제가 있는 경우 인덱서 처리를 계속할 수 있도록 구성 옵션을 설정할 수 있습니다.

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

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

누락된 문서

인덱서가 외부 데이터 원본에서 문서 또는 행을 추출하고 검색 서비스를 통해 인덱싱되는 검색 문서를 만듭니다. 경우에 따라 데이터 원본에 있는 문서가 검색 인덱스에 나타나지 않습니다. 이 예기치 않은 결과는 다음과 같은 이유로 인해 발생할 수 있습니다.

문서는 인덱서 실행 후에 업데이트되었습니다. 인덱서가 일정대로 진행되는 경우 결국 문서를 다시 실행하고 선택합니다.
문서를 수집하기 전에 인덱서의 시간이 초과되었습니다. 최대 처리 시간 제한이 있으며 그 이후에는 문서가 처리되지 않습니다. 포털에서 또는 인덱서 상태 가져오기(REST API)를 호출하여 인덱서 상태를 확인할 수 있습니다.
필드 매핑 또는 AI 보강으로 문서가 변경되었으며 검색 인덱스의 설명이 예상과 다릅니다.
변경 추적 값이 잘못되거나 필수 구성 조건이 누락되었습니다. 높은 워터마크 값이 이후 시간으로 설정된 날짜인 경우, 이 값보다 이전인 날짜를 가진 문서는 인덱서에서 건너뜁니다. 인덱서 상태에서 'initialTrackingState' 및 'finalTrackingState' 필드를 사용하여 인덱서의 변경 내용 추적 상태를 확인할 수 있습니다. Azure SQL 및 MySQL용 인덱서에는 원본 테이블의 높은 워터 마크 열에 인덱스가 있어야 합니다. 그렇지 않은 경우 인덱서에서 사용하는 쿼리가 시간 초과될 수 있습니다.

팁

문서가 누락된 경우 사용 중인 쿼리를 확인하여 해당 문서를 제외하지 않는지 확인합니다. 특정 문서를 쿼리하려면 문서 조회 REST API를 사용합니다.

Blob Storage에서 누락된 콘텐츠

Blob 인덱서는 컨테이너의 blob에서 텍스트를 찾아서 추출합니다. 텍스트 추출에 대한 몇 가지 문제는 다음과 같습니다.

문서에는 스캔된 이미지만 포함됩니다. 스캔된 이미지(JPG)와 같은 텍스트가 아닌 콘텐츠를 포함한 PDF Blob은 표준 Blob 인덱싱 파이프라인에서 결과를 생성하지 않습니다. 텍스트 요소가 포함된 이미지 콘텐츠가 있는 경우 OCR 또는 이미지 분석을 사용하여 텍스트를 찾고 추출할 수 있습니다.
Blob 인덱서는 메타데이터를 인덱스하도록 구성됩니다. 콘텐츠를 추출하려면 콘텐츠 및 메타데이터를 모두 추출하도록 Blob 인덱서를 구성해야 합니다.

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

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

Azure Cosmos DB에서 누락된 콘텐츠

Azure AI 검색에는 Azure Cosmos DB 인덱싱에 대한 암시적 종속성이 있습니다. Azure Cosmos DB에서 자동 인덱싱을 끄면 Azure AI 검색은 성공 상태를 반환하지만 컨테이너 콘텐츠를 인덱싱하지 못합니다. 설정을 확인하고 인덱싱을 설정하는 방법에 대한 지침은 Azure Cosmos DB에서 인덱싱 관리를 참조하세요.

데이터 원본과 인덱스 간의 문서 수 불일치

인덱서는 데이터 원본, 인덱스 자체 또는 코드의 개수와 다른 문서 수를 표시할 수 있습니다. 이 동작이 발생할 수 있는 몇 가지 이유는 다음과 같습니다.

인덱스가 실제 문서 수를 표시하는 데 지연이 될 수 있습니다(특히 포털에서).
인덱서에 삭제된 문서 정책이 있습니다. 문서가 삭제되기 전에 인덱싱된 경우 삭제된 문서는 인덱서 개수에 포함됩니다.
데이터 원본의 ID 열이 고유하지 않은 경우. 이는 Azure Cosmos DB와 같은 열 개념이 있는 데이터 원본의 경우입니다.
데이터 원본 정의에 레코드 수를 예측하는 데 사용하는 쿼리와 다른 쿼리가 있는 경우. 예를 들어, 데이터베이스에서는 데이터베이스 레코드 수를 쿼리하는 반면, 데이터 원본 정의 쿼리에서는 인덱싱할 레코드의 하위 집합만 선택할 수 있습니다.
개수가 파이프라인의 각 구성 요소(데이터 원본, 인덱서 및 인덱스)에 대해 서로 다른 간격으로 검사됩니다.
데이터 원본에 여러 문서에 매핑된 파일이 있습니다. 이 조건은 Blob 인덱싱 및 “parsingMode”가 jsonArray 및 jsonLines로 설정된 경우에 발생할 수 있습니다.

여러 번 처리된 문서

인덱서는 보수적인 버퍼링 전략을 사용하여 데이터 원본의 모든 새 문서와 변경된 문서가 인덱싱 중에 선택되도록 합니다. 특정 상황에서는 이러한 버퍼가 겹쳐서 인덱서가 문서를 두 번 이상 인덱싱하여 처리된 문서 수가 데이터 원본의 실제 문서 수보다 많아질 수 있습니다. 이 동작은 중복 문서와 같은 인덱스에 저장된 데이터에는 영향을 주지 않지만 단지 최종적인 일관성에 도달하는 데 시간이 더 오래 걸릴 수 있습니다. 이 조건은 다음 조건 중 어느 것이라도 참인 경우에 특히 널리 퍼집니다.

주문형 인덱서 요청이 빠른 연속으로 실행됨
데이터 원본의 토폴로지에 여러 복제본 및 파티션이 포함됨(이러한 예제 중 하나는 여기에 설명되어 있음)
데이터 원본은 Azure SQL 데이터베이스이며 “높은 워터마크”로 선택한 열은 datetime2 형식입니다.

인덱서는 빠르게 연속해서 여러 번 호출할 수 없습니다. 업데이트가 신속하게 필요한 경우 지원되는 방법은 데이터 원본을 동시에 업데이트하는 동안 인덱스에 업데이트를 푸시하는 것입니다. 주문형 처리의 경우 요청 속도를 5분 이상 간격으로 실행하고 일정에 따라 인덱서를 실행하는 것이 좋습니다.

30초 버퍼를 사용하는 중복 문서 처리의 예

문서가 두 번 처리되는 조건은 각 작업 및 카운터 작업을 기록하는 다음 타임라인에 설명되어 있습니다. 다음 타임라인은 이슈를 보여 줍니다.

타임라인(hh:mm:ss)	이벤트	인덱서 상위 워터마크	Comment(설명)
00:01:00	최종 일관성에 맞춰 `doc1`을 데이터 원본에 쓰기	`null`	문서 타임스탬프는 00:01:00입니다.
00:01:05	최종 일관성에 맞춰 `doc2`을 데이터 원본에 쓰기	`null`	문서 타임스탬프는 00:01:05입니다.
00:01:10	인덱서 시작	`null`
00:01:11	인덱서가 00:01:10 이전의 모든 변경 내용을 쿼리합니다. 인덱서가 쿼리하는 복제본은 `doc2`만 인식합니다. `doc2`만 검색됩니다.	`null`	인덱서는 타임스탬프를 시작하기 전에 모든 변경 내용을 요청하지만 실제로 하나의 하위 집합을 받습니다. 이 동작을 수행하려면 룩백(look back) 버퍼 기간이 필요합니다.
00:01:12	인덱서가 처음으로 `doc2`를 처리함	`null`
00:01:13	인덱서 종료	00:01:10	상위 워터마크는 현재 인덱서 실행의 시작 타임스탬프로 업데이트됩니다.
00:01:20	인덱서 시작	00:01:10
00:01:21	인덱서가 00:00:40에서 00:01:20 사이의 모든 변경 내용을 쿼리합니다. 인덱서가 쿼리하는 복제본은 `doc1` 및 `doc2` 모두를 인식하고, `doc1` 및 `doc2`를 검색합니다.	00:01:10	인덱서는 현재 상위 워터마크에서 30초 버퍼를 뺀 모든 변경 내용과 현재 인덱서 실행의 시작 타임스탬프를 요청합니다.
00:01:22	인덱서가 처음으로 `doc1`를 처리함	00:01:10
00:01:23	인덱서가 두 번째로 `doc2`를 처리함	00:01:10
00:01:24	인덱서 종료	00:01:20	상위 워터마크는 현재 인덱서 실행의 시작 타임스탬프로 업데이트됩니다.
00:01:32	인덱서 시작	00:01:20
00:01:33	인덱서가 00:00:50에서 00:01:32 사이의 모든 변경 내용을 쿼리하고, `doc1` 및 `doc2`를 검색합니다.	00:01:20	인덱서는 현재 상위 워터마크에서 30초 버퍼를 뺀 모든 변경 내용과 현재 인덱서 실행의 시작 타임스탬프를 요청합니다.
00:01:34	인덱서가 두 번째로 `doc1`를 처리함	00:01:20
00:01:35	인덱서가 세 번째로 `doc2`를 처리함	00:01:20
00:01:36	인덱서 종료	00:01:32	상위 워터마크는 현재 인덱서 실행의 시작 타임스탬프로 업데이트됩니다.
00:01:40	인덱서 시작	00:01:32
00:01:41	인덱서가 00:01:02에서 00:01:40 사이의 모든 변경 내용을 쿼리하고, `doc2`를 검색합니다.	00:01:32	인덱서는 현재 상위 워터마크에서 30초 버퍼를 뺀 모든 변경 내용과 현재 인덱서 실행의 시작 타임스탬프를 요청합니다.
00:01:42	인덱서가 네 번째로 `doc2`를 처리함	00:01:32
00:01:43	인덱서 종료	00:01:40	이 인덱서 실행은 데이터 원본에 대한 마지막 쓰기 이후 30초 이상 지나서 시작되었으며 `doc2`도 처리했습니다. 이는 00:01:35 이전의 모든 인덱서 실행이 제거되면 경우 `doc1` 및 `doc2`를 처리하는 최초이자 유일한 실행이 되기 때문에 예상되는 동작입니다.

실제로 이 시나리오는 특정 데이터 원본에 대해 주문형 인덱서가 몇 분 내에 수동으로 호출되는 경우에만 발생합니다. 인덱서가 인덱서 실행 통계에 따라 총 345개의 문서를 처리했지만 데이터 원본 및 인덱스에는 340개의 문서가 있는 경우처럼 숫자가 일치하지 않거나 동일한 문서에 대해 동일한 기술을 여러 번 실행하면 청구가 증가할 수 있습니다. 일정을 사용한 인덱서 실행이 권장됩니다.

병렬 인덱싱

여러 인덱서가 동시에 작동하는 경우 일부 인덱서가 큐에 들어가 사용 가능한 리소스가 실행을 시작할 때까지 기다리는 것이 일반적입니다. 동시에 실행할 수 있는 인덱서 수는 여러 요인에 따라 달라집니다. 인덱서가 기술 세트와 연결되지 않은 경우 병렬 실행 용량은 AI Search Service에 설정된 복제본 및 파티션 수에 따라 달라집니다.

반면에 인덱서가 기술 세트와 연결된 경우 AI 검색의 내부 클러스터 내에서 작동합니다. 이 경우 동시에 실행할 수 있는 기능은 기술 세트의 복잡성과 다른 기술 세트가 동시에 실행되는지 여부에 따라 결정됩니다. 기본 제공 인덱서는 원본에서 데이터를 안정적으로 추출하도록 설계되었으므로 일정에 따라 실행되는 경우 데이터가 누락되지 않습니다. 다만, 병렬화 및 수평 크기 조정의 인덱서 프로세스에는 다소 시간이 필요할 것으로 예상됩니다.

민감도 레이블을 사용하여 문서 인덱싱

문서에 민감도 레이블이 설정된 경우 인덱싱하지 못할 수 있습니다. 오류가 발생하는 경우 인덱싱 전에 레이블을 제거합니다.

다음을 통해 공유