Konfigurera nyckellös autentisering med Microsoft Entra-ID

Viktigt!

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Modeller som distribueras till Azure AI-modellinferens i Azure AI Services stöder nyckellös auktorisering med Hjälp av Microsoft Entra-ID. Nyckellös auktorisering förbättrar säkerheten, förenklar användarupplevelsen, minskar driftkomplexiteten och ger robust efterlevnadsstöd för modern utveckling. Det gör det till ett starkt val för organisationer som använder säkra och skalbara identitetshanteringslösningar.

Den här artikeln beskriver hur du konfigurerar Microsoft Entra-ID för slutsatsdragning i Azure AI-modellinferens.

Förstå roller i resurskontexten i Azure

Microsoft Entra ID använder idén om rollbaserad åtkomstkontroll (RBAC) för auktorisering. Roller är centrala för att hantera åtkomsten till dina molnresurser. En roll är i princip en samling behörigheter som definierar vilka åtgärder som kan utföras på specifika Azure-resurser. Genom att tilldela roller till användare, grupper, tjänstens huvudnamn eller hanterade identiteter – gemensamt kallade säkerhetsobjekt – kontrollerar du deras åtkomst i Din Azure-miljö till specifika resurser.

När du tilldelar en roll anger du säkerhetsobjektet, rolldefinitionen och omfånget. Den här kombinationen kallas för en rolltilldelning. Azure AI-modellinferens är en funktion för Azure AI Services-resurserna och därför kontrollerar roller som tilldelats den specifika resursen åtkomsten för slutsatsdragning.

Du identifierar två olika typer av åtkomst till resurserna:

• Administrationsåtkomst: De åtgärder som är relaterade till administrationen av resursen. De ändrar vanligtvis tillståndet för resursen och dess konfiguration. I Azure är dessa åtgärder kontrollplansåtgärder och kan köras med hjälp av Azure Portal, Azure CLI eller med infrastruktur som kod. Exempel på är att skapa en ny modelldistribution, ändra konfigurationer för innehållsfiltrering, ändra versionen av modellen som hanteras eller ändra SKU:n för en distribution.

• Utvecklaråtkomst: De åtgärder som är relaterade till förbrukningen av resurserna. Till exempel att anropa API:et för chattens slutförande. Användaren kan dock inte ändra tillståndet för resursen och dess konfiguration.

I Azure utförs alltid administrationsåtgärder med Hjälp av Microsoft Entra-ID. Med roller som Cognitive Services-deltagare kan du utföra dessa åtgärder. Å andra sidan kan utvecklaråtgärder utföras med antingen åtkomstnycklar eller/och Microsoft Entra-ID. Med roller som Cognitive Services-användare kan du utföra dessa åtgärder.

Viktigt!

Att ha administrationsåtkomst till en resurs ger inte nödvändigtvis utvecklaren åtkomst till den. Explicit åtkomst genom att bevilja roller krävs fortfarande. Det motsvarar hur databasservrar fungerar. Att ha administratörsåtkomst till databasservern innebär inte att du kan läsa data i en databas.

Följ de här stegen för att konfigurera utvecklaråtkomst till Azure AI-modellinferens i Azure AI Services-resursen.

Förutsättningar

För att slutföra den här artikeln behöver du:

• En Azure-prenumeration Om du använder GitHub-modeller kan du uppgradera din upplevelse och skapa en Azure-prenumeration i processen. Läs Uppgradera från GitHub-modeller till Azure AI-modellinferens om så är fallet.

• En Azure AI-tjänstresurs. Mer information finns i Skapa en Azure AI Services-resurs.

• Ett konto med Microsoft.Authorization/roleAssignments/write och Microsoft.Authorization/roleAssignments/delete behörigheter, till exempel rollbaserad åtkomstkontroll för administratör .

• Om du vill tilldela en roll måste du ange tre element:

  • Säkerhetsobjekt: t.ex. ditt användarkonto.
  • Rolldefinition: Cognitive Services-användarrollen.
  • Omfång: Azure AI Services-resursen.

Konfigurera Microsoft Entra-ID för slutsatsdragning

Följ dessa steg för att konfigurera Microsoft Entra-ID för slutsatsdragning:

1. Gå till Azure Portal och leta upp den Azure AI Services-resurs som du använder. Om du använder Azure AI Foundry med projekt eller hubbar kan du navigera till det genom att:

   1. Gå till Azure AI Foundry-portalen.

   2. På landningssidan väljer du Öppna hanteringscenter.

   3. Gå till avsnittet Anslutna resurser och välj anslutningen till den Azure AI Services-resurs som du vill konfigurera. Om den inte visas väljer du Visa alla för att se den fullständiga listan.

   4. I avsnittet Anslutningsinformation går du till Resurs och väljer namnet på Azure-resursen. En ny sida öppnas.

   5. Nu är du i Azure Portal där du kan hantera alla aspekter av själva resursen.

