Używanie usługi API Management z wywołaniami modelu Foundry IQ (Wyszukiwanie AI platformy Azure)

Note

Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.

Aby uzyskać terminy stosowane w przypadku korzystania z obsługiwanych modeli innych niż Microsoft, zobacz Modele innych firm. Jeśli skonfigurujesz usługę API Management do kierowania do obsługiwanych bram innych firm, zobacz Bramy innych firm za pośrednictwem usługi API Management.

Użyj Azure API Management jako bramy dla obsługiwanych wywołań modelu IQ (Wyszukiwanie AI platformy Azure) rozwiązania Foundry w celu scentralizowania routingu, ograniczania przepustowości, równoważenia obciążenia i monitorowania. Obsługa zależy od obciążenia roboczego Search oraz od protokołu modelu, sposobu uwierzytelniania i środowiska wykonywania.

Począwszy od 2026-11-01-preview, LLM-y bazy wiedzy zgodne z OpenAI do wyszukiwania agentowego akceptują pełne adresy URL punktów końcowych. Te punkty końcowe mogą być usługą API Management, bramą klienta lub bezpośrednio skonfigurowanym zgodnym dostawcą zewnętrznym. Usługa API Management nie jest wymagana dla tej konfiguracji bazy wiedzy. Ustawienia Azure OpenAI i zgodne ustawienia bazy wiedzy mają różne struktury.

Prerequisites

  • Usługa Foundry IQ i uprawnienie do konfigurowania obciążenia roboczego. Na przykład przypisz Search Service Contributor do tworzenia lub aktualizowania indeksów i baz wiedzy. Zobacz Łączenie za pomocą ról.
  • Punkt końcowy modelu, który implementuje protokół i możliwości wymagane przez obciążenie, w tym ustrukturyzowane dane wyjściowe i wywołania narzędzi tam, gdzie jest to wymagane.
  • W przypadku usługi API Management skonfigurowany interfejs API bramy i zaplecze z oddzielnym uwierzytelnianiem dla połączeń typu search-to-gateway i gateway-to-backend.
  • W przypadku zgodnych modeli LLM bazy wiedzy i natywnych profilów GPT-6 KB ustaw api-version=2026-11-01-preview w żądaniach tworzenia, aktualizacji i pobierania bazy wiedzy. Postępuj zgodnie z konfiguracją KB w wersji zapoznawczej z listopada i weryfikacją wyszukiwania. Użyj istniejących wersji interfejsu API obciążeń dla innych konfiguracji.
  • W przypadku tożsamości zarządzanej wymagane są włączona tożsamość usługi Foundry IQ, autoryzacja w odbierającym punkcie końcowym i uprawnienie do przypisywania wszystkich wymaganych ról.

Wybieranie obsługiwanego obciążenia i interfejsu API

W poniższej tabeli opisano połączenia modelu, a nie certyfikację każdej topologii sieci prywatnej. Zobacz Łączność prywatna, aby uzyskać informacje o wymaganiach dotyczących sieci.

