export FOUNDRY_PROJECT_ENDPOINT='https://<account>.services.ai.azure.com/api/projects/<project>'
export FOUNDRY_MODEL='<deployment-name>'
한국어 ASR를
검색 가능한 용어로
발음이 비슷한 로컬 후보를 먼저 만들고, Microsoft Foundry가 문맥에 맞는 후보 ID만 고릅니다. 자유 생성 대신 제한된 선택과 로컬 검증으로 검색 질의를 안전하게 정규화합니다.
- ✓ DB vocabulary 밖 생성 차단
- ✓ V1 API 호환
- ✓ OpenAI API key 불필요
# 1. PyPI에서 Foundry extra 설치
$ python -m pip install 'pronunciation-mapper[foundry]'
# 2. Microsoft Entra ID 로그인
$ az login
# 외부 tenant라면: az login --tenant '<tenant-id>'
Foundry 연결까지 세 단계
기본 provider는 azure입니다. 배포 이름과 프로젝트 endpoint만 설정하면 됩니다.
-
1
패키지 설치
Azure SDK가 포함된
foundryextra를 설치합니다. -
2
Entra ID 인증
로컬은
az login, 외부 tenant는az login --tenant '<tenant-id>'를 사용합니다. -
3
프로젝트와 배포 지정
FOUNDRY_MODEL에는 catalog ID가 아닌 실제 배포 이름을 넣습니다.
API key는 필요 없습니다. DefaultAzureCredential이 로컬의 Azure CLI 세션 또는 운영 환경의 Managed Identity를 사용합니다.
.env.example은 자동으로 로드되지 않습니다. shell에서 export하거나 애플리케이션에서 dotenv를 로드하세요.
모델의 권한을 줄인 하이브리드 흐름
발음 후보 생성과 최종 검증은 로컬에서, 애매한 문맥 판단만 모델에서 수행합니다.
ASR 입력
원문과 숫자를 보수적으로 정규화
로컬 Top-K
exact alias와 발음 거리로 후보 축소
Foundry 판정
문맥상 후보 ID를 선택하거나 거부
로컬 검증
스키마·span·ID·vocabulary 재검사
검색 질의
공백과 조사를 보존한 canonical term
모델은 replacement 문자열을 만들지 않습니다. 제공된 candidate ID에 대해 replace, keep, abstain 중 하나만 반환합니다.
Foundry가 기본, Ollama는 명시적 옵션
환경 사이의 데이터 경계를 지키기 위해 Azure 장애 시 Ollama로 자동 전환하지 않습니다.
Microsoft Foundry
기본Project-scoped Responses API
- Microsoft Entra ID와 Managed Identity
- Structured Output 기반 제한된 판정
- 프로젝트 단위 모델·관측·거버넌스
OPENAI_API_KEY불필요
provider="azure"
생략 시 기본값
Ollama
옵션로컬 native API
python -m pip install 'pronunciation-mapper[ollama]'ollama pull qwen3.5:4b- 모델별 한국어·JSON 품질 eval 필수
- 모델 자동 pull 및 자동 failover 없음
provider="ollama"
반드시 명시
OpenAI · Claude는 reference-only입니다. V2 adapter와 API key 요구사항이 없으며, 선택하면 다른 provider로 조용히 전환하지 않고 명시적 오류를 반환합니다.
애플리케이션에 연결하기
비동기 Python API가 기본이며, 운영 확인과 배치 테스트에는 같은 엔진을 사용하는 CLI를 쓸 수 있습니다.
import asyncio
from pronunciation_mapper import AgenticPronunciationMapper
async def main():
async with AgenticPronunciationMapper(
["XPN36", "account_no", "transaction", "server", "log"],
custom_mappings={
"엑스피엔36": "XPN36",
"어카운트넘버": "account_no",
"서버": "server",
"로그": "log",
},
) as mapper:
result = await mapper.rewrite(
"엑스피엔36 서버에서 트랜잭숑 로그"
)
print(result.rewritten_text)
asyncio.run(main())
pronunciation-mapper rewrite \
'엑스피엔36 서버에서 트랜잭숑 로그' \
--db-terms examples/db_terms.json \
--provider azure \
--json
# Ollama는 provider와 model을 명시합니다.
pronunciation-mapper rewrite '트랜잭숑 로그' \
--provider ollama \
--model qwen3.5:4b
문자열과 판단 trace를 함께 반환
{
"rewritten_text": "XPN36 server에서 transaction log",
"provider": "azure-foundry",
"model": "<deployment-name>",
"fallback_used": false,
"decisions": [
{
"source": "트랜잭숑",
"replacement": "transaction",
"action": "replace",
"confidence": 0.91
}
]
}
운영 전 확인할 것
정확도뿐 아니라 잘못 바꾸는 비율과 provider 장애 시 동작을 함께 측정하세요.
-
✓
인증과 권한
운영에서는 Managed Identity와 최소 RBAC를 사용합니다.
-
✓
Golden set 평가
exact accuracy, false rewrite, abstention, p95 latency를 release gate로 둡니다.
-
✓
민감 정보 로그
원문·prompt·전체 vocabulary의 content logging은 기본적으로 끕니다.
-
✓
입력 상한
기본 4,096자·64 span·token 256자를 넘기면 잘라 보내지 않고 거부합니다.