Konfigurowanie usługi wyszukiwania w celu nawiązania połączenia przy użyciu tożsamości zarządzanej w usłudze Azure AI Search

Artykuł
09/11/2024

Ważne

Przypisanie tożsamości zarządzanej przypisanej przez użytkownika jest w publicznej wersji zapoznawczej w obszarze Dodatkowe warunki użytkowania. Interfejs API REST zarządzania w wersji zapoznawczej udostępnia przypisanie tożsamości zarządzanej przypisanej przez użytkownika dla usługi Azure AI Search. Obsługa tożsamości zarządzanej przypisanej przez system jest ogólnie dostępna.

Możesz użyć identyfikatora entra firmy Microsoft i przypisań ról dla połączeń wychodzących z usługi Azure AI Search do zasobów dostarczających dane, zastosowanej sztucznej inteligencji lub wektoryzacji podczas indeksowania lub zapytań.

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

Wymagania wstępne

Usługa wyszukiwania w warstwie Podstawowa lub nowsza w dowolnym regionie.
Zasób platformy Azure, który akceptuje żądania przychodzące od podmiotu zabezpieczeń firmy Microsoft Entra, który ma prawidłowe przypisanie roli.

Obsługiwane scenariusze

Usługa Azure AI Search może łączyć się z innymi zasobami platformy Azure w ramach przypisanej przez system lub tożsamości zarządzanej przypisanej przez użytkownika.

usługa wyszukiwania konfiguracja tożsamości zarządzanej przypisanej przez system jest ogólnie dostępna.
usługa wyszukiwania konfiguracja tożsamości zarządzanej przypisanej przez użytkownika jest dostępna w publicznej wersji zapoznawczej w ramach dodatkowych warunków użytkowania.
Użycie płaszczyzny danych tożsamości zarządzanej, niezależnie od tego, czy system, czy przypisany przez użytkownika, jest ogólnie dostępne. Jeśli na przykład chcesz, aby tożsamość zarządzana przypisana przez użytkownika w połączeniu ze źródłem danych indeksatora, magazynie kluczy, sesji debugowania lub pamięci podręcznej wzbogacania można użyć ogólnie dostępnej wersji interfejsu API REST, aby utworzyć połączenie, zakładając, że używana funkcja jest również ogólnie dostępna.

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

Usługa wyszukiwania używa usługi Azure Storage jako źródła danych indeksatora i jako ujścia danych na potrzeby sesji debugowania, buforowania wzbogacania i magazynu wiedzy. W przypadku funkcji wyszukiwania, które zapisują z powrotem do magazynu, tożsamość zarządzana wymaga przypisania roli współautora zgodnie z opisem w sekcji "Przypisywanie roli".

Scenariusz	System	Przypisane przez użytkownika
Połączenia indeksatora z obsługiwanymi źródłami ^{danych platformy Azure 1}	Tak	Tak
Usługa Azure Key Vault dla kluczy zarządzanych przez klienta	Tak	Tak
Sesje debugowania (hostowane w usłudze Azure Storage)¹	Tak	Nie.
Pamięć podręczna wzbogacania (hostowana w usłudze Azure Storage) 1,^²	Tak	Tak
Magazyn wiedzy (hostowany w usłudze Azure Storage) ¹	Tak	Tak
Połączenia z usługami Azure OpenAI, Azure AI Studio i Azure Functions za pośrednictwem umiejętności/wektoryzatorów ³	Tak	Tak

¹ W przypadku łączności między wyszukiwaniem i magazynem konfiguracja zabezpieczeń sieci nakłada ograniczenia dotyczące typu tożsamości zarządzanej, której można użyć. Tylko tożsamość zarządzana systemu może służyć do połączenia z magazynem w tym samym regionie za pośrednictwem reguły wystąpienia zaufanej usługi lub wyjątku usługi. Aby uzyskać szczegółowe informacje, zobacz Dostęp do konta magazynu chronionego przez sieć.

² Usługa wyszukiwania sztucznej inteligencji nie może obecnie łączyć się z tabelami na koncie magazynu, które ma wyłączony dostęp do klucza współużytkowanego.

³ Połączenia z usługami Azure OpenAI, Azure AI Studio i Azure Functions za pośrednictwem umiejętności/wektoryzatorów obejmują: umiejętności niestandardowe, wektoryzator niestandardowy, umiejętności osadzania usługi Azure OpenAI, wektoryzator usługi Azure OpenAI, umiejętności AML i wektoryzator katalogu modeli usługi Azure AI Studio.

Tworzenie tożsamości zarządzanej systemu

Po włączeniu tożsamości zarządzanej przypisanej przez system identyfikator Entra firmy Microsoft tworzy tożsamość usługi wyszukiwania, która może służyć do uwierzytelniania w innych usługach platformy Azure w ramach tej samej dzierżawy. Następnie możesz użyć tej tożsamości w przypisaniach ról do uzyskiwania dostępu do danych i modeli.

