Wektoryzator Azure OpenAI

Uwaga

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.

Wektoryzator Azure OpenAI łączy się z modelem osadzającym wdrożonym w zasobie Azure OpenAI w usłudze Foundry Models lub projekcie Microsoft Foundry, aby generować embeddingi w czasie wykonywania zapytania. Dane są przetwarzane w obszarze geograficznym , w którym wdrożono model.

Mimo że wektoryzatory są używane w czasie wykonywania zapytania, należy określić je w definicjach indeksu i odwoływać się do nich w polach wektorów za pośrednictwem profilu wektorowego. Aby uzyskać więcej informacji, zobacz Konfigurowanie wektoryzatora w indeksie wyszukiwania.

Wektoryzator Azure OpenAI nosi nazwę AzureOpenAIVectorizer w interfejsie API REST. Użyj najnowszej stabilnej wersji Indexes — tworzenie (interfejs API REST) lub pakiet Azure SDK, który udostępnia tę funkcję.

Uwaga

Ten wektoryzator jest powiązany z usługą Azure OpenAI i jest rozliczany według ceny standardowej usługi Azure OpenAI.

Wymagania wstępne

  • Zasób Azure OpenAI w usłudze Foundry Models lub projekt Foundry.

    • Zasób Azure OpenAI musi mieć poddomenę custom, taką jak https://<resource-name>.openai.azure.com. Ten punkt końcowy można znaleźć na stronie Keys i Endpoint w portalu Azure i użyć go dla właściwości resourceUri w tej umiejętności.

    • Zasób nadrzędny projektu Foundry zapewnia dostęp do wielu punktów końcowych, w tym https://<resource-name>.openai.azure.com, https://<resource-name>.services.ai.azure.comi https://<resource-name>.cognitiveservices.azure.com. Te punkty końcowe można znaleźć na stronie Klucze i punkt końcowy w portalu Azure i użyć dowolnego z nich dla właściwości resourceUri w tej umiejętności.

  • Model osadzania Azure OpenAI wdrożony w Twoim zasobie lub projekcie. Aby zapoznać się z obsługiwanymi modelami, zobacz następną sekcję.

Parametry wektoryzatora

W parametrach jest rozróżniana wielkość liter.

Nazwa parametru Opis
resourceUri (Wymagane) Bazowy identyfikator URI zasobu modelu. Obsługiwane domeny zasobów to:

  • openai.azure.com
  • services.ai.azure.com
  • cognitiveservices.azure.com

Azure API Management podstawowe identyfikatory URI bramy HTTPS są również obsługiwane, w tym hosty domyślne azure-api.net i skonfigurowane domeny niestandardowe. Ustaw deploymentId oddzielnie; nie należy podawać adresu URL operacji osadzania kompletnego. Aby uzyskać informacje o wymaganiach dotyczących routingu, uwierzytelniania, kontroli dostępu opartej na rolach (RBAC) i łączności prywatnej, zobacz Używanie usługi API Management z wywołaniami modeli Foundry IQ (Wyszukiwanie AI platformy Azure).

apiKey Klucz tajny używany do uzyskiwania dostępu do modelu. Skonfiguruj tylko jedną metodę uwierzytelniania; w przypadku używania klucza pozostaw authIdentity puste.
deploymentId (Wymagane) Identyfikator wdrożonego modelu osadzania Azure OpenAI. Jest to nazwa wdrożenia określona podczas wdrażania modelu.
authIdentity Tożsamość zarządzana przypisana przez użytkownika używana do połączenia. Pomiń zarówno apiKey, jak i authIdentity, aby użyć tożsamości przypisanej przez system usługi Foundry IQ. W przypadku wywołań bezpośrednich lub przekazywania tokenów przypisz rolę Cognitive Services OpenAI User w usłudze Azure OpenAI hostującej model lub w nadrzędnym zasobie Foundry. Aby zapoznać się z wyborem tożsamości i oddzielnymi przypisaniami bramy/zaplecza, zobacz Role scope and identity identifiers.
modelName (Wymagane) Nazwa modelu Azure OpenAI wdrożonego w określonym deploymentId. Obsługiwane wartości to:

  • text-embedding-ada-002
  • text-embedding-3-large
  • text-embedding-3-small

Obsługiwane typy zapytań wektorowych

Wektoryzator Azure OpenAI obsługuje tylko zapytania text vector.

Aby uzyskać informacje o wymaganiach dotyczących punktu końcowego usługi API Management, uwierzytelniania i sieci prywatnej, zobacz Use API Management with Foundry IQ model calls.

Oczekiwane wymiary pola

Oczekiwane wymiary pola skonfigurowanego za pomocą wektoryzatora Azure OpenAI zależą od skonfigurowanego modelName.

modelName Minimalne wymiary Maksymalne wymiary
text-embedding-ada-002 1536 1536
osadzanie tekstu —3 — duże 1 3072
osadzanie tekstu — 3 małe 1 1536