Obciążenie Dostępność interfejsu API wyszukiwania Wybór protokołu i modelu Punkt końcowy i uwierzytelnianie
umiejętność osadzania Azure OpenAI Natywna obsługa z systemu 2023-10-01-preview; stabilna 2024-07-01. Konfigurowalne nowoczesne rozmiary modeli z 2024-05-01-preview lub ze stabilnego 2024-07-01. Osadzenia; trzy profile osadzeń. Natywny identyfikator URI zasobu oraz identyfikator wdrożenia; obsługiwane są domyślne i niestandardowe domeny bramy usługi API Management. Klucz natywny lub tożsamość zarządzana.
Azure wektoryzator OpenAI Natywna obsługa z systemu 2023-10-01-preview; stabilna 2024-07-01. Osadzenia dla zapytań tekstowych; trzy profile osadzania. Natywny identyfikator URI zasobu oraz identyfikator wdrożenia; obsługiwane są domyślne i niestandardowe domeny bramy usługi API Management. Klucz natywny lub tożsamość zarządzana.
Umiejętność GenAI Prompt Od 2025-05-01-preview; Ogólna dostępność 2026-04-01. Uzupełnianie czatu z punktem końcowym i modelem, które obsługują dane wejściowe umiejętności i parametry generowania. Pełna uri; domyślna lub niestandardowa domena bramy usługi API Management. Natywne właściwości klucza/tożsamości.
Opcjonalny model LLM Content Understanding Umiejętność podstawowa — ogólna dostępność (GA) 2026-04-01; opcjonalne właściwości LLM — ogólna dostępność (GA) 2026-10-01. Operacja Content Understanding z obsługiwanym modelem w dołączonym zasobie. Ustawienia modelu i wdrażania w zasobie Foundry dołączonym do zestawu umiejętności.
Natywny model pobierania bazy wiedzy Istniejący natywny kontrakt bazy wiedzy; profile odpowiedzi GPT-6 wymagają 2026-11-01-preview. Wyszukiwanie wybiera pozycję Chat Completions lub Odpowiedzi z profilu modelu. Ustawienia zasobu/wdrożenia natywnego. Usługa API Management nie jest obsługiwana w przypadku tych ustawień; użyj oddzielnie obsługiwanej zgodnej wersji zapoznawczej KB dla połączenia bramy.
Model pobierania zgodnej bazy wiedzy 2026-11-01-preview. Funkcje Chat Completions lub Responses wybrane w profilu; 21 obsługiwanych profilów KB. Pełny adres URL HTTPS POST; nagłówki lub tożsamość zarządzana z niestandardowym odbiorcą. Nie jest obsługiwane w przypadku źródeł wiedzy z sieci Web.
Natywny czat ingestii źródeł wiedzy Istniejąca umowa zarządzanego pozyskiwania. Werbalizacja obrazów poza Content Understanding tworzy żądania Chat Completions; usługa Content Understanding używa własnej operacji. Natywny model pozyskiwania danych i ustawienia wdrożenia.
Natywne osadzenia źródeł wiedzy Istniejąca umowa zarządzanego pozyskiwania. Natywne embeddingi. Ustawienia zasobu natywnego i wdrożenia.

Usługa API Management nie jest obsługiwana jako brama dla żądań analizatora Content Understanding ani opcjonalnych wywołań modelu opisu obrazu.

Podgląd zgodnej bazy wiedzy ma zastosowanie tylko do konfiguracji modelu pobierania. Nie zmienia konfiguracji modelu pozyskiwania źródła wiedzy ani nie rozszerza natywnej umiejętności osadzania i wektoryzatora na protokoły zgodnego dostawcy.

W przypadku treści chronionych uprawnieniami oddzielna umiejętność GenAI Prompt (Chat Completion) nie czyni z usługi API Management obsługiwanego miejsca docelowego. W przypadku pozyskiwania tylko listy ACL ta umiejętność wymaga obsługiwanego własnego punktu końcowego firmy Microsoft, a nie usługi API Management. W przypadku pozyskiwania etykiet poufności ta umiejętność nie jest obsługiwana. Przed skonfigurowaniem wzbogacania przejrzyj ograniczenia ACL w usłudze SharePoint; uwierzytelnianie lub routing prywatny nie usuwa tych ograniczeń.

Wersje interfejsu API płaszczyzny danych usługi Search, wersje interfejsu API zarządzania usługą Search, wersje interfejsu API zarządzania usługą API Management, wersje interfejsu API modeli niższego poziomu oraz wersje wdrożonych modeli są niezależne. Zmiana wersji interfejsu API usługi Search nie zmienia interfejsu API niższego poziomu ani nie wdraża innego modelu.

Omówienie wymagań dotyczących punktu końcowego i protokołu

Natywne punkty końcowe

W przypadku Azure umiejętności osadzania interfejsu OpenAI i wektoryzatora ustaw resourceUri podstawowy identyfikator URI zasobu lub podstawowy identyfikator URI bramy usługi API Management https. Możesz użyć zarówno domyślnej nazwy hosta bramy, jak i skonfigurowanej domeny niestandardowej, takiej jak https://<apim-name>.azure-api.nethttps://apim.contoso.com. Ustaw deploymentId osobno. Obsługa domeny niestandardowej nie zmienia natywnego protokołu osadzania ani nie dodaje obsługi dowolnych kompatybilnych dostawców.

Wyszukiwanie tworzy /openai/deployments/<deploymentId>/embeddings?api-version=2023-05-15 dla tych natywnych wywołań osadzania. Skonfiguruj interfejs API bramy i zasady, aby akceptowały tę ścieżkę i ciąg zapytania oraz kierowały do zamierzonego wdrożenia Azure OpenAI. Jeśli zaplecze wymaga innej ścieżki, nazwy wdrożenia lub wersji interfejsu API, przepisz je w usłudze API Management. Nie umieszczaj pełnego adresu URL operacji osadzania w resourceUri.

