Konfigurieren eines Suchdiensts zum Herstellen einer Verbindung mit einer verwalteten Identität in Azure KI-Suche

Artikel
11/22/2024

Wichtig

Die Zuweisung einer benutzerseitig zugewiesenen verwalteten Identität befindet sich unter zusätzlichen Nutzungsbedingungen in der öffentlichen Vorschau. Die Verwaltungsvorschau-REST-API stellt die Zuweisung einer benutzerseitig zugewiesenen verwalteten Identität für Azure KI-Suche bereit. Unterstützung für eine systemseitig zugewiesene verwaltete Identität ist allgemein verfügbar.

Sie können Microsoft Entra-ID und Rollenzuweisungen für ausgehende Verbindungen von Azure KI-Suche mit Ressourcen verwenden, die Daten, angewendete KI oder Vektorisierung während der Indizierung oder für Abfragen bereitstellen.

Um Rollen für eine ausgehende Verbindung zu verwenden, konfigurieren Sie zuerst Ihren Suchdienst so, dass eine systemseitig zugewiesene oder benutzerseitig zugewiesene verwaltete Identität als Sicherheitsprinzipal für Ihren Suchdienst in einem Microsoft Entra-Mandanten verwendet wird. Sobald Sie über eine verwaltete Identität verfügen, können Sie Rollen für autorisierten Zugriff zuweisen. Verwaltete Identitäten und Rollenzuweisungen machen die Übergabe von Geheimnissen und Anmeldeinformationen in einer Verbindungszeichenfolge oder Code überflüssig.

Voraussetzungen

Ein Suchdienst auf der Basic-Dienstebene oder höher in einer beliebigen Region.
Eine Azure-Ressource, die eingehende Anforderungen von einem Microsoft Entra-Sicherheitsprinzipal mit einer gültigen Rollenzuweisung akzeptiert.

Unterstützte Szenarios

Azure KI-Suche kann eine Verbindung mit anderen Azure-Ressourcen unter der systemseitig zugewiesenen oder einer benutzerseitig zugewiesenen verwalteten Identität herstellen.

Die Suchdienstkonfiguration einer systemseitig zugewiesenen verwalteten Identität ist allgemein verfügbar.
Die Suchdienstkonfiguration einer benutzerseitig zugewiesenen verwalteten Identitäten befindet sich unter zusätzlichen Nutzungsbedingungen in der öffentlichen Vorschau.
Die Datenebenennutzung einer verwalteten Identität, egal ob system- oder benutzerseitig zugewiesen, ist allgemein verfügbar. Wenn Sie z. B. eine benutzerseitig zugewiesene verwaltete Identität für eine Verbindung mit einer Indexerdatenquelle, einen Schlüsseltresor, eine Debugsitzung oder einen Anreicherungscache verwenden möchten, können Sie eine allgemein verfügbare REST-API-Version verwenden, um die Verbindung zu erstellen, vorausgesetzt, das verwendete Feature ist auch allgemein verfügbar.

Eine systemseitig verwaltete Identität wird angegeben, wenn eine Verbindungszeichenfolge die eindeutige Ressourcen-ID eines Microsoft Entra ID-fähigen Diensts oder einer Microsoft Entra ID-fähigen Anwendung ist. Eine vom Benutzer zugewiesene verwaltete Identität wird mithilfe einer Eigenschaft „identity“ angegeben.

Ein Suchdienst verwendet Azure Storage als Datenquelle für den Indexer und als Datensenke für Debugsitzungen, die Anreicherungsspeicherung und den Wissensspeicher. Für Suchfeatures, die in den Speicher zurückschreiben, benötigt die verwaltete Identität die Zuweisung einer „Mitwirkender“-Rolle, wie im Abschnitt Zuweisen einer Rolle beschrieben.

Szenario	System	Benutzerseitig zugewiesen
Indexerverbindungen mit unterstützten Azure-Datenquellen ¹	Ja	Ja
Azure Key Vault für kundenseitig verwalteten Schlüssel	Ja	Ja
Debugsitzungen (in Azure Storage gehostet)¹	Ja	No
Anreicherungscache (in Azure Storage gehostet) ¹, ²	Ja	Ja
Wissensspeicher (in Azure Storage gehostet) ¹	Ja	Ja
Verbindungen mit Azure OpenAI, Azure KI Foundry und Azure Functions über Skills/Vektorisierer ³	Ja	Ja

¹ Für die Konnektivität zwischen Suche und Speicher legt Ihre Netzwerksicherheitskonfiguration Einschränkungen fest, welche Art von verwalteter Identität Sie verwenden können. Nur eine systemseitig verwaltete Identität kann für eine Verbindung mit Speicher in derselben Region über die Ausnahme für vertrauenswürdige Dienste oder die Ressourceninstanzregel verwendet werden. Ausführliche Informationen finden Sie unter Zugriff auf ein netzwerkgeschütztes Speicherkonto.

