자습서: 디버그 세션을 사용하여 기술 세트 수정

아티클
12/03/2024

Azure AI 검색에서 기술 세트는 검색 가능한 콘텐츠를 분석, 변환 또는 만드는 기술의 작업을 조정합니다. 한 기술의 출력이 다른 기술의 입력이 되는 경우가 많습니다. 입력이 출력에 종속되는 경우 기술 세트 정의 및 필드 연결에 실수가 있으면 작업 및 데이터가 누락될 수 있습니다.

디버그 세션은 Azure AI Search에서 실행되는 기술 세트의 전체적인 시각화를 제공하는 Azure Portal 도구입니다. 이 도구를 사용하면 특정 단계로 드릴다운하여 작업이 중단될 수 있는 위치를 쉽게 확인할 수 있습니다.

이 문서에서는 디버그 세션을 사용하여 누락된 입출력을 찾아 수정합니다. 이 자습서는 포괄적입니다. 샘플 데이터, 개체를 만드는 REST 파일, 기술 세트의 문제 디버깅을 위한 지침을 제공합니다.

Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다.

필수 조건

Azure AI 검색. 서비스를 만들거나 현재 구독에서 기존 서비스를 찾습니다. 이 자습서에서는 체험 서비스를 사용할 수 있습니다. 무료 계층은 Azure AI Search 서비스에 대한 관리 ID 지원을 제공하지 않습니다. Azure Storage에 연결하려면 키를 사용해야 합니다.
샘플 데이터를 호스팅하고 디버그 세션 중에 만들어진 캐시 데이터를 유지하는 데 사용되는 Blob Storage가 있는 Azure Storage 계정입니다. 무료 검색 서비스를 사용하는 경우 스토리지 계정에 공유 액세스 키가 활성화되어 있어야 하며 공용 네트워크 액세스를 허용해야 합니다.
Visual Studio Code와 REST 클라이언트.
샘플 PDF(임상 시험).
보강 파이프라인을 만드는 데 사용되는 샘플 debug-sessions.rest 파일입니다.

참고 항목

이 자습서에서는 언어 인식, 엔터티 인식 및 핵심 구 추출을 위해 Azure AI Services도 사용합니다. 워크로드가 너무 작으므로 Azure AI Services는 최대 20개의 트랜잭션을 무료로 처리하기 위해 백그라운드에서 탭으로 처리됩니다. 즉, 청구 가능한 Azure AI Services 리소스를 만들지 않고도 이 연습을 완료할 수 있습니다.

샘플 데이터 설정

이 섹션에서는 인덱서 및 기술 세트에 작업할 콘텐츠가 있도록 Azure Blob Storage에 샘플 데이터 세트를 만듭니다.

19개 파일로 구성된 샘플 데이터(clinical-trials-pdf-19)를 다운로드합니다.
Azure Storage 계정을 만들거나 기존 계정을 찾습니다.
- 대역폭 요금이 부과되지 않도록 Azure AI Search와 동일한 지역을 선택합니다.
- StorageV2(범용 V2) 계정 유형을 선택합니다.
포털에서 Azure Storage 서비스 페이지로 이동하여 Blob 컨테이너를 만듭니다. 액세스 수준을 "프라이빗"으로 지정하는 것이 가장 좋습니다. 컨테이너 이름을 clinicaltrialdataset으로 지정합니다.
컨테이너에서 업로드를 선택하여 첫 번째 단계에서 다운로드하고 압축을 푼 샘플 파일을 업로드합니다.
포털에서 Azure Storage에 대한 연결 문자열을 복사합니다. 연결 문자열은 포털의 설정>액세스 키에서 가져올 수 있습니다.

키 및 URL 복사

이 자습서에서는 인증 및 권한 부여에 API 키를 사용합니다. Azure Portal에서 가져올 수 있는 검색 서비스 엔드포인트 및 API 키가 필요합니다.

Azure Portal에 로그인하고 개요 페이지로 이동하여 URL을 복사합니다. 엔드포인트의 예는 다음과 같습니다. https://mydemo.search.windows.net
설정>키에서 관리자 키를 복사합니다. 관리자 키는 개체를 추가, 수정, 삭제하는 데 사용됩니다. 교환 가능한 관리자 키는 2개입니다. 둘 중 하나를 복사합니다.