Poniższy fragment parametru używa domyślnej domeny bramy. Użyj go jako parametrów umiejętności osadzania lub wewnątrz elementu azureOpenAIParameters wektoryzatora. Używa tożsamości przypisanej przez system usługi Foundry IQ, ponieważ pomija zarówno apiKey, jak i authIdentity.

{
  "resourceUri": "https://contoso-models.azure-api.net",
  "deploymentId": "my-text-embedding-3-small",
  "modelName": "text-embedding-3-small"
}

W przypadku domeny bramy niestandardowej zmień tylko resourceUri wartość na https://apim.contoso.com. Skonfiguruj tę nazwę hosta i jej certyfikat TLS w bramie usługi API Management. Ustawienia wdrożenia i modelu pozostają oddzielne. Pełne definicje i wybór tożsamości przypisanej przez użytkownika można znaleźć w przykładach umiejętności osadzania i wektoryzatora.

W przypadku umiejętności GenAI Prompt podaj kompletne wywołanie modelu uri, w tym ścieżkę operacji i wszystkie wymagane parametry zapytania. Obsługiwane są domyślne i niestandardowe domeny bramy usługi API Management. Sam podstawowy adres URL bramy nie jest kompletnym adresem URL operacji GenAI.

Natywne wywołania uzupełnień czatu KB używają ścieżki wdrożenia, takiej jak https://<resource-name>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-08-01-preview. Natywne profile GPT-6 KB używają https://<resource-name>.openai.azure.com/openai/v1/responses, a identyfikator wdrożenia znajduje się w treści żądania w elemencie model.

Zgodne punkty końcowe

W przypadku zgodnych modeli LLM bazy wiedzy używanych do pobierania:

  1. Podaj pełny bezwzględny adres URL HTTPS POST w uri, łącznie z jego ścieżką i parametrami zapytania. Przykład:
    • Uzupełnienia czatu: https://<apim-name>.azure-api.net/openai/deployments/<deployment>/chat/completions?api-version=<downstream-api-version>.
    • Odpowiedzi: https://<gateway-host>/openai/v1/responses.
  2. Skonfiguruj punkt końcowy, aby akceptował wybrany protokół. Wyszukiwanie wysyła adres URL bez zmian: nie dołącza ścieżki wdrożenia, operacji ani api-version.
  3. Nie osadzaj poświadczeń ani fragmentu w adresie URL. Wyszukiwanie nie jest zgodne z przekierowaniami, w tym przekierowaniami do tego samego hosta.
  4. Konfigurowanie routingu pod adresem URL lub bramą. Zgodne ciała żądań bazy wiedzy pomijają element model. Jeśli dostawca wymaga identyfikatora model , brama musi ją podać.

Niestandardowe domeny bramy i bezpośrednie punkty końcowe kompatybilne z rozwiązaniami innych firm używają tego samego kontraktu. Jeśli adres URL dostawcy wymaga modelu w treści żądania, potrzebujesz bramy lub adaptera, który dostarcza tę wartość.

modelName wybiera pozycję Wyszukaj profil i możliwości. Nie wybiera ani nie weryfikuje rzeczywistego wdrożenia podrzędnego, nie identyfikuje datowanej wersji modelu dostawcy ani nie czyni dowolnego protokołu dostawcy kompatybilnym. W konfiguracji zgodnej bazy wiedzy nie ma publicznego selektora protokołu.

W przypadku pobierania z bazy wiedzy Responses zachowaj bezstanowe struktury kontynuacji, dane wejściowe i wyjściowe wywołania funkcji oraz zaszyfrowaną zawartość rozumowania. Wyszukiwanie wysyła store:false. Akceptowanie ciągu nazwy modelu lub prostego żądania tekstowego nie jest wystarczające. Tłumaczenie protokołu w bramie nie powoduje, że protokół docelowy jest natywnym protokołem Search.

Konfigurowanie uwierzytelniania między Search a bramą

Zachowaj uwierzytelnianie aplikacji do wyszukiwania niezależnie od uwierzytelniania typu search-to-gateway. Poświadczenia używane do tworzenia lub wykonywania zapytań względem obiektu Search nie są poświadczeniami używanymi do wywołań modelu wychodzącego.

