Azure OpenAI API 가져오기

2025-05-20

적용 대상: 모든 API Management 계층

Azure OpenAI Service에 배포된 AI 모델 엔드포인트를 REST API로 API Management 인스턴스로 가져올 수 있습니다. API Management의 AI 게이트웨이 정책 및 기타 기능을 사용하여 통합을 간소화하고, 가시성을 향상시키며, 모델 엔드포인트에 대한 제어를 향상시킵니다.

이 문서에서는 Azure OpenAI API를 REST API로 Azure API Management 인스턴스로 가져오는 두 가지 옵션을 보여 줍니다.

Azure OpenAI 서비스에서 직접 Azure OpenAI API 가져오기(권장)
Azure OpenAI용 OpenAPI 사양을 다운로드 및 추가하고 API Management에 OpenAPI API로 추가합니다.

API Management에서 AI API를 관리하는 방법에 대해 자세히 알아봅니다.

Azure API Management의 AI 게이트웨이 기능

필수 조건

기존 API Management 인스턴스. 아직 만들지 않았다면 하나 생성하세요.
모델이 배포된 Azure OpenAI 리소스. Azure OpenAI 서비스의 모델 배포에 대한 자세한 내용은 리소스 배포 가이드를 참조하세요.

배포의 ID(이름)를 기록해 둡니다. API Management에서 가져온 API를 테스트할 때 필요합니다.

참고

azure-openai-token-limit 및 azure-openai-emit-token-metric과 같은 API Management 정책은 특정 Azure OpenAI 서비스 모델을 통해 노출되는 특정 API 엔드포인트에 대해 지원됩니다. 자세한 내용은 지원되는 Azure OpenAI 서비스 모델을 참조하세요.
API Management 인스턴스에서 Azure OpenAI 리소스에 대한 액세스 권한을 부여하는 권한입니다.

옵션 1. Azure OpenAI Service에서 API 가져오기

Azure OpenAI API를 Azure OpenAI Service에서 API Management로 직접 가져올 수 있습니다.

참고

현재 이 기능은 작업 영역에서 사용할 수 없습니다.

API를 가져오면 API Management는 자동으로 다음을 구성합니다.

각 Azure OpenAI REST API 엔드포인트에 대한 작업
Azure OpenAI 리소스에 액세스하는 데 필요한 권한이 있는 시스템 할당 ID입니다.
API 요청을 Azure OpenAI 서비스 엔드포인트로 전송하는 백 엔드 리소스 및 set-backend-service 정책입니다.
인스턴스의 시스템 할당 관리 ID를 사용하여 Azure OpenAI 백 엔드에 대한 인증
(선택 사항) Azure OpenAI API를 모니터링하고 관리하는 데 도움이 되는 정책입니다.

Azure OpenAI API를 API Management로 가져오려면 다음을 수행합니다.

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴의 API에서 API>+ API 추가를 선택합니다.
Azure 리소스에서 만들기에서 Azure OpenAI Service를 선택합니다.
기본 사항 탭에서 다음을 수행합니다.
1. 가져오려는 Azure OpenAI 리소스를 선택합니다.
2. 원하는 경우 Azure OpenAI API 버전을 선택합니다. 하나를 선택하지 않으면 프로덕션에 즉시 사용 가능한 최신 REST API 버전이 기본적으로 사용됩니다. 선택한 버전을 기록해 둡다. API를 테스트하는 데 필요합니다.
3. API에 대한 표시 이름과 선택 사항인 설명을 입력합니다.
4. 기준 URL에 API Management 인스턴스가 Azure OpenAI API 엔드포인트에 액세스하는 데 사용하는 경로를 추가합니다. OpenAI SDK 호환성 보장(권장)을 사용하도록 설정하면 /openai가 자동으로 기준 URL에 추가됩니다.
  
  예를 들어, API Management 게이트웨이 엔드포인트가 https://contoso.azure-api.net인 경우 와 유사한 https://contoso.azure-api.net/my-openai-api/openai을 설정합니다.
5. 선택적으로 API와 연결할 제품을 하나 이상 선택합니다. 다음을 선택합니다.
정책 탭에서 필요에 따라 API를 모니터링하고 관리하는 데 도움이 되는 정책을 사용하도록 설정합니다. 나중에 정책을 설정하거나 편집할 수도 있습니다.

