Azure Portal에서 Azure AI 검색 기술 세트 디버그

포털 기반 디버그 세션을 시작하여 오류를 식별 및 해결하고, 변경 내용의 유효성을 검사하고, Azure AI 검색 서비스에서 게시된 기술 세트에 변경 내용을 푸시합니다.

디버그 세션은 단일 문서로 범위가 지정된 캐시된 인덱서 및 기술 세트 실행으로, 대화형으로 변경 내용을 편집하고 테스트하는 데 사용할 수 있습니다. 디버깅을 마치면 기술 세트에 변경 내용을 저장할 수 있습니다.

디버그 세션 작동 방식에 대한 배경 정보는 Azure AI 검색의 디버그 세션을 참조하세요. 샘플 문서를 사용하여 디버그 워크플로를 연습하려면 자습서: 디버그 세션을 참조하세요.

필수 조건

• 데이터 원본, 기술 세트, 인덱서 및 인덱스가 포함된 기존 보강 파이프라인

• Search Service의 기여자 역할 할당.

• 세션 상태를 저장하는 데 사용되는 Azure Storage 계정

• 시스템 관리 ID를 사용하는 경우 Azure Storage의 Storage Blob 데이터 기여자 역할 할당. 그렇지 않으면 Azure Storage에 대한 디버그 세션 연결에 전체 액세스 연결 문자열을 사용하도록 계획합니다.

• Azure Storage 계정이 방화벽 뒤에 있는 경우 Search Service 액세스를 허용하도록 구성합니다.

제한 사항

디버그 세션은 일반 공급된 모든 인덱서 데이터 원본과 대부분의 미리 보기 데이터 원본에서 작동합니다. 다음 목록에서는 예외를 설명합니다.

• Azure Cosmos DB for MongoDB는 현재 지원되지 않습니다.

• Azure Cosmos DB for NoSQL의 경우 인덱스 중에 행이 실패하고 해당 메타데이터가 없는 경우 디버그 세션이 올바른 행을 선택하지 못할 수 있습니다.

• Azure Cosmos DB의 SQL API의 경우 분할된 컬렉션이 이전에 분할되지 않은 경우 디버그 세션에서 문서를 찾을 수 없습니다.

• 사용자 지정 기술의 경우 Azure Storage에 대한 디버그 세션 연결에는 사용자 할당 관리 ID가 지원되지 않습니다. 필수 구성 요소에 명시된 대로 시스템 관리 ID를 사용하거나, 키가 포함된 전체 액세스 연결 문자열을 지정할 수 있습니다. 자세한 내용은 관리 ID를 사용하여 다른 Azure 리소스에 검색 서비스 연결을 참조하세요.

포털은 CMK(고객 관리형 키 암호화)를 지원하지 않습니다. 즉, 디버그 세션과 같은 포털 환경에는 CMK로 암호화된 연결 문자열 또는 기타 암호화된 메타데이터가 있을 수 없습니다. CMK 적용에 대해 검색 서비스가 구성된 경우 디버그 세션이 작동하지 않습니다.

디버그 세션 만들기

1. Azure Portal에 로그인하고 검색 서비스를 찾습니다.

2. 왼쪽 탐색 페이지에서 디버그 세션을 선택합니다.

3. 상단의 작업 표시줄에서 디버그 세션 디버그를 선택합니다.

   

4. 디버그 세션 이름에서 디버그 세션의 기술 세트, 인덱서, 데이터 원본을 기억하는 데 도움이 되는 이름을 제공합니다.

5. 스토리지 연결에서 디버그 세션을 캐싱하기 위한 범용 스토리지 계정을 찾습니다. Blob Storage 또는 Azure Data Lake Storage Gen2에서 Blob 컨테이너를 선택하고 필요에 따라 만들라는 메시지가 표시됩니다. 만든 모든 후속 디버그 세션에 동일한 컨테이너를 다시 사용할 수 있습니다. "cognitive-search-debug-sessions" 같은 컨테이너 이름이 유용할 수 있습니다.

6. 관리 ID 인증에서 Azure Storage에 대한 연결이 관리 ID를 사용하지 않는 경우없음을 선택합니다. 그렇지 않은 경우 Storage Blob 데이터 기여자 권한을 부여한 관리 ID를 선택합니다.

7. 인덱서 템플릿에서 디버그하려는 기술 세트를 구동하는 인덱서를 선택합니다. 인덱서와 기술 세트의 복사본은 세션을 초기화하는 데 사용됩니다.

8. 디버그할 문서에서 인덱스 내의 첫 번째 문서를 선택하거나 특정 문서를 선택합니다. 데이터 원본에 따라 특정 문서를 선택하는 경우 URI 또는 행 ID를 묻는 메시지가 표시됩니다.

   특정 문서가 Blob인 경우 Blob URI를 제공합니다. 포털의 Blob 속성 페이지에서 URI를 찾을 수 있습니다.

   

9. 필요에 따라 인덱서 설정에서 세션을 만드는 데 사용되는 인덱서 실행 설정을 지정합니다. 설정은 실제 인덱서에서 사용하는 설정처럼 보여야 합니다. 디버그 세션에서 지정하는 인덱서 옵션은 인덱서 자체에 영향을 주지 않습니다.

