빠른 시작: 사용자 지정 명명된 엔터티 인식

이 가이드에서는 Microsoft Foundry 또는 REST API와 함께 사용자 지정 명명된 엔터티 인식(NER)을 사용하기 위한 단계별 지침을 제공합니다. NER를 사용하면 사람, 장소, 조직 및 숫자와 같은 구조화되지 않은 텍스트에서 엔터티를 검색하고 분류할 수 있습니다. 사용자 지정 NER를 사용하면 비즈니스와 관련된 엔터티를 식별하고 필요에 따라 조정하도록 모델을 학습시킬 수 있습니다.

시작하기 위해 샘플 대출 계약은 사용자 지정 NER 모델을 빌드하고 이러한 주요 엔터티를 추출하기 위한 데이터 세트로 제공됩니다.

계약 날짜
대출자의 이름, 주소, 도시 및 주
대출 기관의 이름, 주소, 도시 및 주
대출 및 이자 금액

참고

자체적으로 사용하든 Language Studio를 통해 사용하든 간에 Foundry 도구 또는 다중 서비스 리소스에 Azure 언어가 이미 있는 경우 Microsoft Foundry 포털 내에서 기존 언어 리소스를 계속 사용할 수 있습니다. 자세한 내용은 Foundry 포털에서 Foundry 도구를 사용하는 방법을 참조하세요.

필수 구성 요소

Azure 구독. GitHub 계정이 없는 경우 무료로 만들 수 있습니다.
필수 권한입니다. 계정 및 프로젝트를 설정하는 사람이 구독 수준에서 Azure AI 계정 소유자 역할로 할당되었는지 확인합니다. 또는 구독 범위에서 기여자 또는 Cognitive Services 기여자 역할을 갖는 것도 이 요구 사항을 충족합니다. 자세한 내용은 RBAC(역할 기반 액세스 제어)를 참조하세요.
스토리지 계정이 있는 언어 리소스입니다. 추가 기능 선택 페이지에서 사용자 지정 텍스트 분류, 사용자 지정 명명된 엔터티 인식, 사용자 지정 감정 분석 및 상태용 사용자 지정 텍스트 분석을 선택하여 필요한 스토리지 계정을 이 리소스에 연결합니다.

참고

언어 리소스를 만들려면 리소스 그룹에 소유자 역할이 할당되어 있어야 합니다.
기존 스토리지 계정을 연결하는 경우 소유자 역할이 할당되어야 합니다.
Azure Language 리소스와 연결되면 스토리지 계정을 다른 리소스 그룹 또는 구독으로 이동하지 마세요.

Foundry 내에서 생성된 Foundry 프로젝트입니다. 자세한 내용은 Foundry 프로젝트 만들기를참조하세요.
스토리지 컨테이너에 업로드된 사용자 지정 NER 데이터 세트입니다. NER(사용자 지정 명명된 엔터티 인식) 데이터 세트는 사용자 지정 NER 모델을 학습시키는 데 사용되는 레이블이 지정된 텍스트 문서의 컬렉션입니다. 이 빠른 시작에 대한 샘플 데이터 세트를 다운로드 할 수 있습니다. 소스 언어는 영어입니다.

1단계: 필요한 역할, 권한 및 설정 구성

먼저 리소스를 구성해 보겠습니다.

사용자 지정 명명된 엔터티 인식 기능 사용

Azure Portal에서 사용자 지정 텍스트 분류/사용자 지정 명명된 엔터티 인식 기능이 사용하도록 설정되어 있는지 확인합니다.

Azure Portal에서 언어 리소스로 이동합니다.
왼쪽 메뉴의 리소스 관리 섹션에서 기능을 선택합니다.
사용자 지정 텍스트 분류/사용자 지정 명명된 엔터티 인식 기능이 사용하도록 설정되어 있는지 확인합니다.
스토리지 계정이 할당되지 않은 경우 스토리지 계정을 선택하고 연결합니다.
적용을 선택합니다.

언어 리소스에 필요한 역할 추가

Azure Portal의 언어 리소스 페이지에서 왼쪽 창에서 액세스 제어(IAM)를 선택합니다.
역할 할당 추가를 선택하고 언어 리소스에 대한 Cognitive Services 언어 소유자 또는 Cognitive Services 기여자 역할 할당을 추가합니다.
다음에 대한 액세스 권한 할당 내에서 사용자, 그룹 또는 서비스 주체를 선택합니다.
멤버 선택을 선택합니다.
사용자 이름을 선택합니다. 선택 필드에서 사용자 이름을 검색할 수 있습니다. 모든 역할에 대해 이 단계를 반복합니다.
이 리소스에 액세스해야 하는 모든 사용자 계정에 대해 이 단계를 반복합니다.

