Importowanie interfejsu API usługi Azure OpenAI

2025-06-28

DOTYCZY: Wszystkie warstwy usługi API Management

Punkty końcowe modeli AI wdrożonych w usłudze Azure OpenAI można zaimportować do instancji usługi API Management jako interfejs API typu REST. Użyj zasad bramy sztucznej inteligencji i innych funkcji w usłudze API Management, aby uprościć integrację, zwiększyć czytelność i zwiększyć kontrolę nad punktami końcowymi modelu.

W tym artykule przedstawiono dwie opcje importowania interfejsu API usługi Azure OpenAI do wystąpienia usługi Azure API Management jako interfejsu API REST:

Importowanie interfejsu API usługi Azure OpenAI bezpośrednio z usługi Azure OpenAI w modelach foundry (zalecane)
Pobierz i dodaj specyfikację interfejsu OpenAPI dla usługi Azure OpenAI i dodaj ją do usługi API Management jako interfejs API openAPI.

Dowiedz się więcej o zarządzaniu interfejsami API sztucznej inteligencji w usłudze API Management:

Funkcje bramy AI w usłudze Azure API Management

Wymagania wstępne

Istniejąca instancja usługi API Management. Utwórz go, jeśli jeszcze tego nie zrobiono.
Zasób usługi Azure OpenAI z wdrożonym modelem. Aby uzyskać więcej informacji na temat wdrażania modelu w usłudze Azure OpenAI, zobacz przewodnik wdrażania zasobów.

Zanotuj identyfikator (nazwę) wdrożenia. Będzie ona potrzebna podczas testowania zaimportowanych interfejsów API w usłudze API Management.

Uwaga

Zasady usługi API Management, takie jak azure-openai-token-limit i azure-openai-emit-token-metric , są obsługiwane w przypadku niektórych punktów końcowych interfejsu API udostępnianych za pośrednictwem określonych modeli usługi Azure OpenAI. Aby uzyskać więcej informacji, zobacz Obsługiwane Azure OpenAI w modelach Foundry.
Uprawnienia do przyznania dostępu do zasobów Azure OpenAI z instancji zarządzania API.

Sposób 1. Importowanie interfejsu API z usługi Azure OpenAI

Interfejs API usługi Azure OpenAI można zaimportować bezpośrednio z usługi Azure OpenAI do usługi API Management.

Uwaga

Obecnie ta funkcja nie jest dostępna w obszarach roboczych.

Podczas importowania interfejsu API usługa API Management automatycznie konfiguruje:

Operacje dla każdego z punktów końcowych interfejsu API REST usługi Azure OpenAI
Tożsamość przypisana przez system z niezbędnymi uprawnieniami dostępu do zasobu usługi Azure OpenAI.
Zasób backendowy i zasada set-backend-service, które kierują żądania interfejsu API do punktu końcowego usługi Azure OpenAI.
Uwierzytelnianie w zapleczu usługi Azure OpenAI przy użyciu przypisanej przez system tożsamości zarządzanej wystąpienia.
(opcjonalnie) Zasady ułatwiające monitorowanie interfejsu API usługi Azure OpenAI i zarządzanie nim.

Aby zaimportować interfejs API usługi Azure OpenAI do usługi API Management:

W witrynie Azure portal przejdź do usługi API Management.
W menu po lewej stronie, w obszarze APIs, wybierz APIs>+ Dodaj API.
W obszarze Tworzenie z zasobu platformy Azure wybierz pozycję Azure OpenAI.
Na karcie Ustawienia podstawowe:
1. Wybierz zasób Azure OpenAI, który chcesz zaimportować.
2. Opcjonalnie wybierz wersję interfejsu API usługi Azure OpenAI. Jeśli go nie wybierzesz, domyślnie jest używana najnowsza wersja interfejsu API REST gotowego do produkcji. Zanotuj wybraną wersję. Będzie on potrzebny do przetestowania interfejsu API.
3. Wprowadź nazwę wyświetlaną i opcjonalny opis dla API.
4. W polu Podstawowy adres URL dołącz ścieżkę używaną przez wystąpienie usługi API Management do uzyskiwania dostępu do punktów końcowych interfejsu API usługi Azure OpenAI. Jeśli włączysz opcję Zapewnij zgodność z OpenAI SDK (zalecane), /openai jest automatycznie dodawane do podstawowego adresu URL.
  
  Jeśli na przykład punkt końcowy bramy zarządzania interfejsem API to https://contoso.azure-api.net, ustaw podstawowy adres URL podobny do https://contoso.azure-api.net/my-openai-api/openai.
5. Opcjonalnie wybierz co najmniej jeden produkt do skojarzenia z interfejsem API. Wybierz Dalej.
Na karcie Zasady opcjonalnie włącz zasady, aby ułatwić monitorowanie interfejsu API i zarządzanie nim. Można również ustawić lub edytować zasady później.

W przypadku wybrania wprowadź ustawienia lub zaakceptuj wartości domyślne, które definiują następujące zasady (zobacz artykuły połączone, aby zapoznać się z wymaganiami wstępnymi i szczegółami konfiguracji):
Wybierz Przejrzyj i utwórz.
Po zweryfikowaniu ustawień wybierz pozycję Utwórz.

