빠른 시작: 대화형 Language Understanding

아티클
10/21/2024

이 문서를 사용하여 Language Studio 및 REST API를 사용하여 대화 언어 이해를 시작합니다. 예제를 시도하려면 다음 단계를 따르세요.

필수 조건

Azure 구독 - 체험 구독 만들기

Language Studio로 이동하여 Azure 계정으로 로그인합니다.

표시되는 언어 리소스 선택 창에서 Azure 구독을 찾고 언어 리소스를 선택합니다. 리소스가 없는 경우 새 리소스 그룹을 만들 수 있습니다.

인스턴스 세부 정보	필수 값
Azure 구독	Azure 구독.
Azure 리소스 그룹	Azure 리소스 그룹 이름입니다.
Azure 리소스 이름	Azure 리소스 이름입니다.
위치	언어 리소스에 대해 지원되는 지역 중 하나입니다. 예를 들어 "미국 서부 2"로 선택합니다.
가격 책정 계층	언어 리소스에 대해 유효한 지원되는 가격 책정 계층 중 하나입니다. 무료(F0) 계층을 사용하여 서비스를 사용해 볼 수 있습니다.

대화 언어 이해 프로젝트 만들기

언어 리소스를 선택한 후에는 계정과 대화형 Language Understanding 프로젝트를 만듭니다. 프로젝트는 데이터를 기반으로 하는 사용자 지정 ML 모델을 빌드하기 위한 작업 영역입니다. 사용자 및 사용 중인 언어 리소스에 대해 액세스 권한이 있는 다른 사용자만 프로젝트에 액세스할 수 있습니다.

이 빠른 시작의 경우 이 샘플 프로젝트 파일을 다운로드하여 가져올 수 있습니다. 이 프로젝트는 이메일 읽기, 이메일 삭제, 이메일에 문서 첨부와 같은 사용자 입력에서 의도한 명령을 예측할 수 있습니다.

Language Studio의 질문 및 대화 언어 이해 섹션에서 대화 언어 이해를 선택합니다.
그러면 대화형 언어 이해 프로젝트 페이지로 이동합니다. 새 프로젝트 만들기 단추 옆에 있는 가져오기를 선택합니다.
표시되는 창에서 가져올 JSON 파일을 업로드합니다. 파일이 지원되는 JSON 형식을 따르는지 확인합니다.

업로드가 완료되면 스키마 정의 페이지가 표시됩니다. 이 빠른 시작의 경우 스키마가 이미 빌드되었으며 발화에는 이미 의도 및 엔터티로 레이블이 지정되어 있습니다.

모델 학습

일반적으로 프로젝트를 만든 후에는 스키마를 빌드하고 발화에 레이블을 지정해야 합니다. 이 빠른 시작에서는 빌드된 스키마와 레이블이 지정된 발화가 있는 준비된 프로젝트를 이미 가져왔습니다.

모델을 학습시키려면 학습 작업을 시작해야 합니다. 성공적인 학습 작업의 출력은 학습된 모델입니다.

Language Studio 내에서 모델 학습을 시작하려면 다음을 수행합니다.

왼쪽 메뉴에서 모델 학습을 선택합니다.
상단 메뉴에서 학습 작업 시작을 선택합니다.
새 모델 학습을 선택하고 텍스트 상자에 새 모델 이름을 입력합니다. 그렇지 않고 기존 모델을 새 데이터에 대해 학습된 모델로 바꾸려면 기존 모델 덮어쓰기를 선택한 다음, 기존 모델을 선택합니다. 학습된 모델을 덮어쓰는 것은 되돌릴 수 없지만, 새 모델을 배포할 때까지 배포된 모델에는 영향을 주지 않습니다.
학습 모드를 선택합니다. 더 빠른 학습을 위해 표준 학습을 선택할 수 있지만 영어로만 사용할 수 있습니다. 또는 다른 언어 및 다국어 프로젝트에 지원되는 고급 학습을 선택할 수 있지만 학습 시간이 더 오래 걸립니다. 학습 모드에 대해 자세히 알아봅니다.
데이터 분할 방법을 선택합니다. 학습 데이터에서 자동으로 테스트 세트 분할을 선택할 수 있습니다. 그러면 시스템에서 지정된 백분율에 따라 발화를 학습 세트와 테스트 세트 간에 분할합니다. 또는 학습 및 테스트 데이터의 수동 분할을 사용할 수 있습니다. 이 옵션은 레이블을 발화에 지정할 때 발화를 테스트 세트에 추가한 경우에만 사용할 수 있습니다.
학습 단추를 선택합니다.
목록에서 학습 작업 ID를 선택합니다. 이 작업에 대한 학습 진행률, 작업 상태 및 기타 세부 정보를 확인할 수 있는 창이 표시됩니다.
참고 항목
- 성공적으로 완료된 학습 작업만 모델을 생성합니다.
- 학습은 발화 수에 따라 몇 분에서 몇 시간까지 걸릴 수 있습니다.
- 한 번에 하나의 학습 작업만 실행할 수 있습니다. 실행 중인 작업이 완료될 때까지 동일한 프로젝트 내에서 다른 학습 작업을 시작할 수 없습니다.
- 모델을 학습시키는 데 사용되는 기계 학습은 정기적으로 업데이트됩니다. 이전 구성 버전에서 학습하려면 학습 작업 시작 페이지에서 여기를 선택하여 변경을 선택하고 이전 버전을 선택합니다.

