Konfigurowanie usługi Foundry IQ (Wyszukiwanie AI platformy Azure) w celu nawiązania połączenia przy użyciu tożsamości zarządzanej

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.

Można użyć podmiotów zabezpieczeń Microsoft Entra ID i przypisań ról dla połączeń wychodzących z usługi Foundry IQ (Wyszukiwanie AI platformy Azure) do innych zasobów Azure dostarczających dane, zastosowaną sztuczną inteligencję lub wektoryzację podczas indeksowania lub zapytań.

Aby używać ról w połączeniu wychodzącym, najpierw skonfiguruj usługę IQ usługi Foundry tak, aby korzystała z tożsamości zarządzanej przypisanej przez system lub przypisanej przez użytkownika jako podmiotu zabezpieczeń usługi IQ usługi Foundry w dzierżawie Microsoft Entra. Po utworzeniu tożsamości zarządzanej można przypisać role do autoryzowanego dostępu. Tożsamości zarządzane i przypisania ról eliminują konieczność przekazywania danych tajnych i poświadczeń w parametry połączenia lub kodzie.

Wymagania wstępne

  • Usługa Foundry IQ w dowolnym regionie w warstwie Podstawowej lub wyższej.

  • Zasób Azure, który akceptuje żądania przychodzące od podmiotu zabezpieczeń Microsoft Entra, który ma prawidłowe przypisanie roli.

  • Aby utworzyć tożsamość zarządzaną, musisz być właścicielem lub administratorem dostępu użytkowników. Aby przypisać role, musisz być właścicielem, administratorem dostępu użytkowników, administratorem kontroli dostępu opartego na rolach lub członkiem roli niestandardowej z uprawnieniami Microsoft.Authorization/roleAssignments/write.

Obsługiwane scenariusze

W następujących scenariuszach można użyć tożsamości zarządzanych.

Scenariusz Przypisane przez system Przypisany użytkownik
Łączenie ze źródłami danych indeksatora1 Tak Tak
Połącz się z modelami osadzania i uzupełniania czatów w programie Azure OpenAI, Microsoft Foundry i Azure Functions za pośrednictwem umiejętności/wektoryzatorów 2 Tak Tak
Nawiązywanie połączenia z Azure Key Vault dla kluczy zarządzanych przez klienta Tak Tak
Nawiązywanie połączenia z sesjami debugowania (hostowane w Azure Storage)1 Tak Nie
Nawiązywanie połączenia z pamięcią podręczną wzbogacania hostowaną w Azure Storage (wersja zapoznawcza)1,3 Tak Tak 4
Nawiązywanie połączenia z magazynem wiedzy (hostowanym w Azure Storage)1 Tak Tak

1 W przypadku łączności między protokołem IQ i magazynem rozwiązania Foundry zabezpieczenia sieci nakładają ograniczenia dotyczące typu tożsamości zarządzanej, której można użyć. Tylko zarządzana systemowo tożsamość może być używana do połączenia w tym samym regionie do Azure Storage, a takie połączenie musi być za pośrednictwem wyjątku zaufanej usługi lub reguły wystąpienia zasobu. Aby uzyskać szczegółowe informacje, zobacz Dostęp do konta magazynu chronionego przez sieć .

2 Połączenia z Azure OpenAI, Foundry i Azure Functions za pośrednictwem umiejętności/wektoryzatorów obejmują: umiejętności niestandardowe, wektoryzator niestandardowy, umiejętność osadzania Azure OpenAI, wektoryzator Azure OpenAI, umiejętności AML i wektoryzator katalogu modeli Microsoft Foundry.

3 Usługa IQ usługi Foundry nie może obecnie łączyć się z tabelami na koncie magazynu, które ma wyłączony dostęp do klucza współużytkowanego.

4 Tożsamość zarządzana przypisana przez użytkownika na potrzeby połączeń pamięci podręcznej wzbogacania wymaga wersji zapoznawczej interfejsu API REST (2025-11-01-preview lub nowszego) lub pakietu zestawu SDK w wersji zapoznawczej. Wszystkie inne scenariusze tożsamości zarządzanej przypisanej przez użytkownika w tej tabeli są obsługiwane w interfejsie API REST w wersji 2026-04-01 i nowszych.

Utwórz tożsamość zarządzaną przez system

Tożsamość zarządzana przypisana przez system to podmiot zabezpieczeń w Microsoft Entra ID, który jest automatycznie tworzony i połączony z zasobem Azure, takim jak usługa Foundry IQ.