² Der Suchdienst kann derzeit keine Verbindung mit Tabellen in einem Speicherkonto herstellen, für das der Zugriff per gemeinsam verwendetem Schlüssel deaktiviert ist.

³ Verbindungen mit Azure OpenAI, Azure KI Foundry und Azure Functions über Skills/Vektorisierer umfassen Folgendes: Benutzerdefinierte Skills, Benutzerdefinierte Vektorisierer, Azure OpenAI-Einbettungsskills, Azure OpenAI-Vektorisierer, AML-Skill und Azure KI Foundry-Modellkatalogvektorisierer.

Erstellen einer vom System verwalteten Identität

Wenn Sie eine systemseitig zugewiesene verwaltete Identität aktivieren, wird in Microsoft Entra ID eine Identität für den Suchdienst erstellt, die für die Authentifizierung bei anderen Azure-Diensten innerhalb desselben Mandanten verwendet werden kann. Sie können diese Identität dann in Rollenzuweisungen für den Zugriff auf Daten und Modelle verwenden.

Eine vom System zugewiesene verwaltete Identität ist für Ihren Suchdienst eindeutig und für ihre Lebensdauer an den Dienst gebunden. Ein Suchdienst kann nur über eine systemseitig zugewiesene verwaltete Identität verfügen.

Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Wählen Sie unter Einstellungen Identität aus:
Wählen Sie auf der Registerkarte Systemseitig zugewiesen unter Status die Option Ein aus.
Wählen Sie Speichern.

Nachdem Sie die Einstellungen gespeichert haben, wird die Seite aktualisiert und zeigt einen Objektbezeichner an, der Ihrem Suchdienst zugewiesen ist.

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

Weitere Informationen finden Sie unter Erstellen eines Suchdiensts mit einer systemseitig zugewiesenen verwalteten Identität (Azure PowerShell).

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

Weitere Informationen finden Sie unter Erstellen eines Suchdiensts mit einer systemseitig zugewiesenen verwalteten Identität (Azure CLI).

Formulieren Sie eine Anforderung zum Erstellen oder Aktualisieren eines Suchdiensts.

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

Die Bestätigung und ein Objektbezeichner für die vom System verwaltete Identität werden in der Antwort zurückgegeben.

Weitere Informationen finden Sie unter Erstellen oder Aktualisieren eines Diensts (Verwaltungs-REST-API).

Erstellen einer benutzerseitig zugewiesenen verwalteten Identität

Wichtig

Ein Teil dieses Szenarios befindet sich unter zusätzlichen Nutzungsbedingungen in der öffentlichen Vorschau. Die Verwaltungsvorschau-REST-API stellt die Konfiguration für eine benutzerseitig zugewiesene verwaltete Identität für Azure KI-Suche bereit.

Eine benutzerseitig verwaltete Identität ist eine Azure-Ressource. Sie können mehrere benutzerseitig zugewiesene verwaltete Identitäten erstellen, wenn Sie mehr Granularität bei Rollenzuweisungen wünschen. Sie könnten beispielsweise separate Identitäten für verschiedene Anwendungen und Szenarien verwenden.

Schritte:

Erstellen Sie in Ihrem Azure-Abonnement eine benutzerseitig zugewiesene verwaltete Identität.
Aktualisieren Sie im Suchdienst die Dienstdefinition, um die benutzerseitig zugewiesene verwaltete Identität zu aktivieren (dieser Schritt befindet sich in der Vorschau).
Erstellen Sie in anderen Azure-Diensten, mit denen Sie eine Verbindung herstellen möchten, eine Rollenzuweisung für die Identität.
Verweisen Sie in Datenquellenverbindungen in Azure KI-Suche, z. B. in einer Indexerdatenquelle, in den Verbindungsdetails auf die benutzerseitig verwaltete Identität (dieser Schritt ist allgemein verfügbar, wenn die Unterstützung für das Feature allgemein verfügbar ist).

Eine benutzerseitig zugewiesene verwaltete Identität kann auf Abonnements, Ressourcengruppen oder Ressourcentypen festgelegt werden.

Das Zuordnen einer benutzerseitig zugewiesenen verwalteten Identität wird im Azure-Portal, in Vorschauversionen der Verwaltungs-REST-APIs und in Beta-SDK-Paketen unterstützt, die das Feature bereitstellen.

Azure portal
REST-API