스토리지 계정에 필요한 역할 추가

Azure Portal의 스토리지 계정 페이지로 이동합니다.
왼쪽 창에서 액세스 제어(IAM) 를 선택합니다.
역할 할당 추가에 추가를 선택하고 스토리지 계정에서 Storage Blob 데이터 기여자 역할을 선택합니다.
액세스 할당 내에서 관리 ID를 선택합니다.
멤버 선택을 선택합니다.
구독을 선택하고 언어 를 관리 ID로 선택합니다. 선택 필드에서 언어 리소스를 검색할 수 있습니다.

필요한 사용자 역할 추가

중요

이 단계를 건너뛰면 사용자 지정 프로젝트에 연결하려고 하면 403 오류가 발생합니다. 현재 사용자는 스토리지 계정의 소유자인 경우에도 스토리지 계정 Blob 데이터에 액세스하기 위해 이 역할을 맡는 것이 중요합니다.

Azure Portal의 스토리지 계정 페이지로 이동합니다.
왼쪽 창에서 액세스 제어(IAM) 를 선택합니다.
역할 할당 추가에 추가를 선택하고 스토리지 계정에서 Storage Blob 데이터 기여자 역할을 선택합니다.
다음에 대한 액세스 권한 할당 내에서 사용자, 그룹 또는 서비스 주체를 선택합니다.
멤버 선택을 선택합니다.
사용자를 선택합니다. 선택 필드에서 사용자 이름을 검색할 수 있습니다.

중요

방화벽 또는 가상 네트워크 또는 프라이빗 엔드포인트가 있는 경우 신뢰할 수 있는 서비스 목록에서 Azure 서비스가 Azure Portal의 네트워킹 탭에서 이 스토리지 계정에 액세스하도록 허용을 선택해야 합니다.

Foundry에서 사용하도록 설정된 Azure 서비스 허용 스크린샷

2단계: 스토리지 컨테이너에 데이터 세트 업로드

다음으로, 컨테이너를 추가하고 데이터 세트 파일을 스토리지 컨테이너의 루트 디렉터리에 직접 업로드해 보겠습니다. 이러한 문서는 모델을 학습시키는 데 사용됩니다.

언어 리소스와 연결된 스토리지 계정에 컨테이너를 추가합니다. 자세한 내용은 컨테이너 만들기를참조하세요.
GitHub에서 샘플 데이터 세트를 다운로드합니다. 제공된 샘플 데이터 세트에는 20개의 대출 계약이 포함되어 있습니다.
- 각 계약에는 대출 기관과 대출자라는 두 당사자가 포함됩니다.
- 두 당사자, 계약 날짜, 대출 금액 및 이자율에 대한 관련 정보를 추출합니다.
.zip 파일을 열고 문서가 포함된 폴더를 추출합니다.
Foundry로 이동합니다.
아직 로그인하지 않은 경우 포털에서 Azure 자격 증명으로 로그인하라는 메시지를 표시합니다.
로그인한 후 이 빠른 시작을 위해 기존 Foundry 프로젝트에 액세스합니다.
왼쪽 탐색 메뉴에서 관리 센터를 선택합니다.
관리 센터 메뉴의 허브 섹션에서 연결된 리소스를 선택합니다.
그런 다음 연결된 리소스로 설정된 작업 영역 Blob Storage를 선택합니다.
작업 영역 Blob Storage에서 Azure 포털에서 보기를 선택합니다.
Blob Storage에 대한 AzurePortal 페이지의 위쪽 메뉴에서 업로드 를 선택합니다. 다음으로, 이전에 다운로드한 .txt 파일 및 .json 파일을 선택합니다. 마지막으로 업로드 단추를 선택하여 컨테이너에 파일을 추가합니다.

이제 필요한 Azure 리소스가 Azure Portal 내에서 프로비전되고 구성되었으므로, Foundry에서 이러한 리소스를 사용하여 명명된 개체 인식 (NER) 모델을 최적화해 보겠습니다.

3단계: 언어 리소스 연결

다음으로 Foundry가 안전하게 액세스할 수 있도록 언어 리소스에 대한 연결을 만듭니다. 이 연결은 보안 ID 관리 및 인증뿐만 아니라 데이터에 대한 제어 및 격리된 액세스를 제공합니다.

Foundry로 돌아갑니다.
이 빠른 시작을 위해 기존 Foundry 프로젝트에 액세스합니다.
왼쪽 탐색 메뉴에서 관리 센터를 선택합니다.
관리 센터 메뉴의 허브 섹션에서 연결된 리소스를 선택합니다.
주 창에서 + 새 연결 단추를 선택합니다.
외부 자산에 대한 연결 추가 창에서 언어를 선택합니다.
연결 추가를 선택한 다음, 닫기를 선택합니다.