Przykładowa definicja

Poniższy fragment definicji indeksu konfiguruje bezpośrednie połączenie Azure OpenAI. Zastąp <api-key> swoimi poświadczeniami przed wysłaniem żądania.

{
  "vectorizers": [
    {
        "name": "my-openai-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
            "resourceUri": "https://my-fake-azure-openai-resource.openai.azure.com",
            "apiKey": "<api-key>",
            "deploymentId": "my-ada-002-deployment",
            "authIdentity": null,
            "modelName": "text-embedding-ada-002"
        }
    }
  ]
}

Przykład niestandardowej domeny usługi API Management

Ten fragment definicji indeksu konfiguruje wektoryzator z domeną bramy niestandardowej usługi API Management i tożsamością przypisaną przez system usługi Foundry IQ. Zastąp nazwę hosta i nazwę wdrożenia swoimi wartościami. Aby zamiast tego użyć domyślnej domeny bramy, ustaw resourceUri na https://<apim-name>.azure-api.net.

{
  "vectorizers": [
    {
      "name": "apim-embedding",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://apim.contoso.com",
        "deploymentId": "my-text-embedding-3-small",
        "modelName": "text-embedding-3-small"
      }
    }
  ]
}

Odwołanie: Indeksy — tworzenie.

Wybierz ten wektoryzator w profilu wektorowym zgodnym z modelem osadzania używanym w czasie indeksowania. Aby zamiast tego wybrać dołączoną tożsamość Search przypisaną przez użytkownika, dodaj następujący obiekt wewnątrz elementu azureOpenAIParameters:

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

W przypadku uwierzytelniania kluczem podaj apiKey i pomiń authIdentity; Search wysyła klucz w nagłówku api-key. Skonfiguruj bramę dla natywnej trasy osadzania i uwierzytelniania.

Najlepsze rozwiązania dotyczące wydajności

Poniżej przedstawiono niektóre najlepsze rozwiązania, które należy wziąć pod uwagę podczas korzystania z tego wektoryzatora:

  • Jeśli osiągniesz limit TPM (tokenów na minutę) usługi Azure OpenAI, zapoznaj się ze wskazówkami dotyczącymi limitów przydziału, aby odpowiednio temu zaradzić. Aby uzyskać więcej informacji na temat wydajności wystąpienia Azure OpenAI, zapoznaj się z dokumentacją monitorowania Azure OpenAI.

  • Wdrożenie modelu osadzania Azure OpenAI używane na potrzeby tego wektoryzatora powinno być idealnie oddzielone od wdrożenia używanego w innych przypadkach użycia, w tym umiejętności embedding. Ułatwia to dostosowanie każdego wdrożenia do jego konkretnego przypadku użycia, co prowadzi do zoptymalizowanej wydajności oraz ułatwia identyfikację ruchu pochodzącego z indeksatora i wywołań osadzania indeksu.

  • Instancja Azure OpenAI powinna znajdować się w tym samym regionie lub co najmniej w pobliżu regionu, w którym jest hostowana usługa Foundry IQ. Zmniejsza to opóźnienie i zwiększa szybkość transferu danych między usługami.

  • Aby uniknąć częstych kodów błędów 429, rozważ zaimplementowanie równoważenia obciążenia za pośrednictwem usługi API Management przez zaimplementowanie bramy równoważenia obciążenia przed wieloma wdrożeniami modeli osadzających Azure OpenAI.

  • Jeśli masz większy niż domyślny limit TPM usługi Azure OpenAI (tokeny na minutę) opublikowany w dokumentacji limitów przydziału i limitów, otwórz zgłoszenie do pomocy technicznej do zespołu Foundry IQ, aby można go było odpowiednio dostosować. Dzięki temu proces indeksowania nie jest niepotrzebnie spowalniany przez udokumentowany domyślny limit modułu TPM, jeśli masz wyższe limity.

Zagadnienia dotyczące zabezpieczeń uwierzytelniania tożsamości zarządzanej