Melden Sie sich beim Azure-Portal
Wählen Sie Ressource erstellen.
Suchen Sie in der Suchleiste „Dienste und Marketplace durchsuchen“ nach „Benutzerseitig zugewiesene verwaltete Identität“, und wählen Sie dann Erstellen aus.
Wählen Sie das Abonnement, die Ressourcengruppe und die Region an. Geben Sie einen beschreibenden Namen für die Identität ein.
Wählen Sie Erstellen aus, und warten Sie, bis die Bereitstellung der Ressource abgeschlossen ist.

Es dauert mehrere Minuten, bis Sie die Identität verwenden können.
Wählen Sie auf ihrer Suchdienstseite unter Einstellungen Identität aus.
Wählen Sie auf der Registerkarte Benutzerseitig zugewiesen die Option Hinzufügen aus.
Wählen Sie das Abonnement und dann die vom Benutzer zugewiesene verwaltete Ressource aus, die Sie im vorherigen Schritt erstellt haben.

Sie können eine Vorschauversion der Verwaltungs-REST-API anstelle des Azure-Portals verwenden, um eine benutzerseitig zugewiesene verwaltete Identität zuzuweisen. Verwenden Sie API-Versionen 2021-04-01-preview oder höher. In diesem Beispiel wird 2024-06-01-preview verwendet.

Formulieren Sie eine Anforderung zum AKTUALISIEREN eines Suchdiensts.

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

Legen Sie die Eigenschaft „identity“ fest, um eine vollqualifizierte verwaltete Identität anzugeben:
- „type“ ist der Typ der Identität. Gültige Werte sind „SystemAssigned“, „UserAssigned“ oder „SystemAssigned, UserAssigned“ für beide. Der Wert „None“ löscht alle zuvor zugewiesenen Identitäten aus dem Suchdienst.
- „userAssignedIdentities“ enthält die Details der benutzerseitig zugewiesenen verwalteten Identität. Diese Identität muss bereits vorhanden sein, damit Sie sie in der Anforderung „Dienst aktualisieren“ angeben können.

Zuweisen einer Rolle

Sobald Sie über eine verwaltete Identität verfügen, weisen Sie Rollen zu, die Suchdienstberechtigungen für die Azure-Ressource bestimmen.

Leseberechtigungen sind für Indexerdatenverbindungen und für den Zugriff auf einen vom Kunden verwalteten Schlüssel in Azure Key Vault erforderlich.
Schreibberechtigungen sind für KI-Anreicherungsfeatures erforderlich, die Azure Storage zum Hosten von Debugsitzungsdaten, Zwischenspeichern von Anreicherungen und für die langfristige Inhaltsspeicherung in einem Wissensspeicher verwenden.

Der Workflow der Rollenzuweisung wird in den folgenden Schritten veranschaulicht. Dieses Beispiel gilt für Azure OpenAI. Weitere Azure-Ressourcen finden Sie unter Verbinden mit Azure Storage, Verbinden mit Azure Cosmos DB oder Verbinden mit Azure SQL.

Melden Sie sich mit Ihrem Azure-Konto beim Azure-Portal an und wechseln Sie zu Ihrer Azure OpenAI-Ressource.
Wählen Sie im linken Menü Zugriffssteuerung aus.
Wählen Sie Hinzufügen und dann Rollenzuweisung hinzufügen aus.
Wählen Sie unter Auftragsfunktionsrolle die Option Cognitive Services OpenAI-Benutzer und dann Weiter aus.
Wählen Sie unter Mitglieder die Option Verwaltete Identität und dann Mitglieder aus.
Filtern Sie nach Abonnement und Ressourcentyp (Suchdienste), und wählen Sie dann die verwaltete Identität Ihres Suchdiensts aus.
Wählen Sie Überprüfen und zuweisen aus.

Beispiele für Verbindungszeichenfolgen

Sobald eine verwaltete Identität für den Suchdienst definiert und eine Rollenzuweisung erteilt wurde, können ausgehende Verbindungen geändert werden, um die eindeutige Ressourcen-ID der anderen Azure-Ressource zu verwenden. Hier sehen Sie einige Beispiele für Verbindungszeichenfolgen für verschiedene Szenarien.

Sie können allgemein verfügbare REST-API-Versionen und Azure SDK-Pakete für diese Verbindungen verwenden.

Tipp

Sie können die meisten dieser Objekte im Azure-Portal erstellen. Geben Sie dafür eine system- oder benutzerseitig zugewiesene verwaltete Identität an, und zeigen Sie dann die JSON-Definition an, um die Verbindungszeichenfolge abzurufen.

Blobdatenquelle (System):

Eine Indexerdatenquelle enthält eine „Credentials“-Eigenschaft, die bestimmt, wie die Verbindung mit der Datenquelle hergestellt wird. Das folgende Beispiel zeigt eine Verbindungszeichenfolge, die die eindeutige Ressourcen-ID eines Speicherkontos angibt.

