Konfigurace vyhledávací služby pro připojení pomocí spravované identity ve službě Azure AI Search

Článek
11/22/2024

Důležité

Přiřazení spravované identity přiřazené uživatelem je ve verzi Public Preview v rámci dodatečných podmínek použití. Rozhraní REST API pro správu ve verzi Preview poskytuje přiřazení spravované identity přiřazené uživatelem pro Azure AI Search. Podpora spravované identity přiřazené systémem je obecně dostupná.

Pro odchozí připojení z Azure AI Search můžete použít id a přiřazení rolí Microsoft Entra k prostředkům poskytujícím data, použitou AI nebo vektorizaci během indexování nebo dotazů.

Pokud chcete použít role pro odchozí připojení, nejprve nakonfigurujte vyhledávací službu tak, aby jako objekt zabezpečení pro vaši vyhledávací službu v tenantovi Microsoft Entra používala spravovanou identitu přiřazenou systémem nebo přiřazenou uživatelem. Jakmile máte spravovanou identitu, můžete přiřadit role pro autorizovaný přístup. Spravované identity a přiřazení rolí eliminují potřebu předávání tajných kódů a přihlašovacích údajů v připojovací řetězec nebo kódu.

Požadavky

Vyhledávací služba na úrovni Basic nebo vyšší, kterákoli oblast.
Prostředek Azure, který přijímá příchozí požadavky z objektu zabezpečení Microsoft Entra, který má platné přiřazení role.

Podporované scénáře

Azure AI Search se může připojit k jiným prostředkům Azure v rámci přiřazené systému nebo spravované identity přiřazené uživatelem.

Search konfigurace spravované identity přiřazené systémem je obecně dostupná.
Search konfigurace spravované identity přiřazené uživatelem je ve verzi Public Preview v rámci doplňkových podmínek použití.
Obecně dostupné je využití roviny dat spravované identity bez ohledu na to, jestli je systém nebo přiřazený uživatelem. Pokud například chcete spravovanou identitu přiřazenou uživatelem v připojení ke zdroji dat indexeru, trezoru klíčů, ladicí relaci nebo mezipaměti rozšíření, můžete k vytvoření připojení použít obecně dostupnou verzi rozhraní REST API za předpokladu, že je funkce, kterou používáte, obecně dostupná.

Spravovaná identita systému se označuje, když připojovací řetězec je jedinečné ID prostředku služby nebo aplikace pracující s ID Microsoft Entra. Spravovaná identita přiřazená uživatelem se zadává prostřednictvím vlastnosti identity.

Vyhledávací služba používá Azure Storage jako zdroj dat indexeru a jako jímku dat pro ladicí relace, ukládání do mezipaměti rozšiřování a úložiště znalostí. Pro funkce vyhledávání, které se zapisuje zpět do úložiště, potřebuje spravovaná identita přiřazení role přispěvatele, jak je popsáno v části Přiřazení role .

Scénář	Systémový	Přiřazeno uživatelem
Připojení indexeru k podporovaným zdrojům ^{dat Azure 1}	Ano	Yes
Azure Key Vault pro klíče spravované zákazníkem	Ano	Yes
Ladicí relace (hostované ve službě Azure Storage)¹	Yes	No
Mezipaměť rozšiřování (hostovaná ve službě Azure Storage) 1,^²	Ano	Yes
Knowledge Store (hostované ve službě Azure Storage) ¹	Ano	Yes
Připojení k Azure OpenAI, Azure AI Foundry a Azure Functions prostřednictvím dovedností/vektorizátorů ³	Ano	Yes

¹ Pro připojení mezi vyhledáváním a úložištěm konfigurace zabezpečení sítě omezuje, jaký typ spravované identity můžete použít. K připojení k úložišti prostřednictvím výjimky důvěryhodné služby nebo pravidla instance prostředku je možné použít pouze identitu spravovanou systémem. Podrobnosti najdete v tématu Přístup k účtu úložiště chráněnému sítí.