4단계: 사용자 지정 NER 모델 미세 조정

이제 사용자 지정 NER 미세 조정 모델을 만들 준비가 되었습니다.

관리 센터 메뉴의 프로젝트 섹션에서 프로젝트로 이동을 선택합니다.
개요 메뉴에서 미세 조정을 선택합니다.
주 창에서 AI 서비스 미세 조정 탭을 선택한 다음 + 미세 조정 단추를 선택합니다.
서비스 만들기 미세 조정 창에서 사용자 지정 명명된 엔터티 인식 탭을 선택한 다음, 다음을 선택합니다.
서비스 만들기 미세 조정 작업 창에서 다음과 같이 필드를 완료합니다.
- 연결된 서비스입니다. 언어 리소스의 이름은 기본적으로 이 필드에 이미 나타나야 합니다. 그렇지 않으면 드롭다운 메뉴에서 추가합니다.
- 이름. 미세 조정 작업 프로젝트에 이름을 지정합니다.
- 언어. 영어는 기본값으로 설정되며 필드에 이미 나타납니다.
- Description. 필요에 따라 설명을 제공하거나 이 필드를 비워 둘 수 있습니다.
- Blob 저장 컨테이너. 2단계에서 작업 영역 Blob Storage 컨테이너를 선택하고 연결 단추를 선택합니다.
마지막으로 만들기 단추를 선택합니다. 만들기 작업이 완료되는 데 몇 분 정도 걸릴 수 있습니다.

5단계: 모델 학습

Foundry의 미세 조정 워크플로 스크린샷

시작 메뉴에서 데이터 관리를 선택합니다. 학습 및 테스트용 데이터 추가 창에 이전에 Azure Blob Storage 컨테이너에 업로드한 샘플 데이터가 표시됩니다.
다음으로 시작하기 메뉴에서 모델 학습을 선택합니다.
+ Train model 버튼을 선택합니다. 새 모델 학습 창이 나타나면 새 모델의 이름을 입력하고 기본값을 유지합니다. 다음 버튼을 선택합니다.
새 모델 학습 창에서 기본값으로 학습 데이터에서 테스트 세트를 자동으로 분할하는 기능을 활성화 상태로 유지하고, 학습 데이터는 80%, 테스트 데이터는 20%로 권장 비율을 설정합니다.
모델 구성을 검토한 다음 만들기 단추를 선택합니다.
모델을 학습한 후 시작 메뉴에서 모델 평가(Evaluate model)를 선택할 수 있습니다. 모델 평가 창에서 모델을 선택하고 필요한 경우 개선할 수 있습니다.

6단계: 모델 배포

일반적으로 모델을 학습한 후 평가 세부 정보를 검토합니다. 이 빠른 시작에서는 모델을 배포하고 Azure Language Playground에서 또는 예측 API를 호출하여 테스트할 수 있도록 할 수 있습니다. 그러나 원하는 경우 잠시 시간을 내어 왼쪽 메뉴에서 모델 평가를 선택하고 모델에 대한 심층 원격 분석을 탐색할 수 있습니다. Foundry 내에서 모델을 배포하려면 다음 단계를 완료합니다.

왼쪽 메뉴에서 모델 배포 를 선택합니다.
다음으로, 모델 배포 창에서 ➕학습된 모델 배포를 선택합니다.
새 배포 만들기 단추가 선택되어 있는지 확인합니다.
학습된 모델 배포 창 필드를 완료합니다.
- 배포 이름입니다. 모델 이름을 지정합니다.
- 모델을 할당합니다. 드롭다운 메뉴에서 학습된 모델을 선택합니다.
- 지역. 드롭다운 메뉴에서 지역을 선택합니다.
마지막으로 만들기 단추를 선택합니다. 모델을 배포하는 데 몇 분 정도 걸릴 수 있습니다.
배포에 성공하면 모델 배포 페이지에서 모델의 배포 상태를 볼 수 있습니다. 표시되는 만료 날짜는 배포된 모델을 예측 작업에 사용할 수 없게 되는 날짜를 표시합니다. 이 날짜는 일반적으로 학습 구성이 배포된 후 18개월입니다.

7단계: Azure 언어 플레이그라운드 사용해 보기

언어 플레이그라운드는 코드를 작성하지 않고도 프로덕션 환경에 배포하기 전에 미세 조정된 모델을 테스트하고 구성하는 샌드박스를 제공합니다.