Dla każdej usługi Foundry IQ można mieć jedną tożsamość zarządzaną przypisaną przez system. Jest ona unikatowa dla usługi Foundry IQ i powiązana z usługą przez cały okres istnienia.

Po włączeniu tożsamości zarządzanej przypisanej przez system Microsoft Entra ID tworzy podmiot zabezpieczeń dla usługi Foundry IQ, który jest używany do uwierzytelniania w innych zasobach Azure. Następnie możesz użyć tej tożsamości w przypisaniach ról w celu uzyskania autoryzowanego dostępu do danych i operacji.

  1. Przejdź do usługi Foundry IQ w portalu Azure.

  2. W okienku po lewej stronie wybierz pozycję Ustawienia>Tożsamość.

  3. Na karcie Przypisane przez system w obszarze Stan wybierz pozycję Włączone.

  4. Wybierz pozycję Zapisz.

    Zrzut ekranu przedstawiający stronę Tożsamość w portalu Azure.

    Po zapisaniu ustawień strona zostanie zaktualizowana w celu wyświetlenia identyfikatora obiektu przypisanego do usługi IQ usługi Foundry.

    Zrzut ekranu przedstawiający identyfikator obiektu tożsamości systemu.

Tworzenie tożsamości zarządzanej przypisanej przez użytkownika

Tożsamość zarządzana przypisana przez użytkownika to zasób Azure, który można ograniczyć do subskrypcji, grup zasobów lub typów zasobów.

Możesz utworzyć wiele tożsamości zarządzanych przypisanych przez użytkownika, aby uzyskać większą szczegółowość w przypisywaniu ról. Na przykład możesz chcieć użyć oddzielnych tożsamości dla różnych aplikacji i scenariuszy. Jako niezależnie utworzony i zarządzany zasób nie jest powiązany z samą usługą.

Kroki konfigurowania tożsamości zarządzanej przypisanej przez użytkownika są następujące:

  • W ramach subskrypcji Azure utwórz tożsamość zarządzaną przypisaną przez użytkownika.

  • W usłudze Foundry IQ skojarz tożsamość zarządzaną przypisaną przez użytkownika z usługą Foundry IQ.

  • W innych usługach Azure, z którymi chcesz nawiązać połączenie, utwórz przypisanie roli dla tożsamości.

Kojarzenie tożsamości zarządzanej przypisanej przez użytkownika z usługą IQ rozwiązania Foundry jest obsługiwane w portalu Azure, interfejsach API REST zarządzania wyszukiwaniem i pakietach zestawu SDK, które udostępniają tę funkcję.

  1. Zaloguj się do portalu Azure.

  2. W lewym górnym rogu pulpitu nawigacyjnego wybierz pozycję Utwórz zasób.

  3. Użyj pola wyszukiwania, aby znaleźć tożsamość zarządzaną przypisaną przez użytkownika, a następnie wybierz pozycję Utwórz.

    Zrzut ekranu przedstawiający kafelek tożsamości zarządzanej przypisanej przez użytkownika w Azure Marketplace.

  4. Wybierz subskrypcję, grupę zasobów i region. Nadaj tożsamości nazwę opisową.

  5. Wybierz pozycję Utwórz i poczekaj na zakończenie wdrażania zasobu.

    Zanim będzie można użyć tożsamości, może upłynąć kilka minut.

  6. Na stronie usługi Foundry IQ wybierz pozycję Ustawienia>Tożsamość.

  7. Na karcie Przypisane przez użytkownika wybierz Dodaj.

  8. Wybierz subskrypcję i wcześniej utworzoną tożsamość zarządzaną przypisaną przez użytkownika.

Przypisywanie roli

Po utworzeniu tożsamości zarządzanej przypisz role, które określają uprawnienia usługi Foundry IQ na zasobie Azure.

W przypadku bezpośredniego połączenia z modelem Azure OpenAI przypisz rolę Cognitive Services OpenAI User do przypisanej przez system lub przypisanej przez użytkownika tożsamości wybranej przez usługę Foundry IQ. Określ zakres przypisania do zasobu Azure OpenAI lub Microsoft Foundry, który hostuje wdrożenie i odpowiada resourceUri. W przypadku projektu Foundry użyj zasobu nadrzędnego, a nie obiektu projektu, usługi IQ usługi Foundry, indeksu, źródła wiedzy, bazy wiedzy lub nazwy wdrożenia.