선택한 경우 다음 정책을 정의하는 설정을 입력하거나 기본값을 적용합니다(필수 구성 요소 및 구성 세부 정보는 연결된 문서 참조).
- 토큰 사용 관리
- 토큰 사용량 추적
- 응답의 의미 있는 캐싱 사용
- API에 대한 AI 콘텐츠 안전을 구성합니다.
검토 + 생성를 선택합니다.
설정의 유효성을 검사한 후 만들기를 선택합니다.

옵션 2. API Management에 OpenAPI 사양 추가

또는 Azure OpenAI REST API에 대한 OpenAPI 사양을 수동으로 다운로드하여 API Management에 OpenAPI API로 추가합니다.

OpenAPI 사양 다운로드

2024-10-21 GA 버전과 같은 Azure OpenAI REST API에 대한 OpenAPI 사양을 다운로드합니다.

텍스트 편집기에서 다운로드한 사양 파일을 엽니다.
사양의 servers 요소에서 사양의 url 및 default 엔드포인트 자리 표시자 값에 있는 Azure OpenAI Service 엔드포인트의 이름을 대체합니다. 예를 들어, Azure OpenAI Service 엔드포인트가 contoso.openai.azure.com인 경우 servers 요소를 다음 값으로 업데이트합니다.
- url: https://contoso.openai.azure.com/openai
- 기본 엔드포인트: contoso.openai.azure.com
```
[...]
"servers": [
    {
      "url": "https://contoso.openai.azure.com/openai",
      "variables": {
        "endpoint": {
          "default": "contoso.openai.azure.com"
        }
      }
    }
  ],
[...]
```
사양에서 API version의 값을 기록해 둡다. API를 테스트하는 데 필요합니다. 예: 2024-10-21

API Management에 OpenAPI 사양 추가

Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴에서 API>+ API 추가를 선택합니다.
새 API 정의에서 OpenAPI를 선택합니다. API의 표시 이름과 이름을 입력합니다.
API Management 인스턴스의 Azure OpenAI API 엔드포인트에 액세스하려면 로 끝나는 /openai를 입력합니다. 예: my-openai-api/openai
만들기를 선택합니다.

API를 가져오며 OpenAPI 사양의 작업이 표시됩니다.

Azure OpenAI API에 대한 인증 구성

Azure OpenAI API에 인증하려면 API 키 또는 관리 ID를 제공합니다. Azure OpenAI API를 API Management 인스턴스로 직접 가져온 경우 API Management 인스턴스의 관리 ID를 사용한 인증이 자동으로 구성됩니다.

OpenAPI 사양에서 Azure OpenAI API를 추가한 경우 인증을 구성해야 합니다. API Management 정책을 사용한 인증 구성에 대한 자세한 내용은 Azure OpenAI API 인증 및 권한 부여를 참조하세요.

Azure OpenAI API 테스트

Azure OpenAI API가 예상대로 작동하는지 확인하려면 API Management 테스트 콘솔에서 테스트합니다. API를 테스트하려면 Azure OpenAI 리소스 및 API 버전에 구성된 모델 배포 ID(이름)를 제공해야 합니다.

이전 단계에서 만든 API를 선택합니다.
테스트 탭을 선택합니다.
Azure OpenAI 리소스에 배포한 모델과 호환되는 작업을 선택합니다. 이 페이지에는 매개 변수 및 헤더에 대한 필드가 표시됩니다.
템플릿 매개 변수에 다음 값을 입력합니다.
- deployment-id - Azure OpenAI 서비스의 배포 ID입니다.
- api-version - API를 가져올 때 선택한 API 버전과 같은 유효한 Azure OpenAI API 버전입니다.
필요에 따라 다른 매개 변수와 헤더를 입력합니다. 작업에 따라 요청 본문을 구성하거나 업데이트해야 할 수 있습니다.

참고

테스트 콘솔에서 API Management는 Ocp-Apim-Subscription-Key 헤더를 자동으로 채우고 기본 제공된 모든 액세스 구독의 구독 키를 구성합니다. 이 키를 사용하면 API Management 인스턴스의 모든 API에 액세스할 수 있습니다. 선택적으로 HTTP 요청 옆에 있는 "눈" 아이콘을 선택하여 Ocp-Apim-Subscription-Key 헤더를 표시합니다.
보내기를 선택합니다.

테스트가 성공하면 백 엔드는 성공적인 HTTP 응답 코드와 일부 데이터로 응답합니다. 응답에 추가된 토큰 사용량 데이터는 Azure OpenAI API 토큰 사용량을 모니터링하고 관리하는 데 도움이 됩니다.