상단 메뉴 모음에서 놀이터에서 체험을 선택합니다.
Azure Language Playground 창에서 사용자 지정 명명된 엔터티 인식 타일을 선택합니다.
구성 섹션의 드롭다운 메뉴에서 프로젝트 이름 및 배포 이름을 선택합니다.
엔터티를 입력하고 실행을 선택합니다.
세부 정보 창에서 결과를 평가할 수 있습니다.

완료되었습니다. 축하합니다!

이 빠른 시작에서는 미세 조정된 사용자 지정 NER 모델을 만들고, Foundry에 배포하고, Azure Language Playground에서 모델을 테스트했습니다.

리소스 정리

프로젝트가 더 이상 필요하지 않은 경우 Foundry에서 삭제할 수 있습니다.

Foundry 홈페이지로 이동합니다. 이 단계를 이미 완료하고 세션이 활성 상태인 경우가 아니면 로그인하여 인증 프로세스를 시작합니다.
Foundry를 사용하여 건물 유지에서 삭제할 프로젝트를 선택합니다.
관리 센터를 선택합니다.
프로젝트 삭제를 선택합니다.

모든 프로젝트와 함께 허브를 삭제하려면 다음을 수행합니다.

허브 섹션의 개요 탭으로 이동합니다.
오른쪽에서 허브 삭제를 선택합니다.
이 링크는 Azure 포털을 열어서 사용자가 허브를 삭제할 수 있도록 합니다.

필수 구성 요소

Azure 구독 - 체험 구독 만들기

Foundry Tools 리소스 및 Azure Storage 계정에서 새 Azure 언어 만들기

NER(사용자 지정 명명된 엔터티 인식)를 사용하려면 먼저 프로젝트를 만들고 모델 학습을 시작하는 데 필요한 자격 증명을 제공하는 언어 리소스를 만들어야 합니다. 모델을 빌드하는 데 사용되는 데이터 세트를 업로드할 수 있는 Azure Storage 계정도 필요합니다.

중요

빠르게 시작하려면 새 언어 리소스를 만드는 것이 좋습니다. 이 문서에 제공된 단계를 사용하여 Azure 언어 리소스를 만들고 동시에 스토리지 계정을 만들고/또는 연결합니다. 둘 다 동시에 만드는 것이 나중에 수행하는 것보다 쉽습니다.

사용하려는 기존 리소스가 있는 경우 스토리지 계정에 연결해야 합니다. 자세한 내용은 프로젝트 만들기를 참조하세요.

Azure Portal에서 새 리소스 만들기

Azure Portal에 로그인하여 Foundry Tools 리소스에서 새 Azure 언어를 만듭니다.
표시되는 창의 사용자 지정 기능에서 사용자 지정 텍스트 분류 및 사용자 지정 명명된 엔터티 인식을 선택합니다. 화면 하단에서 계속해서 리소스 만들기를 선택합니다.

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

이름	설명
Subscription	Azure 구독.
리소스 그룹	내 리소스를 포함하는 리소스 그룹. 기존 리소스 그룹을 사용하거나 새로 만들 수 있습니다.
지역	언어 리소스의 지역입니다. 예를 들어 "미국 서부 2"입니다.
이름	리소스의 이름입니다.
가격 책정 계층	언어 리소스에 대한 가격 책정 계층입니다. 무료(F0) 계층을 사용하여 서비스를 사용해 볼 수 있습니다.

참고

"로그인 계정이 선택한 스토리지 계정의 리소스 그룹의 소유자가 아닙니다"라는 메시지가 표시되는 경우 언어 리소스를 만들려면 계정에 리소스 그룹에 할당된 소유자 역할이 있어야 합니다. 도움이 필요하면 Azure 구독 소유자에게 문의합니다.

사용자 지정 텍스트 분류 및 사용자 지정 명명된 엔터티 인식 섹션에서 기존 스토리지 계정을 선택하거나 새 스토리지 계정을 선택합니다. 이러한 값은 프로덕션 환경에서 사용하려는 스토리지 계정 값 이 아니라 시작하는 데 도움이 됩니다. 프로젝트를 빌드하는 동안 대기 시간을 방지하려면 언어 리소스와 동일한 지역의 스토리지 계정에 연결합니다.

스토리지 계정 값 권장되는 값

스토리지 계정 이름 임의의 이름

Storage 계정 유형 표준 LRS(로컬 중복 스토리지)
책임 있는 AI 알림이 선택되어 있는지 확인합니다. 페이지 하단에서 검토 + 만들기를 선택한 다음, 만들기를 선택합니다.

스토리지 계정 값	권장되는 값
스토리지 계정 이름	임의의 이름
Storage 계정 유형	표준 LRS(로컬 중복 스토리지)