Gdy wektoryzator Azure OpenAI używa tożsamości zarządzanej, usługa Foundry IQ wysyła token dostępu Microsoft Entra dla odbiorcy Cognitive Services (https://cognitiveservices.azure.com) oraz tekst zapytania do punktu końcowego skonfigurowanego w elemencie resourceUri. Ten proces ma zastosowanie, gdy wybierzesz tożsamość przypisaną przez użytkownika za pomocą authIdentity lub pominiesz zarówno apiKey, jak i authIdentity, aby użyć tożsamości przypisanej przez system.

Skonfiguruj tylko punkty końcowe, którym ufasz i które kontrolujesz, i które mają odbierać zarówno token, jak i tekst. Sama nazwa hosta nie potwierdza prawa własności ani zaufania. Nie należy polegać na sprawdzeniu połączenia w celu ustalenia, czy brama usługi API Management znajduje się przed zasobem, którego jesteś właścicielem.

Skonfiguruj punkt końcowy odbierający, aby zweryfikować podpis tokenu i standardowe roszczenia, w tym wystawcę, odbiorców, dzierżawcę, okres istnienia i wymagane uprawnienia. Zastosuj zasadę najmniejszych uprawnień do tożsamości zarządzanej usługi Foundry IQ. Informacje na temat konfiguracji bramy i oddzielnej tożsamości usługi API Management do back-endu zawiera artykuł Use API Management with Foundry IQ model calls.

Uwaga

Token tożsamości zarządzanej wystawiony dla odbiorcy Foundry Tools jest ważny w przypadku każdego narzędzia Foundry Tools lub zasobu Azure OpenAI, dla którego tożsamość ma autoryzację. Wysłanie go do niezaufanego punktu końcowego może ujawnić token.

Aby ułatwić utrzymanie bezpiecznego wdrożenia, postępuj zgodnie z następującymi praktykami:

  • Ustaw resourceUri tylko na punkty końcowe, którym ufasz i które należą do Ciebie. Użyj domen zasobów w parametrach wektoryzatora. Jeśli używasz punktu końcowego usługi APIM, potwierdź jego routing przed włączeniem tożsamości zarządzanej. Nazwa hosta, która wygląda na godną zaufania, nie jest dowodem własności.
  • Zastosuj najmniejsze uprawnienia do każdego połączenia. W przypadku bezpośrednich wywołań Azure OpenAI lub zamierzonego przekazywania tokenu przyznaj wybranej tożsamości Search rolę Cognitive Services OpenAI User w zasobie Azure OpenAI lub nadrzędnym zasobie Foundry hostującym wdrożenie. Gdy usługa APIM kończy uwierzytelnianie usługi Search i używa własnej tożsamości, autoryzuj usługę Search w APIM i przyznaj tę rolę zaplecza tożsamości usługi APIM w zasobie hostingu modelu, a nie usłudze Search. Unikaj szerszych ról.
  • Oceń Network Security Perimeter (NSP) i łączność prywatną dla określonego obciążenia. Prywatny punkt końcowy lub integracja z siecią wirtualną w samym odbiorniku nie zapewnia trasy z hosta wykonywania zapytania.
  • Jeśli używasz punktu końcowego usługi APIM, upewnij się, że brama weryfikuje żądania przychodzące i przekazuje je tylko do zamierzonego zaplecza. Należy również okresowo przeglądać zasady dostępu.
  • Preferuj tożsamość zarządzaną zamiast apiKey. Jeśli używasz apiKeymetody , zapisz ją i obracaj ją bezpiecznie i nie osadzaj jej w kontroli źródła. Skonfiguruj tylko jedną metodę uwierzytelniania.
  • Okresowo przeglądaj definicje indeksów, przypisania ról tożsamości zarządzanej i konfiguracje usługi APIM, aby potwierdzić, że resourceUri wartości, mechanizmy kontroli dostępu i uprawnienia tożsamości pozostają aktualne i odpowiednie. Przejrzyj zmiany konfiguracji za pomocą ustanowionych procesów zarządzania zmianami i przeglądu zabezpieczeń.
  • Monitoruj dzienniki logowania Azure OpenAI i Foundry Tools, zdarzenia uwierzytelniania i dzienniki dostępu pod kątem nieoczekiwanych lub nieautoryzowanych działań.
  • Usuń nieużywane wektoryzatory, punkty końcowe, przypisania ról i klucze interfejsu API, które nie są już wymagane.

Ograniczanie dostępu do konfiguracji indeksu i wektoryzatora

Użytkownicy, którzy mogą tworzyć lub modyfikować definicje indeksów, kontrolują zarówno docelowy punkt końcowy (resourceUri), jak i konfigurację uwierzytelniania używaną przez wektoryzator. Ponieważ wektoryzator wysyła token tożsamości zarządzanej dla odbiorców usług Cognitive Services do tego punktu końcowego, ogranicz te uprawnienia do zaufanych administratorów i postępuj zgodnie ze standardowymi procesami zarządzania zmianami i przeglądu zabezpieczeń podczas konfigurowania wektoryzatorów z obsługą tożsamości zarządzanej.

Nie zakładaj, że ustawienie zarządzania properties.dataExfiltrationProtections: ["BlockAll"] powoduje wyłączenie każdego wektoryzatora Azure OpenAI. Ogranicz uprawnienia edycji indeksu i przejrzyj miejsca docelowe, zasady bramy i przypisania ról. Aby uzyskać te same obowiązki związane z zaufaniem docelowym w indeksowaniu, zobacz Niestandardowe zagadnienia dotyczące zabezpieczeń umiejętności internetowego interfejsu API.

Zobacz też