모델 배포

일반적으로 모델을 학습시킨 후 평가 세부 정보를 검토합니다. 이 빠른 시작에서는 모델을 배포하고 Language Studio에서 사용해 볼 수 있도록 하거나, 예측 API를 호출할 수 있습니다.

Language Studio 내에서 모델을 배포하려면:

왼쪽 메뉴에서 모델 배포를 선택합니다.
배포 추가를 선택하여 배포 추가 마법사를 시작합니다.
새 배포 이름 만들기를 선택하여 새 배포를 만들고 아래 드롭다운에서 학습된 모델을 할당합니다. 그렇지 않으면 기존 배포 이름 덮어쓰기를 선택하여 기존 배포에서 사용하는 모델을 효과적으로 바꿀 수 있습니다.

참고 항목

기존 배포를 덮어쓸 때는 예측 API 호출을 변경할 필요가 없지만 새로 할당된 모델을 기반으로 결과를 얻을 수 있습니다.
모델 드롭다운에서 학습된 모델을 선택합니다.
배포를 선택하여 배포 작업을 시작합니다.
배포에 성공하면 만료 날짜가 옆에 표시됩니다. 배포 만료는 배포된 모델을 예측에 사용할 수 없게 되는 때이며, 일반적으로 학습 구성이 만료된 후 12개월 후에 발생합니다.

배포된 모델 테스트

Language Studio 내에서 배포된 모델을 테스트하려면 다음을 수행합니다.

왼쪽 메뉴에서 배포 테스트를 선택합니다.
다국어 프로젝트의 경우 텍스트 언어 선택 드롭다운에서 테스트할 발화의 언어를 선택합니다.
배포 이름 드롭다운에서 테스트하려는 모델에 해당하는 배포 이름을 선택합니다. 배포에 할당된 모델만 테스트할 수 있습니다.
텍스트 상자에 테스트할 발화를 입력합니다. 예를 들어, 메일 관련 발화에 대한 애플리케이션을 만든 경우 이 메일 삭제를 입력할 수 있습니다.
페이지 위쪽에서 테스트 실행을 선택합니다.
테스트를 실행한 후 결과에서 모델의 응답을 확인해야 합니다. 엔터티 카드 보기에서 결과를 보거나 JSON 형식으로 볼 수 있습니다.

리소스 정리

프로젝트가 더 이상 필요하지 않은 경우 언어 스튜디오를 사용하여 프로젝트를 삭제할 수 있습니다. 왼쪽 탐색 메뉴에서 프로젝트를 선택하고, 삭제하려는 프로젝트를 선택한 다음, 위쪽 메뉴에서 삭제를 선택합니다.

필수 조건

Azure 구독 - 체험 구독 만들기

Azure Portal에서 새 리소스 만들기

새로운 Azure AI 언어 리소스를 만들려면 Azure Portal에 로그인하세요.
새 리소스 만들기를 선택합니다.
표시되는 창에서 언어 서비스를 검색합니다.
만들기를 선택합니다.

다음 세부 정보를 사용하여 언어 리소스를 만듭니다.

인스턴스 세부 정보	필수 값
지역	언어 리소스에 대해 지원되는 지역 중 하나입니다.
이름	언어 리소스의 필수 이름
가격 책정 계층	언어 리소스에 대해 지원되는 가격 책정 계층 중 하나입니다.

리소스 키 및 엔드포인트 가져오기

Azure Portal에서 리소스 개요 페이지로 이동합니다.
왼쪽 메뉴에서 키 및 엔드포인트를 선택합니다. API 요청에 엔드포인트와 키를 사용합니다.