Value Purpose
Podmiot zabezpieczeń tożsamości zarządzanej/identyfikator obiektu Identyfikuje adresata przypisania roli.
identyfikator klienta Identyfikuje tożsamość aplikacji. Nie jest to zakres przypisania roli ani wartość authIdentity.userAssignedIdentity.
Identyfikator zasobu tożsamości przypisanej przez użytkownika Wybiera dołączoną tożsamość zarządzaną w obsługiwanej konfiguracji wyszukiwania authIdentity. Nie jest to zakres zasobów modelu.
Identyfikator zasobu hostingu modelu Ustawia zakres przypisania roli. Identyfikuje nadrzędny zasób Azure OpenAI lub Foundry.
Nazwa wdrożenia i nazwa hosta punktu końcowego Zidentyfikuj wdrożenie modelu i miejsce docelowe połączenia, a nie adresata przypisania roli.

Ta sama reguła zakresu ma zastosowanie, gdy obsługiwany punkt końcowy modelu używa openai.azure.com, services.ai.azure.com lub cognitiveservices.azure.com. W przypadku usługi API Management, która weryfikuje uwierzytelnianie wyszukiwania i używa własnej tożsamości zaplecza, przypisz rolę modelu do tożsamości zaplecza bramy. Autoryzuj wyszukiwanie w bramie oddzielnie. Zobacz Uwierzytelnianie typu wyszukiwanie-brama.

  • Uprawnienia do odczytu są wymagane w przypadku połączeń danych indeksatora i uzyskiwania dostępu do klucza zarządzanego przez klienta w Azure Key Vault.

  • Uprawnienia do zapisu są niezbędne dla funkcji wzbogacania AI, które wykorzystują Azure Storage do hostowania danych sesji debugowania, buforowania procesów wzbogacania i długoterminowego przechowywania zawartości w magazynie wiedzy.

Poniższe kroki ilustrują przepływ pracy przypisywania ról. Ten przykład dotyczy Azure OpenAI. W przypadku innych zasobów Azure zobacz Połączenie z Azure StoragePołączenie z Azure Cosmos DB lub Połączenie z Azure SQL.

  1. Przejdź do zasobu hostowania modelu Azure OpenAI lub zasobu nadrzędnego projektu Foundry w portalu Azure.

  2. Wybierz pozycję Kontrola dostępu z menu po lewej stronie.

  3. Wybierz pozycję Dodaj , a następnie wybierz pozycję Dodaj przypisanie roli.

  4. W obszarze Role funkcji zadania wybierz pozycję Użytkownik usług Cognitive Services OpenAI, a następnie wybierz pozycję Dalej.

  5. W obszarze Członkowie wybierz pozycję Tożsamość zarządzana , a następnie wybierz pozycję Członkowie.

  6. Filtruj według subskrypcji i typu zasobu (usługi IQ rozwiązania Foundry), a następnie wybierz tożsamość zarządzaną usługi IQ usługi Foundry.

  7. Wybierz pozycję Przejrzyj i przypisz.

Propagacja przypisania roli i łączność sieciowa są oddzielone od wyboru tożsamości. W przypadku błędu 401 lub 403 potwierdź wybrany zakres tożsamości i hostingu modelu przed udzieleniem szerszego dostępu. Wyłączenie uwierzytelniania klucza lokalnego nie powoduje usunięcia potrzeby prawidłowej tożsamości, ról i trasy sieciowej.

Prawidłowa tożsamość i przypisanie roli nie uniemożliwiają wygaśnięcia buforowanego tokenu źródłowego podczas długiego działania indeksatora. Aby uzyskać informacje na temat zachowania odświeżania wstępnego i tymczasowych środków zaradczych, zobacz Token tożsamości zarządzanej wygasa podczas przebiegu.

Przykłady parametrów połączenia

Jak pamiętasz z opisu scenariuszy, można użyć tożsamości zarządzanych w parametrach połączenia do innych zasobów Azure. Ta sekcja zawiera przykłady.

Połączenia tożsamości zarządzanej przypisane przez system używają ogólnie dostępnych wersji interfejsu API REST. Połączenia tożsamości zarządzanej przypisane przez użytkownika używają interfejsu API REST w wersji 2026-04-01 lub nowszej, z wyjątkiem połączeń pamięci podręcznej wzbogacania, które nadal wymagają wersji zapoznawczej interfejsu API.

Wskazówka

Większość tych obiektów można utworzyć w portalu Azure, określając tożsamość zarządzaną przypisaną przez użytkownika lub systemową, a następnie wyświetlić definicję JSON, aby uzyskać parametry połączenia.

Źródło danych obiektu blob (tożsamość zarządzana przez system):

Źródło danych indeksatora zawiera credentials właściwość, która określa sposób nawiązywania połączenia ze źródłem danych. W poniższym przykładzie przedstawiono łańcuch połączenia określający unikatowy identyfikator zasobu konta magazynowego.