2. Välj Åtkomstkontroll (IAM) i det vänstra navigeringsfältet.

   Dricks

   Använd alternativet Visa min åtkomst för att kontrollera vilka roller som redan har tilldelats dig.

3. Välj Rolltilldelningar och välj sedan Lägg till lägg till>rolltilldelning.

4. I Jobbfunktionsroller skriver du Cognitive Services-användare. Listan över roller filtreras bort.

5. Välj rollen och välj Nästa.

6. På Medlemmar väljer du den användare eller grupp som du vill bevilja åtkomst till. Vi rekommenderar att du använder säkerhetsgrupper när det är möjligt eftersom de är enklare att hantera och underhålla.

7. Välj Nästa och slutför guiden.

8. Den valda användaren kan nu använda Microsoft Entra-ID för slutsatsdragning.

   Dricks

   Tänk på att Azure-rolltilldelningar kan ta upp till fem minuter att sprida. När du arbetar med säkerhetsgrupper sprids omedelbart tillägg eller borttagning av användare från säkerhetsgruppen.

Observera att nyckelbaserad åtkomst fortfarande är möjlig för användare som redan har tillgängliga nycklar. Om du vill återkalla nycklarna går du till Azure Portal i det vänstra navigeringsfönstret och väljer Resurshanteringsnycklar>>och Slutpunkter Återskapa Key1 och Återskapa nyckel2.

Använda Microsoft Entra-ID i koden

När du har konfigurerat Microsoft Entra-ID i resursen måste du uppdatera koden så att den används när slutpunkten för slutsatsdragning används. I följande exempel visas hur du använder en modell för chattavslut:

Python

Installera paketet azure-ai-inference med hjälp av pakethanteraren, till exempel pip:

pip install azure-ai-inference>=1.0.0b5

Varning

Azure AI Services-resursen kräver versionen azure-ai-inference>=1.0.0b5 för Python.

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
    model="mistral-large-2407",
)

JavaScript

Installera paketet @azure-rest/ai-inference med npm:

npm install @azure-rest/ai-inference

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    "mistral-large-2407",
    clientOptions,
);

C#

Installera Azure AI-slutsatsdragningsbiblioteket med följande kommando:

dotnet add package Azure.AI.Inference --prerelease

Azure.Identity Installera paketet:

dotnet add package Azure.Identity

Importera följande namnområden:

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

var credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    "mistral-large-2407",
    clientOptions.
);

Java

Lägg till paketet i projektet:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar:

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .model("mistral-large-2407")
    .buildClient();

Utforska våra exempel och läs API-referensdokumentationen för att komma igång.

REST

Använd referensavsnittet för att utforska API-designen och vilka parametrar som är tillgängliga och ange autentiseringstoken i rubriken Authorization. Referensavsnittet för chattavslut beskriver till exempel hur du använder vägen /chat/completions för att generera förutsägelser baserat på chattformaterade instruktioner. Observera att sökvägen /models ingår i URL:ens rot:

Begär

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

Token måste utfärdas med omfånget https://cognitiveservices.azure.com/.default.

I testsyfte är det enklaste sättet att få en giltig token för ditt användarkonto att använda Azure CLI. Kör följande Azure CLI-kommando i en konsol:

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Alternativ för autentiseringsuppgifter när du använder Microsoft Entra-ID

DefaultAzureCredential är en åsiktsbaserad, ordnad sekvens av mekanismer för autentisering till Microsoft Entra-ID. Varje autentiseringsmekanism är en klass som härleds från TokenCredential klassen och kallas för autentiseringsuppgifter. Vid körning DefaultAzureCredential försöker autentisera med hjälp av den första autentiseringsuppgiften. Om det inte går att hämta en åtkomsttoken görs nästa autentiseringsuppgifter i sekvensen och så vidare tills en åtkomsttoken har hämtats. På så sätt kan din app använda olika autentiseringsuppgifter i olika miljöer utan att skriva miljöspecifik kod.

När föregående kod körs på din lokala utvecklingsarbetsstation letar den i miljövariablerna efter ett huvudnamn för programtjänsten eller lokalt installerade utvecklarverktyg, till exempel Visual Studio, för en uppsättning autentiseringsuppgifter för utvecklare. Endera metoden kan användas för att autentisera appen till Azure-resurser under lokal utveckling.

När den distribueras till Azure kan samma kod även autentisera din app till andra Azure-resurser. DefaultAzureCredential kan hämta miljöinställningar och hanterade identitetskonfigurationer för att autentisera till andra tjänster automatiskt.

Bästa praxis

