다음을 통해 공유

Azure AI 언어에 대한 원시 문서 지원(미리 보기)

  • 아티클

Important

  • Azure AI 언어 공개 미리 보기 릴리스는 적극 개발 중인 기능에 대한 조기 액세스를 제공합니다.
  • 기능, 방식 및 프로세스는 GA(일반 공급) 전에 사용자 피드백에 따라 변경될 수 있습니다.

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

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

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

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

지원되는 문서 형식

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

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

입력 지침

지원되는 파일 형식

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

문서 크기

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

HTTP 요청을 통한 원시 문서 포함

이제 시작하겠습니다.

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

    참고 항목

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    8. 리소스가 성공적으로 배포되면 리소스로 이동을 선택합니다.

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

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

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

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

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

Azure Blob Storage 컨테이너 만들기

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

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

인증

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

  • SAS(공유 액세스 서명) 토큰. 사용자 위임 SAS 토큰은 Microsoft Entra 자격 증명으로 보호됩니다. SAS 토큰은 Azure 스토리지 계정의 리소스에 대한 안전한 위임된 액세스를 제공합니다.

  • 관리 ID RBAC(역할 기반 액세스 제어). Azure 리소스에 대한 관리 ID는 Microsoft Entra ID 및 Azure 관리되는 리소스에 대한 특정 권한을 만드는 서비스 주체입니다.

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

SAS 토큰이 추가된 스토리지 URL을 보여 주는 스크린샷입니다.

  • 원본 컨테이너 또는 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 값을 사용하여 이 명령을 편집합니다. Personally Identifiable Information (PII) 또는 Document Summarization 코드 샘플 프로젝트를 선택하여 원시 문서를 분석해 봅니다.

PII 샘플 문서

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

POST 요청을 빌드합니다.

  1. 기본 설정 편집기 또는 IDE를 사용하여 native-document이라는 앱의 새 디렉터리를 만듭니다.

  2. native-document 디렉터리에 pii-detection.json이라는 새 json 파일을 만듭니다.

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

요청 샘플

{ 
    "displayName": "Document PII Redaction example", 
    "analysisInput": { 
        "documents": [ 
            { 
                "language": "en-US", 
                "id": "Output-1", 
                "source": { 
                    "location": "{your-source-blob-with-SAS-URL}" 
                }, 
                "target": { 
                    "location": "{your-target-container-with-SAS-URL}" 
                } 
            } 
        ] 
    }, 
    "tasks": [ 
        { 
            "kind": "PiiEntityRecognition", 
            "taskName": "Redact PII Task 1", 
            "parameters": { 
                "redactionPolicy": { 
                    "policyKind": "entityMask"  // Optional. Defines redactionPolicy; changes behavior based on value. Options: noMask, characterMask (default), and entityMask. 
                }, 
                "piiCategories": [ 
                    "Person", 
                    "Organization" 
                ], 
                "excludeExtractionData": false  // Default is false. If true, only the redacted document is stored, without extracted entities data. 
            } 
        } 
    ] 
}

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

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

POST 요청 실행

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

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

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

    Important

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

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-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=2024-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=2024-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)

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

POST 응답의 작업 위치 값을 보여 주는 스크린샷.

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

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

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

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

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

    • {jobId}를 POST 응답의 작업-위치 헤더로 바꿉니다.

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

Get 요청

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-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=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

응답 검사

JSON 출력으로200(성공) 응답을 받습니다. 상태 필드는 작업의 결과를 나타냅니다. 작업이 완료되지 않는 경우 상태는 "실행 중" 또는 “시작 안 함”이 되며, 수동으로 또는 스크립트를 통해 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 검색 개요 문서 요약 개요