Python으로 모델 호출하기

1.3 Python으로 모델 호출하기

세부 학습 목표

• Python 구조를 JSON 요청으로 표현하고 모델의 실제 응답을 읽는 코드를 설명한다.
• 프로젝트 엔드포인트·모델 배포·실행 신원·SDK의 연결을 구성한다.
• 입력·인증·권한·배포·용량 오류를 구별해 다음 확인을 정한다.

개요

• 요청 준비: Python 사전·리스트를 JSON으로 표현.
• 호출 설정: 프로젝트 주소·배포 이름·인증 주체 확인.
• 결과 확인: 응답 내용·오류·사용량·지연을 나누어 검사.

Python 요청을 읽는 데 필요한 문법

• 사전 dict는 이름과 값을 묶고, 리스트 list는 여러 항목을 순서대로 담습니다.

  JSON은 이 구조를 서비스 사이에서 주고받기 위한 데이터 표현입니다. Python의 None과 JSON의 null, Python의 True와 JSON의 true는 표기가 다릅니다. 직접 문자열을 이어 붙이기보다 직렬화 함수를 사용하는 편이 안전합니다.

import json
 
request_data = {
    "question": "출장비 규정의 적용일을 알려줘",
    "document_ids": ["policy-2026-07"],
    "include_sources": True,
}
wire = json.dumps(request_data, ensure_ascii=False)
restored = json.loads(wire)
assert restored["include_sources"] is True
assert restored["document_ids"][0] == "policy-2026-07"
print(restored["question"])

기대 출력은 출장비 규정의 적용일을 알려줘입니다. 이 예제는 로컬 데이터의 직렬화와 복원을 확인하며, 실제 모델 호출은 아래에서 수행합니다.

Foundry 프로젝트로 첫 호출하기

아래는 실제 서비스 연결 예제입니다. 프로젝트·지원 모델 배포·Azure 권한이 필요하고 호출 비용이 발생할 수 있습니다. 이 교재의 검증 범위는 코드 구문과 공식 API 계약 확인이며, 사용자의 Azure 구독에서 실행한 결과는 아닙니다.

• 준비: Python, Azure CLI, Foundry 프로젝트, 호출 가능한 모델 배포.

  터미널에서 az version으로 Azure CLI 설치를 확인합니다. 명령을 찾지 못하면 공식 설치 안내 에 따라 설치하고 새 터미널을 엽니다. Azure CLI는 Python 가상 환경에 설치하는 패키지와 별개입니다.

py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install "azure-ai-projects>=2.8.0" azure-identity
az login

위 명령은 Windows PowerShell 기준입니다. macOS/Linux에서는 python3 -m venv .venv로 만들고 source .venv/bin/activate로 활성화한 뒤 패키지를 설치합니다. 활성화하지 않으면 다른 Python에 설치하거나 실행할 수 있습니다. 설치 후 사용한 버전을 기록합니다.

• 환경 변수는 코드를 실행할 터미널에서 설정합니다.

  아래 자리표시자를 포털에서 확인한 실제 값으로 바꿉니다. $env: 설정은 현재 PowerShell과 여기서 시작한 Python에 적용됩니다. 다른 터미널에서 실행하면 다시 설정해야 합니다.

$env:FOUNDRY_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:MODEL_DEPLOYMENT_NAME = "<deployment-name>"

• 실행 순서: 아래 Python 코드를 first_call.py로 저장 → 같은 터미널에서 python first_call.py 실행.

  성공하면 문맥 한도를 설명하는 답변이 출력됩니다. 생성 문장은 매번 달라질 수 있으므로 고정 문장 일치보다 응답 존재와 내용의 정확성을 확인합니다. macOS/Linux에서는 같은 변수 이름을 export FOUNDRY_PROJECT_ENDPOINT="..."와 export MODEL_DEPLOYMENT_NAME="..."으로 설정합니다.

• 엔드포인트는 프로젝트 API 주소입니다.

  검색 서비스 주소나 모델 이름을 넣지 않습니다. DefaultAzureCredential은 실행 환경의 사용 가능한 인증 수단을 시도하므로 로컬에서는 로그인한 사용자, 클라우드에서는 관리 ID 등 실제 선택된 신원과 권한을 확인합니다.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
 
credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=credential,
)
client = project.get_openai_client()
try:
    response = client.responses.create(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        input="LLM의 문맥 한도를 두 문장으로 설명해줘.",
    )
    print(response.output_text)
finally:
    client.close()
    project.close()
    credential.close()

• AIProjectClient는 프로젝트의 기능에 접근하는 클라이언트입니다.

  get_openai_client()로 얻은 클라이언트에서 Responses API를 호출하고, output_text로 텍스트 출력을 읽습니다. 도구 호출처럼 텍스트가 아닌 출력 항목이 필요한 작업에서는 전체 출력 구조도 확인해야 합니다.