Tożsamość zarządzana systemu jest wskazywana, gdy parametry połączenia jest unikatowym identyfikatorem zasobu usługi lub aplikacji obsługującej Microsoft Entra ID. Tożsamość zarządzana przypisana przez użytkownika jest określana za pośrednictwem właściwości identity.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Źródło danych obiektu blob (tożsamość zarządzana przez użytkownika):

Tożsamość zarządzana przypisana przez użytkownika jest obsługiwana poprzez właściwość identity w SearchIndexerDataSource z użyciem REST API w wersji 2026-04-01 lub nowszej.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Magazyn wiedzy (tożsamość zarządzana przez system):

Definicja magazynu wiedzy zawiera ciąg połączenia do Azure Storage. Ciąg połączenia jest unikatowym identyfikatorem zasobu konta magazynowania. Zwróć uwagę, że ciąg nie zawiera kontenerów ani tabel w ścieżce. Są one zdefiniowane w definicji projekcji osadzonej, a nie w parametry połączenia.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Magazyn wiedzy (tożsamość zarządzana przez użytkownika):

Tożsamość zarządzana przypisana przez użytkownika jest obsługiwana za pośrednictwem właściwości w identity, korzystając z interfejsu API REST w wersji 2026-04-01 lub nowszej.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};",
  "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }
}

Pamięć podręczna wzbogacania (wersja zapoznawcza):

Indeksator tworzy, używa i zapamiętuje kontener używany do buforowanych modyfikacji danych. Nie jest konieczne dołączenie kontenera do stringu połączenia pamięci podręcznej. Identyfikator obiektu można znaleźć na stronie Tożsamość usługi IQ rozwiązania Foundry w portalu Azure.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Sesja debugowania:

Sesja debugowania uruchamia się w portalu Azure i przyjmuje ciąg połączenia podczas rozpoczęcia sesji. Możesz wkleić ciąg podobny do poniższego przykładu.

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Umiejętność niestandardowa:

Niestandardowa umiejętność jest przeznaczona dla punktu końcowego funkcji Azure lub aplikacji obsługującej kod niestandardowy.

  • uri to punkt końcowy funkcji lub aplikacji.

  • authResourceId informuje usługę IQ usługi Foundry w celu nawiązania połączenia przy użyciu tożsamości zarządzanej, przekazując identyfikator aplikacji funkcji docelowej lub aplikacji we właściwości .

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Przykłady połączeń dla modeli

W przypadku połączeń nawiązywanych przy użyciu tożsamości zarządzanych w tej sekcji przedstawiono przykłady informacji o połączeniach używanych przez usługę Foundry IQ do nawiązywania połączenia z modelem na innym zasobie. Połączenie za pośrednictwem tożsamości zarządzanej systemu jest przezroczyste; tożsamość i role są na miejscu, a połączenie powiedzie się, jeśli zostały prawidłowo skonfigurowane. Z kolei tożsamość zarządzana przez użytkownika wymaga dodatkowych właściwości połączenia.

umiejętność osadzania Azure OpenAI i wektoryzator Azure OpenAI:

Umiejętność osadzania i wektoryzator Foundry IQ (Wyszukiwanie AI platformy Azure) są przeznaczone dla punktu końcowego usługi Azure OpenAI hostującej model osadzania. Punkt końcowy jest określony w definicji umiejętności osadzania Azure OpenAI i/lub w definicji wektoryzatora Azure OpenAI.

Tożsamość zarządzana przez system jest używana automatycznie, jeśli "apikey" i "authIdentity" jest pusta, jak pokazano w poniższym przykładzie. Właściwość "authIdentity" jest używana tylko dla tożsamości zarządzanej przypisanej przez użytkownika.

Przykład tożsamości zarządzanej przez system:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Oto przykład wektoryzatora skonfigurowany dla tożsamości zarządzanej przypisanej przez system. Wektoryzator jest określony w indeksie wyszukiwania.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

Przykład tożsamości zarządzanej przypisanej przez użytkownika:

Tożsamość zarządzana przypisana przez użytkownika jest używana, jeśli "apiKey" jest pusta i podano prawidłową "authIdentity" wartość.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

Oto przykład wektoryzatora skonfigurowany dla tożsamości zarządzanej przypisanej przez użytkownika. Wektoryzator jest określony w indeksie wyszukiwania.

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

Sprawdzanie dostępu do zapory

Jeśli zasób Azure znajduje się za zaporą, upewnij się, że istnieje reguła ruchu przychodzącego, która zezwala na żądania z usługi Foundry IQ i z portalu Azure.

Zobacz też