새 CLU 샘플 프로젝트 가져오기

언어 리소스를 만든 후에는 계정과 대화형 Language Understanding 프로젝트를 만듭니다. 프로젝트는 데이터를 기반으로 하는 사용자 지정 ML 모델을 빌드하기 위한 작업 영역입니다. 사용자 및 사용 중인 언어 리소스에 대해 액세스 권한이 있는 다른 사용자만 프로젝트에 액세스할 수 있습니다.

이 빠른 시작의 경우 이 샘플 프로젝트를 다운로드하여 가져올 수 있습니다. 이 프로젝트는 이메일 읽기, 이메일 삭제, 이메일에 문서 첨부와 같은 사용자 입력에서 의도한 명령을 예측할 수 있습니다.

프로젝트 가져오기 작업 트리거

다음 URL, 헤더 및 JSON 본문을 사용하여 POST 요청을 제출하여 프로젝트를 가져옵니다.

요청 URL

API 요청을 만들 때 다음 URL을 사용합니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:import?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분하며 가져오는 JSON 파일의 프로젝트 이름과 일치해야 합니다.	`EmailAppDemo`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

본문

보내는 JSON 본문은 다음 예제와 유사합니다. JSON 개체에 대한 자세한 내용은 참조 설명서를 참조하세요.

{
  "projectFileVersion": "{API-VERSION}",
  "stringIndexType": "Utf16CodeUnit",
  "metadata": {
    "projectKind": "Conversation",
    "settings": {
      "confidenceThreshold": 0.7
    },
    "projectName": "{PROJECT-NAME}",
    "multilingual": true,
    "description": "Trying out CLU",
    "language": "{LANGUAGE-CODE}"
  },
  "assets": {
    "projectKind": "Conversation",
    "intents": [
      {
        "category": "intent1"
      },
      {
        "category": "intent2"
      }
    ],
    "entities": [
      {
        "category": "entity1"
      }
    ],
    "utterances": [
      {
        "text": "text1",
        "dataset": "{DATASET}",
        "intent": "intent1",
        "entities": [
          {
            "category": "entity1",
            "offset": 5,
            "length": 5
          }
        ]
      },
      {
        "text": "text2",
        "language": "{LANGUAGE-CODE}",
        "dataset": "{DATASET}",
        "intent": "intent2",
        "entities": []
      }
    ]
  }
}

키	자리 표시자	값	예제
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`
`projectName`	`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`EmailAppDemo`
`language`	`{LANGUAGE-CODE}`	프로젝트에 사용된 발화의 언어 코드를 지정하는 문자열입니다. 프로젝트가 다국어 프로젝트인 경우 대부분의 발화에 대한 언어 코드를 선택합니다.	`en-us`
`multilingual`	`true`	데이터 세트에서 여러 언어로 된 문서를 포함할 수 있도록 하는 부울 값입니다. 모델이 배포되면 학습 문서에 포함되지 않은 언어를 포함한 모든 지원되는 언어로 모델을 쿼리할 수 있습니다.	`true`
`dataset`	`{DATASET}`	테스트 집합과 학습 집합 간에 데이터를 분할하는 방법에 대한 정보는 모델을 학습하는 방법을 참조하세요. 이 필드에 사용할 수 있는 값은 `Train` 및 `Test`입니다.	`Train`

요청이 성공하면 API 응답에는 가져오기 작업의 상태를 검사하는 데 사용할 수 있는 URL이 포함된 operation-location 헤더가 포함됩니다. 다음과 같은 형식으로 지정됩니다.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

가져오기 작업 상태 가져오기

성공적인 프로젝트 가져오기 요청을 보내면 가졍오기 작업 상태(엔드포인트, 프로젝트 이름 및 작업 ID 포함)를 확인하기 위한 전체 요청 URL이 응답의 operation-location 헤더에 포함됩니다.