² Vyhledávací služba AI se momentálně nemůže připojit k tabulkám v účtu úložiště, který má vypnutý přístup ke sdíleným klíčům.

³ Připojení k Azure OpenAI, Azure AI Foundry a Azure Functions prostřednictvím dovedností a vektorizátorů zahrnují: vlastní dovednosti, vlastní vektorizátor, dovednosti azure OpenAI pro vkládání, vektorizátor Azure OpenAI, dovednosti AML a vektorizátor katalogu modelů Azure AI Foundry.

Vytvoření spravované identity systému

Když povolíte spravovanou identitu přiřazenou systémem, Vytvoří ID Microsoft Entra identitu pro vaši vyhledávací službu, která se dá použít k ověření v jiných službách Azure ve stejném tenantovi. Tuto identitu pak můžete použít v přiřazení rolí pro přístup k datům a modelům.

Spravovaná identita přiřazená systémem je jedinečná pro vaši vyhledávací službu a je svázaná se službou po celou dobu jejího života. Vyhledávací služba může mít pouze jednu spravovanou identitu přiřazenou systémem.

Přihlaste se k webu Azure Portal a vyhledejte vyhledávací službu.
V části Nastavení vyberte Identita.
Na kartě Přiřazený systém v části Stav vyberte Zapnuto.
Zvolte Uložit.

Po uložení nastavení se stránka aktualizuje tak, aby zobrazovala identifikátor objektu, který je přiřazen k vaší vyhledávací službě.

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

Další informace najdete v tématu Vytvoření vyhledávací služby se spravovanou identitou přiřazenou systémem (Azure PowerShell.

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

Další informace najdete v tématu Vytvoření vyhledávací služby se spravovanou identitou přiřazenou systémem (Azure CLI).

Formulujte žádost o vytvoření nebo aktualizaci vyhledávací služby.

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

V odpovědi se vrátí potvrzení a identifikátor objektu pro spravovanou identitu systému.

Další informace naleznete v tématu Vytvoření nebo aktualizace služby (Management REST API).

Vytvoření spravované identity přiřazené uživatelem

Důležité

Část tohoto scénáře je ve verzi Public Preview v rámci dodatečných podmínek použití. Rozhraní REST API pro správu ve verzi Preview poskytuje konfiguraci spravované identity přiřazené uživatelem pro Azure AI Search.

Spravovaná identita přiřazená uživatelem je prostředek v Azure. Pokud chcete mít v přiřazeních rolí větší členitost, můžete vytvořit několik spravovaných identit přiřazených uživatelem. Můžete například chtít samostatné identity pro různé aplikace a scénáře.

Postup:

Ve svém předplatném Azure vytvořte spravovanou identitu přiřazenou uživatelem.
Ve vyhledávací službě aktualizujte definici služby, aby se povolila spravovaná identita přiřazená uživatelem (tento krok je ve verzi Preview).
V jiných službách Azure, ke které se chcete připojit, vytvořte přiřazení role pro identitu.
V připojeních ke zdrojům dat ve službě Azure AI Search, jako je zdroj dat indexeru, odkazujte na identitu spravovanou uživatelem v podrobnostech o připojení (tento krok je obecně dostupný, pokud je podpora této funkce obecně dostupná).

Spravovanou identitu přiřazenou uživatelem je možné nastavit na předplatná, skupiny prostředků nebo typy prostředků.

Přidružení spravované identity přiřazené uživatelem se podporuje na webu Azure Portal, ve verzích Preview rozhraní REST API pro správu a v beta balíčcích sady SDK, které tuto funkci poskytují.

Azure Portal
REST API

Přihlaste se k portálu Azure Portal.
Vyberte Vytvořit prostředek.
Na panelu hledání "Search s a marketplace" vyhledejte spravovanou identitu přiřazenou uživatelem a pak vyberte Vytvořit.
Vyberte předplatné, skupinu prostředků a oblast. Zadejte popisný název identity.
Vyberte Vytvořit a počkejte na dokončení nasazení prostředku.

Než budete moct identitu použít, trvá to několik minut.
Na stránce vyhledávací služby v části Nastavení vyberte Identita.
Na kartě Přiřazený uživatel vyberte Přidat.
Zvolte předplatné a pak vyberte spravovaný prostředek přiřazený uživatelem, který jste vytvořili v předchozím kroku.

K přiřazení spravované identity přiřazené uživatelem můžete místo webu Azure Portal použít rozhraní REST API služby Preview Management. Použijte verze 2021-04-01-preview rozhraní API nebo novější. Tento příklad používá 2024-06-01-preview.

Formulujte požadavek na aktualizaci vyhledávací služby.

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]": {}
    }
  }
}