Blob 컨테이너에 샘플 데이터 업로드

Azure Storage 계정을 만들고 언어 리소스에 연결한 후에는 샘플 데이터 세트의 문서를 컨테이너의 루트 디렉터리에 업로드해야 합니다. 이러한 문서는 모델을 학습시키는 데 사용됩니다.

GitHub에서 샘플 데이터 세트를 다운로드합니다.
.zip 파일을 열고 문서가 포함된 폴더를 추출합니다.
Azure Portal에서 생성된 스토리지 계정으로 이동하고 선택합니다.
스토리지 계정에서 데이터 스토리지 아래에 있는 왼쪽 메뉴에서 컨테이너를 선택합니다. 표시된 화면에서 + 컨테이너를 선택합니다. 컨테이너에 example-data 이름을 지정하고 기본 공개 액세스 수준을 그대로 둡니다.
컨테이너를 만든 후 선택합니다. 그런 다음 업로드 단추를 선택하여 이전에 다운로드한 .txt 및 .json 파일을 선택합니다.

제공된 샘플 데이터 세트에는 20개의 대출 계약이 포함되어 있습니다. 각 계약에는 대출 기관과 대출자라는 두 당사자가 포함됩니다. 제공된 샘플 파일을 사용하여 두 당사자, 계약 날짜, 대출 금액 및 이자율에 대한 관련 정보를 추출할 수 있습니다.

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

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

사용자 지정 NER 프로젝트 만들기

리소스 및 스토리지 계정이 구성되면 새 사용자 지정 NER 프로젝트를 만듭니다. 프로젝트는 데이터를 기반으로 하는 사용자 지정 ML 모델을 빌드하기 위한 작업 영역입니다. 사용자의 프로젝트에는 사용자와 Azure 언어 리소스에 액세스할 수 있는 다른 사용자가 액세스할 수 있습니다.

이전 단계의 샘플 데이터에서 다운로드한 태그 파일을 사용하고 다음 요청의 본문에 추가합니다.

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

다음 URL, 헤더 및 JSON 본문을 사용하여 레이블 파일을 가져오는 POST 요청을 제출합니다. 레이블 파일이 허용되는 형식을 따르는지 확인합니다.

이름이 같은 프로젝트가 이미 있는 경우 해당 프로젝트의 데이터가 바뀝니다.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/:import?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{API-VERSION}`	호출하는 API의 버전입니다. 여기서 참조하는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

본문

요청에 다음 JSON을 사용합니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

{
    "projectFileVersion": "{API-VERSION}",
    "stringIndexType": "Utf16CodeUnit",
    "metadata": {
        "projectName": "{PROJECT-NAME}",
        "projectKind": "CustomEntityRecognition",
        "description": "Trying out custom NER",
        "language": "{LANGUAGE-CODE}",
        "multilingual": true,
        "storageInputContainerName": "{CONTAINER-NAME}",
        "settings": {}
    },
    "assets": {
    "projectKind": "CustomEntityRecognition",
        "entities": [
            {
                "category": "Entity1"
            },
            {
                "category": "Entity2"
            }
        ],
        "documents": [
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 500,
                        "labels": [
                            {
                                "category": "Entity1",
                                "offset": 25,
                                "length": 10
                            },
                            {
                                "category": "Entity2",
                                "offset": 120,
                                "length": 8
                            }
                        ]
                    }
                ]
            },
            {
                "location": "{DOCUMENT-NAME}",
                "language": "{LANGUAGE-CODE}",
                "dataset": "{DATASET}",
                "entities": [
                    {
                        "regionOffset": 0,
                        "regionLength": 100,
                        "labels": [
                            {
                                "category": "Entity2",
                                "offset": 20,
                                "length": 5
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

키	자리 표시자	값	예제
`api-version`	`{API-VERSION}`	호출하는 API의 버전입니다. 여기서 사용되는 버전은 URL에서 동일한 API 버전이어야 합니다. 사용 가능한 다른 API 버전에 대한 자세한 정보	`2022-03-01-preview`
`projectName`	`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`projectKind`	`CustomEntityRecognition`	프로젝트 종류입니다.	`CustomEntityRecognition`
`language`	`{LANGUAGE-CODE}`	프로젝트에 사용되는 문서의 언어 코드를 지정하는 문자열입니다. 프로젝트가 다국어 프로젝트인 경우 대부분의 문서의 언어 코드를 선택합니다.	`en-us`
`multilingual`	`true`	데이터 세트에 여러 언어로 된 문서를 포함할 수 있고 모델을 배포할 때 지원되는 모든 언어로 모델을 쿼리할 수 있는 부울 값입니다(반드시 학습 문서에 포함되지는 않음). 다국어 지원에 대한 내용은 언어 지원을 참조하세요.	`true`
`storageInputContainerName`	{CONTAINER-NAME}	업로드된 문서를 포함하는 Azure Storage 컨테이너의 이름입니다.	`myContainer`
`entities`		프로젝트에 있고 문서에서 추출한 모든 엔터티 형식을 포함하는 배열입니다.
`documents`		프로젝트의 모든 문서 및 각 문서 내에서 레이블이 지정된 엔터티 목록을 포함하는 배열입니다.	[]
`location`	`{DOCUMENT-NAME}`	스토리지 컨테이너에 있는 문서의 위치입니다.	`doc1.txt`
`dataset`	`{DATASET}`	학습 전 분할 시 이 파일이 이동하는 테스트 집합입니다. 자세한 내용은 모델 학습 방법을참조하세요. 이 필드에 사용할 수 있는 값은 `Train` 및 `Test`입니다.	`Train`