• Använd deterministiska autentiseringsuppgifter i produktionsmiljöer: Överväg starkt att flytta från DefaultAzureCredential till någon av följande deterministiska lösningar i produktionsmiljöer:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se listan Härledd för alternativ.
  • En avskalad implementering optimerad för Azure-miljön ChainedTokenCredential där appen körs. ChainedTokenCredential skapar i princip en specifik lista över godtagbara alternativ för autentiseringsuppgifter, till exempel ManagedIdentity för produktion och VisualStudioCredential utveckling.

• Konfigurera systemtilldelade eller användartilldelade hanterade identiteter till de Azure-resurser där koden körs om möjligt. Konfigurera Microsoft Entra ID-åtkomst till dessa specifika identiteter.

Använda Microsoft Entra-ID i projektet

Även om din resurs har Konfigurerat Microsoft Entra-ID kan dina projekt fortfarande använda nycklar för att använda förutsägelser från resursen. När du använder Azure AI Foundry Playground används de autentiseringsuppgifter som är associerade med den anslutning som projektet har.

Om du vill ändra det här beteendet måste du uppdatera anslutningarna från dina projekt för att använda Microsoft Entra-ID. Följ de här stegen:

1. Gå till Azure AI Foundry-portalen.

2. Navigera till de projekt eller hubbar som använder Azure AI Services-resursen via en anslutning.

3. Välj Hanteringscenter.

4. Gå till avsnittet Anslutna resurser och välj anslutningen till den Azure AI Services-resurs som du vill konfigurera. Om den inte visas väljer du Visa alla för att se den fullständiga listan.

5. Välj redigeringsikonen bredvid Åtkomstinformation i avsnittet Anslutningsinformation.

6. Under Autentisering ändrar du värdet till Microsoft Entra-ID.

7. Välj Uppdatera.

8. Anslutningen är konfigurerad för att fungera med Microsoft Entra-ID nu.

Inaktivera nyckelbaserad autentisering i resursen

Det rekommenderas att du inaktiverar nyckelbaserad autentisering när du implementerade Microsoft Entra-ID och fullständigt åtgärdade kompatibilitets- eller reservproblem i alla program som använder tjänsten.

Viktigt!

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Modeller som distribueras till Azure AI-modellinferens i Azure AI Services stöder nyckellös auktorisering med Hjälp av Microsoft Entra-ID. Nyckellös auktorisering förbättrar säkerheten, förenklar användarupplevelsen, minskar driftkomplexiteten och ger robust efterlevnadsstöd för modern utveckling. Det gör det till ett starkt val för organisationer som använder säkra och skalbara identitetshanteringslösningar.

Den här artikeln beskriver hur du konfigurerar Microsoft Entra-ID för slutsatsdragning i Azure AI-modellinferens.

Förstå roller i resurskontexten i Azure

Microsoft Entra ID använder idén om rollbaserad åtkomstkontroll (RBAC) för auktorisering. Roller är centrala för att hantera åtkomsten till dina molnresurser. En roll är i princip en samling behörigheter som definierar vilka åtgärder som kan utföras på specifika Azure-resurser. Genom att tilldela roller till användare, grupper, tjänstens huvudnamn eller hanterade identiteter – gemensamt kallade säkerhetsobjekt – kontrollerar du deras åtkomst i Din Azure-miljö till specifika resurser.

När du tilldelar en roll anger du säkerhetsobjektet, rolldefinitionen och omfånget. Den här kombinationen kallas för en rolltilldelning. Azure AI-modellinferens är en funktion för Azure AI Services-resurserna och därför kontrollerar roller som tilldelats den specifika resursen åtkomsten för slutsatsdragning.

Du identifierar två olika typer av åtkomst till resurserna:

• Administrationsåtkomst: De åtgärder som är relaterade till administrationen av resursen. De ändrar vanligtvis tillståndet för resursen och dess konfiguration. I Azure är dessa åtgärder kontrollplansåtgärder och kan köras med hjälp av Azure Portal, Azure CLI eller med infrastruktur som kod. Exempel på är att skapa en ny modelldistribution, ändra konfigurationer för innehållsfiltrering, ändra versionen av modellen som hanteras eller ändra SKU:n för en distribution.

• Utvecklaråtkomst: De åtgärder som är relaterade till förbrukningen av resurserna. Till exempel att anropa API:et för chattens slutförande. Användaren kan dock inte ändra tillståndet för resursen och dess konfiguration.

I Azure utförs alltid administrationsåtgärder med Hjälp av Microsoft Entra-ID. Med roller som Cognitive Services-deltagare kan du utföra dessa åtgärder. Å andra sidan kan utvecklaråtgärder utföras med antingen åtkomstnycklar eller/och Microsoft Entra-ID. Med roller som Cognitive Services-användare kan du utföra dessa åtgärder.

Viktigt!

Att ha administrationsåtkomst till en resurs ger inte nödvändigtvis utvecklaren åtkomst till den. Explicit åtkomst genom att bevilja roller krävs fortfarande. Det motsvarar hur databasservrar fungerar. Att ha administratörsåtkomst till databasservern innebär inte att du kan läsa data i en databas.

