이번 글에서는 Azure AI Language 실습 폴더에 작성한 코드들을 하나씩 리뷰해보겠습니다.
실습한 기능은 NER, PII Detection, Sentiment Analysis, Key Phrase Extraction, Translation입니다.
단순히 “코드가 실행됐다”에서 끝내지 않고, 각 코드가 어떤 역할을 하는지, 왜 이런 구조로 작성했는지, 그리고 출력된 JSON 결과를 어떻게 읽어야 하는지까지 정리해보겠습니다.
이번 글의 핵심
Azure AI Language 실습 코드는 텍스트 하나를 여러 관점에서 분석하는 구조입니다. NER은 개체를 찾고, PII는 개인정보를 찾고, 감정 분석은 문장의 분위기를 판단하고, 핵심 구 추출은 중요한 표현을 뽑고, 번역은 다른 언어로 바꿉니다.
https://github.com/yunalee-dev/Azure-AI-Services-Labs
GitHub - yunalee-dev/Azure-AI-Services-Labs
Contribute to yunalee-dev/Azure-AI-Services-Labs development by creating an account on GitHub.
github.com
목차
1. 이번 실습 전체 구조
이번 실습은 Azure AI Language의 기본 기능을 Python 코드로 호출해보는 구조입니다. 하나의 샘플 데이터 파일을 두고, 각 기능별 Python 파일이 같은 데이터를 서로 다른 방식으로 분석합니다.
02-ai-language/
├── README.md
├── 01-ner/
│ └── analyze_ner.py
├── 02-pii-detection/
│ └── analyze_pii.py
├── 03-sentiment-analysis/
│ └── analyze_sentiment.py
├── 04-key-phrase-extraction/
│ └── analyze_key_phrases.py
├── 05-translation/
│ └── translate_text.py
├── notebooks/
├── sample-data/
│ └── language_samples.json
└── outputs/
├── key_phrase_results.json
├── ner_results.json
├── pii_results.json
├── sentiment_results.json
└── translation_results.jsonVS Code에서 결과 파일이 보이는 순서는 파일명 정렬이나 생성 순서에 따라 다를 수 있습니다. 하지만 실습 흐름 자체는 보통 아래 순서로 보는 것이 가장 이해하기 쉽습니다.
추천 실습 순서
NER → PII Detection → Sentiment Analysis → Key Phrase Extraction → Translation
이 순서가 좋은 이유는 먼저 텍스트 안에서 “무엇이 등장하는지”를 보고, 그중 개인정보가 무엇인지 확인한 다음, 문장의 분위기와 핵심 주제를 분석하고, 마지막으로 다른 언어로 변환하는 흐름이 자연스럽기 때문입니다.
2. 폴더와 파일 역할 리뷰
각 폴더는 하나의 기능을 담당합니다. 이렇게 기능별로 폴더를 나누면 나중에 GitHub에 올렸을 때도 구조가 명확하고, 블로그 글이나 포트폴리오 설명에도 활용하기 좋습니다.
| 파일 | 역할 | 결과 파일 |
|---|---|---|
| 01-ner/analyze_ner.py | 텍스트에서 사람, 조직, 장소, 날짜 같은 엔터티를 추출 | ner_results.json |
| 02-pii-detection/analyze_pii.py | 이름, 이메일, 전화번호 같은 개인정보를 탐지하고 마스킹 | pii_results.json |
| 03-sentiment-analysis/analyze_sentiment.py | 문장의 감정을 긍정, 중립, 부정으로 분석 | sentiment_results.json |
| 04-key-phrase-extraction/analyze_key_phrases.py | 문장에서 핵심 표현을 추출 | key_phrase_results.json |
| 05-translation/translate_text.py | Azure Translator REST API로 텍스트 번역 | translation_results.json |
3. language_samples.json의 역할
language_samples.json은 이번 실습의 입력 데이터입니다. 코드가 분석할 문장들을 미리 모아둔 파일이라고 보면 됩니다.
이 파일에는 영어 문장과 한국어 문장을 함께 넣었습니다. 이렇게 한 이유는 Azure AI Language가 영어뿐 아니라 한국어 텍스트도 어느 정도 분석할 수 있는지 확인하기 위해서입니다.
| 샘플 문장 유형 | 넣은 이유 | 확인 가능한 기능 |
|---|---|---|
| Microsoft, Bill Gates, 날짜 포함 문장 | 조직, 사람, 장소, 날짜 추출 확인 | NER, PII, Key Phrase |
| 배송 지연과 고객 지원 문장 | 긍정과 부정이 섞인 문장 분석 | Sentiment, Key Phrase |
| 이메일, 전화번호 포함 문장 | 개인정보 탐지 확인 | PII, NER |
| 한국어 고객 문의 문장 | 한국어 분석 결과 확인 | Sentiment, Key Phrase, NER |
주의
이전 실행에서 NER과 PII가 실패했던 이유는 한 번에 너무 많은 문서를 보냈기 때문입니다. 사용 중인 리소스나 API 조건에 따라 한 번에 처리할 수 있는 문서 수 제한이 있을 수 있습니다. 현재 결과는 5개 문서 기준으로 정상 생성된 상태입니다.
4. NER 코드 리뷰와 결과 해석
NER은 Named Entity Recognition의 약자입니다. 한국어로는 명명된 엔터티 인식이라고 부릅니다.
쉽게 말해 문장 안에서 사람 이름, 회사명, 장소, 날짜처럼 의미 있는 이름 정보를 찾아내는 기능입니다.
코드 역할
analyze_ner.py는 language_samples.json에서 문장을 읽어온 뒤, Azure AI Language의 recognize_entities 기능을 호출합니다. 그 결과로 각 문장에서 발견된 엔터티의 텍스트, 카테고리, 신뢰도, 위치 정보를 저장합니다.
results = client.recognize_entities(documents=documents)
for entity in result.entities:
print(entity.text, entity.category, entity.confidence_score)결과 해석
첫 번째 문장에서는 Microsoft가 Organization, Bill Gates와 Paul Allen이 Person, Albuquerque가 Location, April 4, 1975가 DateTime으로 잘 추출되었습니다.
| 추출값 | 카테고리 | 해석 |
|---|---|---|
| Microsoft | Organization | 회사명으로 인식 |
| Bill Gates, Paul Allen | Person | 사람 이름으로 인식 |
| Albuquerque | Location | 도시로 인식 |
| April 4, 1975 | DateTime | 날짜로 인식 |
다만 한국어 문장에서는 조금 아쉬운 결과도 보입니다. 예를 들어 2026년 6월 19일이 하나의 날짜로 깔끔하게 잡히지 않고, 2026은 Quantity, 6은 DateTime, 19는 Quantity처럼 나뉘었습니다. 또 열이라는 글자가 Quantity로 잡히는 오류도 있었습니다.
해석 포인트
영어 문장은 비교적 정확하게 인식되었지만, 한국어 날짜나 조사, 띄어쓰기 구조에서는 일부 오인식이 나타났습니다. 따라서 실무에서 한국어 NER을 사용할 때는 결과를 그대로 저장하기보다 후처리 로직을 함께 설계하는 것이 좋습니다.
5. PII Detection 코드 리뷰와 결과 해석
PII는 Personally Identifiable Information의 약자입니다. 개인을 식별할 수 있는 정보를 의미합니다. 이름, 이메일, 전화번호, 주소, 날짜, 조직명 등이 문맥에 따라 PII로 탐지될 수 있습니다.
코드 역할
analyze_pii.py는 Azure AI Language의 recognize_pii_entities 기능을 사용합니다. 이 코드는 원문에서 개인정보로 판단되는 값을 찾고, 동시에 redacted_text라는 마스킹된 문장도 반환합니다.
results = client.recognize_pii_entities(documents=documents)
print(result.redacted_text)
for entity in result.entities:
print(entity.text, entity.category)결과 해석
가장 명확한 결과는 세 번째 문장입니다. Mina Kim, mina.kim@example.com, 010-1234-5678이 각각 Person, Email, PhoneNumber로 탐지되었습니다.
| 원문 값 | PII 카테고리 | 마스킹 결과 |
|---|---|---|
| Mina Kim | Person | ******** |
| mina.kim@example.com | ******************** | |
| 010-1234-5678 | PhoneNumber | ************* |
여기서 중요한 점은 PII Detection이 단순히 이메일과 전화번호만 찾는 것이 아니라는 점입니다. 사람 이름, 조직명, 날짜도 개인정보로 판단될 수 있습니다. 그래서 Microsoft나 Bill Gates 같은 값도 일부 문맥에서는 마스킹 대상이 됩니다.
실무 주의점
PII Detection은 보수적으로 동작할 수 있습니다. 즉, 실제로는 공개 가능한 조직명이나 일반 표현도 개인정보로 판단해 마스킹할 수 있습니다. 따라서 블로그, 고객 상담, 문서 자동화에 적용할 때는 어떤 카테고리를 마스킹할지 정책을 정해야 합니다.
6. Sentiment Analysis 코드 리뷰와 결과 해석
Sentiment Analysis는 문장의 감정을 분석하는 기능입니다. 결과는 보통 positive, neutral, negative로 나뉩니다. 각 감정에 대한 confidence score도 함께 제공됩니다.
코드 역할
analyze_sentiment.py는 analyze_sentiment 기능을 호출합니다. 문서 전체 감정뿐 아니라 문장 단위 감정도 함께 저장하도록 작성되어 있습니다.
results = client.analyze_sentiment(
documents=documents,
show_opinion_mining=True
)결과 해석
가장 흥미로운 결과는 배송 지연 문장입니다. 문장에는 “delivery was delayed”라는 부정적인 표현이 있지만, “customer support team was kind and helpful”이라는 긍정적인 표현도 함께 들어 있습니다. 최종 결과는 positive 0.96으로 긍정에 가깝게 나왔습니다.
| 문장 요약 | 결과 | 해석 |
|---|---|---|
| Microsoft 설립 정보 | neutral 0.99 | 사실 설명 문장이므로 중립 |
| 배송 지연 + 친절한 고객 지원 | positive 0.96 | 지원팀에 대한 긍정 표현이 강하게 반영 |
| 배송 지연과 환불 절차 문의 | negative 0.92 | 지연과 환불이라는 불만 맥락이 반영 |
| 상품 만족 + 배송 지연 | negative 0.66 | 긍정과 부정이 섞였지만 배송 지연 쪽이 더 강하게 반영 |
이 결과를 보면 감정 분석은 단어 하나만 보고 판단하지 않습니다. 문장 전체의 맥락을 보고 어느 쪽 감정이 더 강한지 계산합니다. 그래서 같은 “배송 지연”이 들어가도 뒤에 친절한 대응이 있으면 긍정으로 나올 수 있고, 환불 절차 문의처럼 불편 맥락이 강하면 부정으로 나올 수 있습니다.
7. Key Phrase Extraction 코드 리뷰와 결과 해석
Key Phrase Extraction은 문장에서 핵심 표현을 뽑아내는 기능입니다. 긴 문장을 읽고 “이 문장에서 중요한 키워드는 무엇인가?”를 찾아주는 역할을 합니다.
코드 역할
analyze_key_phrases.py는 extract_key_phrases 기능을 호출합니다. 결과는 문장별 핵심 구 리스트로 저장됩니다.
results = client.extract_key_phrases(documents=documents)
for phrase in result.key_phrases:
print(phrase)결과 해석
첫 번째 문장에서는 Bill Gates, Paul Allen, Microsoft, Albuquerque, April이 핵심 표현으로 추출되었습니다. 이는 문장 안에서 중요한 인물, 조직, 장소, 날짜 관련 표현을 잘 잡은 결과입니다.
두 번째 문장에서는 customer support team, three days, delivery가 추출되었습니다. 이 문장에서 핵심 이슈가 배송 지연과 고객 지원이라는 점을 잘 보여줍니다.
| 문장 | 추출된 핵심 구 | 해석 |
|---|---|---|
| Microsoft 설립 문장 | Bill Gates, Paul Allen, Microsoft | 주요 인물과 조직을 핵심 표현으로 추출 |
| 배송 지연 문장 | customer support team, three days, delivery | 고객 문의의 주요 이슈를 추출 |
| 한국어 환불 문의 | 배송 지연, 환불 절차 | 고객 문의의 핵심 주제를 잘 추출 |
한국어 결과도 꽤 자연스럽습니다. 특히 배송 지연, 환불 절차, 서울 강남구 같은 표현은 블로그 예시로 보여주기 좋습니다. 다만 서울에, 문의는처럼 조사까지 포함된 표현이 나올 수 있습니다. 이런 경우 실무에서는 후처리로 조사나 불필요한 어미를 정리할 수 있습니다.
8. Translation 코드 리뷰와 결과 해석
번역 실습은 Azure AI Language의 TextAnalyticsClient가 아니라, Azure Translator REST API를 사용했습니다. 번역은 Language Studio의 텍스트 분석 기능과는 별도 API로 다루는 것이 자연스럽습니다.
코드 역할
translate_text.py는 requests 라이브러리로 Translator API에 직접 요청을 보냅니다. 명령어에서 --to ko를 주면 대상 언어를 한국어로 지정합니다.
python 02-ai-language/05-translation/translate_text.py --to ko이 구조의 장점은 대상 언어를 쉽게 바꿀 수 있다는 점입니다. 예를 들어 일본어로 번역하고 싶다면 --to ja, 스페인어로 번역하고 싶다면 --to es처럼 실행할 수 있습니다.
결과 해석
| 원문 | 번역 결과 | 해석 |
|---|---|---|
| Azure AI Language helps developers analyze text... | Azure AI Language는 개발자가 텍스트를 분석하고... | 기술 문장을 자연스럽게 번역 |
| The customer wants to cancel the order... | 고객이 주문을 취소하고 환불을 요청하고 싶어 합니다. | 고객센터 문맥에 맞게 자연스럽게 번역 |
| 오늘 배송이 지연되어 고객센터에 문의했습니다. | 오늘 배송이 지연되어 고객센터에 문의했습니다. | 이미 한국어이므로 결과가 거의 동일 |
세 번째 문장은 원문이 이미 한국어인데 대상 언어도 한국어로 지정했기 때문에 결과가 거의 그대로 나왔습니다. 이 예시는 번역 API가 무조건 문장을 바꾸는 것이 아니라, 대상 언어가 같으면 원문과 유사한 결과를 반환할 수 있다는 점을 보여줍니다.
9. 코드 개선 포인트
현재 코드는 실습용으로 충분히 잘 구성되어 있습니다. 각 기능이 독립적으로 실행되고, 결과가 JSON으로 저장되며, 샘플 데이터도 분리되어 있습니다. 다만 GitHub 포트폴리오나 블로그 시리즈로 발전시키려면 몇 가지를 개선하면 좋습니다.
1. 공통 코드 분리
현재 각 파일에는 .env 로드, 클라이언트 생성, 샘플 데이터 읽기, 결과 저장 코드가 반복됩니다. 이 부분은 나중에 common 폴더로 분리하면 좋습니다.
common/
├── config.py
├── azure_language_client.py
└── file_utils.py2. Batch 처리 함수 추가
이전 실행에서 NER과 PII가 실패했던 이유는 한 번에 보낸 문서 수가 제한을 넘었기 때문입니다. 따라서 실무형 코드로 개선하려면 문서를 일정 개수씩 나눠 보내는 함수가 필요합니다.
def chunk_documents(documents, batch_size=5):
for i in range(0, len(documents), batch_size):
yield documents[i:i + batch_size]이렇게 해두면 문서가 5개든 50개든 500개든 자동으로 나누어 처리할 수 있습니다.
3. outputs 폴더 Git 관리 기준 정하기
결과 JSON 파일은 학습 기록으로 남기고 싶다면 Git에 올려도 됩니다. 하지만 실제 서비스 데이터라면 개인정보가 포함될 수 있으므로 Git에 올리면 안 됩니다. 이번 실습 결과는 예제 데이터라서 괜찮지만, 나중에는 .gitignore 기준을 명확히 정하는 것이 좋습니다.
| 파일 유형 | Git에 올려도 되는가 | 이유 |
|---|---|---|
| .env | 절대 올리면 안 됨 | API Key와 Endpoint가 들어 있음 |
| .env.example | 올려도 됨 | 키 없이 환경변수 이름만 공유 |
| sample-data | 예제 데이터면 가능 | 실습 재현에 필요 |
| outputs | 예제 결과면 가능 | 실습 결과 확인용으로 유용 |
중요
실제 고객 데이터, 이메일, 전화번호, 이름이 들어간 outputs 파일은 GitHub에 올리면 안 됩니다. 이번 실습처럼 가짜 예제 데이터일 때만 결과 파일을 포트폴리오용으로 올리는 것이 안전합니다.
10. 정리
이번 실습에서는 Azure AI Language의 주요 기능을 Python 코드로 실행해보았습니다. 각 기능은 같은 텍스트를 입력받지만 서로 다른 관점에서 결과를 반환합니다.
NER은 문장 안의 사람, 조직, 장소, 날짜 같은 엔터티를 찾습니다. PII Detection은 개인정보로 판단되는 값을 찾고 마스킹합니다. Sentiment Analysis는 문장의 감정을 긍정, 중립, 부정으로 분석합니다. Key Phrase Extraction은 문장의 핵심 표현을 뽑아냅니다. Translation은 텍스트를 다른 언어로 번역합니다.
현재 코드는 실습용으로 충분히 잘 동작하고 있습니다. 특히 결과를 JSON으로 저장하는 구조는 나중에 Gradio 앱이나 REST API 실습으로 확장하기 좋습니다. 다만 반복되는 코드는 common 폴더로 분리하고, 문서 수 제한을 고려해 batch 처리 함수를 추가하면 더 실무적인 코드가 됩니다.
11. 전체 흐름 한 번에 정리
language_samples.json에 샘플 문장 작성
→ analyze_ner.py로 엔터티 추출
→ analyze_pii.py로 개인정보 탐지 및 마스킹
→ analyze_sentiment.py로 감정 분석
→ analyze_key_phrases.py로 핵심 구 추출
→ translate_text.py로 번역 실행
→ outputs 폴더에 JSON 결과 저장
→ 결과 JSON을 보고 각 기능의 차이 해석
이 흐름을 이해하면 Azure AI Language를 단순히 “API 호출”로 보는 것이 아니라, 텍스트 데이터를 업무에 맞게 분석하는 도구 모음으로 이해할 수 있습니다. 고객 문의, 상담 기록, 이메일, 리뷰 데이터를 다룰 때 이 구조를 그대로 응용할 수 있습니다.
12. 핵심 키워드 정리
| 키워드 | 의미 |
|---|---|
| Azure AI Language | 텍스트를 이해하고 분석하는 Azure의 자연어 처리 서비스 |
| NER | 문장에서 사람, 조직, 장소, 날짜 같은 엔터티를 추출하는 기능 |
| PII | 개인을 식별할 수 있는 민감 정보를 의미 |
| Redacted Text | 개인정보가 별표 등으로 마스킹된 텍스트 |
| Sentiment Analysis | 문장의 감정을 긍정, 중립, 부정으로 분석하는 기능 |
| Confidence Score | 모델이 결과를 얼마나 확신하는지 나타내는 점수 |
| Key Phrase | 문장에서 중요한 핵심 표현 |
| Translator API | 텍스트를 다른 언어로 번역하는 Azure API |
| JSON | 분석 결과를 구조화해서 저장하는 데이터 형식 |
| Batch Processing | 여러 문서를 일정 개수씩 나눠 처리하는 방식 |
13. 다음 글 예고
이번 글에서는 Azure AI Language 실습 코드와 결과 JSON을 리뷰하면서 NER, PII Detection, Sentiment Analysis, Key Phrase Extraction, Translation의 차이를 정리했습니다. 다음 글에서는 이 코드들을 common 모듈로 리팩토링하고, Gradio 화면으로 연결하는 방법을 알아보겠습니다.
특히 다음 글에서는 사용자가 웹 화면에 문장을 입력하면 Azure AI Language API가 분석 결과를 반환하고, 그 결과를 표와 JSON으로 보여주는 간단한 텍스트 분석 앱을 만들어보겠습니다.