Sposób 2. Dodawanie specyfikacji interfejsu OpenAPI do usługi API Management

Alternatywnie ręcznie pobierz specyfikację interfejsu OpenAPI dla interfejsu API REST usługi Azure OpenAI i dodaj ją do usługi API Management jako interfejs API OpenAPI.

Pobieranie specyfikacji interfejsu OpenAPI

Pobierz specyfikację interfejsu OpenAPI dla interfejsu API REST usługi Azure OpenAI, taką jak wersja ogólnie dostępna 2024-10-21.

W edytorze tekstów otwórz pobrany plik specyfikacji.
W elemecie servers w specyfikacji zastąp nazwę punktu końcowego usługi Azure OpenAI wartościami zastępczymi url i default punktem końcowym w specyfikacji. Przykładowo, jeśli punkt końcowy usługi Azure OpenAI to contoso.openai.azure.com, zaktualizuj element servers przy użyciu następujących wartości:
- adres URL: https://contoso.openai.azure.com/openai
- domyślny punkt końcowy: contoso.openai.azure.com
```
[...]
"servers": [
    {
      "url": "https://contoso.openai.azure.com/openai",
      "variables": {
        "endpoint": {
          "default": "contoso.openai.azure.com"
        }
      }
    }
  ],
[...]
```
Zanotuj wartość interfejsu API version w specyfikacji. Będzie on potrzebny do przetestowania interfejsu API. Przykład: 2024-10-21.

Dodawanie specyfikacji interfejsu OpenAPI do usługi API Management

W witrynie Azure portal przejdź do usługi API Management.
W menu po lewej stronie wybierz pozycję API>+ Dodaj API.
W obszarze Definiowanie nowego interfejsu API wybierz pozycję OpenAPI. Wprowadź nazwę wyświetlaną i nazwę dla API.
Wprowadź sufiks adresu URL interfejsu API kończący się na /openai, aby uzyskać dostęp do punktów końcowych interfejsu Azure OpenAI w Twoim wystąpieniu usługi API Management. Przykład: my-openai-api/openai.
Wybierz pozycję Utwórz.

API jest importowane i wyświetla operacje ze specyfikacji OpenAPI.

Konfigurowanie uwierzytelniania w interfejsie API usługi Azure OpenAI

Aby uwierzytelnić się w interfejsie API usługi Azure OpenAI, należy podać klucz interfejsu API lub tożsamość zarządzaną. Jeśli zaimportowano interfejs API usługi Azure OpenAI bezpośrednio do wystąpienia usługi API Management, uwierzytelnianie przy użyciu tożsamości zarządzanej wystąpienia usługi API Management zostanie automatycznie skonfigurowane.

Jeśli dodano interfejs API Azure OpenAI ze specyfikacji interfejsu OpenAPI, musisz skonfigurować uwierzytelnianie. Aby uzyskać więcej informacji na temat konfigurowania uwierzytelniania przy użyciu zasad usługi API Management, zobacz Uwierzytelnianie i autoryzacja do interfejsu API usługi Azure OpenAI.

Testowanie interfejsu API usługi Azure OpenAI

Aby upewnić się, że interfejs API usługi Azure OpenAI działa zgodnie z oczekiwaniami, przetestuj go w konsoli testowej usługi API Management. Aby przetestować interfejs API, musisz podać identyfikator wdrożenia modelu (nazwa) skonfigurowany w zasobie azure OpenAI i wersji interfejsu API.

Wybierz interfejs API utworzony w poprzednim kroku.
Wybierz kartę Test.
Wybierz operację zgodną z modelem wdrożonym w zasobie Azure OpenAI. Na stronie są wyświetlane pola parametrów i nagłówków.
W obszarze Parametry szablonu wprowadź następujące wartości:
- deployment-id — identyfikator wdrożenia w usłudze Azure OpenAI
- api-version — prawidłowa wersja interfejsu API usługi Azure OpenAI, taka jak wersja interfejsu API wybrana podczas importowania interfejsu API.
Wprowadź inne parametry i nagłówki zgodnie z potrzebami. W zależności od operacji może być konieczne skonfigurowanie lub zaktualizowanie treści żądania.

Uwaga

W konsoli testowej usługa API Management automatycznie wypełnia nagłówek Ocp-Apim-Subscription-Key i konfiguruje klucz subskrypcji wbudowanej subskrypcji z pełnym dostępem. Ten klucz umożliwia dostęp do każdego interfejsu API w instancji usługi zarządzania API. Opcjonalnie wyświetl nagłówek Ocp-Apim-Subscription-Key, wybierając ikonę "oko" obok żądania HTTP.
Wybierz Wyślij.

Po pomyślnym zakończeniu testu zaplecze odpowiada z pomyślnym kodem odpowiedzi HTTP i pewnymi danymi. Dołączono do odpowiedzi dane użycia tokenu, które ułatwiają monitorowanie użycia tokenów interfejsu API usługi Azure OpenAI i zarządzanie nim.

Udostępnij za pośrednictwem