유효한 API 키는 요청별로 요청을 보내는 애플리케이션과 이를 처리하는 검색 서비스 간에 신뢰를 설정합니다.

데이터 원본, 기술 세트, 인덱스 및 인덱서 만들기

이 섹션에서는 이 자습서에서 수정할 수 있는 "버그가 있는" 워크플로를 만듭니다.

Visual Studio Code를 시작하고 debug-sessions.rest 파일을 엽니다.
검색 서비스 URL, 검색 서비스 관리 API 키, 스토리지 연결 문자열, PDF를 저장하는 Blob 컨테이너 이름 등의 변수를 제공합니다.
각 요청을 차례로 보냅니다. 인덱서 만들기를 완료하는 데 몇 분 정도 걸립니다.
파일을 닫습니다.

포털에서 결과 확인

샘플 코드는 기술 세트 실행 중에 발생한 문제의 결과로 버그가 있는 인덱스를 의도적으로 만듭니다. 문제는 인덱스에 데이터가 없다는 것입니다.

Azure Portal의 검색 서비스 개요 페이지에서 인덱스 탭을 선택합니다.
임상 시험을 선택합니다.
검색 탐색기의 JSON 보기에 이 JSON 쿼리 문자열을 입력합니다. 특정 문서에 대한 필드를 반환합니다(고유한 metadata_storage_path 필드로 식별됨).
```
"search": "*",
"select": "metadata_storage_path, organizations, locations",
"count": true
```
쿼리를 실행합니다. organizations 및 locations에 대한 빈 값이 표시되어야 합니다.

이러한 필드는 Blob의 콘텐츠 내에서 조직과 위치를 검색하는 데 사용되는 기술 세트의 엔터티 인식 기술을 통해 채워져야 합니다. 다음 연습에서는 기술 세트를 디버그하여 무엇이 잘못되었는지 확인합니다.

오류 및 경고를 조사하는 또 다른 방법은 Azure Portal을 통하는 것입니다.

인덱서 탭을 열고 clinical-trials-idxr을 선택합니다.

인덱서 작업은 전반적으로 성공했지만 경고가 발생했습니다.
성공을 선택하여 경고를 확인합니다(대부분 오류가 있으면 세부 정보 링크는 실패함입니다). 인덱서에서 내보낸 모든 경고의 긴 목록이 표시됩니다.

디버그 세션 시작

검색 서비스 왼쪽 탐색 창의 검색 관리에서 디버그 세션을 선택합니다.
+ 디버그 세션 추가를 선택합니다.
세션 이름을 지정합니다.
인덱서 템플릿에서 인덱서 이름을 제공합니다. 인덱서에는 데이터 원본, 기술 세트 및 인덱스에 대한 참조가 있습니다.
스토리지 계정을 선택합니다.
세션을 저장합니다.
디버그 세션이 설정 페이지로 열립니다. 초기 구성을 수정하고 기본값을 재정의할 수 있습니다. 디버그 세션은 단일 문서에서만 작동합니다. 기본값은 디버그 세션의 기초로 컬렉션의 첫 번째 문서를 수락하는 것입니다. Azure Storage에서 해당 URI를 제공하여 디버그할 특정 문서를 선택할 수 있습니다.
디버그 세션 초기화가 완료되면 매핑 및 검색 인덱스가 있는 기술 워크플로가 표시됩니다. 보강된 문서 데이터 구조가 측면의 세부 정보 창에 나타납니다. 워크플로를 더 많이 볼 수 있도록 다음 스크린샷에서 제외했습니다.

기술 세트 관련 문제 찾기

인덱서에서 보고한 모든 문제는 오류 및 경고로 표시됩니다.

이 목록은 단일 문서에 대한 오류만 자세히 설명하므로 오류 및 경고 수는 이전에 표시된 목록보다 훨씬 작은 목록입니다. 인덱서에서 표시하는 목록과 마찬가지로 경고 메시지를 선택하면 이 경고의 세부 정보를 볼 수 있습니다.

경고를 선택하여 알림을 검토합니다. 네 가지가 표시됩니다.