Följ de här stegen för att konfigurera utvecklaråtkomst till Azure AI-modellinferens i Azure AI Services-resursen.

Förutsättningar

För att slutföra den här artikeln behöver du:

• En Azure-prenumeration Om du använder GitHub-modeller kan du uppgradera din upplevelse och skapa en Azure-prenumeration i processen. Läs Uppgradera från GitHub-modeller till Azure AI-modellinferens om så är fallet.

• En Azure AI-tjänstresurs. Mer information finns i Skapa en Azure AI Services-resurs.

• Ett konto med Microsoft.Authorization/roleAssignments/write och Microsoft.Authorization/roleAssignments/delete behörigheter, till exempel rollbaserad åtkomstkontroll för administratör .

• Om du vill tilldela en roll måste du ange tre element:

  • Säkerhetsobjekt: t.ex. ditt användarkonto.
  • Rolldefinition: Cognitive Services-användarrollen.
  • Omfång: Azure AI Services-resursen.

• Installera Azure CLI.

• Identifiera följande information:

  • ditt prenumerations-ID för Azure

  • Ditt Azure AI Services-resursnamn.

  • Resursgruppen där Azure AI Services-resursen distribueras.

Konfigurera Microsoft Entra-ID för slutsatsdragning

Följ de här stegen för att konfigurera Microsoft Entra-ID för slutsatsdragning i din Azure AI Services-resurs:

1. Logga in på din Azure-prenumeration:

   az login
   

2. Om du har fler än en prenumeration väljer du den prenumeration där resursen finns:

   az account set --subscription "<subscription-id>"
   

3. Ange följande miljövariabler med namnet på den Azure AI Services-resurs som du planerar att använda och resursgruppen.

   ACCOUNT_NAME="<ai-services-resource-name>"
   RESOURCE_GROUP="<resource-group>"
   

4. Hämta det fullständiga namnet på resursen:

   RESOURCE_ID=$(az resource show -g $RESOURCE_GROUP -n $ACCOUNT_NAME --resource-type "Microsoft.CognitiveServices/accounts")
   

5. Hämta objekt-ID:t för det säkerhetsobjekt som du vill tilldela behörigheter till. I följande exempel visas hur du hämtar objekt-ID:t som är associerat med:

   Ditt eget inloggade konto:

   OBJECT_ID=$(az ad signed-in-user show --query id --output tsv)
   

   En säkerhetsgrupp:

   OBJECT_ID=$(az ad group show --group "<group-name>" --query id --output tsv)
   

   Ett huvudnamn för tjänsten:

   OBJECT_ID=$(az ad sp show --id "<service-principal-guid>" --query id --output tsv)
   

6. Tilldela cognitive services-användarrollen till tjänstens huvudnamn (omfångsbegränsat till resursen). Genom att tilldela en roll ger du tjänstens huvudnamn åtkomst till den här resursen.

   az role assignment create --assignee-object-id $OBJECT_ID --role "Cognitive Services User" --scope $RESOURCE_ID
   

7. Den valda användaren kan nu använda Microsoft Entra-ID för slutsatsdragning.

   Dricks

   Tänk på att Azure-rolltilldelningar kan ta upp till fem minuter att sprida. Att lägga till eller ta bort användare från en säkerhetsgrupp sprids omedelbart.

Använda Microsoft Entra-ID i koden

När Microsoft Entra-ID har konfigurerats i resursen måste du uppdatera koden så att den används när slutpunkten för slutsatsdragning används. I följande exempel visas hur du använder en modell för chattavslut:

Python

Installera paketet azure-ai-inference med hjälp av pakethanteraren, till exempel pip:

pip install azure-ai-inference>=1.0.0b5

Varning

Azure AI Services-resursen kräver versionen azure-ai-inference>=1.0.0b5 för Python.

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
    model="mistral-large-2407",
)

JavaScript

Installera paketet @azure-rest/ai-inference med npm:

npm install @azure-rest/ai-inference

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    "mistral-large-2407",
    clientOptions,
);

C#

Installera Azure AI-slutsatsdragningsbiblioteket med följande kommando:

dotnet add package Azure.AI.Inference --prerelease

Azure.Identity Installera paketet:

dotnet add package Azure.Identity

Importera följande namnområden:

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

var credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    "mistral-large-2407",
    clientOptions.
);

Java

Lägg till paketet i projektet:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar:

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .model("mistral-large-2407")
    .buildClient();

Utforska våra exempel och läs API-referensdokumentationen för att komma igång.

REST