Uwierzytelnianie natywne

Natywne ustawienia osadzania Azure OpenAI używają apiKey lub tożsamości zarządzanej Search. Uwierzytelnianie klucza zwraca wartość api-key, a nie automatycznie Ocp-Apim-Subscription-Key. Skonfiguruj nagłówek lub zasady subskrypcji usługi API Management, aby pasować do nagłówka wysyłanego obciążenia.

Natywna tożsamość zarządzana uzyskuje token dla odbiorcy usługi Cognitive Services (https://cognitiveservices.azure.com). Pomiń apiKey tożsamość przypisaną authIdentity przez system lub użyj obiektu tożsamości obciążenia dla dołączonej tożsamości przypisanej przez użytkownika. Skonfiguruj tylko jedną metodę uwierzytelniania. Zobacz każdą dokumentację obciążenia, aby zapoznać się z obsługiwanymi właściwościami tożsamości.

Skonfiguruj bramę, aby zweryfikować token i autoryzować wybraną tożsamość wyszukiwania, w tym sygnaturę, wystawcę, odbiorców usług Cognitive Services, dzierżawcę, okres ważności i wymagane uprawnienia. Uwierzytelnianie natywne nie uzyskuje tokenu dla odbiorców aplikacji bramy niestandardowej. Użyj wzorca klient-brama w scenariuszu 2: Aplikacja kliencka autoryzuje usługę API Management z walidacją skonfigurowaną dla odbiorcy, do którego to obciążenie faktycznie wysyła żądania. Scenariusz 3 opisuje autoryzację przy użyciu menedżera poświadczeń do systemów zaplecza SaaS, a nie tego połączenia.

Zgodne uwierzytelnianie

Podczas tworzenia zgodnego połączenia bazy wiedzy LLM określ dokładnie jeden skuteczny tryb uwierzytelniania w elemencie openAICompatibleParameters:

Mode Configuration Wymaganie dotyczące punktu końcowego odbierającego
Przechowywane nagłówki Niepusta headers mapa. Nazwy nagłówków i wartości są tajne. Zaakceptuj i zweryfikuj skonfigurowane poświadczenia. W przypadku usługi API Management to wymaganie może zawierać jego nagłówek subskrypcji.
Tożsamość zarządzana managedIdentityAudience, opcjonalnie z authIdentity. Zweryfikuj i autoryzuj tożsamość wyszukiwania dla grupy odbiorców aplikacji klienta.

managedIdentityAudiencemusi być kanonicznym identyfikatorem GUID aplikacji Microsoft Entra, takim jak 11111111-2222-3333-4444-555555555555. Nie używaj api://, /.default, zakresu ani grupy odbiorców usługi Cognitive Services. Pomiń authIdentity, aby użyć tożsamości przypisanej przez system usługi Foundry IQ.

Aby wybrać dołączoną tożsamość przypisaną przez użytkownika, dodaj ten obiekt tożsamości obok managedIdentityAudience:

{
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  }
}

Ten fragment właściwości nie jest kompletnym połączeniem. Oba tryby razem, żaden tryb podczas tworzenia, pusta mapa nagłówka lub authIdentity bez managedIdentityAudience są nieprawidłowe. Błędy pozyskiwania lub walidacji tokenu nie wracają do uwierzytelniania anonimowego.

Konfigurowanie uwierzytelniania bramy do backendu

Zabezpiecz połączenie z zapleczem oddzielnie. W przypadku zaplecza Microsoft obsługiwanego Azure openAI typowy wzorzec to kończenie poświadczeń w usłudze API Management, a następnie uwierzytelnianie przy użyciu własnej tożsamości zarządzanej usługi API Management lub przypisanej przez użytkownika. Przypisz tej tożsamości użytkownika openAI usług Cognitive Services w zasobie Azure openAI lub nadrzędnym zasobie foundry usług Cognitive Services, który hostuje wdrożenie zaplecza i jest właścicielem punktu końcowego. Skonfiguruj zasady zaplecza, aby używały tej tożsamości. Tożsamość wyszukiwania nie wymaga roli w tym zapleczu, gdy usługa API Management kończy swoje poświadczenia i używa własnej tożsamości.

Alternatywnie przechowuj klucz zaplecza w usłudze API Management w wartości nazwanej i użyj zasad, aby przekazać go do zaplecza. Klucz zaplecza nie jest kluczem subskrypcji search-to-gateway.

