Share via

Azure AI 언어에 대한 네이티브 문서 지원(미리 보기)

  • 아티클

Important

  • 네이티브 문서 지원은 제어된 미리 보기입니다. 네이티브 문서 지원 기능에 대한 액세스를 요청하려면 언어 서비스 미리 보기 양식에 대한 액세스 적용을 완료하고 제출 합니다 .

  • Azure AI Language 공개 미리 보기 릴리스는 활성 개발 중인 기능에 대한 초기 액세스를 제공합니다.

  • 기능, 방식 및 프로세스는 GA(일반 공급) 전에 사용자 피드백에 따라 변경될 수 있습니다.

Azure AI Language는 텍스트 기반 데이터에 NLP(자연어 처리) 기능을 적용하는 클라우드 기반 서비스입니다. 네이티브 문서 지원 기능을 사용하면 HTTP POST 요청 본문을 사용하여 데이터를 보내고 HTTP GET 요청 쿼리 문자열을 사용하여 API 요청을 비동기적으로 보내 상태 결과를 검색할 수 있습니다. 처리된 문서는 Azure Blob Storage 대상 컨테이너에 있습니다.

네이티브 문서는 Microsoft Word(docx) 또는 이식 가능한 문서 파일(pdf)과 같은 원본 문서를 만드는 데 사용되는 파일 형식을 나타냅니다. 네이티브 문서 지원을 사용하면 Azure AI 언어 리소스 기능을 사용하기 전에 텍스트 전처리가 필요하지 않습니다. 현재 네이티브 문서 지원은 다음 기능에 사용할 수 있습니다.

  • PII(개인 식별 정보). PII 탐지 기능은 구조화되지 않은 텍스트에서 중요한 정보를 식별, 분류 및 수정할 수 있습니다. API는 네이 PiiEntityRecognition 티브 문서 처리를 지원합니다.

  • 문서 요약입니다. 문서 요약은 자연어 처리를 사용하여 문서에 대한 추출(두드러진 문장 추출) 또는 추상적(상황별 단어 추출) 요약을 생성합니다. API와 ExtractiveSummarization API는 모두 AbstractiveSummarization 네이티브 문서 처리를 지원합니다.

지원되는 문서 형식

애플리케이션은 네이티브 파일 형식을 사용하여 네이티브 문서를 만들거나 저장하거나 엽니다. 현재 PII 및 문서 요약 기능은 다음과 같은 네이티브 문서 형식을 지원합니다.

파일 형식 파일 확장명 설명
Text .txt 서식이 지정되지 않은 텍스트 문서입니다.
Adobe PDF .pdf 이식 가능한 문서 파일 형식의 문서입니다.
Microsoft Word .docx Microsoft Word 문서 파일입니다.

입력 지침

지원되는 파일 형식

Type 지원 및 제한 사항
Pdf 완전히 스캔된 PDF는 지원되지 않습니다.
이미지 내의 텍스트 텍스트가 포함된 디지털 이미지는 지원되지 않습니다.
디지털 테이블 스캔한 문서의 테이블은 지원되지 않습니다.

문서 크기

Attribute 입력 제한
요청당 총 문서 수 ≤ 20
요청당 총 콘텐츠 크기 ≤ 1MB

HTTP 요청을 사용하여 네이티브 문서 포함