Tożsamość zarządzana przypisana przez system jest unikatowa dla usługi wyszukiwania i powiązana z usługą przez jej okres istnienia. Usługa wyszukiwania może mieć tylko jedną tożsamość zarządzaną przypisaną przez system.

Zaloguj się do witryny Azure Portal i znajdź usługę wyszukiwania.
W obszarze Ustawienia wybierz pozycję Tożsamość.
Na karcie Przypisane przez system w obszarze Stan wybierz pozycję Włączone.
Wybierz pozycję Zapisz.

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

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

Aby uzyskać więcej informacji, zobacz Tworzenie usługi wyszukiwania z przypisaną przez system tożsamością zarządzaną (Azure PowerShell).

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

Aby uzyskać więcej informacji, zobacz Tworzenie usługi wyszukiwania przy użyciu tożsamości zarządzanej przypisanej przez system (interfejs wiersza polecenia platformy Azure).

Sformułuj żądanie tworzenia lub aktualizowania usługi wyszukiwania.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Potwierdzenie i identyfikator obiektu tożsamości zarządzanej systemu jest zwracany w odpowiedzi.

Aby uzyskać więcej informacji, zobacz Tworzenie lub aktualizowanie usługi (interfejs API REST zarządzania).

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

Ważne

Część tego scenariusza jest dostępna w publicznej wersji zapoznawczej w obszarze Dodatkowe warunki użytkowania. Interfejs API REST zarządzania w wersji zapoznawczej udostępnia konfigurację tożsamości zarządzanej przypisanej przez użytkownika dla usługi Azure AI Search.

Tożsamość zarządzana przypisana przez użytkownika jest zasobem na platformie Azure. Możesz utworzyć wiele tożsamości zarządzanych przypisanych przez użytkownika, jeśli chcesz uzyskać większą szczegółowość przypisań ról. Na przykład możesz chcieć użyć oddzielnych tożsamości dla różnych aplikacji i scenariuszy.

Kroki są następujące:

W ramach subskrypcji platformy Azure utwórz tożsamość zarządzaną przypisaną przez użytkownika.
W usłudze wyszukiwania zaktualizuj definicję usługi, aby włączyć tożsamość zarządzaną przypisaną przez użytkownika (ten krok jest w wersji zapoznawczej).
W innych usługach platformy Azure, z którymi chcesz nawiązać połączenie, utwórz przypisanie roli dla tożsamości.
W przypadku połączeń ze źródłem danych w usłudze Azure AI Search, takich jak źródło danych indeksatora, należy odwołać się do tożsamości zarządzanej przez użytkownika w szczegółach połączenia (ten krok jest ogólnie dostępny, jeśli obsługa funkcji jest ogólnie dostępna).

Tożsamość zarządzana przypisana przez użytkownika może być ograniczona do subskrypcji, grup zasobów lub typów zasobów.

Kojarzenie tożsamości zarządzanej przypisanej przez użytkownika jest obsługiwane w witrynie Azure Portal, w wersjach zapoznawczych interfejsów API REST zarządzania oraz w pakietach zestawu SDK w wersji beta, które udostępniają tę funkcję.

Witryna Azure Portal
Interfejs API REST

Zaloguj się do witryny Azure Portal.
Wybierz pozycję Utwórz zasób.
Na pasku wyszukiwania "usługa wyszukiwania s and marketplace" wyszukaj pozycję "Tożsamość zarządzana przypisana przez użytkownika", a następnie wybierz pozycję Utwórz.
Wybierz subskrypcję, grupę zasobów i region. Nadaj tożsamości nazwę opisową.
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.
Na stronie usługi wyszukiwania w obszarze Ustawienia wybierz pozycję Tożsamość.
Na karcie Przypisane przez użytkownika wybierz pozycję Dodaj.
Wybierz subskrypcję, a następnie wybierz zasób zarządzany przypisany przez użytkownika utworzony w poprzednim kroku.

Aby przypisać tożsamość zarządzaną przypisaną przez użytkownika, możesz użyć interfejsu API REST zarządzania w wersji zapoznawczej zamiast portalu. Użyj wersji interfejsu 2021-04-01-preview API lub nowszych. W tym przykładzie użyto wartości 2024-06-01-preview.

Sformułuj żądanie aktualizacji usługi wyszukiwania.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2024-06-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Ustaw właściwość "identity", aby określić w pełni kwalifikowaną tożsamość zarządzaną:
- "type" to typ tożsamości. Prawidłowe wartości to "SystemAssigned", "UserAssigned" lub "SystemAssigned, UserAssigned" dla obu tych elementów. Wartość "Brak" czyści wszystkie wcześniej przypisane tożsamości z usługi wyszukiwania.
- Element "userAssignedIdentities" zawiera szczegóły tożsamości zarządzanej przypisanej przez użytkownika. Ta tożsamość musi już istnieć , zanim będzie można ją określić w żądaniu usługi aktualizacji.

Przypisywanie roli

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