W przypadku zaplecza klienta lub zewnętrznego zaplecza skonfiguruj wymaganą autoryzację, routing i adaptację protokołu. Tożsamość zarządzana typu wyszukiwanie-brama nie ustanawia autoryzacji w tym zapleczu.

Zobacz Opcje uwierzytelniania po stronie usługi, tożsamości zarządzane usługi API Management i możliwości bramy generowania sztucznej inteligencji.

Wybieranie zakresu roli i tożsamości

W przypadku bezpośrednich wywołań interfejsu OpenAI Azure lub zamierzonego przekazywania tokenu przypisz użytkownika openAI usług Cognitive Services do wybranej tożsamości zarządzanej wyszukiwania. Określanie zakresu przypisania do zasobu openAI lub nadrzędnego rozwiązania Foundry Azure, który hostuje wdrożenie i jest właścicielem punktu końcowego.

Jeśli na przykład projekt contoso-project używa wdrożenia my-text-embedding-3-small w zasobie contoso-foundrynadrzędnym, zakres roli to /subscriptions/<model-subscription-id>/resourceGroups/<model-resource-group>/providers/Microsoft.CognitiveServices/accounts/contoso-foundry. W przypadku autonomicznego Azure zasobu OpenAI o nazwie contoso-modelsużyj odpowiedniego identyfikatora zasobu kończącego się na ./Microsoft.CognitiveServices/accounts/contoso-models Żaden zakres nie zawiera /projects/<project-name> ani nazwy wdrożenia.

Aby uzyskać informacje o identyfikatorach tożsamości i krokach przypisywania ról, zobacz Przypisz rolę. W przypadku domeny niestandardowej usługi API Management zidentyfikuj zasób hostingu modelu z poziomu konfiguracji zaplecza bramy, a nie z nazwy hosta bramy.

Na stronie Kontrola dostępu (IAM) zasobu hostującego model przypisz rolę do poprawnego podmiotu zabezpieczeń. Jeśli usługa Search i zasób modelu znajdują się w różnych grupach zasobów lub subskrypcjach w tej samej dzierżawie Microsoft Entra, użyj subskrypcji i grupy zasobów zasobu modelu w zakresie przypisania roli. Upewnij się, że masz uprawnienia do przypisywania ról w tym zakresie. Zobacz Azure zakres RBAC. Tożsamości zarządzane nie obsługują dostępu między katalogami.

W przypadku błędów 401 lub 403 sprawdź wybraną tożsamość, zakres zasobów, propagację przypisania roli i każdą nogę uwierzytelniania. Jeśli uwierzytelnianie lokalne jest wyłączone w zasobie modelu, użyj autoryzowanej tożsamości zarządzanej, a nie klucza. Kontrola dostępu oparta na rolach przyznaje autoryzację; nie konfiguruje dns, zapór ani tras prywatnych.

Korzystanie z zgodnego modelu bazy wiedzy

Aby uzyskać pełną konfigurację REST, dokładne profile modelu 21 KB i oddzielne przykłady uzupełniania czatów i odpowiedzi, zobacz Używanie modelu zgodnego z platformą OpenAI (wersja zapoznawcza).

Istniejącą bazę wiedzy można przełączyć z natywnej Azure openAI lub punktu końcowego modelu Microsoft Foundry na punkt końcowy usługi APIM lub niestandardowej domeny bez ponownego tworzenia. Użyj 2026-11-01-preview lub nowszej obsługiwanej wersji zapoznawczej i postępuj zgodnie z wymaganiami dotyczącymi aktualizacji połączenia modelu.

Skonfiguruj model LLM do pobierania w kolekcji models bazy wiedzy przy użyciu elementów kind: "openAICompatible" i openAICompatibleParameters. Baza wiedzy z internetowym źródłem wiedzy wymaga natywnej Azure konfiguracji czatu OpenAI.

Po skonfigurowaniu sprawdź połączenie modelu pobierania w tej samej bazie wiedzy przy użyciu polecenia 2026-11-01-preview. Użyj pobierania opartego na usłudze LLM i sprawdź niesekretowe działanie modelu i routing bramy. Pomyślne utworzenie lub sam get nie weryfikuje wywołania modelu.

Obsługiwane modele osadzania Azure OpenAI

Osadzanie profilów

