비고
Foundry IQ (Azure AI 검색)는 관리 검색을 위해 고급 수준의 지식 원본 API 및 지식 베이스 API와 함께 직접 인덱싱 및 쿼리 API를 제공합니다. Azure 포털, REST API 또는 Azure SDK 사용하여 이러한 기능을 구성하거나 Microsoft Foundry 포털의 기술 자료에 에이전트를 연결합니다.
적용 대상: Blob 인덱서, 파일 인덱서 (미리 보기)
기본적으로 인덱서는 Blob 또는 파일의 내용을 단일 검색 문서로 처리합니다. 검색 인덱스에서 보다 세부적인 표현을 원하는 경우 parsingMode 값을 설정하여 한 Blob 또는 파일에서 여러 검색 문서를 만들 수 있습니다. 많은 검색 문서를 생성하는 parsingMode 값에는 (delimitedText의 경우) 또는 jsonArray (jsonLines의 경우) 또는 markdown에 대한 하위 모드 oneToMany 가 포함 됩니다.
이러한 구문 분석 모드를 사용하는 경우 나타나는 새 검색 문서에는 고유한 문서 키가 있어야 하며 해당 값의 원본을 결정하는 데 문제가 발생합니다. 부모 Blob의 형식 metadata_storage_path property에 하나 이상의 고유 값이 있지만 둘 이상의 검색 문서에 해당 값을 제공하는 경우 키는 더 이상 인덱스에서 고유하지 않습니다.
이 문제를 해결하기 위해 Blob 인덱서는 단일 Blob 부모에서 파생된 각 자식 검색 문서를 고유하게 식별할 수 있는 문서를 AzureSearch_DocumentKey 생성합니다. 이 문서에서는 이 기능의 작동 방식을 설명합니다.
일대다 문서 키
문서 키는 인덱스의 각 문서를 식별합니다. 기본 Blob 키 매핑은 metadata_storage_path를 사용하지만, 유효 키는 구문 분석 모드 및 매핑에 따라 달라집니다. 기본 매핑이 항상 최종 식별자를 선택한다고 가정하기보다는 이 문서에 설명된 구문 분석된 일치 키의 동작을 검토하세요.
일대다 검색 문서 시나리오에서는 metadata_storage_path property에 기반한 암시적 문서 키를 사용할 수 없습니다. 해결 방법으로 Foundry IQ(Azure AI 검색)는 Blob에서 추출된 각 개별 엔터티에 대한 문서 키를 생성할 수 있습니다. 시스템은 AzureSearch_DocumentKey이라는 키를 생성하여 각 검색 문서에 추가합니다. 인덱서는 각 Blob에서 만든 "많은 문서"를 추적하고 시간이 지남에 따라 원본 데이터가 변경되면 검색 인덱스에 대한 업데이트를 대상으로 지정할 수 있습니다.
기본적으로 키 인덱스 필드에 대한 명시적 필드 매핑이 지정되지 않으면, AzureSearch_DocumentKey가 base64Encode 필드 매핑 함수를 사용하여 해당 필드에 매핑됩니다.
생성된 키 또는 Base64 변환은 권한 부여 경계가 아닙니다. 원본 콘텐츠가 키를 제공하는 경우 키를 제어할 수 있는 사용자와 다른 Blob 또는 인덱서가 동일한 값을 사용할 수 있는지 검토합니다. 단일 blob 내에서의 고유성만으로는 충분하지 않습니다. 문서 식별 정보 및 권한 출처 보호를 참조하세요.
대형 Blob은 하나의 메타데이터 전용 문서를 생성합니다.
Blob 인덱서가 일대다 구문 분석 모드로 indexStorageMetadataOnlyForOversizedDocuments이 true로 설정된 경우 큰 Blob은 콘텐츠 분할기를 우회합니다. 인덱서는 콘텐츠 행당 하나의 문서가 아닌 하나의 메타데이터 전용 문서를 내보낸다.
해당 문서에는 구문 분석된 콘텐츠 키 또는 행 서수가 없습니다. 원시 키 원본은 metadata_storage_path로 대체됩니다. Base64 인코딩을 포함한 기존의 키 변환은 인덱스 키 필드에 기록된 값을 변경할 수 있습니다.
일반 크기 Blob은 기존 키 동작을 유지합니다. 즉, 구성된 콘텐츠 파생 키 또는 Blob 경로와 행 서수를 기반으로 생성된 AzureSearch_DocumentKey를 사용합니다. 다음 표에서는 두 크기를 모두 포함하는 폴더를 보여 줍니다. 최종 인코딩된 인덱스 키가 아닌 원시 키 원본을 표시합니다.
| 원본 콘텐츠 | 생성된 문서 | 원시 키 소스 |
|---|---|---|
| 생성된 키와 두 개의 행이 있는 보통 크기의 JSON Lines blob입니다. | 두 개의 콘텐츠 문서입니다. | Blob 경로와 해당 행 서수(예: {blob-path};{row-ordinal}). |
| 구성된 고유한 콘텐츠 키가 있는 일반 크기의 Blob입니다. | 파싱된 각 행마다 문서 하나. | 각 행의 설정된 콘텐츠 키입니다. |
| 메타데이터 전용 대체가 활성화된 크기가 큰 Blob입니다. | 하나의 메타데이터 전용 문서입니다. |
metadata_storage_path, 행 서수 없이 |
열거 순서는 키 선택을 변경하지 않습니다. 정상 크기의 Blob은 과도하게 큰 Blob의 앞에 있든 뒤에 있든 관계없이 해당 콘텐츠 또는 생성된 키를 유지합니다.
indexStorageMetadataOnlyForOversizedDocuments를 일대다 구문 분석 모드와 결합하면 ACL 수집이 지원되지 않습니다. 이 제한 사항은 JSON Lines, JSON 배열, 구분된 텍스트 및 일대다 Markdown 구문 분석에도 적용됩니다.
Blob이 보통 크기에서 큼으로 또는 오버사이즈에서 일반 크기로 변경되면 해당 키 선택이 변경됩니다. 이전 키에 저장된 문서는 자동으로 삭제되지 않으며 이전 콘텐츠와 ACL 값을 유지할 수 있습니다. 대체 레코드를 만들면 이전 레코드 또는 해당 권한 부여가 제거된다고 가정하지 마세요. 명시적 문서 삭제 또는 적절한 인덱스 재구축을 계획하고 문서 ID 및 권한 신뢰 경계를 유지합니다.
구성 설정 및 원본 크기 제한은 인덱서 오류 처리를 참조하세요.
Example
다음 필드를 사용하여 인덱스 정의를 가정합니다.
idtemperaturepressuretimestamp
Blob 컨테이너에는 다음과 같은 구조의 Blob이 있습니다.
Blob1.json
{ "temperature": 100, "pressure": 100, "timestamp": "2024-02-13T00:00:00Z" }
{ "temperature" : 33, "pressure" : 30, "timestamp": "2024-02-14T00:00:00Z" }
Blob2.json
{ "temperature": 1, "pressure": 1, "timestamp": "2023-01-12T00:00:00Z" }
{ "temperature" : 120, "pressure" : 3, "timestamp": "2022-05-11T00:00:00Z" }
인덱스를 만들고 parsingMode 를 jsonLines 키 필드에 대한 명시적 필드 매핑을 지정하지 않고 설정하면 다음 매핑이 암시적으로 적용됩니다.
{
"sourceFieldName" : "AzureSearch_DocumentKey",
"targetFieldName": "id",
"mappingFunction": { "name" : "base64Encode" }
}
이 설정은 다음 그림과 유사하게 명확한 문서 키를 생성합니다(간단히 하기 위해 base64로 인코딩된 ID가 단축됨).
| 아이디 | 온도 | 압력 | 시간표시 |
|---|---|---|---|
| aHR0 ... YjEuanNvbjsx | 100 | 100 | 2024-02-13T00:00:00Z |
| aHR0 ... YjEuanNvbjsy | 33 | 30 | 2024-02-14T00:00:00Z |
| aHR0 ... YjIuanNvbjsx | 1 | 1 | 2023년 1월 12일 00시 00분 00초 UTC |
| aHR0 ... YjIuanNvbjsy | 120 | 3 | 2022-05-11T00:00:00Z |
인덱스 키 필드에 대한 사용자 지정 필드 매핑
이전 예제와 동일한 인덱스 정의를 가정하면 Blob 컨테이너에 다음 구조의 Blob이 있다고 가정합니다.
Blob1.json
recordid, temperature, pressure, timestamp
1, 100, 100,"2024-02-13T00:00:00Z"
2, 33, 30,"2024-02-14T00:00:00Z"
Blob2.json
recordid, temperature, pressure, timestamp
1, 1, 1,"2023-01-12T00:00:00Z"
2, 120, 3,"2022-05-11T00:00:00Z"
delimitedText를 사용하여 인덱서 를 만들 때 다음과 같이 키 필드에 필드 매핑 함수를 설정하는 것이 자연스럽게 느껴질 수 있습니다.
{
"sourceFieldName" : "recordid",
"targetFieldName": "id"
}
그러나 이 매핑은 필드가 recordid 간에 고유하지 않으므로 인덱스에 4개의 문서가 표시되지 않습니다. 따라서 AzureSearch_DocumentKey 속성에서 적용된 암시적 필드 매핑을 “일대다” 구문 분석 모드의 키 인덱스 필드에 사용하는 것이 좋습니다.
명시적 필드 매핑을 설정하려면 모든 Blob에서 각 개별 엔터티에 대해 sourceField가 고유해야 합니다.
비고
추출된 엔터티당 고유성을 보장하는 데 사용되는 AzureSearch_DocumentKey 접근 방식은 변경될 수 있으므로 애플리케이션의 요구에 따라 해당 값에 의존해서는 안 됩니다.
데이터에서 인덱스 키 필드 지정
첫 번째 예제와 같이 매핑이 표시되도록 명시적 필드 매핑을 지정하지 않고 이전 예제 및 parsingMode 와 동일한 인덱스 정의를 설정 jsonLines 한다고 가정하면 Blob 컨테이너에 다음 구조의 Blob이 있다고 가정합니다.
이러한 입력은 Blob에서 중복 키를 보여 줍니다. 이는 별도의 레코드에 권장되는 구성이 아닙니다.
Blob1.json
{ "id": "1", "temperature": 100, "pressure": 100, "timestamp": "2024-02-13T00:00:00Z" }
{ "id": "2", "temperature": 33, "pressure": 30, "timestamp": "2024-02-14T00:00:00Z" }
Blob2.json
{ "id": "1", "temperature": 1, "pressure": 1, "timestamp": "2023-01-12T00:00:00Z" }
{ "id": "2", "temperature": 120, "pressure": 3, "timestamp": "2022-05-11T00:00:00Z" }
각 문서에는 인덱스의 id 필드로 정의하는 필드가 key 포함됩니다. 이 경우 시스템은 문서에 대한 AzureSearch_DocumentKey를 생성하지만 키로 사용하지는 않습니다. 대신 필드 값이 id 키 필드에 매핑됩니다.
이전 예제와 마찬가지로 이 매핑은 필드가 id에서 고유하지 않기 때문에 인덱스에 4개의 문서가 표시되지 않습니다. 이 상황이 발생하면 JSON 항목을 지정 id 하면 새 문서를 업로드하는 대신 기존 문서와 병합됩니다. 그러면 인덱스는 지정된 id항목의 최신 상태를 반영합니다.
제한점
이 문서에서 설명한 대로 인덱스의 문서 항목이 파일의 한 줄에서 만들어지면 파일에서 해당 줄을 삭제해도 인덱스에서 해당 항목이 자동으로 제거되지는 않습니다. 문서 항목을 삭제하려면 REST API 삭제 작업을 사용하여 인덱스로 삭제 요청을 수동으로 제출해야 합니다.
키 매핑을 변경하면 레코드가 이전 키 아래에 남을 수도 있습니다. 생성된 키, 다시 설정 또는 권한 새로 고침은 문서 소유권을 설정하지 않습니다. 키 선택은 수집 작성 권한이 있는 작성자가 제어하도록 유지합니다. 문서 ID 및 사용 권한 출처 보호를 참조하세요.
다음 단계
Blob 인덱싱의 기본 구조 및 워크플로에 아직 익숙하지 않은 경우 먼저 Foundry IQ를 사용하여 인덱싱 Azure Blob Storage 검토해야 합니다. 다양한 Blob 콘텐츠 형식의 구문 분석 모드에 대한 자세한 내용은 다음 문서를 검토하세요.