API 요청을 보내면 작업이 올바르게 제출되었음을 나타내는 응답을 받게 됩니다 202 . 응답 헤더에서 operation-location 값을 추출합니다. 형식의 예는 다음과 같습니다.

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

이 작업은 비동기식이므로 {JOB-ID}은 요청을 식별하는 데 사용됩니다. 이 URL을 사용하여 가져오기 작업 상태를 가져옵니다.

이 요청에 대한 가능한 오류 시나리오:

선택한 리소스에 스토리지 계정에 대한 적절한 권한이 없습니다.
지정한 storageInputContainerName이 없습니다.
잘못된 언어 코드가 사용되었거나 언어 코드 형식이 문자열이 아닌 경우입니다.
multilingual 값은 부울이 아닌 문자열입니다.

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

다음 GET 요청을 사용하여 프로젝트 가져오기의 상태를 가져옵니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

요청 URL

{ENDPOINT}/language/authoring/analyze-text/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입니다. 이 값은 이전 단계에서 받은 `location` 헤더 값에 있습니다.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

모델 학습

일반적으로 프로젝트를 만든 후에는 계속해서 프로젝트에 연결된 컨테이너에 있는 문서에 태그를 지정하기 시작합니다. 이 빠른 시작에서는 태그가 지정된 샘플 데이터 세트를 가져오고 샘플 JSON 태그 파일을 사용하여 프로젝트를 초기화했습니다.

학습 작업 시작

프로젝트를 가져온 후 모델 학습을 시작할 수 있습니다.

학습 작업을 제출하려면 다음 URL, 헤더 및 JSON 본문을 사용하여 POST 요청을 제출합니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

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

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

요청 본문

요청 본문에서 다음 JSON을 사용합니다. 학습이 완료되면 모델이 {MODEL-NAME} 로 제공됩니다. 성공적인 학습 작업만 모델을 생성합니다.

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

키	자리 표시자	값	예제
modelLabel	`{MODEL-NAME}`	성공적으로 학습되면 모델에 할당할 모델 이름입니다.	`myModel`
trainingConfigVersion	`{CONFIG-VERSION}`	모델을 학습시키는 데 사용되는 모델 버전 입니다.	`2022-05-01`
evaluationOptions		데이터를 학습 세트 및 테스트 세트 간에 분할하는 옵션입니다.	`{}`
kind	`percentage`	분할 방법입니다. 가능한 값은 `percentage` 또는 `manual`입니다. 자세한 내용은 모델 학습 방법을참조하세요.	`percentage`
trainingSplitPercentage	`80`	학습 세트에 포함할 태그가 지정된 데이터의 백분율입니다. 권장 값은 `80`입니다.	`80`
testingSplitPercentage	`20`	테스트 세트에 포함할 태그가 지정된 데이터의 백분율입니다. 권장 값은 `20`입니다.	`20`

참고

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

API 요청을 보내면 작업이 올바르게 제출되었음을 나타내는 응답을 받게 됩니다 202 . 응답 헤더에서 다음과 같이 포맷된 location 값을 추출합니다.

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

이 작업은 비동기식이므로 {JOB-ID}은 요청을 식별하는 데 사용됩니다. 이 URL을 사용하여 학습 상태를 가져올 수 있습니다.

학습 작업 상태 가져오기

이 샘플 데이터 세트에 대해 학습하는 데 10~30분 정도 걸릴 수 있습니다. 다음 요청을 사용하여 성공적으로 완료될 때까지 학습 작업의 상태를 계속 폴링할 수 있습니다.

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