Nastavte vlastnost identity tak, aby určila plně kvalifikovanou spravovanou identitu:
- "type" je typ identity. Platné hodnoty jsou SystemAssigned, UserAssigned nebo SystemAssigned, UserAssigned, UserAssigned pro oba. Hodnota None vymaže všechny dříve přiřazené identity z vyhledávací služby.
- "userAssignedIdentities" obsahuje podrobnosti o spravované identitě přiřazené uživatelem. Tato identita už musí existovat , než ji můžete zadat v žádosti o službu aktualizace.

Přiřaďte roli

Jakmile máte spravovanou identitu, přiřaďte role, které určují oprávnění vyhledávací služby k prostředku Azure.

Oprávnění ke čtení jsou potřebná pro datová připojení indexeru a pro přístup ke klíči spravovanému zákazníkem ve službě Azure Key Vault.
Oprávnění k zápisu jsou potřebná pro funkce rozšiřování AI, které používají Azure Storage k hostování dat relace ladění, ukládání do mezipaměti rozšiřování a dlouhodobého úložiště obsahu v úložišti znalostí.

Následující kroky znázorňují pracovní postup přiřazení role. Tento příklad je určený pro Azure OpenAI. Další prostředky Azure najdete v tématu Připojení ke službě Azure Storage, Připojení ke službě Azure Cosmos DB nebo Připojení k Azure SQL.

Přihlaste se k webu Azure Portal pomocí svého účtu Azure a přejděte k prostředku Azure OpenAI.
V nabídce vlevo vyberte Řízení přístupu.
Vyberte Přidat a pak vyberte Přidat přiřazení role.
V části Role funkce úlohy vyberte Uživatele OpenAI služeb Cognitive Services a pak vyberte Další.
V části Členové vyberte Spravovanou identitu a pak vyberte Členové.
Vyfiltrujte podle předplatného a typu prostředku (Search) a pak vyberte spravovanou identitu vyhledávací služby.
Vyberte Zkontrolovat + přiřadit.

Příklady připojovacích řetězců

Po definování spravované identity pro vyhledávací službu a přiřazení role je možné odchozí připojení upravit tak, aby používala jedinečné ID prostředku druhého prostředku Azure. Tady je několik příkladů připojovací řetězec pro různé scénáře.

Pro tato připojení můžete použít obecně dostupné verze rozhraní REST API a balíčky sady Azure SDK.

Tip

Většinu těchto objektů můžete vytvořit na webu Azure Portal, zadat spravovanou identitu přiřazenou systémem nebo uživatelem a pak zobrazit definici JSON, abyste získali připojovací řetězec.

Zdroj dat objektů blob (systém):

Zdroj dat indexeru obsahuje vlastnost "credentials", která určuje způsob vytvoření připojení ke zdroji dat. Následující příklad ukazuje připojovací řetězec určení jedinečného ID prostředku účtu úložiště.

