Azure AI Foundry 기본 · Ollama 옵션

한국어 ASR를
검색 가능한 용어

발음이 비슷한 로컬 후보를 먼저 만들고, Microsoft Foundry가 문맥에 맞는 후보 ID만 고릅니다. 자유 생성 대신 제한된 선택과 로컬 검증으로 검색 질의를 안전하게 정규화합니다.

  • DB vocabulary 밖 생성 차단
  • V1 API 호환
  • OpenAI API key 불필요
quick-start.sh
# 1. PyPI에서 Foundry extra 설치
$ python -m pip install 'pronunciation-mapper[foundry]'

# 2. Microsoft Entra ID 로그인
$ az login
# 외부 tenant라면: az login --tenant '<tenant-id>'
v2.0.1 · Python 3.10+ · Foundry Project Responses API
Quick start

Foundry 연결까지 세 단계

기본 provider는 azure입니다. 배포 이름과 프로젝트 endpoint만 설정하면 됩니다.

  1. 1

    패키지 설치

    Azure SDK가 포함된 foundry extra를 설치합니다.

  2. 2

    Entra ID 인증

    로컬은 az login, 외부 tenant는 az login --tenant '<tenant-id>'를 사용합니다.

  3. 3

    프로젝트와 배포 지정

    FOUNDRY_MODEL에는 catalog ID가 아닌 실제 배포 이름을 넣습니다.

환경 변수 .env 또는 shell
export FOUNDRY_PROJECT_ENDPOINT='https://<account>.services.ai.azure.com/api/projects/<project>'
export FOUNDRY_MODEL='<deployment-name>'

API key는 필요 없습니다. DefaultAzureCredential이 로컬의 Azure CLI 세션 또는 운영 환경의 Managed Identity를 사용합니다.

.env.example은 자동으로 로드되지 않습니다. shell에서 export하거나 애플리케이션에서 dotenv를 로드하세요.

Bounded decision agent

모델의 권한을 줄인 하이브리드 흐름

발음 후보 생성과 최종 검증은 로컬에서, 애매한 문맥 판단만 모델에서 수행합니다.

01

ASR 입력

원문과 숫자를 보수적으로 정규화

02

로컬 Top-K

exact alias와 발음 거리로 후보 축소

03

Foundry 판정

문맥상 후보 ID를 선택하거나 거부

04

로컬 검증

스키마·span·ID·vocabulary 재검사

05

검색 질의

공백과 조사를 보존한 canonical term

핵심 가드레일

모델은 replacement 문자열을 만들지 않습니다. 제공된 candidate ID에 대해 replace, keep, abstain 중 하나만 반환합니다.

Local validation
Provider policy

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" 반드시 명시
i

OpenAI · Claude는 reference-only입니다. V2 adapter와 API key 요구사항이 없으며, 선택하면 다른 provider로 조용히 전환하지 않고 명시적 오류를 반환합니다.

API & CLI

애플리케이션에 연결하기

비동기 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())
RewriteResult

문자열과 판단 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
    }
  ]
}
latency_ms usage diagnostics distance
provider 실패 정책 fallback_strategy
"heuristic"기본 · V1 후보 적용 "original"원문/숫자 정규화 유지 "raise"오류를 호출자에게 전파
Production checklist

운영 전 확인할 것

정확도뿐 아니라 잘못 바꾸는 비율과 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자를 넘기면 잘라 보내지 않고 거부합니다.

Ready to rewrite?

검색 정확도는 높이고,
모델의 자유도는 낮추세요.

빠른 시작으로 돌아가기