Använd referensavsnittet för att utforska API-designen och vilka parametrar som är tillgängliga och ange autentiseringstoken i rubriken Authorization. Referensavsnittet för chattavslut beskriver till exempel hur du använder vägen /chat/completions för att generera förutsägelser baserat på chattformaterade instruktioner. Observera att sökvägen /models ingår i URL:ens rot:

Begär

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

Token måste utfärdas med omfånget https://cognitiveservices.azure.com/.default.

I testsyfte är det enklaste sättet att få en giltig token för ditt användarkonto att använda Azure CLI. Kör följande Azure CLI-kommando i en konsol:

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Alternativ för autentiseringsuppgifter när du använder Microsoft Entra-ID

DefaultAzureCredential är en åsiktsbaserad, ordnad sekvens av mekanismer för autentisering till Microsoft Entra-ID. Varje autentiseringsmekanism är en klass som härleds från TokenCredential klassen och kallas för autentiseringsuppgifter. Vid körning DefaultAzureCredential försöker autentisera med hjälp av den första autentiseringsuppgiften. Om det inte går att hämta en åtkomsttoken görs nästa autentiseringsuppgifter i sekvensen och så vidare tills en åtkomsttoken har hämtats. På så sätt kan din app använda olika autentiseringsuppgifter i olika miljöer utan att skriva miljöspecifik kod.

När föregående kod körs på din lokala utvecklingsarbetsstation letar den i miljövariablerna efter ett huvudnamn för programtjänsten eller lokalt installerade utvecklarverktyg, till exempel Visual Studio, för en uppsättning autentiseringsuppgifter för utvecklare. Endera metoden kan användas för att autentisera appen till Azure-resurser under lokal utveckling.

När den distribueras till Azure kan samma kod även autentisera din app till andra Azure-resurser. DefaultAzureCredential kan hämta miljöinställningar och hanterade identitetskonfigurationer för att autentisera till andra tjänster automatiskt.

Bästa praxis

• Använd deterministiska autentiseringsuppgifter i produktionsmiljöer: Överväg starkt att flytta från DefaultAzureCredential till någon av följande deterministiska lösningar i produktionsmiljöer:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se listan Härledd för alternativ.
  • En avskalad implementering optimerad för Azure-miljön ChainedTokenCredential där appen körs. ChainedTokenCredential skapar i princip en specifik lista över godtagbara alternativ för autentiseringsuppgifter, till exempel ManagedIdentity för produktion och VisualStudioCredential utveckling.

• Konfigurera systemtilldelade eller användartilldelade hanterade identiteter till de Azure-resurser där koden körs om möjligt. Konfigurera Microsoft Entra ID-åtkomst till dessa specifika identiteter.

Viktigt!

Objekt markerade (förhandsversion) i den här artikeln är för närvarande i offentlig förhandsversion. Den här förhandsversionen tillhandahålls utan ett serviceavtal och vi rekommenderar det inte för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds eller kan vara begränsade. Mer information finns i Kompletterande villkor för användning av Microsoft Azure-förhandsversioner.

Modeller som distribueras till Azure AI-modellinferens i Azure AI Services stöder nyckellös auktorisering med Hjälp av Microsoft Entra-ID. Nyckellös auktorisering förbättrar säkerheten, förenklar användarupplevelsen, minskar driftkomplexiteten och ger robust efterlevnadsstöd för modern utveckling. Det gör det till ett starkt val för organisationer som använder säkra och skalbara identitetshanteringslösningar.

Den här artikeln beskriver hur du konfigurerar Microsoft Entra-ID för slutsatsdragning i Azure AI-modellinferens.

Förstå roller i resurskontexten i Azure

Microsoft Entra ID använder idén om rollbaserad åtkomstkontroll (RBAC) för auktorisering. Roller är centrala för att hantera åtkomsten till dina molnresurser. En roll är i princip en samling behörigheter som definierar vilka åtgärder som kan utföras på specifika Azure-resurser. Genom att tilldela roller till användare, grupper, tjänstens huvudnamn eller hanterade identiteter – gemensamt kallade säkerhetsobjekt – kontrollerar du deras åtkomst i Din Azure-miljö till specifika resurser.

När du tilldelar en roll anger du säkerhetsobjektet, rolldefinitionen och omfånget. Den här kombinationen kallas för en rolltilldelning. Azure AI-modellinferens är en funktion för Azure AI Services-resurserna och därför kontrollerar roller som tilldelats den specifika resursen åtkomsten för slutsatsdragning.

Du identifierar två olika typer av åtkomst till resurserna:

• Administrationsåtkomst: De åtgärder som är relaterade till administrationen av resursen. De ändrar vanligtvis tillståndet för resursen och dess konfiguration. I Azure är dessa åtgärder kontrollplansåtgärder och kan köras med hjälp av Azure Portal, Azure CLI eller med infrastruktur som kod. Exempel på är att skapa en ny modelldistribution, ändra konfigurationer för innehållsfiltrering, ändra versionen av modellen som hanteras eller ändra SKU:n för en distribution.