"하나 이상의 기술 입력이 잘못되었으므로 기술을 실행할 수 없습니다. 필수 기술 입력이 없습니다. 이름: "텍스트", 원본: "/문서/콘텐츠"."
"출력 필드 'locations'를 검색 인덱스에 매핑할 수 없습니다. 인덱서의 'outputFieldMappings' 속성을 확인하십시오. '/document/merged_content/locations' 값이 없습니다."
"출력 필드 'organizations'를 검색 인덱스에 매핑할 수 없습니다. 인덱서의 'outputFieldMappings' 속성을 확인하십시오. '/document/merged_content/organizations' 값이 없습니다."
"기술이 실행되었지만 하나 이상의 기술 입력이 잘못되었기 때문에 예기치 못한 결과가 발생할 수 있습니다. 선택적 기술 입력이 누락되었습니다. 이름: 'languageCode', 원본: '/document/languageCode'. 식 언어 구문 분석 문제: 값 '/document/languageCode'가 없습니다".

많은 기술에 "languageCode" 매개 변수가 있습니다. 작업을 검사하면 언어 코드 입력이 EntityRecognitionSkill.#1('locations' 및 'organizations' 출력에 문제가 있는 동일한 엔터티 인식 기술임)에서 누락된 것을 알 수 있습니다.

네 가지 알림이 모두 이 기술에 대한 것이므로 다음 단계는 이 기술을 디버깅하는 것입니다. 가능하면 출력 문제로 이동하기 전에 먼저 입력 문제를 해결하는 것부터 시작합니다.

누락된 기술 입력 값 수정

작업 화면에서 경고를 보고하는 기술을 선택합니다. 이 자습서에서는 엔터티 인식 기술입니다.
기술 세부 정보 창은 반복 및 해당 입력 및 출력에 대한 섹션, 기술의 JSON 정의에 대한 기술 설정, 이 기술이 내보내는 오류 및 경고에 대한 메시지와 함께 오른쪽에 열립니다.
각 입력을 마우스로 가리키거나 입력을 선택하여 식 계산기에서 값을 표시합니다. 이 입력에 대해 표시된 결과는 텍스트 입력처럼 보이지 않습니다. 텍스트 대신 일련의 새 줄 바꿈 문자 \n \n\n\n\n처럼 보입니다. 텍스트가 없다는 것은 엔터티를 식별할 수 없음을 의미하므로 이 문서가 기술의 필수 조건을 충족하지 못하거나 대신 사용해야 하는 다른 입력이 있습니다.
보강된 데이터 구조로 다시 전환하고 이 문서의 보강 노드를 검토합니다. "content"에 대한 \n \n\n\n\n에는 원본 원본이 없지만 "merged_content"에 대한 다른 값에는 OCR 출력이 있습니다. 표시는 없지만 이 PDF의 콘텐츠는 "merged_content"에서 추출되고 처리된 텍스트에서 알 수 있듯이 JPEG 파일인 것으로 보입니다.
기술로 다시 전환하고 기술 세트 설정을 선택하여 JSON 정의를 엽니다.
식을 /document/content에서 /document/merged_content로 변경한 다음 저장을 선택합니다. 경고가 더 이상 나열되지 않습니다.
세션 창 메뉴에서 실행을 선택합니다. 그러면 문서를 사용하여 기술 세트의 다른 실행이 시작됩니다.
디버그 세션 실행이 완료되면 경고 수가 1씩 감소합니다. 경고는 텍스트 입력에 대한 오류가 사라졌지만 다른 경고는 남아 있음을 보여 줍니다. 다음 단계는 누락되거나 빈 값 /document/languageCode에 대한 경고를 해결하는 것입니다.
기술을 선택하고 /document/languageCode를 마우스로 가리킵니다. 이 입력의 값은 유효한 입력이 아닌 null입니다.
이전 문제와 마찬가지로, 먼저 보강된 데이터 구조에서 해당 노드의 증거를 검토합니다. "언어코드" 노드는 없지만 "언어"에 대한 노드는 있습니다. 따라서 기술 설정에 오타가 있습니다.
/document/language 식을 복사합니다.
기술 세부 정보 창에서 #1 기술에 대한 기술 설정을 선택하고 새 값 /document/language을 붙여넣습니다.
저장을 선택합니다.
실행을 선택합니다.
디버그 세션 실행이 완료되면 기술 세부 정보 창에서 결과를 확인할 수 있습니다. /document/language를 마우스로 가리키면 표현식 계산기에 en이 값으로 표시되어야 합니다.

