다음을 통해 공유

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

  • 아티클

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

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

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

필수 조건

  • Azure AI 검색 서비스. Azure AI 검색이 Azure Storage에 쓰고 기술 세트에 사용되는 Azure AI 리소스를 호출할 수 있도록 허용하는 시스템 할당 관리 ID 및 역할 할당을 사용하는 것이 좋습니다.

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

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

  • 역할 할당의 경우 검색 서비스 ID에는 다음의 내용이 있어야 합니다.

    • 기술 세트에서 사용하는 Azure AI 다중 서비스 계정에 대한 Cognitive Services 사용자 권한입니다.

    • Azure Storage에 대한 Storage Blob 데이터 기여자 권한입니다. 그렇지 않으면 Azure Storage에 대한 디버그 세션 연결에 전체 액세스 연결 문자열을 사용하도록 계획합니다.

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

제한 사항

디버그 세션은 다음을 제외하고 일반 공급한 모든 인덱서 데이터 원본 및 대부분의 미리 보기 데이터 원본에서 작동합니다.

  • SharePoint 온라인 인덱서

  • Azure Cosmos DB for MongoDB 인덱서

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

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

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

디버그 세션 만들기

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

  2. 왼쪽 메뉴에서 검색 관리>디버그 세션을 선택합니다.

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

    포털 페이지의 디버그 세션 명령 스크린샷

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

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

  6. 스토리지 계정에서 디버그 세션을 캐싱하기 위한 범용 스토리지 계정을 찾습니다.

  7. 이전에 검색 서비스 시스템 관리 ID에 Storage Blob 데이터 기여자 권한을 할당한 경우 관리 ID를 사용하여 인증을 선택합니다.

  8. 저장을 선택합니다.

    • Azure AI 검색은 Azure Storage에 ms-az-cognitive-search-debugsession이라는 Blob 컨테이너를 만듭니다.
    • 해당 컨테이너 내에서 세션 이름으로 제공한 이름을 사용하여 폴더를 만듭니다.
    • 디버그 세션을 시작합니다.

  9. 디버그 세션이 설정 페이지로 열립니다. 초기 구성을 수정하고 기본값을 재정의할 수 있습니다.

  10. 스토리지 연결 문자열에서 연결 문자열을 지정하거나 스토리지 계정을 변경할 수 있습니다.

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

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

    Blob Storage의 URI 속성 스크린샷

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

  13. 변경한 경우 세션 저장을 선택한 다음, 실행을 선택합니다.

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

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

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

오류 및 경고로 시작

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

디버그 세션은 전체 인덱스에서 하나의 문서를 기반으로 합니다. 입력 또는 출력이 잘못된 것으로 보이는 경우 해당 문서에 문제가 있을 수 있습니다. 다른 문서를 선택하여 오류 및 경고 발생이 일반적인지 아니면 단일 문서에만 발생하는지 확인할 수 있습니다.

문제 목록의 오류 또는 경고를 선택합니다.

페이지 맨 위에 있는 오류 및 경고 단추의 스크린샷

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

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

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

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

  3. 오류 또는 경고로 이동하여 개수가 줄었는지 확인합니다.

보강된 콘텐츠 또는 생성된 콘텐츠 보기

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

기술 세트에서 만들거나 사용하는 모든 콘텐츠가 식 계산기에서 나타납니다. 링크를 마우스로 가리키면 보강된 문서 트리에서 각 입력 또는 출력 값을 볼 수 있습니다. 각 기술의 입력 또는 출력을 보려면 다음 단계를 수행합니다.

  1. 디버그 세션에서 파란색 화살표를 확장하여 상황에 맞는 세부 정보를 볼 수 있습니다. 기본적으로 세부 정보는 보강된 문서 데이터 구조입니다. 그러나 기술 또는 매핑을 선택하는 경우 해당 개체에 대한 세부 정보가 표시됩니다.

    상황에 맞는 세부 정보를 표시하는 데 사용되는 파란색 화살표를 나타내는 스크린샷

  2. 기술을 선택합니다.

    자세한 내용을 드릴다운한 기술 세부 정보 창을 보여 주는 스크린샷

  3. 기술 처리에 대해 더 자세히 알아보려면 링크를 따릅니다. 예를 들어 다음 스크린샷은 텍스트 분할 기술의 첫 번째 반복 출력을 보여 줍니다.

    지정된 출력에 대한 식 계산기가 있는 기술 세부 정보 창을 보여 주는 스크린샷

인덱스 매핑 확인

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

워크플로의 인덱스 매핑 영역의 스크린샷

매핑 옵션 중 하나를 선택하고 세부 정보 보기를 확장하여 원본 및 대상 정의를 검토합니다.

  • 프로젝션 매핑은 데이터 가져오기 및 벡터화 마법사에서 만든 기술과 같이 통합된 벡터화를 제공하는 기술 세트에서 찾을 수 있습니다. 이러한 매핑은 부모-자식(청크) 필드 매핑과 청크 분할된 콘텐츠에 대한 보조 인덱스를 만드는지 여부를 결정합니다.

  • 출력 필드 매핑은 인덱서에서 찾을 수 있으며 기술 세트가 기본 제공을 호출하거나 또는 사용자 지정 기술을 호출할 때 사용됩니다. 이러한 매핑은 보강 트리의 노드에서 검색 인덱스의 필드까지 데이터 경로를 설정하는 데 사용됩니다. 경로에 대한 자세한 내용은 보강 노드 경로 구문을 참조하세요.

  • 필드 매핑은 인덱서 정의에서 찾을 수 있으며 데이터 원본의 원시 콘텐츠와 인덱스의 필드에서 데이터 경로를 설정합니다. 필드 매핑을 사용하여 인코딩 및 디코딩 단계를 추가할 수도 있습니다.

이 예제에서는 프로젝션 매핑에 대한 세부 정보를 보여 줍니다. JSON을 편집하여 매핑 문제를 해결할 수 있습니다.

출력 필드 매핑 노드 및 세부 정보의 스크린샷

기술 정의 편집

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

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

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

  1. 작업 화면에서 기술을 선택합니다. 기술 세부 정보 창이 오른쪽에 열립니다.

  2. 기술 설정을 사용하여 기술 정의를 편집합니다. JSON을 직접 편집할 수 있습니다.

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

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

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

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

공용 URL 가져오기

이 섹션에서는 사용자 지정 기술에 대한 퍼블릭 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은 임의로 생성됩니다.

    ngrok 터미널의 스크린샷

Azure Portal에서 구성

사용자 지정 기술에 대한 퍼블릭 URL이 있으면 디버그 세션 내에서 사용자 지정 웹 API 기술 URI를 수정하여 Tunnelmole 또는 ngrok 전달 URL을 호출합니다. 기술 세트 코드를 실행하기 위해 Azure Function을 사용할 때 "/api/FunctionName"을 추가해야 합니다.

기술 세부 정보 창의 기술 설정 섹션에서 기술 정의를 편집할 수 있습니다.

코드 테스트

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

다음 단계

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

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