요청 URL

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

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{JOB-ID}`	모델의 학습 상태를 찾기 위한 ID입니다. 이 값은 이전 단계에서 받은 `location` 헤더 값에 있습니다.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

응답 본문

요청을 보내면 다음과 같은 응답을 가져오게 됩니다.

{
  "result": {
    "modelLabel": "{MODEL-NAME}",
    "trainingConfigVersion": "{CONFIG-VERSION}",
    "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": "{JOB-ID}",
  "createdDateTime": "2022-04-18T15:44:44Z",
  "lastUpdatedDateTime": "2022-04-18T15:45:48Z",
  "expirationDateTime": "2022-04-25T15:44:44Z",
  "status": "running"
}

모델 배포

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

배포 작업 시작

다음 URL, 헤더 및 JSON 본문을 사용하여 PUT 요청을 제출하여 배포 작업을 제출합니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}/deployments/{deploymentName}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{DEPLOYMENT-NAME}`	배포의 이름입니다. 이 값은 대/소문자를 구분합니다.	`staging`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

요청 본문

요청 본문에서 다음 JSON을 사용합니다. 배포에 할당할 모델의 이름을 사용합니다.

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

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

API 요청을 보내면 작업이 올바르게 제출되었음을 나타내는 응답을 받게 됩니다 202 . 응답 헤더에서 다음과 같이 포맷된 operation-location 값을 추출합니다.

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

이 작업은 비동기식이므로 {JOB-ID}은 요청을 식별하는 데 사용됩니다. 이 URL을 사용하여 배포 상태를 가져올 수 있습니다.

배포 작업 상태 가져오기

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

{ENDPOINT}/language/authoring/analyze-text/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입니다. `location` 이전 단계에서 받은 헤더 값에 있습니다.	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

응답 본문

요청을 보내면 다음과 같은 응답을 가져오게 됩니다. status 매개 변수가 "succeeded"로 변경될 때까지 이 엔드포인트를 계속 폴링합니다. 요청의 성공을 나타내는 200 코드를 확인해 야 합니다.

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

사용자 지정 엔터티 추출

모델을 배포한 후에는 이를 사용하여 예측 API를 통해 텍스트에서 엔터티를 추출할 수 있습니다. 이전에 다운로드한 샘플 데이터 세트에서 이 단계에서 사용할 수 있는 몇 가지 테스트 문서를 찾을 수 있습니다.

사용자 지정 NER 작업 제출

이 POST 요청을 사용하여 텍스트 분류 작업을 시작합니다.

{ENDPOINT}/language/analyze-text/jobs?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

키	값
Ocp-Apim-Subscription-Key	이 API에 대한 액세스를 제공하는 키입니다.

본문

{
  "displayName": "Extracting entities",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "{LANGUAGE-CODE}",
        "text": "Text1"
      },
      {
        "id": "2",
        "language": "{LANGUAGE-CODE}",
        "text": "Text2"
      }
    ]
  },
  "tasks": [
     {
      "kind": "CustomEntityRecognition",
      "taskName": "Entity Recognition",
      "parameters": {
        "projectName": "{PROJECT-NAME}",
        "deploymentName": "{DEPLOYMENT-NAME}"
      }
    }
  ]
}