• Utvecklaråtkomst: De åtgärder som är relaterade till förbrukningen av resurserna. Till exempel att anropa API:et för chattens slutförande. Användaren kan dock inte ändra tillståndet för resursen och dess konfiguration.

I Azure utförs alltid administrationsåtgärder med Hjälp av Microsoft Entra-ID. Med roller som Cognitive Services-deltagare kan du utföra dessa åtgärder. Å andra sidan kan utvecklaråtgärder utföras med antingen åtkomstnycklar eller/och Microsoft Entra-ID. Med roller som Cognitive Services-användare kan du utföra dessa åtgärder.

Viktigt!

Att ha administrationsåtkomst till en resurs ger inte nödvändigtvis utvecklaren åtkomst till den. Explicit åtkomst genom att bevilja roller krävs fortfarande. Det motsvarar hur databasservrar fungerar. Att ha administratörsåtkomst till databasservern innebär inte att du kan läsa data i en databas.

Följ de här stegen för att konfigurera utvecklaråtkomst till Azure AI-modellinferens i Azure AI Services-resursen.

Förutsättningar

För att slutföra den här artikeln behöver du:

• En Azure-prenumeration Om du använder GitHub-modeller kan du uppgradera din upplevelse och skapa en Azure-prenumeration i processen. Läs Uppgradera från GitHub-modeller till Azure AI-modellinferens om så är fallet.

• En Azure AI-tjänstresurs. Mer information finns i Skapa en Azure AI Services-resurs.

• Ett konto med Microsoft.Authorization/roleAssignments/write och Microsoft.Authorization/roleAssignments/delete behörigheter, till exempel rollbaserad åtkomstkontroll för administratör .

• Om du vill tilldela en roll måste du ange tre element:

  • Säkerhetsobjekt: t.ex. ditt användarkonto.
  • Rolldefinition: Cognitive Services-användarrollen.
  • Omfång: Azure AI Services-resursen.

• Installera Azure CLI.

• Identifiera följande information:

  • ditt prenumerations-ID för Azure

Om den här självstudiekursen

Exemplet i den här artikeln baseras på kodexempel som finns i lagringsplatsen Azure-Samples/azureai-model-inference-bicep . Om du vill köra kommandona lokalt utan att behöva kopiera eller klistra in filinnehåll använder du följande kommandon för att klona lagringsplatsen och gå till mappen för kodningsspråket:

git clone https://github.com/Azure-Samples/azureai-model-inference-bicep

Filerna för det här exemplet finns i:

cd azureai-model-inference-bicep/infra

Förstå resurserna

Självstudien hjälper dig att skapa:

• En Azure AI Services-resurs med nyckelåtkomst inaktiverad. För enkelhetens skull distribuerar den här mallen inte modeller.
• En rolltilldelning för ett visst säkerhetsobjekt med rollen Cognitive Services-användare.

Du använder följande tillgångar för att skapa dessa resurser:

1. Använd mallen modules/ai-services-template.bicep för att beskriva din Azure AI Services-resurs:

   modules/ai-services-template.bicep

   @description('Location of the resource.')
   param location string = resourceGroup().location
   
   @description('Name of the Azure AI Services account.')
   param accountName string
   
   @description('The resource model definition representing SKU')
   param sku string = 'S0'
   
   @description('Whether or not to allow keys for this account.')
   param allowKeys bool = true
   
   @allowed([
     'Enabled'
     'Disabled'
   ])
   @description('Whether or not public endpoint access is allowed for this account.')
   param publicNetworkAccess string = 'Enabled'
   
   @allowed([
     'Allow'
     'Deny'
   ])
   @description('The default action for network ACLs.')
   param networkAclsDefaultAction string = 'Allow'
   
   resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
     name: accountName
     location: location
     identity: {
       type: 'SystemAssigned'
     }
     sku: {
       name: sku
     }
     kind: 'AIServices'
     properties: {
       publicNetworkAccess: publicNetworkAccess
       networkAcls: {
         defaultAction: networkAclsDefaultAction
       }
       disableLocalAuth: allowKeys
     }
   }
   
   output endpointUri string = account.properties.endpoints['Azure AI Model Inference API']
   output id string = account.id
   

   Dricks

   Observera att den här mallen kan ta parametern allowKeys som, när false inaktiverar användningen av nycklar i resursen. Denna konfiguration är valfri.

2. Använd mallen modules/role-assignment-template.bicep för att beskriva en rolltilldelning i Azure:

   modules/role-assignment-template.bicep

   @description('Specifies the role definition ID used in the role assignment.')
   param roleDefinitionID string
   
   @description('Specifies the principal ID assigned to the role.')
   param principalId string
   
   @description('Specifies the resource ID of the resource to assign the role to.')
   param scopeResourceId string = resourceGroup().id
   
   var roleAssignmentName= guid(principalId, roleDefinitionID, scopeResourceId)
   resource roleAssignment 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
     name: roleAssignmentName
     properties: {
       roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionID)
       principalId: principalId
     }
   }
   
   output name string = roleAssignment.name
   output resourceId string = roleAssignment.id
   