Id Microsoft Entra ověřuje požadavek pomocí systémové spravované identity vyhledávací služby. Všimněte si, že připojovací řetězec neobsahuje kontejner. V definici zdroje dat je název kontejneru zadán ve vlastnosti "kontejner" (není zobrazeno), nikoli v připojovací řetězec.

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

Zdroj dat objektu blob (uživatel):

Žádost o vyhledávání ve službě Azure Storage je také možné provést v rámci spravované identity přiřazené uživatelem. Identita uživatele vyhledávací služby je zadána ve vlastnosti "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}"
  }

Úložiště znalostí:

Definice úložiště znalostí zahrnuje připojovací řetězec do služby Azure Storage. Připojovací řetězec je jedinečné ID prostředku vašeho účtu úložiště. Všimněte si, že řetězec v cestě neobsahuje kontejnery ani tabulky. Ty jsou definovány v definici vložené projekce, nikoli v připojovací řetězec.

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

Mezipaměť rozšiřování:

Indexer vytvoří, použije a pamatuje kontejner použitý pro rozšiřování v mezipaměti. Kontejner není nutné zahrnout do připojovací řetězec mezipaměti. ID objektu najdete na stránce Identita vaší vyhledávací služby na webu Azure Portal.

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

Ladicí relace:

Ladicí relace se spustí na webu Azure Portal a při spuštění relace vezme připojovací řetězec. Můžete vložit řetězec podobný následujícímu příkladu.

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

Vlastní dovednost:

Vlastní dovednost cílí na koncový bod funkce Azure nebo aplikace hostující vlastní kód.

uri je koncový bod funkce nebo aplikace.
authResourceId říká vyhledávací službě, aby se připojila pomocí spravované identity a předala ID aplikace cílové funkce nebo aplikace ve vlastnosti.

{
  "@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": [ ...]
}

Dovednosti vkládání Azure OpenAI a vektorizátor Azure OpenAI:

Dovednost a vektorizátor vkládání Azure OpenAI do služby AI Search cílí na koncový bod služby Azure OpenAI hostující model vkládání. Koncový bod se zadává v definici dovednosti azure OpenAI pro vkládání a/nebo v definici vektorizátoru Azure OpenAI.

Identita spravovaná systémem se používá automaticky, pokud "apikey" jsou prázdná "authIdentity" , jak je znázorněno v následujícím příkladu. Vlastnost "authIdentity" se používá pouze pro spravovanou identitu přiřazenou uživatelem.

Příklad identity spravované systémem:

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

Tady je příklad vektorizátoru nakonfigurovaný pro spravovanou identitu přiřazenou systémem. Vektorizátor je určen v indexu vyhledávání.

 "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"
      }
    }
  ]

Příklad spravované identity přiřazené uživatelem:

Spravovaná identita přiřazená uživatelem se používá, pokud "apiKey" je prázdná a je zadána platná "authIdentity" .

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

Tady je příklad vektorizátoru nakonfigurovaný pro spravovanou identitu přiřazenou uživatelem. Vektorizátor je určen v indexu vyhledávání.

 "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>"
          }
      }
    }
  ]

Kontrola přístupu k bráně firewall

Pokud je váš prostředek Azure za bránou firewall, ujistěte se, že existuje příchozí pravidlo, které přijímá požadavky z vaší vyhledávací služby a z webu Azure Portal.

Pro připojení stejné oblasti ke službě Azure Blob Storage nebo Azure Data Lake Storage Gen2 použijte identitu spravovanou systémem a výjimku důvěryhodné služby. Volitelně můžete nakonfigurovat pravidlo instance prostředku tak, aby přijímalo požadavky.
Pro všechny ostatní prostředky a připojení nakonfigurujte pravidlo brány firewall protokolu IP, které přijímá požadavky ze služby Azure AI Search. Podrobnosti najdete v tématu Přístup k obsahu chráněnému funkcemi zabezpečení sítě Azure.

Sdílet prostřednictvím