입력 경고가 사라졌습니다. 이제 조직 및 위치의 출력 필드에 대한 두 가지 경고만 남아 있습니다.

누락된 기술 출력 값 수정

인덱서의 'output FieldMappings' 속성을 확인하라는 메시지가 표시되므로 거기서 시작할 예정입니다.

작업 표면에서 출력 필드 매핑을 선택합니다. 출력 필드 매핑이 없습니다.
첫 번째 단계로 검색 인덱스가 예상 필드가 있는지 확인합니다. 이 경우 인덱스는 "위치" 및 "조직"에 대한 필드를 포함합니다.
인덱스에 문제가 없다면 다음 단계는 기술 출력을 확인하는 것입니다. 이전과 마찬가지로 보강된 데이터 구조를 선택하고 노드를 스크롤하여 "위치" 및 "조직"을 찾습니다. 부모는 "merged_content"가 아니라 "content"입니다. 컨텍스트가 잘못되었습니다.
엔터티 인식 기술에 대한 기술 세부 정보 창으로 다시 전환합니다.
기술 설정에서 context을(를) document/merged_content(으)로 변경합니다. 이 시점에서 기술 정의를 세 번 수정해야 합니다.
저장을 선택합니다.
실행을 선택합니다.

모든 오류가 해결되었습니다.

기술 세트에 대한 변경 내용 적용

디버그 세션이 시작되었을 때 검색 서비스에서 기술 세트의 복사본을 만들었습니다. 이 작업은 검색 서비스에서 원래 기술 세트를 보호하기 위해 수행되었습니다. 기술 세트 디버깅을 완료했으면 수정 사항을 커밋(원래 기술 세트 덮어쓰기)할 수 있습니다.

또는 변경 내용을 커밋할 준비가 되지 않은 경우 디버그 세션을 저장하고 나중에 다시 열 수 있습니다.

기본 디버그 세션 메뉴에서 변경 내용 커밋을 선택합니다.
확인을 선택하여 기술 업데이트를 확인합니다.
디버그 세션을 닫고 왼쪽 탐색 창에서 인덱서를 엽니다.
‘clinical-trials-idxr’을 선택합니다.
재설정을 선택합니다.
실행을 선택합니다.
새로 고침을 선택하여 다시 설정 상태를 표시하고 명령을 실행합니다.

인덱서 실행이 완료되었으면 실행 기록 탭의 최신 실행 타임스탬프 옆에 녹색 확인 표시와 '성공'이라는 단어가 있어야 합니다. 변경 내용이 적용되었는지 확인하려면 다음을 수행합니다.

왼쪽 탐색 창에서 인덱스를 엽니다.
'clinical-trials' 인덱스를 선택하고 검색 탐색기 탭에서 특정 문서(고유 metadata_storage_path 필드로 식별됨)에 대한 필드를 반환하는 쿼리 문자열인 $select=metadata_storage_path, organizations, locations&$count=true를 입력합니다.
검색을 선택합니다.

결과에 organizations 및 locations가 예상 값으로 채워진 것이 보입니다.

리소스 정리

본인 소유의 구독으로 이 모듈을 진행하고 있는 경우에는 프로젝트가 끝날 때 여기에서 만든 리소스가 계속 필요한지 확인하는 것이 좋습니다. 계속 실행되는 리소스에는 요금이 부과될 수 있습니다. 리소스를 개별적으로 삭제하거나 리소스 그룹을 삭제하여 전체 리소스 세트를 삭제할 수 있습니다.

왼쪽 탐색 창의 모든 리소스 또는 리소스 그룹 링크를 사용하여 포털에서 리소스를 찾고 관리할 수 있습니다.

무료 서비스는 3개의 인덱스, 인덱서 및 데이터 원본으로 제한됩니다. 포털에서 개별 항목을 삭제하여 제한 이하로 유지할 수 있습니다.

다음 단계

이 자습서에서는 기술 세트 정의 및 처리의 다양한 측면을 알아보았습니다. 개념과 워크플로에 대해 자세히 알아보려면 다음 문서를 참조하세요.

다음을 통해 공유