키	자리 표시자	값	예제
`displayName`	`{JOB-NAME}`	작업 이름입니다.	`MyJobName`
`documents`	[{},{}]	작업을 실행할 문서 목록입니다.	`[{},{}]`
`id`	`{DOC-ID}`	문서 이름 또는 ID입니다.	`doc1`
`language`	`{LANGUAGE-CODE}`	문서의 언어 코드를 지정하는 문자열입니다. 이 키를 지정하지 않으면 서비스는 프로젝트를 만드는 동안 선택한 프로젝트의 기본 언어를 가정합니다. 지원되는 언어 코드 목록은 언어 지원을 참조하세요.	`en-us`
`text`	`{DOC-TEXT}`	작업을 실행할 작업을 문서화합니다.	`Lorem ipsum dolor sit amet`
`tasks`		수행하려는 작업 목록입니다.	`[]`
`taskName`	`CustomEntityRecognition`	작업 이름	CustomEntityRecognition
`parameters`		작업에 전달할 매개 변수 목록입니다.
`project-name`	`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`deployment-name`	`{DEPLOYMENT-NAME}`	배포의 이름입니다. 이 값은 대/소문자를 구분합니다.	`prod`

응답

작업이 성공적으로 제출되었음을 나타내는 202 응답이 표시됩니다. 응답 헤더에서 operation-location을 추출합니다. operation-location은 다음과 같은 형식으로 지정됩니다.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

이 URL을 사용하여 작업 완료 상태를 쿼리하고 작업이 완료되면 결과를 가져올 수 있습니다.

작업 결과 가져오기

다음 GET 요청을 사용하여 사용자 지정 엔터티 인식 작업의 상태/결과를 쿼리합니다.

{ENDPOINT}/language/analyze-text/jobs/{JOB-ID}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

키	값
Ocp-Apim-Subscription-Key	이 API에 대한 액세스를 제공하는 키입니다.

응답 본문

응답은 다음 매개 변수가 포함된 JSON 문서입니다.

{
  "createdDateTime": "2021-05-19T14:32:25.578Z",
  "displayName": "MyJobName",
  "expirationDateTime": "2021-05-19T14:32:25.578Z",
  "jobId": "xxxx-xxxx-xxxxx-xxxxx",
  "lastUpdateDateTime": "2021-05-19T14:32:25.578Z",
  "status": "succeeded",
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "EntityRecognitionLROResults",
        "taskName": "Recognize Entities",
        "lastUpdateDateTime": "2020-10-01T15:01:03Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "entities": [
                {
                  "category": "Event",
                  "confidenceScore": 0.61,
                  "length": 4,
                  "offset": 18,
                  "text": "trip"
                },
                {
                  "category": "Location",
                  "confidenceScore": 0.82,
                  "length": 7,
                  "offset": 26,
                  "subcategory": "GPE",
                  "text": "Seattle"
                },
                {
                  "category": "DateTime",
                  "confidenceScore": 0.8,
                  "length": 9,
                  "offset": 34,
                  "subcategory": "DateRange",
                  "text": "last week"
                }
              ],
              "id": "1",
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2020-04-01"
        }
      }
    ]
  }
}

리소스 정리

프로젝트가 더 이상 필요하지 않은 경우 다음과 같은 DELETE 요청을 사용하여 삭제할 수 있습니다. 자리 표시자 값을 사용자 고유의 값으로 바꿉니다.

{Endpoint}/language/authoring/analyze-text/projects/{projectName}?api-version={API-VERSION}

자리 표시자	값	예제
`{ENDPOINT}`	API 요청을 인증하기 위한 엔드포인트입니다.	`https://<your-custom-subdomain>.cognitiveservices.azure.com`
`{PROJECT-NAME}`	프로젝트의 이름입니다. 이 값은 대/소문자를 구분합니다.	`myProject`
`{API-VERSION}`	호출하는 API의 버전입니다. 참조되는 값은 릴리스된 최신 버전에 대한 값입니다. 자세한 내용은 모델 수명 주기를 참조하세요.	`2022-05-01`

headers

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

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

API 요청을 보내면 성공을 나타내는 응답을 받게 202 됩니다. 즉, 프로젝트가 삭제됩니다. 작업의 상태를 확인하는 데 사용되는 Operation-Location 헤더가 포함된 성공적인 호출 결과.

엔터티 추출 모델을 만든 후 런타임 API를 사용하여 엔터티를 추출할 수 있습니다.

사용자 고유의 사용자 지정 NER 프로젝트를 만들 때 방법 문서를 사용하여 모델 태그 지정, 학습 및 사용에 대해 자세히 알아보세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-11-18

다음을 통해 공유

빠른 시작: 사용자 지정 명명된 엔터티 인식

필수 구성 요소

1단계: 필요한 역할, 권한 및 설정 구성

사용자 지정 명명된 엔터티 인식 기능 사용

언어 리소스에 필요한 역할 추가

스토리지 계정에 필요한 역할 추가

필요한 사용자 역할 추가

2단계: 스토리지 컨테이너에 데이터 세트 업로드

3단계: 언어 리소스 연결

4단계: 사용자 지정 NER 모델 미세 조정

5단계: 모델 학습

6단계: 모델 배포

7단계: Azure 언어 플레이그라운드 사용해 보기

리소스 정리

필수 구성 요소

Foundry Tools 리소스 및 Azure Storage 계정에서 새 Azure 언어 만들기

Azure Portal에서 새 리소스 만들기

Blob 컨테이너에 샘플 데이터 업로드

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

사용자 지정 NER 프로젝트 만들기

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

headers

본문

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

요청 URL

headers

모델 학습

학습 작업 시작

headers

요청 본문

학습 작업 상태 가져오기

요청 URL

headers

응답 본문

모델 배포

배포 작업 시작

headers

요청 본문

배포 작업 상태 가져오기

headers

응답 본문

사용자 지정 엔터티 추출

사용자 지정 NER 작업 제출

headers

본문

응답

작업 결과 가져오기

headers

응답 본문

리소스 정리

headers

관련 콘텐츠

피드백

추가 리소스