10. 구성은 이 스크린샷과 유사해야 합니다. 세션 저장을 선택하여 시작합니다.

    

디버그 세션은 선택한 문서에 대해 인덱서 및 기술 세트를 실행하면서 시작됩니다. 생성된 문서의 콘텐츠와 메타데이터가 세션에서 표시되고 사용할 수 있습니다.

실행되는 동안 취소 단추를 사용하여 디버그 세션을 취소할 수 있습니다. 취소 단추를 누르면 부분 결과를 분석할 수 있습니다.

디버그 세션은 추가 처리를 거치기 때문에 인덱서보다 실행하는 데 시간이 오래 걸릴 것으로 예상됩니다.

오류 및 경고로 시작

포털의 인덱서 실행 기록은 모든 문서에 대한 전체 오류 및 경고 목록을 제공합니다. 디버그 세션에서 오류 및 경고는 하나의 문서로 제한됩니다. 이 목록을 살펴보고, 변경한 다음, 목록으로 돌아가서 이슈가 해결되었는지 확인합니다.

메시지를 보려면 AI 보강 > 기술 그래프에서 기술을 선택한 다음, 세부 정보 창에서 오류/경고를 선택합니다.

출력으로 넘어가기 전에 입력 문제를 해결하는 것이 좋습니다.

수정 후 오류가 해결되었는지 여부를 증명하려면 다음 단계를 수행합니다.

1. 기술 세부 정보 창에서 저장을 선택하여 변경 내용을 유지합니다.

2. 세션 창에서 실행을 선택하여 수정된 정의로 기술 세트 실행을 호출합니다.

3. 오류/경고로 돌아가서 개수가 줄었는지 확인합니다. 탭을 열 때까지 목록이 새로 고쳐지지 않습니다.

보강 노드의 콘텐츠 보기

AI 보강 파이프라인은 원본 문서에서 정보 및 구조를 추출하거나 유추하여 프로세스에서 보강된 문서를 만듭니다. 먼저 문서 크래킹 중에 보강된 문서가 만들어지고 루트 노드(/document)와 메타데이터 및 문서 키와 같이 데이터 원본에서 직접 거둬들인 모든 콘텐츠에 대한 노드로 채워집니다. 기술 실행 중에 기술에 의해 추가 노드가 만들어지고, 각 기술 출력은 보강 트리에 새 노드를 추가합니다.

보강된 문서는 내부용이지만 디버그 세션을 통해 기술 실행 중에 생성된 콘텐츠에 액세스할 수 있습니다. 각 기술의 콘텐츠 또는 출력을 보려면 다음 단계를 수행합니다.

1. 그래프 유형이 종속성 그래프로 설정된 기본 보기 AI 보강 > 기술 그래프로 시작합니다.

2. 기술을 선택합니다.

3. 오른쪽의 세부 정보 창에서 실행을 선택하고 출력을 선택한 다음, 식 계산기(</>)를 열어 식과 결과를 봅니다.

   

4. 또는 AI 보강 > 보강된 데이터 구조를 열어 노드 목록을 아래로 스크롤합니다. 이 목록에는 출력에 대한 열과 출력을 생성하는 데 사용된 업스트림 개체를 나타내는 다른 열이 포함된 잠재적 노드와 실제 노드가 포함됩니다.

   

기술 정의 편집

필드 매핑이 올바른 경우 개별 기술의 구성 및 콘텐츠를 확인합니다. 기술이 출력을 생성하지 못하는 경우 속성 또는 매개 변수가 누락되었을 수 있으며, 이는 오류 및 유효성 검사 메시지를 통해 확인할 수 있습니다.

잘못된 컨텍스트 또는 입력 식과 같은 다른 이슈는 무엇이 잘못되었는지는 알려 주지만 해결하는 방법은 알려 주지 않으므로 해결하기 어려울 수 있습니다. 컨텍스트 및 입력 구문에 대한 도움말은 Azure AI 검색 기술 세트에서 보강 참조를 참조하세요. 개별 메시지에 대한 도움말은 일반적인 인덱서 오류 및 경고 해결을 참조하세요.

다음 단계에서는 기술에 대한 정보를 가져오는 방법을 보여 줍니다.

1. AI 보강 > 기술 그래프에서 기술을 선택합니다. 기술 세부 정보 창이 오른쪽에 열립니다.

2. 다음 방법 중 하나를 사용하여 기술 정의를 편집합니다.

   • 기술 설정(시각적 편집기를 선호하는 경우)
   • 기술 JSON 편집기(JSON 문서를 직접 편집하려는 경우)

