통합 모델 API 만들기 및 관리

적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄 | 프리미엄 v2

Azure API Management 통합 모델 API를 만들어 단일 클라이언트 연결 엔드포인트를 통해 여러 LLM 백 엔드를 노출할 수 있습니다. 클라이언트 애플리케이션은 하나의 친숙한 API 형식인 OpenAI Chat Completions API를 사용하지만, API Management는 OpenAI Chat Completions API 또는 Anthropic Messages API를 사용하여 백 엔드 모델로 요청을 자동으로 변환합니다.

메모

통합 모델 API는 미리 보기 상태이며 현재 고객에게 배포되고 있습니다. 클래식 계층에서는 AI Gateway 초기 릴리스 채널을 통해 이 기능에 대한 초기 액세스를 사용할 수 있습니다.

단일 API 계층 뒤에서 모델 액세스를 중앙 집중화하여 다음을 수행할 수 있습니다.

  • 백 엔드 모델에서 사용하는 형식과 독립적으로 클라이언트에 대한 단일 API 형식을 표준화합니다.
  • 모델 공급자 간에 정책을 사용하여 관찰 가능성, 보안 및 거버넌스를 통합합니다.
  • 모델 공급자 간에 모델 장애 조치(failover)를 구성합니다.
  • 별칭을 사용하여 백 엔드 모델 이름에서 클라이언트 연결 모델 이름을 분리합니다.

API Management에서 AI API를 관리하는 방법에 대한 자세한 내용은 Azure API Management AI 게이트웨이 기능을 참조하세요.

지원되는 백 엔드

통합 모델 API는 다음 백 엔드 API 형식을 지원합니다.

  • OpenAI 채팅 완료 API
  • 인류 메시지 API

사전 요구 사항

통합 모델 API 만들기 - Azure 포털

API Management에서 통합 모델 API를 만들려면 다음 단계를 사용합니다.

API를 만들 때 API Management는 자동으로 다음을 구성합니다.

  • /models 구성된 모든 모델을 나열하는 모델 검색을 위한 엔드포인트입니다.
  • OpenAI 채팅 완료 형식의 요청을 수락하는 것과 같은 /llm/v1/chat/completions 단일 라우팅 엔드포인트입니다.
  • 추가하는 각 백 엔드 모델에 대한 번역 논리 서식을 지정합니다.
  • 요청을 올바른 공급자 엔드포인트로 전송하는 백 엔드 리소스입니다.

통합 모델 API를 만들려면 다음을 수행합니다.

  1. Azure Portal에서 API Management 인스턴스로 이동합니다.

  2. 사이드바 메뉴의 API에서 Models>+통합 모델 추가 >API를 선택합니다.

    Azure Portal의 통합 모델 API 타일 스크린샷.

  3. 통합 모델 API 구성 탭에서 다음을 수행합니다.

    1. API의 표시 이름을 입력합니다. API Management는 표시 이름에 따라 API 이름을 자동으로 생성하지만 원하는 경우 편집할 수 있습니다.
    2. API 경로에서 클라이언트가 API를 호출하는 데 사용하는 경로를 입력합니다. 기본값은 /llm/v1.에서 채팅 완료 엔드포인트 /llm/v1/chat/completions를 생성하는 것입니다.
    3. 필요에 따라 API와 연결할 제품을 하나 이상 선택합니다 .
    4. 다음을 선택합니다.

  4. 모델 구성 탭에서 + 추가를 선택하여 모델 추가 창을 연 다음 각 모델 배포에 대해 다음 설정을 구성합니다.

    1. 백엔드 구성 아래:

      • 모델에서 백 엔드 모델 이름(예: gpt-4o 또는claude-sonnet-4.6)을 입력합니다.
      • API 형식에서 백 엔드 모델이 예상하는 형식(예: OpenAI 채팅 완료 API 또는 Anthropic 메시지 API)을 선택합니다.
      • URL에 백 엔드 엔드포인트 URL(예: Foundry의 모델 배포 또는 다른 공급자의 경우 공급자의 API 엔드포인트 URL)을 입력합니다.

    2. 권한 부여 자격 증명 아래에서 API Management가 백 엔드에 인증하는 방법을 선택합니다.

      • 헤더: 헤더 이름 (예 api-key : 또는 Authorization)과 해당 헤더 값 (API 키 또는 비밀)을 입력합니다.
      • 관리 ID: Azure 모델 배포의 경우 인스턴스의 시스템 할당 관리 ID 또는 사용자 할당 관리 ID를 사용하여 백 엔드에 인증할 수 있습니다.

      관리 ID에 대한 설정에 대한 설명은 인증 관리 ID 정책에 대한 참조를 참조하세요.

    포털에서 모델 설정을 추가하는 모델 추가 창의 스크린샷

  5. 토큰 사용 관리 탭에서 필요에 따라 토큰 사용량을 모니터링하고 관리하도록 다음 정책을 구성합니다.

  6. AI 콘텐츠 안전 설정 탭에서 Azure AI 콘텐츠 보안 서비스를 구성하여 안전하지 않은 콘텐츠가 있는 프롬프트를 차단합니다.

  7. 검토 + 생성를 선택한 다음, 생성를 선택합니다.