Umiejętność osadzania Azure OpenAI i wektoryzator obsługują następujące modele. Użyj istniejącej konfiguracji obciążenia z elementami resourceUri, deploymentIdi modelName.

Profile Wymiary domyślne Zaakceptowane wymiary
text-embedding-ada-002 1536 Tylko 1536
text-embedding-3-small 1536 1–1536
text-embedding-3-large 3072 1–3072

Efektywne wymiary wyjściowe muszą być zgodne z polem wektorowym. Użyj tego samego modelu osadzania i ustawień podczas pozyskiwania i wykonywania zapytań; same wymiary równe nie ustanawiają współużytkowanej przestrzeni semantycznej. Aby uzyskać pełne konfiguracje, zobacz dokumentację elementów embedding skill i Azure OpenAI vectorizer.

Aktualizowanie poświadczeń i konfiguracji modelu

W przypadku zgodnych modeli LLM bazy wiedzy headers są tylko do zapisu. Publiczne odpowiedzi całkowicie pomijają właściwość, łącznie z nazwami nagłówków. Nie zwracają wartości maskowanej, {}ani null.

W przypadku tej samej bazy wiedzy i powiązania modelu aktualizacja, która pomija headers, może zachować zapisane poświadczenia tylko wtedy, gdy dokładny punkt końcowy, profil modelu i tożsamość uwierzytelniania pozostają niezmienione.

Update Wymagana akcja
Odczyt do PUT bez zmian Zachowaj te same ustawienia zasobu/powiązania i połączenia/profilu/tożsamości. Pominięte nagłówki mogą zachowywać przechowywane poświadczenia.
Zmieniono miejsce docelowe, profil lub tożsamość Podaj nowe dane uwierzytelniające. Nie przesyłaj pominiętego sekretu do zmienionego zakresu.
Kopiowanie, zmienianie nazwy lub tworzenie na podstawie wyniku odczytu Jawnie podaj uwierzytelnianie; pominięcie nie dziedziczy poświadczeń innego obiektu.
Obracanie poświadczenia nagłówka Wyślij pełną prawidłową mapę nagłówka zastępczego w tym samym wiązaniu modelu.
Przełączanie między trybem nagłówka a trybem tożsamości zarządzanej Podaj nowy prawidłowy tryb i usuń stary tryb z żądania.
Odrzucona aktualizacja Istniejące przechowywane poświadczenia pozostają niezmienione.

Możesz na przykład zmienić nagłówek bazy wiedzy, wysyłając istniejącą kompletną definicję bazy wiedzy z mapą zastępczą headers. Kolejne polecenie GET pomija headers; niezmienione put tego wyniku odczytu może zachować zastąpienie. Nie zmieniaj uri w tym wyniku odczytu i nie oczekuj, że pominięty wpis tajny będzie podążał za nim.

Powtórz weryfikację pobierania wspomaganego przez LLM po rotacji oraz po aktualizacji typu read-to-PUT bez zmian. Upewnij się, że brama akceptuje poświadczenia zastępcze i pobieranie nadal kończy się powodzeniem bez rejestrowania nazw nagłówków, wartości lub tokenów.

Konfigurowanie łączności prywatnej

Prywatny punkt końcowy usługi API Management jest połączeniem przychodzącym z podrzędnym zasobem środowiska uruchomieniowego Gateway. Gateway nie jest warstwą. Adresy URL zarządzania, portalu i dokumentacji dla deweloperów nie są punktami końcowymi wywołania modelu i nie są objęte tym połączeniem Private Link bramy.

Warstwy i topologia usługi API Management