시작해 보겠습니다.

  • 이 프로젝트의 경우 cURL 명령줄 도구를 사용하여 REST API를 호출합니다.

    참고 항목

    cURL 패키지는 대부분의 Windows 10 및 Windows 11 및 대부분의 macOS 및 Linux 배포판에 미리 설치되어 있습니다. 다음 명령을 사용하여 패키지 버전을 검사 수 있습니다. Windows: macOS curl -V Linux: curl.exe -Vcurl --version

  • cURL이 설치되지 않은 경우 플랫폼에 대한 설치 링크는 다음과 같습니다.

  • 활성 Azure 계정. 계정이 없는 경우 무료 계정에 만들 수 있습니다.

  • Azure Blob Storage 계정 또한 원본 및 대상 파일에 대한 Azure Blob Storage 계정에 컨테이너를 생성해야 합니다.

    • 원본 컨테이너. 이 컨테이너는 분석을 위해 네이티브 파일을 업로드하는 위치입니다(필수).
    • 대상 컨테이너. 이 컨테이너는 분석된 파일이 저장되는 위치입니다(필수).

  • 단일 서비스 언어 리소스(다중 서비스 Azure AI 서비스 리소스 아님):

    다음과 같이 언어 리소스 프로젝트 및 인스턴스 세부 정보 필드를 완료합니다.

    1. 구독. 사용 가능한 Azure 구독 중 하나를 선택합니다.

    2. 리소스 그룹. 새 리소스 그룹을 만들거나 동일한 수명 주기, 권한 및 정책을 공유하는 기존 리소스 그룹에 리소스를 추가할 수 있습니다.

    3. 리소스 지역. 비즈니스 또는 애플리케이션에서 특정 지역을 요구하지 않는 한 전체를 선택합니다. 인증에 RBAC(시스템 할당 관리 ID)를 사용하려는 경우 미국 서부와 같은 지리적 지역을 선택합니다.

    4. Name(이름): 리소스에 대해 선택한 이름을 입력합니다. 선택하는 이름이 Azure 내에서 고유해야 합니다.

    5. 가격 책정 계층. 평가판 가격 책정 계층(Free F0)을 통해 서비스를 사용해보고, 나중에 프로덕션용 유료 계층으로 업그레이드할 수 있습니다.

    6. 검토 + 생성를 선택합니다.

    7. 서비스 약관을 검토하고 만들기를 선택하여 리소스를 배포합니다.

    8. 리소스를 성공적으로 배포한 후 리소스로 이동을 선택합니다.

키 및 언어 서비스 엔드포인트 검색

언어 서비스에 대한 요청은 액세스를 인증하기 위해 읽기 전용 키 및 사용자 지정 엔드포인트가 필요합니다.

  1. 새 리소스를 만든 경우 배포한 후 리소스로 이동을 선택합니다. 기존 언어 서비스 리소스가 있는 경우 리소스 페이지로 직접 이동합니다.

  2. 왼쪽 레일의 리소스 관리에서 키 및 엔드포인트를 선택합니다.

  3. 사용자와 사용자를 language service instance endpoint 복사하여 코드 샘플에 붙여 key 넣어 언어 서비스에 대한 요청을 인증할 수 있습니다. API 호출을 수행하는 데는 키가 하나만 필요합니다.

Azure Blob Storage 컨테이너 만들기

원본 및 대상 파일에 대한 Azure Blob Storage 계정에 컨테이너를 만듭니다.

  • 원본 컨테이너. 이 컨테이너는 분석을 위해 네이티브 파일을 업로드하는 위치입니다(필수).
  • 대상 컨테이너. 이 컨테이너는 분석된 파일이 저장되는 위치입니다(필수).

인증

Blob을 만들거나 읽거나 삭제하려면 언어 리소스에 스토리지 계정에 대한 액세스 권한이 부여되어야 합니다. 스토리지 데이터에 대한 액세스 권한을 부여하는 데 사용할 수 있는 두 가지 기본 방법이 있습니다.

이 프로젝트의 경우 SAS(공유 액세스 서명) 토큰이 쿼리 문자열로 추가된 URL에 대한 액세스를 source locationtarget location 인증합니다. 각 토큰은 특정 Blob(파일)에 할당됩니다.

Screenshot of a storage url with SAS token appended.

  • 원본 컨테이너 또는 Blob은 읽기 및 목록 액세스를 지정해야 합니다.
  • 대상 컨테이너 또는 Blob은 쓰기 및 목록 액세스를 지정해야 합니다.

팁

단일 파일(Blob)을 처리하고 있으므로 Blob 수준에서 SAS 액세스를 위임하는 것이 좋습니다.

요청 헤더 및 매개 변수

parameter 설명
-X POST <endpoint> API에 액세스하기 위한 언어 리소스 엔드포인트를 지정합니다.
--header Content-Type: application/json JSON 데이터를 보내기 위한 콘텐츠 형식.
--header "Ocp-Apim-Subscription-Key:<key> API에 액세스하기 위한 언어 리소스 키를 지정합니다.
-data 요청과 함께 전달하려는 데이터가 포함된 JSON 파일입니다.

다음 cURL 명령은 BASH 셸에서 실행됩니다. 사용자 고유의 리소스 이름, 리소스 키 및 JSON 값을 사용하여 이 명령을 편집합니다. 또는 Document Summarization 코드 샘플 프로젝트를 선택하여 네이 Personally Identifiable Information (PII) 티브 문서를 분석해 보세요.