모델 별칭 관리

모델 별칭은 클라이언트에 모델을 호출할 때 사용할 안정적인 공급자 중립적 이름을 제공합니다. gpt 또는 claude-sonnet와 같은 별칭을 할당하면 클라이언트에 표시되는 모델 이름을 실제 백엔드 배포와 분리할 수 있습니다. 모델을 업그레이드하거나 A/B 테스트를 실행하려는 경우 클라이언트 코드를 변경하지 않고 별칭 대상을 업데이트할 수 있습니다.

모델 별칭 업데이트 또는 추가

통합 모델 API를 만든 후 모델 별칭을 업데이트하려면 다음을 수행합니다.

  1. Azure 포털에서 API Management 인스턴스로 이동한 다음, APIs 선택합니다.
  2. 통합 모델 API를 선택합니다.
  3. 모델 탭을 선택하여 모델 별칭을 업데이트하거나 추가합니다.
    • 클라이언트 연결 별칭을 업데이트하려면 업데이트할 별칭을 선택한 다음 백 엔드 구성 을 업데이트하여 백 엔드 모델을 지정합니다. 새 백 엔드에 대한 권한 부여 자격 증명 을 추가합니다.
    • 새 모델을 추가하려면 이전 섹션에서 설명한 대로 + 추가 를 선택하고 백 엔드, 권한 부여 및 클라이언트 설정을 구성합니다.
  4. 저장을 선택합니다.

모델 별칭 검색

개발자는 통합 모델 API의 엔드포인트를 호출 /models 하여 사용 가능한 모델 및 해당 별칭을 검색할 수 있습니다. API Management는 클라이언트 쪽 별칭이 있는 모델 목록을 반환합니다.

클라이언트 애플리케이션에서 API 호출

클라이언트 애플리케이션은 OpenAI 호환 SDK를 사용하여 통합 모델 API를 호출할 수 있습니다. API Management 엔드포인트에서 SDK의 기본 URL을 가리키고 API Management 구독 키 또는 인증에 지원되는 다른 인증 방법을 사용합니다.

다음 예제에서는 Python OpenAI SDK를 사용하고 인증을 위해 헤더에 API Management 구독 키를 전달합니다. 요청 본문은 API Management에 구성된 클라이언트 연결 모델 별칭(예 gptclaude-sonnet: .:)을 지정합니다.

from openai import OpenAI

client = OpenAI(
    base_url="https://<apim-instance>.azure-api.net/llm/v1",
    api_key="<api-management-subscription-key>",
)

# Specify the client-facing model alias
response = client.chat.completions.create(
    model="gpt",  # or "claude-sonnet", "gemini", or any other configured alias
    messages=[{"role": "user", "content": "What can you do?"}],
)
print(response.choices[0].message.content)

다른 백 엔드 모델로 전환하려면 값만 변경합니다 model . 다른 코드 변경은 필요하지 않습니다.

관련 콘텐츠

  • Last updated on