Poziom lub topologia Możliwość API Management Kwalifikacja wyszukiwania
Standard v2 Przychodzący prywatny punkt końcowy i wychodząca integracja z siecią wirtualną. Zweryfikuj trasę wykonywania obciążenia wyszukiwania oddzielnie.
Premium v2 Prywatny punkt końcowy dla ruchu przychodzącego i opcje integracji/iniekcji sieci wirtualnej. Możliwość usługi API Management nie jest gwarancją, że każda wstrzyknięta topologia współpracuje z udostępnionym mechanizmem Search Shared Private Link.
Klasyczna wersja Premium, niewstrzyknięta do sieci wirtualnej Obsługuje przychodzące prywatne punkty końcowe. Nie traktuj wszystkich klasycznych wystąpień Premium jako nieobsługiwanych.
Classic Premium, wewnętrzne wstrzykiwanie do sieci wirtualnej Prywatne punkty końcowe nie są obsługiwane. Nieobsługiwane w przypadku tego projektu udostępnionego łącza prywatnego.
Klasyczna wersja Premium, zewnętrzna iniekcja sieci wirtualnej Prywatne punkty końcowe nie są obsługiwane. Nieobsługiwane w przypadku tego projektu udostępnionego łącza prywatnego.
Classic Developer, Basic, Standard Uwzględnione w stosowalności prywatnego punktu końcowego usługi API Management, z zastrzeżeniem ograniczeń. Nie jest to ogólne poświadczenie tras obciążeń usługi Search.
Własna brama lub brama obszaru roboczego Nieobsługiwane w przypadku udokumentowanego przychodzącego połączenia prywatnego punktu końcowego. To ograniczenie dotyczy łączności prywatnej, a nie wszystkich scenariuszy protokołu publicznego.

Zobacz Warstwy usługi API Management w wersji 2 i ograniczenia prywatnego punktu końcowego. Funkcje usługi API Management w wersji 2 korzystają z interfejsu API zarządzania w wersji 2024-05-01 lub nowszej. Ta wersja nie wybiera interfejsu API płaszczyzny danych Search ani interfejsu API zarządzania.

Klasyczna wersja Premium pozostaje obsługiwana i nie jest wycofana. Usługa API Management nie ma obecnie zautomatyzowanych narzędzi do migrowania istniejącego wystąpienia warstwy klasycznej, w tym premium, do wystąpienia w wersji 2-warstwowej. Warstwy w wersji 2 są dostępne dla nowo utworzonych wystąpień. Zobacz często zadawane pytania dotyczące migracji usługi API Management w wersji 2 i warstwy klasycznej.

Na przykład klasyczne wystąpienie Premium z wewnętrznym wstrzyknięciem sieci wirtualnej i docelową funkcją wyszukiwania udostępnionego łącza Microsoft.ApiManagement/service / Gateway prywatnego jest nieobsługiwane. Zewnętrzna iniekcja VNet ma to samo ograniczenie. Prawidłowy identyfikator zasobu, zatwierdzone żądanie połączenia lub domena niestandardowa nie usuwa tego ograniczenia topologii.

Aby uzyskać kwalifikujące się wzbogacanie indeksatora, postępuj zgodnie z instrukcjami Make outbound connections through a shared private link (Utwórz połączenia wychodzące za pośrednictwem udostępnionego łącza prywatnego):

  1. Potwierdź uprawnienia do warstwy usługi Search, chmury, obciążenia i prywatnego wykonywania.
  2. Utwórz udostępniony link prywatny przeznaczony dla typu Microsoft.ApiManagement/service zasobu z identyfikatorem Gatewaygrupy . Istniejący przewodnik Search używa interfejsu API zarządzania 2025-05-01; nie jest to wersja interfejsu API modelu docelowego.
  3. Zatwierdź połączenie w usłudze API Management i potwierdź pomyślne aprowizowanie i zatwierdzenie.
  4. Ustaw wartość kwalifikowanych indeksatorów parameters.configuration.executionEnvironment na "private".
  5. Zweryfikuj rozpoznawanie nazw DNS, protokół TLS i routing z rzeczywistego środowiska wykonawczego. Użyj skonfigurowanej nazwy hosta bramy, a nie prywatnego adresu IP w identyfikatorze URI modelu. Jego certyfikat musi być zgodny z nazwą hosta. W przypadku domeny niestandardowej skonfiguruj system DNS dla tej nazwy, a także domyślną prywatną konfigurację DNS privatelink.azure-api.net. Standardowa v2 i Premium v2 wymagają również, aby nazwa bramy niestandardowej była publicznie rozpoznawalna; zobacz ograniczenia DNS domeny niestandardowej.
  6. Wyłącz dostęp do sieci publicznej usługi API Management dopiero po skonfigurowaniu prywatnego punktu końcowego i zweryfikowaniu trasy prywatnej. W przypadku publicznego połączenia search-to-APIM zachowaj publiczny punkt końcowy bramy dostępny w ramach zasad sieciowych. Ustawienia sieci publicznej w usłudze Search, API Management i zapleczu są niezależne.
  7. Zabezpiecz sieć między usługą API Management a zapleczem niezależnie.