3. 보강 트리에서 노드를 참조하기 위한 경로 구문을 확인합니다. 다음은 가장 일반적인 입력 경로 중 일부입니다.

   • /document/content - 텍스트 청크용. 이 노드는 Blob의 콘텐츠 속성으로 채워집니다.
   • /document/merged_content - 텍스트 병합 기술을 포함하는 기술 세트의 텍스트 청크용
   • /document/normalized_images/* - 이미지에서 인식되거나 유추된 텍스트용

필드 매핑 확인

기술이 출력을 생성하지만 검색 인덱스가 비어 있는 경우 필드 매핑을 확인합니다. 필드 매핑은 콘텐츠가 파이프라인에서 검색 인덱스로 이동하는 방법을 지정합니다.

1. 그래프 유형이 종속성 그래프로 설정된 기본 보기 AI 보강 > 기술 그래프로 시작합니다.

2. 상단 근처에 있는 필드 매핑을 선택합니다. 검색 인덱스의 각 검색 문서를 고유하게 식별하고 데이터 원본의 원본 문서와 연결하는 문서 키를 하나 이상 찾아야 합니다.

   데이터 원본에서 바로 원시 콘텐츠를 가져오고 보강을 건너뛰는 경우 필드 매핑에서 해당 필드를 찾아야 합니다.

3. 그래프 하단에서 출력 필드 매핑을 선택합니다. 여기서는 기술 출력과 검색 인덱스의 대상 필드에 대한 매핑을 찾을 수 있습니다. 데이터 가져오기 마법사를 사용하지 않은 경우 출력 필드 매핑은 수동으로 정의되며 불완전하거나 잘못 입력될 수 있습니다.

   출력 필드 매핑의 필드가 지정된 대로 검색 인덱스에 있는지 확인하고 맞춤법 및 보강 노드 경로 구문을 확인합니다.

   

로컬에서 사용자 지정 기술 디버그

사용자 지정 기술은 코드가 외부에서 실행되므로 디버그하는 것이 더 어려울 수 있으므로 디버그 세션을 사용하여 디버그할 수 없습니다. 이 섹션에서는 사용자 지정 Web API 기술, 디버그 세션, Visual Studio Code 및 ngrok 또는 Tunnelmole을 로컬에서 디버그하는 방법을 설명합니다. 이 기술은 Azure Functions에서 실행되는 사용자 지정 기술 또는 로컬에서 실행되는 다른 웹 프레임워크(예: FastAPI)와 함께 작동합니다.

공용 URL 가져오기

Tunnelmole 사용

Tunnelmole은 터널을 통해 로컬 컴퓨터에 요청을 전달하는 공용 URL을 만들 수 있는 오픈 소스 터널링 도구입니다.

1. Tunnelmole 설치:

   • npm: npm install -g tunnelmole
   • Linux: curl -s https://tunnelmole.com/sh/install-linux.sh | sudo bash
   • Mac: curl -s https://tunnelmole.com/sh/install-mac.sh --output install-mac.sh && sudo bash install-mac.sh
   • Windows: npm을 사용하여 설치합니다. 또는 NodeJS가 설치되어 있지 않은 경우 Windows용 미리 컴파일된 .exe 파일을 다운로드하여 PATH에 배치합니다.

2. 이 명령을 실행하여 새 터널을 만듭니다.

   tmole 7071
   

   다음과 같은 응답이 표시됩니다.

   http://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   https://m5hdpb-ip-49-183-170-144.tunnelmole.net is forwarding to localhost:7071
   

   이전 예제에서 https://m5hdpb-ip-49-183-170-144.tunnelmole.net은 Azure 함수가 노출되는 기본 포트인 로컬 머신의 7071 포트로 전달합니다.

ngrok 사용

ngrok는 인터넷 요청이 로컬 컴퓨터에 도달할 수 있도록 터널링 또는 전달 URL을 만들 수 있는 널리 사용되는 비공개 플랫폼 간 애플리케이션입니다. ngrok를 사용하여 검색 서비스의 보강 파이프라인에서 컴퓨터로 요청을 전달하여 로컬 디버깅을 허용합니다.

1. ngrok를 설치합니다.

2. 터미널을 열고 ngrok 실행 파일이 있는 폴더로 이동합니다.

3. 다음 명령을 사용하여 ngrok를 실행하여 새 터널을 만듭니다.

   ngrok http 7071 
   

   참고 항목

   기본적으로 Azure 함수는 7071에 노출됩니다. 다른 도구 및 구성을 사용하려면 다른 포트를 제공해야 할 수 있습니다.

4. ngrok가 시작되면 다음 단계를 위해 공용 전달 URL을 복사하고 저장합니다. 이 전달 URL은 임의로 생성됩니다.

   

Azure Portal에서 구성

디버그 세션 내에서 Tunnelmole 또는 ngrok 전달 URL을 호출하도록 사용자 지정 Web API 기술 URI를 수정합니다. 기술 세트 코드를 실행하기 위해 Azure Function을 사용할 때 "/api/FunctionName"을 추가해야 합니다.

포털에서 기술 정의를 편집할 수 있습니다.

코드 테스트

이제 디버그 세션의 새 요청을 로컬 Azure Function으로 보내야 합니다. Visual Studio 코드에서 중단점을 사용하여 코드를 디버그하거나 단계별로 실행할 수 있습니다.

다음 단계

이제 디버그 세션 시각적 편집기의 레이아웃과 기능을 이해했으므로 자습서를 통해 실습해 보세요.

자습서: 디버그 세션 살펴보기