Uprawnienia do odczytu są wymagane w przypadku połączeń danych indeksatora i uzyskiwania dostępu do klucza zarządzanego przez klienta w usłudze Azure Key Vault.
Uprawnienia do zapisu są wymagane w przypadku funkcji wzbogacania sztucznej inteligencji, które używają usługi Azure Storage do hostowania danych sesji debugowania, buforowania wzbogacania i długoterminowego przechowywania zawartości w magazynie wiedzy.

Poniższe kroki ilustrują przepływ pracy przypisywania ról. Ten przykład dotyczy usługi Azure OpenAI. Aby uzyskać informacje o innych zasobach platformy Azure, zobacz Nawiązywanie połączenia z usługą Azure Storage, Nawiązywanie połączenia z usługą Azure Cosmos DB lub Nawiązywanie połączenia z usługą Azure SQL.

Zaloguj się do witryny Azure Portal przy użyciu konta platformy Azure i przejdź do zasobu Azure OpenAI.
Wybierz pozycję Kontrola dostępu z menu po lewej stronie.
Wybierz pozycję Dodaj , a następnie wybierz pozycję Dodaj przypisanie roli.
W obszarze Role funkcji zadania wybierz pozycję Użytkownik openAI usług Cognitive Services, a następnie wybierz pozycję Dalej.
W obszarze Członkowie wybierz pozycję Tożsamość zarządzana, a następnie wybierz pozycję Członkowie.
Filtruj według subskrypcji i typu zasobu (usługa wyszukiwania), a następnie wybierz tożsamość zarządzaną usługi wyszukiwania.
Wybierz Przejrzyj + przypisz.

Przykłady parametrów połączenia

Po zdefiniowaniu tożsamości zarządzanej dla usługi wyszukiwania i przypisaniu roli można zmodyfikować połączenia wychodzące w celu użycia unikatowego identyfikatora zasobu innego zasobu platformy Azure. Oto kilka przykładów parametry połączenia dla różnych scenariuszy.

Dla tych połączeń można używać ogólnie dostępnych wersji interfejsu API REST i pakietów zestawu Azure SDK.

Napiwek

Większość tych obiektów można utworzyć w witrynie Azure Portal, 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 (system):

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

Microsoft Entra ID uwierzytelnia żądanie przy użyciu tożsamości zarządzanej przez system usługi wyszukiwania. Zwróć uwagę, że parametry połączenia nie zawiera kontenera. W definicji źródła danych nazwa kontenera jest określona we właściwości "container" (nie pokazano), a nie w parametry połączenia.

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

Źródło danych obiektu blob (użytkownik):

Żądanie wyszukiwania w usłudze Azure Storage można również wykonać w ramach tożsamości zarządzanej przypisanej przez użytkownika. Tożsamość użytkownika usługi wyszukiwania jest określona we właściwości "identity".

"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:

Definicja magazynu wiedzy zawiera parametry połączenia do usługi Azure Storage. Parametry połączenia jest unikatowym identyfikatorem zasobu konta magazynu. 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};"
}

Pamięć podręczna wzbogacania:

Indeksator tworzy, używa i zapamiętuje kontener używany do buforowanych wzbogacenia. Nie jest konieczne dołączenie kontenera do parametry połączenia pamięci podręcznej. Identyfikator obiektu można znaleźć na stronie Tożsamość usługi wyszukiwania w portalu.

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

Sesja debugowania:

Sesja debugowania jest uruchamiana w portalu i pobiera parametry połączenia po rozpoczęciu 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 platformy Azure lub aplikacji obsługującej kod niestandardowy. Punkt końcowy jest określony w niestandardowej definicji umiejętności. Obecność identyfikatora "authResourceId" informuje usługę wyszukiwania o nawiązaniu 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": [ ...]
}

Umiejętności osadzania usługi Azure OpenAI i wektoryzator azure OpenAI:

Umiejętność osadzania i wektoryzatora usługi Azure OpenAI w usłudze AI Search jest przeznaczona dla punktu końcowego usługi Azure OpenAI obsługującej model osadzania. Punkt końcowy jest określony w definicji umiejętności osadzania usługi Azure OpenAI i/lub w definicji wektoryzatora usługi Azure OpenAI. Tożsamość zarządzana przez system jest używana, jeśli jest skonfigurowana, a wartość "apikey" i "authIdentity" jest pusta. 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"
    }
  ]
}

 "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:

{
  "@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>"
   }
}

 "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 platformy Azure znajduje się za zaporą, upewnij się, że istnieje reguła ruchu przychodzącego, która przyznaje żądania z usługi wyszukiwania.

W przypadku połączeń w tym samym regionie z usługą Azure Blob Storage lub Azure Data Lake Storage Gen2 użyj tożsamości zarządzanej systemu i zaufanego wyjątku usługi. Opcjonalnie możesz skonfigurować regułę wystąpienia zasobu, aby przyznać żądania.
W przypadku wszystkich innych zasobów i połączeń skonfiguruj regułę zapory ip, która przyznaje żądania z usługi Search. Aby uzyskać szczegółowe informacje, zobacz Indeksator dostępu do zawartości chronionej przez funkcje zabezpieczeń sieci platformy Azure.

Udostępnij za pośrednictwem