Nie dodawaj właściwości wykonywania indeksatora do żądań pobierania bazy wiedzy ani żądań wektoryzacji zapytań. Rejestracja obiektu docelowego bramy API Management nie zapewnia obsługi tras prywatnych dla każdego hosta wykonania bazy wiedzy lub wektoryzatora zapytań. Akceptowanie prywatnego adresu docelowego nie powoduje utworzenia trasy. Obsługa usługi API Management również nie ustanawia ogólnej obsługi dowolnych Microsoft.Network/privateLinkServices celów.

Zagadnienia dotyczące zabezpieczeń

Usługa Foundry IQ wysyła dane wejściowe modelu i skonfigurowane materiały uwierzytelniające do wybranego punktu końcowego. Skonfiguruj tylko punkty końcowe, którym ufasz i które kontrolujesz, i które mają otrzymywać te dane wejściowe i poświadczenia. Sama nazwa hosta lub identyfikator GUID elementu audience nie ustanawia własności punktu końcowego, autoryzacji ani łączności prywatnej.

Zweryfikuj tokeny tożsamości zarządzanej w odbieranym punkcie końcowym, w tym podpis, wystawcę, odbiorcę, dzierżawcę, okres istnienia i wymagane uprawnienia. Zastosuj zasadę najmniejszych uprawnień zarówno do tożsamości usługi Search, jak i API Management. Ogranicz uprawnienia do modyfikowania definicji indeksów, baz wiedzy, źródeł wiedzy i zasad bramy.

Przed włączeniem połączenia przejrzyj routing, dostawców downstream, rejestrowanie, przechowywanie, przetwarzanie geograficzne i mechanizmy kontroli dostępu. Zabezpiecz uwierzytelnianie typu search-to-gateway niezależnie od uwierzytelniania między bramą a zapleczem. Tożsamość zarządzana nie sprawia, że zaplecze klienta ani firmy trzeciej jest obsługiwane przez Microsoft.

Ustawienie properties.dataExfiltrationProtections Zarządzanie wyszukiwaniem używa publicznej wartości ["BlockAll"]. Blokuje ona kompatybilne wywołania modelu bazy wiedzy. Nie traktuj tej wartości jako przełącznika, który wyłącza każdy wektoryzator Azure OpenAI. Przejrzyj wskazówki dotyczące zabezpieczeń wektoryzatora Azure OpenAI i mechanizmy kontroli sieci dla określonego obciążenia.

Rozwiązywanie problemów z nieobsługiwanymi kombinacjami

Objaw lub konfiguracja Co należy sprawdzić?
Nie znaleziono operacji lub przekierowanie Podaj pełny zgodny adres URL POST i poprawne parametry zapytania. Wyszukiwanie nie dołącza ścieżek ani nie śledzi przekierowań.
Brak modelu dostawcy Zgodne treści KB pomijają element model. Konfigurowanie routingu adresów URL lub iniekcji bramy; modelName nie jest selektorem wdrażania dostawcy.
Błąd usługi Responses KB Użyj profilu bazy wiedzy odpowiedzi i punktu końcowego z obsługą wersji zapoznawczej z listopada i wymaganymi strukturami kontynuacji. Nie ma obiecanego awaryjnego rozwiązania Chat Completions.
Uwierzytelnianie zostało odrzucone Użyj dokładnie jednego prawidłowego trybu. Sprawdź odbiorców natywnych i niestandardowych aplikacji, walidację tokenu, nazwy nagłówków i obie nogi uwierzytelniania.
Aktualizacja kończy się niepowodzeniem po odczytaniu obiektu Podaj nowe poświadczenia dla zmienionego zakresu. Nie kopiuj poświadczeń tylko do zapisu, pomijając.
Azure żądanie osadzania openAI kończy się niepowodzeniem Użyj obsługiwanego modelu osadzania, pasujących wymiarów oraz ustawień identyfikatora URI zasobu i wdrożenia udokumentowanych dla umiejętności lub wektoryzatora.
Żądanie prywatne kończy się niepowodzeniem Sprawdź uprawnienia do wykonywania obciążenia, zatwierdzanie, dns, TLS, warstwę/topologię usługi API Management oraz łączność zaplecza niezależnie.
Internetowe źródło wiedzy z zgodnym modelem bazy wiedzy Użyj natywnej Azure konfiguracji czatu OpenAI.