오류를 계층별로 해석하기

• 실제 상태 코드만으로 원인을 하나로 확정하지 말고 오류 본문과 요청 ID도 함께 봅니다.

  비동기 호출에서는 완료를 기다리는 await와 취소·시간 제한을 관리합니다. API나 SDK가 달라지면 메서드 이름과 출력 구조가 바뀔 수 있으므로 프로젝트/모델 엔드포인트와 사용한 패키지 버전을 한 묶음으로 기록합니다.

엔드포인트와 배포 이름 구분

• SDK와 API는 대상 서비스에 맞는 엔드포인트와 인증 범위를 요구합니다.

  예제의 URL을 복사하는 대신 어떤 리소스에서 어떤 API를 호출하는지 먼저 파악합니다.

• 상황: 팀원이 다른 프로젝트의 엔드포인트에 현재 배포 이름을 붙여 호출한 뒤 404를 받습니다.

• 적용: 엔드포인트의 소속, 배포 이름, 요청 경로와 API 지원 버전을 비교합니다.

  정상 인증을 받아도 잘못된 대상이면 찾지 못할 수 있습니다.

키 없는 인증과 토큰 수명

• 키 없는 접근에서는 클라이언트가 대상 리소스를 위한 액세스 토큰을 얻고, 서버는 토큰과 역할 정책을 검사합니다.

  어떤 자격 증명 소스를 쓸지는 실행 환경에 달려 있습니다.

• 상황: 로컬 PC에서는 성공하지만 배포된 앱에서는 토큰 취득 단계에서 실패합니다.

• 적용: 로컬 계정과 운영 관리 ID는 서로 다른 보안 주체입니다.

  운영 앱에서 실제 토큰 취득 가능 여부와 해당 주체의 역할 할당·권한 전파를 확인합니다.

Python SDK 호출의 입출력 파악

• 모델 호출은 네트워크 요청, 서비스 검증, 모델 처리, 응답 파싱의 단계로 진행합니다.

  개발자는 반환 텍스트 외에도 상태 코드·요청 ID·사용량을 기록해야 장애를 분석할 수 있습니다.

• 상황: 챗봇이 200 응답을 받았지만 필요한 JSON 필드가 누락됐습니다.

• 적용: HTTP 200은 요청 처리 성공만 나타냅니다.

  JSON 스키마, 필수 필드, 원문과의 내용 일치 여부를 후속 단계에서 검사합니다.

커넥터 통합과 실패 분류

• 커넥터는 외부 데이터·기능을 애플리케이션에 연결합니다.

  실패를 처리할 때는 인증(401), 인가(403), 대상 미발견(404), 제한·일시적 용량 문제(429), 연결 실패를 구분합니다. 특히 429는 호출량 초과 외에도 일시적 서비스 용량 문제일 수 있으므로 응답 본문과 헤더를 확인합니다.

• 상황: 검색 커넥터가 403을 반환했는데 개발자가 무한 재시도하도록 구현했습니다.

• 적용: 403은 역할·접근 정책·허용 범위를 우선 확인합니다.

  429는 오류 유형·응답 헤더를 확인한 뒤 필요한 경우 재시도하고, 나머지 실패 유형에는 원인별 처리 정책을 적용합니다.

• 커넥터·엔드포인트 

• 429 원인과 대응 

확인 문제

포털: endpoint=resource-A / deployment=support-prod / HTTP 200
앱:   endpoint=resource-A / model=support-test / HTTP 404
resource-A 배포 목록: [support-prod]
앱의 같은 ID로 support-prod 호출: HTTP 200

client = InferenceClient(endpoint=MODEL_ENDPOINT)
client.generate(...)       # HTTP 200
client.projects.list()     # AttributeError: projects
요구: 추론 호출과 프로젝트 리소스 조회
설치된 패키지 이름·버전: 확인 전

project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
두 실행의 endpoint·토큰 audience: 동일하고 유효
로컬: principal=dev17 / project_read=allowed / HTTP 200
배포: principal=mi42 / project_read=denied  / HTTP 403

참고 자료

• Microsoft Foundry SDKs and endpoints 
• Use the Azure OpenAI Responses API 
• json — JSON encoder and decoder¶ 
• 8. Errors and Exceptions¶ 
• Manage Azure OpenAI in Microsoft Foundry Models quota 
• Azure CLI 설치와 버전 확인 

자료 확인: 2026-10-23 · 적용 사례 교정: 2026-10-23. 사례는 교육용이며 Azure API 호출·요금은 실행 검증하지 않았습니다.

프로젝트 호출 코드가 HTTP 응답을 받았지만, 애플리케이션이 기대하는 결과 필드는 비어 있습니다. SDK와 호출 대상의 설정도 변경됐습니다.