다음 GET 요청을 사용하여 가져오기 작업의 상태를 쿼리합니다. 이전 단계에서 받은 URL을 사용하거나 자리 표시자 값을 자신의 값으로 바꿀 수 있습니다.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/import/jobs/{JOB-ID}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{JOB-ID}`	내보내기 작업 상태를 찾기 위한 ID입니다.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	설명	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.	`{YOUR-PRIMARY-RESOURCE-KEY}`

응답 본문

요청을 보내면 다음과 같은 응답이 수신됩니다. status 매개 변수가 "succeeded"로 변경될 때까지 이 엔드포인트를 계속 폴링합니다.

{
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx",
  "createdDateTime": "2022-04-18T15:17:20Z",
  "lastUpdatedDateTime": "2022-04-18T15:17:22Z",
  "expirationDateTime": "2022-04-25T15:17:20Z",
  "status": "succeeded"
}

모델 학습 시작

일반적으로 프로젝트를 만든 후에는 스키마를 빌드하고 발화에 태그를 지정해야 합니다. 이 빠른 시작에서는 빌드된 스키마와 태그가 지정된 발화가 있는 준비된 프로젝트를 이미 가져왔습니다.

다음 URL, 헤더 및 JSON 본문을 사용하여 POST 요청을 만들어 학습 작업을 제출합니다.

요청 URL

API 요청을 만들 때 다음 URL을 사용합니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:train?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분합니다.	`EmailApp`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

요청 본문

요청에 다음 개체를 사용합니다. 학습이 완료되면 modelLabel 매개 변수에 사용하는 값의 이름을 따서 모델 이름이 지정됩니다.

{
  "modelLabel": "{MODEL-NAME}",
  "trainingMode": "{TRAINING-MODE}",
  "trainingConfigVersion": "{CONFIG-VERSION}",
  "evaluationOptions": {
    "kind": "percentage",
    "testingSplitPercentage": 20,
    "trainingSplitPercentage": 80
  }
}

키	자리 표시자	값	예제
`modelLabel`	`{MODEL-NAME}`	사용자의 모델 이름.	`Model1`
`trainingConfigVersion`	`{CONFIG-VERSION}`	학습 구성 모델 버전입니다. 기본적으로 최신 모델 버전이 사용됩니다.	`2022-05-01`
`trainingMode`	`{TRAINING-MODE}`	학습에 사용할 학습 모드입니다. 지원되는 모드는 더 빠른 학습이지만 영어로만 사용할 수 있는 표준 학습 및 다른 언어 및 다국어 프로젝트에 지원되지만 학습 시간이 더 오래 걸리는 고급 학습입니다. 학습 모드에 대해 자세히 알아봅니다.	`standard`
`kind`	`percentage`	분할 방법입니다. 가능한 값은 `percentage` 또는 `manual`입니다. 자세한 내용은 모델 학습 방법을 참조하세요.	`percentage`
`trainingSplitPercentage`	`80`	학습 세트에 포함할 태그가 지정된 데이터의 백분율입니다. 권장 값은 `80`입니다.	`80`
`testingSplitPercentage`	`20`	테스트 세트에 포함할 태그가 지정된 데이터의 백분율입니다. 권장 값은 `20`입니다.	`20`

참고 항목

Kind가 percentage로 설정되고 두 백분율의 합계가 100이어야 하는 경우에만 trainingSplitPercentage 및 testingSplitPercentage가 필요합니다.

API 요청을 보내면 성공을 나타내는 202 응답을 받게 됩니다. 응답 헤더에서 operation-location 값을 추출합니다. 다음과 같이 형식이 지정됩니다.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

이 URL을 사용하여 학습 작업 상태를 가져올 수 있습니다.

학습 작업 상태 가져오기

학습을 완료하는 데 시간이 걸릴 수 있습니다. 경우에 따라 10분~30분 정도 소요될 수 있습니다. 다음 요청을 사용하여 성공적으로 완료될 때까지 학습 작업의 상태를 계속 폴링할 수 있습니다.

성공적인 학습 요청을 보내면 작업의 상태 확인하기 위한 전체 요청 URL(엔드포인트, 프로젝트 이름 및 작업 ID 포함)이 응답의 operation-location 헤더에 포함됩니다.

다음 GET 요청을 사용하여 모델의 학습 진행률에 대한 상태를 가져옵니다. 아래의 자리 표시자 값을 자신의 값으로 바꿉니다.

요청 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/train/jobs/{JOB-ID}?api-version={API-VERSION}

자리 표시자	값	예제
`{YOUR-ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분합니다.	`EmailApp`
`{JOB-ID}`	모델의 학습 상태를 찾기 위한 ID입니다.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

응답 본문

요청을 보내면 다음과 같은 응답을 받게 됩니다. status 매개 변수가 "succeeded"로 변경될 때까지 이 엔드포인트를 계속 폴링합니다.

{
  "result": {
    "modelLabel": "{MODEL-LABEL}",
    "trainingConfigVersion": "{TRAINING-CONFIG-VERSION}",
    "trainingMode": "{TRAINING-MODE}",
    "estimatedEndDateTime": "2022-04-18T15:47:58.8190649Z",
    "trainingStatus": {
      "percentComplete": 3,
      "startDateTime": "2022-04-18T15:45:06.8190649Z",
      "status": "running"
    },
    "evaluationStatus": {
      "percentComplete": 0,
      "status": "notStarted"
    }
  },
  "jobId": "xxxxx-xxxxx-xxxx-xxxxx-xxxx",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

키	값	예제
`modelLabel`	모델 이름	`Model1`
`trainingConfigVersion`	학습 구성 버전입니다. 기본적으로 최신 버전이 사용됩니다.	`2022-05-01`
`trainingMode`	선택한 학습 모드	`standard`
`startDateTime`	학습 시작 시간	`2022-04-14T10:23:04.2598544Z`
`status`	학습 작업 상태	`running`
`estimatedEndDateTime`	예상 학습 작업 완료 시간	`2022-04-14T10:29:38.2598544Z`
`jobId`	학습 작업 ID	`xxxxx-xxxx-xxxx-xxxx-xxxxxxxxx`
`createdDateTime`	학습 작업 생성 날짜 및 시간	`2022-04-14T10:22:42Z`
`lastUpdatedDateTime`	학습 작업 마지막 업데이트 날짜 및 시간	`2022-04-14T10:23:45Z`
`expirationDateTime`	학습 작업 만료 날짜 및 시간	`2022-04-14T10:22:42Z`

모델 배포

일반적으로 모델을 학습시킨 후 평가 세부 정보를 검토합니다. 이 빠른 시작에서는 모델을 배포하고 예측 API를 호출하여 결과를 쿼리합니다.

배포 작업 제출

다음 URL, 헤더 및 JSON 본문을 사용하여 PUT 요청을 만들어 대화형 언어 이해 모델 배포를 시작합니다.

요청 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{DEPLOYMENT-NAME}`	배포의 이름입니다. 이 값은 대/소문자를 구분합니다.	`staging`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

요청 본문

{
  "trainedModelLabel": "{MODEL-NAME}",
}

키	자리 표시자	값	예제
trainedModelLabel	`{MODEL-NAME}`	배포에 할당될 모델 이름입니다. 성공적으로 학습된 모델만 할당할 수 있습니다. 이 값은 대/소문자를 구분합니다.	`myModel`

API 요청을 보내면 성공을 나타내는 202 응답을 받게 됩니다. 응답 헤더에서 operation-location 값을 추출합니다. 다음과 같이 형식이 지정됩니다.

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

이 URL을 사용하여 배포 작업 상태를 가져올 수 있습니다.

배포 작업 상태 가져오기

성공적인 배포 요청을 보내면 작업 상태(엔드포인트, 프로젝트 이름 및 작업 ID 포함)를 확인하기 위한 전체 요청 URL이 응답의 operation-location 헤더에 포함됩니다.

다음 GET 요청을 사용하여 배포 작업의 상태를 가져옵니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

요청 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/deployments/{DEPLOYMENT-NAME}/jobs/{JOB-ID}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{DEPLOYMENT-NAME}`	배포의 이름입니다. 이 값은 대/소문자를 구분합니다.	`staging`
`{JOB-ID}`	모델의 학습 상태를 찾기 위한 ID입니다.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

응답 본문

요청을 보내면 다음과 같은 응답이 수신됩니다. status 매개 변수가 "succeeded"로 변경될 때까지 이 엔드포인트를 계속 폴링합니다.

{
    "jobId":"{JOB-ID}",
    "createdDateTime":"{CREATED-TIME}",
    "lastUpdatedDateTime":"{UPDATED-TIME}",
    "expirationDateTime":"{EXPIRATION-TIME}",
    "status":"running"
}

모델 쿼리

모델이 배포된 후 예측 API를 통해 예측하는 데 사용할 수 있습니다.

배포가 성공하면 배포된 모델에서 예측에 대한 쿼리를 시작할 수 있습니다.

다음 URL, 헤더 및 JSON 본문을 사용하여 POST 요청을 만들어 대화형 Language Understanding 모델 테스트를 시작합니다.

요청 URL

{ENDPOINT}/language/:analyze-conversations?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

요청 본문

{
  "kind": "Conversation",
  "analysisInput": {
    "conversationItem": {
      "id": "1",
      "participantId": "1",
      "text": "Text 1"
    }
  },
  "parameters": {
    "projectName": "{PROJECT-NAME}",
    "deploymentName": "{DEPLOYMENT-NAME}",
    "stringIndexType": "TextElement_V8"
  }
}

키	자리 표시자	값	예제
`participantId`	`{JOB-NAME}`		`"MyJobName`
`id`	`{JOB-NAME}`		`"MyJobName`
`text`	`{TEST-UTTERANCE}`	의도를 예측하고 엔터티를 추출하려는 발화입니다.	`"Read Matt's email`
`projectName`	`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`deploymentName`	`{DEPLOYMENT-NAME}`	배포의 이름입니다. 이 값은 대/소문자를 구분합니다.	`staging`

요청을 보내면 예측에 대해 다음과 같은 응답을 받게 됩니다.

응답 본문

{
  "kind": "ConversationResult",
  "result": {
    "query": "Text1",
    "prediction": {
      "topIntent": "inten1",
      "projectKind": "Conversation",
      "intents": [
        {
          "category": "intent1",
          "confidenceScore": 1
        },
        {
          "category": "intent2",
          "confidenceScore": 0
        },
        {
          "category": "intent3",
          "confidenceScore": 0
        }
      ],
      "entities": [
        {
          "category": "entity1",
          "text": "text1",
          "offset": 29,
          "length": 12,
          "confidenceScore": 1
        }
      ]
    }
  }
}

키	샘플 값	설명
query	“Matt의 메일 읽기”	쿼리를 위해 제출한 텍스트입니다.
topIntent	“읽기”	신뢰도 점수가 가장 높은 예측 의도입니다.
의도	[]	쿼리 텍스트에 대해 예측된 모든 의도 목록과 각각의 신뢰도 점수입니다.
엔터티	[]	쿼리 텍스트에서 추출된 엔터티 목록을 포함하는 배열입니다.

대화 프로젝트에 대한 API 응답

대화 프로젝트에서는 프로젝트 내에 있는 의도와 엔터티 모두에 대한 예측을 얻을 수 있습니다.

의도 및 엔터티에는 모델에서 프로젝트의 특정 요소를 예측하는 것과 관련하여 0.0~1.0 사이의 신뢰도 점수가 포함됩니다.
상위 채점 의도가 자체 매개 변수 내에 포함되어 있습니다.
예측된 엔터티만 응답에 표시됩니다.
엔터티는 다음을 표시합니다.
- 추출된 엔터티의 텍스트입니다.
- 오프셋 값으로 표시되는 시작 위치
- 길이 값으로 표시되는 엔터티 텍스트의 길이입니다.

리소스 정리

프로젝트가 더 이상 필요하지 않은 경우 API를 사용하여 프로젝트를 삭제할 수 있습니다.

다음 URL, 헤더 및 JSON 본문을 사용하여 DELETE 요청을 만들어 대화형 언어 이해 프로젝트를 삭제합니다.

요청 URL

{ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트에 대한 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{API-VERSION}`	호출하는 API의 버전입니다.	`2023-04-01`

헤더

다음 헤더를 사용하여 요청을 인증합니다.

키	값
`Ocp-Apim-Subscription-Key`	리소스의 키입니다. API 요청을 인증하는 데 사용됩니다.

API 요청을 보내면 성공을 나타내는 202 응답을 받게 됩니다. 이는 프로젝트가 삭제되었음을 의미합니다.

다음 단계

엔터티 구성 요소에 대해 알아보기

다음을 통해 공유

빠른 시작: 대화형 Language Understanding

필수 조건

Language Studio에 로그인

대화 언어 이해 프로젝트 만들기

모델 학습

모델 배포

배포된 모델 테스트

리소스 정리

필수 조건

Azure Portal에서 새 리소스 만들기

리소스 키 및 엔드포인트 가져오기

새 CLU 샘플 프로젝트 가져오기

프로젝트 가져오기 작업 트리거

요청 URL

헤더

본문

가져오기 작업 상태 가져오기

헤더

응답 본문

모델 학습 시작

요청 URL

헤더

요청 본문

학습 작업 상태 가져오기

요청 URL

헤더

응답 본문

모델 배포

배포 작업 제출

요청 URL

헤더

요청 본문

배포 작업 상태 가져오기

요청 URL

헤더

응답 본문

모델 쿼리

요청 URL

헤더

요청 본문

응답 본문

대화 프로젝트에 대한 API 응답

리소스 정리

요청 URL

헤더

다음 단계

피드백

추가 리소스