Microsoft Entra ID authentifiziert die Anforderung mithilfe der systemseitig verwalteten Identität des Suchdiensts. Beachten Sie, dass die Verbindungszeichenfolge keinen Container beinhaltet. In einer Datenquellendefinition wird ein Containername in der Eigenschaft „container“ (nicht dargestellt) angegeben statt in der Verbindungszeichenfolge.

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

Blob-Datenquelle (Benutzer):

Eine Suchanforderung an Azure Storage kann auch unter einer benutzerseitig zugewiesenen verwalteten Identität vorgenommen werden. Die Benutzeridentität des Suchdiensts wird in der Eigenschaft „identity“ angegeben.

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

Wissensspeicher:

Eine Wissensspeicherdefinition beinhaltet eine Verbindungszeichenfolge zum Azure Storage. Die Verbindungszeichenfolge ist die eindeutige Ressourcen-ID Ihres Speicherkontos. Beachten Sie, dass die Zeichenfolge keine Container oder Tabellen im Pfad enthält. Diese werden in der eingebetteten Projektionsdefinition definiert, nicht in der Verbindungszeichenfolge.

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

Anreicherungscache:

Ein Indexer erstellt, verwendet und speichert den Container, der für die zwischengespeicherten Anreicherungen verwendet wird. Es ist nicht erforderlich, den Container in die Cacheverbindungszeichenfolge einzufügen. Sie finden die Objekt-ID im Azure-Portal auf der Seite Identität Ihres Suchdiensts.

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

Debugsitzung:

Eine Debugsitzung wird im Azure-Portal ausgeführt und nimmt eine Verbindungszeichenfolge an, wenn Sie die Sitzung starten. Sie können eine Verbindungszeichenfolge wie im folgenden Beispiel einfügen:

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

Benutzerdefinierter Skill:

Ein benutzerdefinierter Skill ist auf den Endpunkt einer Azure-Funktion oder -App ausgerichtet, die benutzerdefinierten Code hostet.

uri ist der Endpunkt der Funktion oder App.
authResourceId weist den Suchdienst an, eine Verbindung mithilfe einer verwalteten Identität herzustellen. Dabei wird die Anwendungs-ID der Zielfunktion oder -App in der Eigenschaft übergeben.

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

Azure OpenAI-Einbettungsskill und Azure OpenAI-Vektorisierung:

Ein Azure OpenAI-Einbettungsskill und -Vektorisierung in der KI-Suche zielen auf den Endpunkt eines Azure OpenAI-Dienstes, der ein Einbettungsmodell hostet. Der Endpunkt wird in der Azure OpenAI-Einbettungsskilldefinition und/oder in der Azure OpenAI-Vektorisierungsdefinition angegeben.

Die vom System verwaltete Identität wird automatisch verwendet, wenn "apikey" und "authIdentity" leer sind, wie im folgenden Beispiel gezeigt. Die Eigenschaft "authIdentity" wird nur für die benutzerseitig zugewiesene verwaltete Identität verwendet.

Beispiel zu einer systemseitig verwalteten Identität:

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

Dies ist ein Vektorisierungsbeispiel, das für eine systemseitig zugewiesene verwaltete Identität konfiguriert ist. Eine Vektorisierung wird in einem Suchindex angegeben.

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

Beispiel zu einer benutzerseitig zugewiesenen verwalteten Identität:

Eine benutzerseitig zugewiesene verwaltete Identität wird verwendet, wenn "apiKey" leer ist und ein gültiger Wert für "authIdentity" bereitgestellt wird.

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

Dies ist ein Vektorisierungsbeispiel, das für eine benutzerseitig zugewiesene verwaltete Identität konfiguriert ist. Eine Vektorisierung wird in einem Suchindex angegeben.

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

Überprüfen des Firewallzugriffs

Wenn sich Ihre Azure-Ressource hinter einer Firewall befindet, achten Sie darauf, dass eine Eingangsregel vorhanden ist, die Anforderungen von Ihrem Suchdienst und vom Azure-Portal zulässt.

Verwenden Sie für Verbindungen in derselben Region mit Azure Blob Storage oder Azure Data Lake Storage Gen2 eine systemseitig zugewiesene verwaltete Identität und die Ausnahme für vertrauenswürdige Dienste. Optional können Sie eine Ressourceninstanzregel konfigurieren, um Anforderungen zuzulassen.
Konfigurieren Sie für alle anderen Ressourcen und Verbindungen eine IP-Firewallregel, die Anforderungen von Azure KI-Suche zulässt. Weitere Informationen dazu finden Sie unter Indexerzugriff auf mit Azure-Netzwerksicherheitsfeatures geschützten Inhalt.

Freigeben über