Skapa resurserna

Följ dessa steg i konsolen:

1. Definiera huvuddistributionen:

   deploy-entra-id.bicep

   @description('Location to create the resources in')
   param location string = resourceGroup().location
   
   @description('Name of the resource group to create the resources in')
   param resourceGroupName string = resourceGroup().name
   
   @description('Name of the AI Services account to create')
   param accountName string = 'azurei-models-dev'
   
   @description('ID of the developers to assign the user role to')
   param securityPrincipalId string
   
   module aiServicesAccount 'modules/ai-services-template.bicep' = {
     name: 'aiServicesAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       accountName: accountName
       location: location
       allowKeys: false
     }
   }
   
   module roleAssignmentDeveloperAccount 'modules/role-assignment-template.bicep' = {
     name: 'roleAssignmentDeveloperAccount'
     scope: resourceGroup(resourceGroupName)
     params: {
       roleDefinitionID: 'a97b65f3-24c7-4388-baec-2e87135dc908' // Azure Cognitive Services User
       principalId: securityPrincipalId
     }
   }
   
   output endpoint string = aiServicesAccount.outputs.endpointUri
   

2. Logga in på Azure:

   az login
   

3. Se till att du har rätt prenumeration:

   az account set --subscription "<subscription-id>"
   

4. Kör distributionen:

   RESOURCE_GROUP="<resource-group-name>"
   SECURITY_PRINCIPAL_ID="<your-security-principal-id>"
   
   az deployment group create \
     --resource-group $RESOURCE_GROUP \
     --securityPrincipalId $SECURITY_PRINCIPAL_ID
     --template-file deploy-entra-id.bicep
   

5. Mallen matar ut slutpunkten för Azure AI-modellens slutsatsdragning som du kan använda för att använda någon av de modelldistributioner som du har skapat.

Använda Microsoft Entra-ID i koden

När du har konfigurerat Microsoft Entra-ID i resursen måste du uppdatera koden så att den används när slutpunkten för slutsatsdragning används. I följande exempel visas hur du använder en modell för chattavslut:

Python

Installera paketet azure-ai-inference med hjälp av pakethanteraren, till exempel pip:

pip install azure-ai-inference>=1.0.0b5

Varning

Azure AI Services-resursen kräver versionen azure-ai-inference>=1.0.0b5 för Python.

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

import os
from azure.ai.inference import ChatCompletionsClient
from azure.identity import DefaultAzureCredential

client = ChatCompletionsClient(
    endpoint="https://<resource>.services.ai.azure.com/models",
    credential=DefaultAzureCredential(),
    credential_scopes=["https://cognitiveservices.azure.com/.default"],
    model="mistral-large-2407",
)

JavaScript

Installera paketet @azure-rest/ai-inference med npm:

npm install @azure-rest/ai-inference

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

import ModelClient from "@azure-rest/ai-inference";
import { isUnexpected } from "@azure-rest/ai-inference";
import { DefaultAzureCredential } from "@azure/identity";

const clientOptions = { credentials: { "https://cognitiveservices.azure.com" } };

const client = new ModelClient(
    "https://<resource>.services.ai.azure.com/models", 
    new DefaultAzureCredential(),
    "mistral-large-2407",
    clientOptions,
);

C#

Installera Azure AI-slutsatsdragningsbiblioteket med följande kommando:

dotnet add package Azure.AI.Inference --prerelease

Azure.Identity Installera paketet:

dotnet add package Azure.Identity

Importera följande namnområden:

using Azure;
using Azure.Identity;
using Azure.AI.Inference;

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar med Entra-ID:

var credential = new DefaultAzureCredential();
AzureAIInferenceClientOptions clientOptions = new AzureAIInferenceClientOptions();
BearerTokenAuthenticationPolicy tokenPolicy = new BearerTokenAuthenticationPolicy(credential, new string[] { "https://cognitiveservices.azure.com/.default" });
clientOptions.AddPolicy(tokenPolicy, HttpPipelinePosition.PerRetry);

ChatCompletionsClient client = new ChatCompletionsClient(
    new Uri("https://<resource>.services.ai.azure.com/models"),
    credential,
    "mistral-large-2407",
    clientOptions.
);

Java

Lägg till paketet i projektet:

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-inference</artifactId>
    <version>1.0.0-beta.1</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.13.3</version>
</dependency>

Sedan kan du använda paketet för att använda modellen. I följande exempel visas hur du skapar en klient för att använda chattavslutningar:

TokenCredential defaultCredential = new DefaultAzureCredentialBuilder().build();
ChatCompletionsClient client = new ChatCompletionsClientBuilder()
    .credential(defaultCredential)
    .endpoint("https://<resource>.services.ai.azure.com/models")
    .model("mistral-large-2407")
    .buildClient();

Utforska våra exempel och läs API-referensdokumentationen för att komma igång.

REST

Använd referensavsnittet för att utforska API-designen och vilka parametrar som är tillgängliga och ange autentiseringstoken i rubriken Authorization. Referensavsnittet för chattavslut beskriver till exempel hur du använder vägen /chat/completions för att generera förutsägelser baserat på chattformaterade instruktioner. Observera att sökvägen /models ingår i URL:ens rot:

Begär

POST https://<resource>.services.ai.azure.com/models/chat/completions?api-version=2024-05-01-preview
Authorization: Bearer <bearer-token>
Content-Type: application/json

Token måste utfärdas med omfånget https://cognitiveservices.azure.com/.default.

I testsyfte är det enklaste sättet att få en giltig token för ditt användarkonto att använda Azure CLI. Kör följande Azure CLI-kommando i en konsol:

az account get-access-token --resource https://cognitiveservices.azure.com --query "accessToken" --output tsv

Alternativ för autentiseringsuppgifter när du använder Microsoft Entra-ID

DefaultAzureCredential är en åsiktsbaserad, ordnad sekvens av mekanismer för autentisering till Microsoft Entra-ID. Varje autentiseringsmekanism är en klass som härleds från TokenCredential klassen och kallas för autentiseringsuppgifter. Vid körning DefaultAzureCredential försöker autentisera med hjälp av den första autentiseringsuppgiften. Om det inte går att hämta en åtkomsttoken görs nästa autentiseringsuppgifter i sekvensen och så vidare tills en åtkomsttoken har hämtats. På så sätt kan din app använda olika autentiseringsuppgifter i olika miljöer utan att skriva miljöspecifik kod.

När föregående kod körs på din lokala utvecklingsarbetsstation letar den i miljövariablerna efter ett huvudnamn för programtjänsten eller lokalt installerade utvecklarverktyg, till exempel Visual Studio, för en uppsättning autentiseringsuppgifter för utvecklare. Endera metoden kan användas för att autentisera appen till Azure-resurser under lokal utveckling.

När den distribueras till Azure kan samma kod även autentisera din app till andra Azure-resurser. DefaultAzureCredential kan hämta miljöinställningar och hanterade identitetskonfigurationer för att autentisera till andra tjänster automatiskt.

Bästa praxis

• Använd deterministiska autentiseringsuppgifter i produktionsmiljöer: Överväg starkt att flytta från DefaultAzureCredential till någon av följande deterministiska lösningar i produktionsmiljöer:

  • En specifik TokenCredential implementering, till exempel ManagedIdentityCredential. Se listan Härledd för alternativ.
  • En avskalad implementering optimerad för Azure-miljön ChainedTokenCredential där appen körs. ChainedTokenCredential skapar i princip en specifik lista över godtagbara alternativ för autentiseringsuppgifter, till exempel ManagedIdentity för produktion och VisualStudioCredential utveckling.

• Konfigurera systemtilldelade eller användartilldelade hanterade identiteter till de Azure-resurser där koden körs om möjligt. Konfigurera Microsoft Entra ID-åtkomst till dessa specifika identiteter.

Inaktivera nyckelbaserad autentisering i resursen

Det rekommenderas att du inaktiverar nyckelbaserad autentisering när du implementerade Microsoft Entra-ID och fullständigt åtgärdade kompatibilitets- eller reservproblem i alla program som använder tjänsten. Du kan uppnå det genom att ändra egenskapen disableLocalAuth:

modules/ai-services-template.bicep

@description('Location of the resource.')
param location string = resourceGroup().location

@description('Name of the Azure AI Services account.')
param accountName string

@description('The resource model definition representing SKU')
param sku string = 'S0'

@description('Whether or not to allow keys for this account.')
param allowKeys bool = true

@allowed([
  'Enabled'
  'Disabled'
])
@description('Whether or not public endpoint access is allowed for this account.')
param publicNetworkAccess string = 'Enabled'

@allowed([
  'Allow'
  'Deny'
])
@description('The default action for network ACLs.')
param networkAclsDefaultAction string = 'Allow'

resource account 'Microsoft.CognitiveServices/accounts@2023-05-01' = {
  name: accountName
  location: location
  identity: {
    type: 'SystemAssigned'
  }
  sku: {
    name: sku
  }
  kind: 'AIServices'
  properties: {
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = account.properties.endpoints['Azure AI Model Inference API']
output id string = account.id

Nästa steg

• Utveckla program med hjälp av Azure AI-modellinferenstjänsten i Azure AI-tjänster