PII 샘플 문서

이 빠른 시작에서는 원본 컨테이너에 업로드된 원본 문서가 필요합니다. 이 프로젝트에 대한 Microsoft Word 샘플 문서 또는 Adobe PDF를 다운로드할 수 있습니다. 소스 언어는 영어입니다.

POST 요청 빌드

  1. 기본 설정 편집기 또는 IDE를 사용하여 이름이 지정된 native-document앱에 대한 새 디렉터리를 만듭니다.

  2. 네이티브 문서 디렉터리에 pii-detection.json 이라는 새 json 파일을 만듭니다.

  3. 다음 PII(개인 식별 정보) 요청 샘플을 복사하여 파일에 붙여넣 pii-detection.json 습니다. Azure Portal Storage 계정 컨테이너 인스턴스의 값으로 대체 {your-source-container-SAS-URL} 합니다 {your-target-container-SAS-URL} .

요청 샘플

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • 원본 location 값은 원본 컨테이너 SAS URL이 아닌 원본 문서(Blob)의 SAS URL입니다.

  • 가능한 값은 redactionPolicyUseRedactionCharacterWithRefId (기본값) 또는 UseEntityTypeName. 자세한 내용은 PiiTask 매개 변수를 참조하세요.

POST 요청 실행

  1. POST 요청의 예비 구조는 다음과 같습니다.

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview

  2. POST 요청을 실행하기 전에 Azure Portal 언어 서비스 인스턴스의 값으로 바꿉 {your-language-resource-endpoint}{your-key} 니다.

    Important

    완료되면 코드에서 키를 제거하고 공개적으로 게시하지 마세요. 프로덕션의 경우 Azure Key Vault와 같은 자격 증명을 안전하게 저장하고 액세스하는 방법을 사용합니다. 자세한 내용은Azure AI 서비스 보안을 참조하세요.

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    명령 프롬프트/터미널

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. 샘플 응답은 다음과 같습니다.

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST 응답(jobId)

읽기 전용 Operation-Location 헤더를 포함하는 202(성공) 응답을 받습니다. 이 헤더의 값에는 비동기 작업의 상태 가져와 GET 요청을 사용하여 결과를 검색하기 위해 쿼리할 수 있는 jobId가 포함되어 있습니다.

Screenshot showing the operation-location value in the POST response.

분석 결과 가져오기(GET 요청)

  1. POST 요청이 성공하면 POST 요청에 반환된 작업 위치 헤더를 폴링하여 처리된 데이터를 봅니다.

  2. GET 요청의 예비 구조는 다음과 같습니다.

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

  3. 명령을 실행하기 전에 다음을 변경합니다.

    • {jobId}를 POST 응답의 Operation-Location 헤더로 바꿉다.

    • {your-language-resource-endpoint} 및 {your-key}를 Azure Portal의 언어 서비스 인스턴스 값으로 바꿉니다.

요청 가져오기

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

응답 검사

JSON 출력을 사용하여 200(성공) 응답을 받습니다. 상태 필드는 작업의 결과를 나타냅니다. 작업이 완료되지 않은 경우 상태 값이 "실행 중" 또는 "notStarted"이며 수동으로 또는 스크립트를 통해 API를 다시 호출해야 합니다. 호출 간에 1초 이상의 간격을 사용하는 것이 좋습니다.

샘플 응답

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

성공적으로 완료되면 다음을 수행합니다.

  • 분석된 문서는 대상 컨테이너에서 찾을 수 있습니다.
  • 성공적인 POST 메서드는 서비스에서 일괄 처리 요청을 생성했음을 나타내는 응답 코드를 반환 202 Accepted 합니다.
  • POST 요청은 후속 GET 요청에 사용되는 값을 제공하는 응답 헤더 Operation-Location 도 반환했습니다.

리소스 정리

Azure AI 서비스 구독을 정리하고 제거하려면 리소스 또는 리소스 그룹을 삭제할 수 있습니다. 리소스 그룹을 삭제하면 해당 리소스 그룹에 연결된 다른 모든 리소스가 함께 삭제됩니다.

다음 단계

PII 검색 개요문서 요약 개요