Sdílet prostřednictvím

Konfigurace ověřování bez klíčů pomocí ID Microsoft Entra

  • Článek

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Modely nasazené do odvozování modelů Azure AI ve službách Azure AI podporují autorizaci bez klíčů pomocí ID Microsoft Entra. Autorizace bez klíčů zvyšuje zabezpečení, zjednodušuje uživatelské prostředí, snižuje provozní složitost a poskytuje robustní podporu dodržování předpisů pro moderní vývoj. Je to silná volba pro organizace, které přijímají zabezpečená a škálovatelná řešení pro správu identit.

Tento článek vysvětluje, jak nakonfigurovat ID Microsoft Entra pro odvozování v odvozování modelu Azure AI.

Principy rolí v kontextu prostředku v Azure

Microsoft Entra ID používá k autorizaci myšlenku řízení přístupu na základě role (RBAC). Role jsou centrální pro správu přístupu ke cloudovým prostředkům. Role je v podstatě kolekce oprávnění, která definují akce, které se dají provádět s konkrétními prostředky Azure. Přiřazením rolí uživatelům, skupinám, instančním objektům nebo spravovaným identitám ( souhrnně označovaným jako objekty zabezpečení) řídíte jejich přístup v rámci prostředí Azure ke konkrétním prostředkům.

Při přiřazování role zadáte objekt zabezpečení, definici role a obor. Tato kombinace se označuje jako přiřazení role. Odvození modelu Azure AI je schopnost prostředků azure AI Services, a proto role přiřazené k danému konkrétnímu prostředku řídí přístup k odvozování.

Identifikujete dva různé typy přístupu k prostředkům:

  • Přístup pro správu: Akce, které souvisejí se správou prostředku. Obvykle mění stav prostředku a jeho konfigurace. V Azure jsou tyto operace operace řídicí roviny a je možné je spouštět pomocí webu Azure Portal, Azure CLI nebo infrastruktury jako kódu. Mezi příklady patří vytvoření nových nasazení modelu, změna konfigurací filtrování obsahu, změna verze modelu obsluhované nebo změna skladové položky nasazení.

  • Přístup pro vývojáře: Akce, které souvisejí se spotřebou prostředků. Například vyvolání rozhraní API pro dokončování chatu. Uživatel ale nemůže změnit stav prostředku a jeho konfigurace.

V Azure se operace správy provádějí vždy pomocí ID Microsoft Entra. Role, jako je přispěvatel služeb Cognitive Services, umožňují tyto operace provádět. Na druhou stranu je možné operace vývojáře provádět pomocí přístupových klíčů nebo id Microsoft Entra. Role, jako je uživatel služeb Cognitive Services, umožňují tyto operace provádět.

Důležité

Přístup správce k prostředku nemusí nutně udělit vývojářskému přístupu. Explicitní přístup udělením rolí se stále vyžaduje. Je to podobné tomu, jak databázové servery fungují. Přístup správce k databázovému serveru neznamená, že můžete číst data uvnitř databáze.

Podle těchto kroků nakonfigurujte přístup vývojářů k odvození modelu Azure AI v prostředku Azure AI Services.

Požadavky

K dokončení tohoto článku potřebujete:

  • Předplatné Azure. Pokud používáte modely GitHubu, můžete v procesu upgradovat prostředí a vytvořit předplatné Azure. Pokud se jedná o váš případ, přečtěte si článek Upgrade z modelů GitHubu na model Azure AI.

  • Prostředek služeb Azure AI Další informace najdete v tématu Vytvoření prostředku Azure AI Services.

  • Účet s oprávněními Microsoft.Authorization/roleAssignments/writeMicrosoft.Authorization/roleAssignments/delete , jako je řízení přístupu na základě role správce .

  • Pokud chcete přiřadit roli, musíte zadat tři prvky:

    • Objekt zabezpečení: např. váš uživatelský účet.
    • Definice role: role uživatele služeb Cognitive Services.
    • Rozsah: prostředek Azure AI Services.

Konfigurace ID Microsoft Entra pro odvozování

Podle těchto kroků nakonfigurujte ID Microsoft Entra pro odvozování:

  1. Přejděte na web Azure Portal a vyhledejte prostředek služby Azure AI, který používáte. Pokud používáte Azure AI Foundry s projekty nebo rozbočovači, můžete k němu přejít:

    1. Přejděte na portál Azure AI Foundry.

    2. Na cílové stránce vyberte Otevřít centrum pro správu.

    3. Přejděte do části Připojené prostředky a vyberte připojení k prostředku azure AI Services, který chcete nakonfigurovat. Pokud seznam není uvedený, vyberte Zobrazit vše a zobrazte úplný seznam.

    4. V části Podrobnosti o připojení v části Prostředek vyberte název prostředku Azure. Otevře se nová stránka.

    5. Teď jste na webu Azure Portal , kde můžete spravovat všechny aspekty samotného prostředku.

  2. Na levém navigačním panelu vyberte Řízení přístupu (IAM).

    Tip

    Pomocí možnosti Zobrazit můj přístup ověřte, které role už máte přiřazené.

  3. Vyberte Přiřazení rolí a pak vyberte Přidat>přiřazení role.

  4. V rolích funkcí úloh zadejte uživatele služeb Cognitive Services. Seznam rolí se odfiltruje.

  5. Vyberte roli a vyberte Další.

  6. V části Členové vyberte uživatele nebo skupinu, ke které chcete udělit přístup. Skupiny zabezpečení doporučujeme používat, kdykoli je to možné, protože jejich správa a údržba je jednodušší.

  7. Vyberte Další a dokončete průvodce.

  8. Vybraný uživatel teď může pro odvozování použít ID Microsoft Entra.

    Tip

    Mějte na paměti, že rozšíření přiřazení rolí Azure může trvat až pět minut. Při práci se skupinami zabezpečení se okamžitě rozšíří přidání nebo odebrání uživatelů ze skupiny zabezpečení.

Všimněte si, že přístup založený na klíčích je stále možný pro uživatele, kteří už mají klíče k dispozici. Pokud chcete odvolat klíče, vyberte na webu Azure Portal na levém navigačním panelu klíče správy>prostředků a koncové body znovu vygenerujte klíč1 a znovu vygenerujte>klíč2.

Použití ID Microsoft Entra v kódu

Jakmile ve svém prostředku nakonfigurujete ID Microsoft Entra, musíte aktualizovat kód tak, aby ho používal při využívání koncového bodu odvozování. Následující příklad ukazuje, jak používat model dokončování chatu:

Nainstalujte balíček azure-ai-inference pomocí správce balíčků, například pip:

pip install azure-ai-inference

Pak můžete balíček použít k využívání modelu. Následující příklad ukazuje, jak vytvořit klienta, který bude využívat dokončování chatu s ID Entra:

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"],
)

Možnosti přihlašovacích údajů při použití ID Microsoft Entra

DefaultAzureCredential je názorná, seřazená posloupnost mechanismů pro ověřování v Microsoft Entra ID. Každý mechanismus ověřování je třída odvozená z TokenCredential třídy a je známá jako přihlašovací údaje. Za běhu DefaultAzureCredential se pokusí ověřit pomocí prvních přihlašovacích údajů. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Aplikace tak může používat různé přihlašovací údaje v různých prostředích bez psaní kódu specifického pro prostředí.

Když předchozí kód běží na místní vývojové pracovní stanici, hledá v proměnných prostředí instanční objekt aplikace nebo v místně nainstalovaných vývojářských nástrojích, jako je Visual Studio, pro sadu přihlašovacích údajů vývojáře. K ověření aplikace v prostředcích Azure se dá použít některý z přístupů během místního vývoje.

Při nasazení do Azure může stejný kód také ověřit vaši aplikaci v jiných prostředcích Azure. DefaultAzureCredential může načíst nastavení prostředí a konfigurace spravovaných identit pro automatické ověřování v jiných službách.

Osvědčené postupy

  • Použití deterministických přihlašovacích údajů v produkčních prostředích: Důrazně zvažte přechod z DefaultAzureCredential jednoho z následujících deterministických řešení v produkčních prostředích:

    • Konkrétní TokenCredential implementace, například ManagedIdentityCredential. Možnosti najdete v seznamu odvozených položek.
    • Pared-down ChainedTokenCredential implementace optimalizovaná pro prostředí Azure, ve kterém vaše aplikace běží. ChainedTokenCredential v podstatě vytvoří konkrétní seznam povolených přijatelných možností přihlašovacích údajů, například ManagedIdentity pro produkční prostředí a VisualStudioCredential vývoj.

  • Nakonfigurujte spravované identity přiřazené systémem nebo uživatelem přiřazené k prostředkům Azure, ve kterých je váš kód spuštěný, pokud je to možné. Nakonfigurujte přístup Microsoft Entra ID k těmto konkrétním identitám.

Řešení problému

Následující tabulka obsahuje několik scénářů, které vám můžou pomoct s řešením potíží s ID Microsoft Entra:

Chyba nebo scénář Původní příčina Řešení
Používáte sadu SDK. Známé problémy Před dalším řešením potíží doporučujeme nainstalovat nejnovější verzi softwaru, který používáte pro připojení ke službě. Chyby ověřování mohly být opraveny v novější verzi softwaru, který používáte.
401 Principal does not have access to API/Operation Požadavek označuje ověřování správným způsobem, ale instanční objekt uživatele nemá požadovaná oprávnění k použití koncového bodu odvození. Ujistěte se, že máte:
1. Přiřadili jste uživateli služeb Cognitive Services roli k vašemu objektu zabezpečení k prostředku azure AI Services.
2. Před prvním voláním počkejte aspoň 5 minut.
401 HTTP/1.1 401 PermissionDenied Požadavek označuje ověřování správným způsobem, ale instanční objekt uživatele nemá požadovaná oprávnění k použití koncového bodu odvození. Přiřadili jste uživateli služeb Cognitive Services roli k vašemu objektu zabezpečení v prostředku Azure AI Services. Role, jako je správce nebo přispěvatel , nemají velký přístup k odvozování. Před prvním voláním počkejte aspoň 5 minut.
Používáte volání rozhraní REST API a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že hlavička Authentication obsahuje platný token s oborem https://cognitiveservices.azure.com/.default.
Používáte AzureOpenAI třídu a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že používáte model OpenAI připojený ke koncovému bodu https://<resource>.openai.azure.com. Nemůžete použít OpenAI třídu nebo model typu Model jako služba. Pokud váš model není z OpenAI, použijte sadu Azure AI Inference SDK.
Používáte sadu Azure AI Inference SDK a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že jste připojení ke koncovému bodu https://<resource>.services.ai.azure.com/model a že jste uvedli správný rozsah pro ID Entra (https://cognitiveservices.azure.com/.default).
404 Not found Adresa URL koncového bodu je nesprávná na základě sady SDK, kterou používáte, nebo neexistuje nasazení modelu. Ujistěte se, že používáte správnou sadu SDK připojenou ke správnému koncovému bodu:
1. Pokud používáte sadu SDK pro odvozování Azure AI, ujistěte se, že je https://<resource>.services.ai.azure.com/model koncový bod v model="<model-deployment-name>" datových částech, nebo koncový bod je https://<resource>.openai.azure.com/deployments/<model-deployment-name>.
Pokud používáte AzureOpenAI třídu, ujistěte se, že koncový bod je https://<resource>.openai.azure.com.

Použití ID Microsoft Entra v projektu

I když je pro váš prostředek nakonfigurované ID Microsoft Entra ID, můžou vaše projekty stále používat klíče k využívání predikcí z prostředku. Při použití dětského hřiště Azure AI Foundry se použijí přihlašovací údaje přidružené k připojení k vašemu projektu.

Pokud chcete toto chování změnit, musíte aktualizovat připojení z projektů tak, aby používala ID Microsoft Entra. Postupujte následovně:

  1. Přejděte na portál Azure AI Foundry.

  2. Přejděte k projektům nebo rozbočovačům, které používají prostředek služby Azure AI Services prostřednictvím připojení.

  3. Vyberte Centrum pro správu.

  4. Přejděte do části Připojené prostředky a vyberte připojení k prostředku azure AI Services, který chcete nakonfigurovat. Pokud seznam není uvedený, vyberte Zobrazit vše a zobrazte úplný seznam.

  5. V části Podrobnosti o připojení vedle podrobností accessu vyberte ikonu pro úpravy.

  6. V části Ověřování změňte hodnotu na Microsoft Entra ID.

  7. Vyberte Aktualizovat.

  8. Vaše připojení je teď nakonfigurované tak, aby fungovalo s ID Microsoft Entra.

Zakázání ověřování na základě klíčů v prostředku

Zakázání ověřování založeného na klíčích se doporučuje, když jste implementovali ID Microsoft Entra a plně vyřešili problémy kompatibility nebo náhradního prostředku ve všech aplikacích, které službu využívají.

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Modely nasazené do odvozování modelů Azure AI ve službách Azure AI podporují autorizaci bez klíčů pomocí ID Microsoft Entra. Autorizace bez klíčů zvyšuje zabezpečení, zjednodušuje uživatelské prostředí, snižuje provozní složitost a poskytuje robustní podporu dodržování předpisů pro moderní vývoj. Je to silná volba pro organizace, které přijímají zabezpečená a škálovatelná řešení pro správu identit.

Tento článek vysvětluje, jak nakonfigurovat ID Microsoft Entra pro odvozování v odvozování modelu Azure AI.

Principy rolí v kontextu prostředku v Azure

Microsoft Entra ID používá k autorizaci myšlenku řízení přístupu na základě role (RBAC). Role jsou centrální pro správu přístupu ke cloudovým prostředkům. Role je v podstatě kolekce oprávnění, která definují akce, které se dají provádět s konkrétními prostředky Azure. Přiřazením rolí uživatelům, skupinám, instančním objektům nebo spravovaným identitám ( souhrnně označovaným jako objekty zabezpečení) řídíte jejich přístup v rámci prostředí Azure ke konkrétním prostředkům.

Při přiřazování role zadáte objekt zabezpečení, definici role a obor. Tato kombinace se označuje jako přiřazení role. Odvození modelu Azure AI je schopnost prostředků azure AI Services, a proto role přiřazené k danému konkrétnímu prostředku řídí přístup k odvozování.

Identifikujete dva různé typy přístupu k prostředkům:

  • Přístup pro správu: Akce, které souvisejí se správou prostředku. Obvykle mění stav prostředku a jeho konfigurace. V Azure jsou tyto operace operace řídicí roviny a je možné je spouštět pomocí webu Azure Portal, Azure CLI nebo infrastruktury jako kódu. Mezi příklady patří vytvoření nových nasazení modelu, změna konfigurací filtrování obsahu, změna verze modelu obsluhované nebo změna skladové položky nasazení.

  • Přístup pro vývojáře: Akce, které souvisejí se spotřebou prostředků. Například vyvolání rozhraní API pro dokončování chatu. Uživatel ale nemůže změnit stav prostředku a jeho konfigurace.

V Azure se operace správy provádějí vždy pomocí ID Microsoft Entra. Role, jako je přispěvatel služeb Cognitive Services, umožňují tyto operace provádět. Na druhou stranu je možné operace vývojáře provádět pomocí přístupových klíčů nebo id Microsoft Entra. Role, jako je uživatel služeb Cognitive Services, umožňují tyto operace provádět.

Důležité

Přístup správce k prostředku nemusí nutně udělit vývojářskému přístupu. Explicitní přístup udělením rolí se stále vyžaduje. Je to podobné tomu, jak databázové servery fungují. Přístup správce k databázovému serveru neznamená, že můžete číst data uvnitř databáze.

Podle těchto kroků nakonfigurujte přístup vývojářů k odvození modelu Azure AI v prostředku Azure AI Services.

Požadavky

K dokončení tohoto článku potřebujete:

  • Předplatné Azure. Pokud používáte modely GitHubu, můžete v procesu upgradovat prostředí a vytvořit předplatné Azure. Pokud se jedná o váš případ, přečtěte si článek Upgrade z modelů GitHubu na model Azure AI.

  • Prostředek služeb Azure AI Další informace najdete v tématu Vytvoření prostředku Azure AI Services.

  • Účet s oprávněními Microsoft.Authorization/roleAssignments/writeMicrosoft.Authorization/roleAssignments/delete , jako je řízení přístupu na základě role správce .

  • Pokud chcete přiřadit roli, musíte zadat tři prvky:

    • Objekt zabezpečení: např. váš uživatelský účet.
    • Definice role: role uživatele služeb Cognitive Services.
    • Rozsah: prostředek Azure AI Services.

  • Nainstalujte rozhraní příkazového řádku Azure CLI.

  • Identifikujte následující informace:

    • ID vašeho předplatného Azure

    • Název prostředku azure AI Services

    • Skupina prostředků, ve které je nasazený prostředek Azure AI Services.

Konfigurace ID Microsoft Entra pro odvozování

Podle těchto kroků nakonfigurujte ID Microsoft Entra pro odvozování ve vašem prostředku služby Azure AI Services:

  1. Přihlaste se k předplatnému Azure:

    az login

  2. Pokud máte více než jedno předplatné, vyberte předplatné, ve kterém se nachází váš prostředek:

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

  3. Nastavte následující proměnné prostředí s názvem prostředku Azure AI Services, který plánujete použít a skupinu prostředků.

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

  4. Získejte úplný název vašeho prostředku:

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

  5. Získejte ID objektu objektu objektu zabezpečení, ke kterému chcete přiřadit oprávnění. Následující příklad ukazuje, jak získat ID objektu přidružené k:

    Váš vlastní přihlášený účet:

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

    Skupina zabezpečení:

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

    Instanční objekt:

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

  6. Přiřaďte roli uživatele služeb Cognitive Services k instančnímu objektu (vymezenému prostředku). Přiřazením role udělujete instančnímu objektu přístup k tomuto prostředku.

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

  7. Vybraný uživatel teď může pro odvozování použít ID Microsoft Entra.

    Tip

    Mějte na paměti, že rozšíření přiřazení rolí Azure může trvat až pět minut. Přidání nebo odebrání uživatelů ze skupiny zabezpečení se okamžitě rozšíří.

Použití ID Microsoft Entra v kódu

Jakmile je v prostředku nakonfigurované ID Microsoft Entra, musíte aktualizovat kód, aby ho používal při využívání koncového bodu odvozování. Následující příklad ukazuje, jak používat model dokončování chatu:

Nainstalujte balíček azure-ai-inference pomocí správce balíčků, například pip:

pip install azure-ai-inference

Pak můžete balíček použít k využívání modelu. Následující příklad ukazuje, jak vytvořit klienta, který bude využívat dokončování chatu s ID Entra:

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"],
)

Možnosti přihlašovacích údajů při použití ID Microsoft Entra

DefaultAzureCredential je názorná, seřazená posloupnost mechanismů pro ověřování v Microsoft Entra ID. Každý mechanismus ověřování je třída odvozená z TokenCredential třídy a je známá jako přihlašovací údaje. Za běhu DefaultAzureCredential se pokusí ověřit pomocí prvních přihlašovacích údajů. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Aplikace tak může používat různé přihlašovací údaje v různých prostředích bez psaní kódu specifického pro prostředí.

Když předchozí kód běží na místní vývojové pracovní stanici, hledá v proměnných prostředí instanční objekt aplikace nebo v místně nainstalovaných vývojářských nástrojích, jako je Visual Studio, pro sadu přihlašovacích údajů vývojáře. K ověření aplikace v prostředcích Azure se dá použít některý z přístupů během místního vývoje.

Při nasazení do Azure může stejný kód také ověřit vaši aplikaci v jiných prostředcích Azure. DefaultAzureCredential může načíst nastavení prostředí a konfigurace spravovaných identit pro automatické ověřování v jiných službách.

Osvědčené postupy

  • Použití deterministických přihlašovacích údajů v produkčních prostředích: Důrazně zvažte přechod z DefaultAzureCredential jednoho z následujících deterministických řešení v produkčních prostředích:

    • Konkrétní TokenCredential implementace, například ManagedIdentityCredential. Možnosti najdete v seznamu odvozených položek.
    • Pared-down ChainedTokenCredential implementace optimalizovaná pro prostředí Azure, ve kterém vaše aplikace běží. ChainedTokenCredential v podstatě vytvoří konkrétní seznam povolených přijatelných možností přihlašovacích údajů, například ManagedIdentity pro produkční prostředí a VisualStudioCredential vývoj.

  • Nakonfigurujte spravované identity přiřazené systémem nebo uživatelem přiřazené k prostředkům Azure, ve kterých je váš kód spuštěný, pokud je to možné. Nakonfigurujte přístup Microsoft Entra ID k těmto konkrétním identitám.

Řešení problému

Následující tabulka obsahuje několik scénářů, které vám můžou pomoct s řešením potíží s ID Microsoft Entra:

Chyba nebo scénář Původní příčina Řešení
Používáte sadu SDK. Známé problémy Před dalším řešením potíží doporučujeme nainstalovat nejnovější verzi softwaru, který používáte pro připojení ke službě. Chyby ověřování mohly být opraveny v novější verzi softwaru, který používáte.
401 Principal does not have access to API/Operation Požadavek označuje ověřování správným způsobem, ale instanční objekt uživatele nemá požadovaná oprávnění k použití koncového bodu odvození. Ujistěte se, že máte:
1. Přiřadili jste uživateli služeb Cognitive Services roli k vašemu objektu zabezpečení k prostředku azure AI Services.
2. Před prvním voláním počkejte aspoň 5 minut.
401 HTTP/1.1 401 PermissionDenied Požadavek označuje ověřování správným způsobem, ale instanční objekt uživatele nemá požadovaná oprávnění k použití koncového bodu odvození. Přiřadili jste uživateli služeb Cognitive Services roli k vašemu objektu zabezpečení v prostředku Azure AI Services. Role, jako je správce nebo přispěvatel , nemají velký přístup k odvozování. Před prvním voláním počkejte aspoň 5 minut.
Používáte volání rozhraní REST API a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že hlavička Authentication obsahuje platný token s oborem https://cognitiveservices.azure.com/.default.
Používáte AzureOpenAI třídu a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že používáte model OpenAI připojený ke koncovému bodu https://<resource>.openai.azure.com. Nemůžete použít OpenAI třídu nebo model typu Model jako služba. Pokud váš model není z OpenAI, použijte sadu Azure AI Inference SDK.
Používáte sadu Azure AI Inference SDK a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že jste připojení ke koncovému bodu https://<resource>.services.ai.azure.com/model a že jste uvedli správný rozsah pro ID Entra (https://cognitiveservices.azure.com/.default).
404 Not found Adresa URL koncového bodu je nesprávná na základě sady SDK, kterou používáte, nebo neexistuje nasazení modelu. Ujistěte se, že používáte správnou sadu SDK připojenou ke správnému koncovému bodu:
1. Pokud používáte sadu SDK pro odvozování Azure AI, ujistěte se, že je https://<resource>.services.ai.azure.com/model koncový bod v model="<model-deployment-name>" datových částech, nebo koncový bod je https://<resource>.openai.azure.com/deployments/<model-deployment-name>.
Pokud používáte AzureOpenAI třídu, ujistěte se, že koncový bod je https://<resource>.openai.azure.com.

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Modely nasazené do odvozování modelů Azure AI ve službách Azure AI podporují autorizaci bez klíčů pomocí ID Microsoft Entra. Autorizace bez klíčů zvyšuje zabezpečení, zjednodušuje uživatelské prostředí, snižuje provozní složitost a poskytuje robustní podporu dodržování předpisů pro moderní vývoj. Je to silná volba pro organizace, které přijímají zabezpečená a škálovatelná řešení pro správu identit.

Tento článek vysvětluje, jak nakonfigurovat ID Microsoft Entra pro odvozování v odvozování modelu Azure AI.

Principy rolí v kontextu prostředku v Azure

Microsoft Entra ID používá k autorizaci myšlenku řízení přístupu na základě role (RBAC). Role jsou centrální pro správu přístupu ke cloudovým prostředkům. Role je v podstatě kolekce oprávnění, která definují akce, které se dají provádět s konkrétními prostředky Azure. Přiřazením rolí uživatelům, skupinám, instančním objektům nebo spravovaným identitám ( souhrnně označovaným jako objekty zabezpečení) řídíte jejich přístup v rámci prostředí Azure ke konkrétním prostředkům.

Při přiřazování role zadáte objekt zabezpečení, definici role a obor. Tato kombinace se označuje jako přiřazení role. Odvození modelu Azure AI je schopnost prostředků azure AI Services, a proto role přiřazené k danému konkrétnímu prostředku řídí přístup k odvozování.

Identifikujete dva různé typy přístupu k prostředkům:

  • Přístup pro správu: Akce, které souvisejí se správou prostředku. Obvykle mění stav prostředku a jeho konfigurace. V Azure jsou tyto operace operace řídicí roviny a je možné je spouštět pomocí webu Azure Portal, Azure CLI nebo infrastruktury jako kódu. Mezi příklady patří vytvoření nových nasazení modelu, změna konfigurací filtrování obsahu, změna verze modelu obsluhované nebo změna skladové položky nasazení.

  • Přístup pro vývojáře: Akce, které souvisejí se spotřebou prostředků. Například vyvolání rozhraní API pro dokončování chatu. Uživatel ale nemůže změnit stav prostředku a jeho konfigurace.

V Azure se operace správy provádějí vždy pomocí ID Microsoft Entra. Role, jako je přispěvatel služeb Cognitive Services, umožňují tyto operace provádět. Na druhou stranu je možné operace vývojáře provádět pomocí přístupových klíčů nebo id Microsoft Entra. Role, jako je uživatel služeb Cognitive Services, umožňují tyto operace provádět.

Důležité

Přístup správce k prostředku nemusí nutně udělit vývojářskému přístupu. Explicitní přístup udělením rolí se stále vyžaduje. Je to podobné tomu, jak databázové servery fungují. Přístup správce k databázovému serveru neznamená, že můžete číst data uvnitř databáze.

Podle těchto kroků nakonfigurujte přístup vývojářů k odvození modelu Azure AI v prostředku Azure AI Services.

Požadavky

K dokončení tohoto článku potřebujete:

  • Předplatné Azure. Pokud používáte modely GitHubu, můžete v procesu upgradovat prostředí a vytvořit předplatné Azure. Pokud se jedná o váš případ, přečtěte si článek Upgrade z modelů GitHubu na model Azure AI.

  • Prostředek služeb Azure AI Další informace najdete v tématu Vytvoření prostředku Azure AI Services.

  • Účet s oprávněními Microsoft.Authorization/roleAssignments/writeMicrosoft.Authorization/roleAssignments/delete , jako je řízení přístupu na základě role správce .

  • Pokud chcete přiřadit roli, musíte zadat tři prvky:

    • Objekt zabezpečení: např. váš uživatelský účet.
    • Definice role: role uživatele služeb Cognitive Services.
    • Rozsah: prostředek Azure AI Services.

O tomto kurzu

Příklad v tomto článku vychází z ukázek kódu obsažených v úložišti Azure-Samples/azureai-model-inference-bicep . Pokud chcete příkazy spustit místně, aniž byste museli kopírovat nebo vkládat obsah souboru, naklonujte úložiště pomocí následujících příkazů a přejděte do složky pro váš kódovací jazyk:

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

Soubory pro tento příklad jsou v:

cd azureai-model-inference-bicep/infra

Vysvětlení prostředků

Tento kurz vám pomůže vytvořit:

  • Prostředek azure AI Services s zakázaným přístupem ke klíči Pro zjednodušení tato šablona nenasazuje modely.
  • Přiřazení role pro daný objekt zabezpečení s rolí Uživatel služeb Cognitive Services.

K vytvoření těchto prostředků používáte následující prostředky:

  1. Pomocí šablony modules/ai-services-template.bicep popíšete prostředek Azure AI Services:

    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: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

    Tip

    Všimněte si, že tato šablona může převzít parametr allowKeys , který zakáže false použití klíčů v prostředku. Tato konfigurace je volitelná.

  2. Pomocí šablony modules/role-assignment-template.bicep popíšete přiřazení role v 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

Vytvoření prostředků

V konzole postupujte takto:

  1. Definujte hlavní nasazení:

    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. Přihlaste se k Azure:

    az login

  3. Ujistěte se, že jste ve správném předplatném:

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

  4. Spusťte nasazení:

    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. Šablona vypíše koncový bod odvozování modelu Azure AI, který můžete použít k využívání jakéhokoli vytvořeného nasazení modelu.

Použití ID Microsoft Entra v kódu

Jakmile ve svém prostředku nakonfigurujete ID Microsoft Entra, musíte aktualizovat kód tak, aby ho používal při využívání koncového bodu odvozování. Následující příklad ukazuje, jak používat model dokončování chatu:

Nainstalujte balíček azure-ai-inference pomocí správce balíčků, například pip:

pip install azure-ai-inference

Pak můžete balíček použít k využívání modelu. Následující příklad ukazuje, jak vytvořit klienta, který bude využívat dokončování chatu s ID Entra:

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"],
)

Možnosti přihlašovacích údajů při použití ID Microsoft Entra

DefaultAzureCredential je názorná, seřazená posloupnost mechanismů pro ověřování v Microsoft Entra ID. Každý mechanismus ověřování je třída odvozená z TokenCredential třídy a je známá jako přihlašovací údaje. Za běhu DefaultAzureCredential se pokusí ověřit pomocí prvních přihlašovacích údajů. Pokud se tento přihlašovací údaj nepodaří získat přístupový token, pokusí se další přihlašovací údaje v této sekvenci atd., dokud se přístupový token úspěšně nezíská. Aplikace tak může používat různé přihlašovací údaje v různých prostředích bez psaní kódu specifického pro prostředí.

Když předchozí kód běží na místní vývojové pracovní stanici, hledá v proměnných prostředí instanční objekt aplikace nebo v místně nainstalovaných vývojářských nástrojích, jako je Visual Studio, pro sadu přihlašovacích údajů vývojáře. K ověření aplikace v prostředcích Azure se dá použít některý z přístupů během místního vývoje.

Při nasazení do Azure může stejný kód také ověřit vaši aplikaci v jiných prostředcích Azure. DefaultAzureCredential může načíst nastavení prostředí a konfigurace spravovaných identit pro automatické ověřování v jiných službách.

Osvědčené postupy

  • Použití deterministických přihlašovacích údajů v produkčních prostředích: Důrazně zvažte přechod z DefaultAzureCredential jednoho z následujících deterministických řešení v produkčních prostředích:

    • Konkrétní TokenCredential implementace, například ManagedIdentityCredential. Možnosti najdete v seznamu odvozených položek.
    • Pared-down ChainedTokenCredential implementace optimalizovaná pro prostředí Azure, ve kterém vaše aplikace běží. ChainedTokenCredential v podstatě vytvoří konkrétní seznam povolených přijatelných možností přihlašovacích údajů, například ManagedIdentity pro produkční prostředí a VisualStudioCredential vývoj.

  • Nakonfigurujte spravované identity přiřazené systémem nebo uživatelem přiřazené k prostředkům Azure, ve kterých je váš kód spuštěný, pokud je to možné. Nakonfigurujte přístup Microsoft Entra ID k těmto konkrétním identitám.

Řešení problému

Následující tabulka obsahuje několik scénářů, které vám můžou pomoct s řešením potíží s ID Microsoft Entra:

Chyba nebo scénář Původní příčina Řešení
Používáte sadu SDK. Známé problémy Před dalším řešením potíží doporučujeme nainstalovat nejnovější verzi softwaru, který používáte pro připojení ke službě. Chyby ověřování mohly být opraveny v novější verzi softwaru, který používáte.
401 Principal does not have access to API/Operation Požadavek označuje ověřování správným způsobem, ale instanční objekt uživatele nemá požadovaná oprávnění k použití koncového bodu odvození. Ujistěte se, že máte:
1. Přiřadili jste uživateli služeb Cognitive Services roli k vašemu objektu zabezpečení k prostředku azure AI Services.
2. Před prvním voláním počkejte aspoň 5 minut.
401 HTTP/1.1 401 PermissionDenied Požadavek označuje ověřování správným způsobem, ale instanční objekt uživatele nemá požadovaná oprávnění k použití koncového bodu odvození. Přiřadili jste uživateli služeb Cognitive Services roli k vašemu objektu zabezpečení v prostředku Azure AI Services. Role, jako je správce nebo přispěvatel , nemají velký přístup k odvozování. Před prvním voláním počkejte aspoň 5 minut.
Používáte volání rozhraní REST API a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že hlavička Authentication obsahuje platný token s oborem https://cognitiveservices.azure.com/.default.
Používáte AzureOpenAI třídu a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že používáte model OpenAI připojený ke koncovému bodu https://<resource>.openai.azure.com. Nemůžete použít OpenAI třídu nebo model typu Model jako služba. Pokud váš model není z OpenAI, použijte sadu Azure AI Inference SDK.
Používáte sadu Azure AI Inference SDK a získáte 401 Unauthorized. Access token is missing, invalid, audience is incorrect, or have expired. Požadavek se nedaří provést ověření pomocí ID Entra. Ujistěte se, že jste připojení ke koncovému bodu https://<resource>.services.ai.azure.com/model a že jste uvedli správný rozsah pro ID Entra (https://cognitiveservices.azure.com/.default).
404 Not found Adresa URL koncového bodu je nesprávná na základě sady SDK, kterou používáte, nebo neexistuje nasazení modelu. Ujistěte se, že používáte správnou sadu SDK připojenou ke správnému koncovému bodu:
1. Pokud používáte sadu SDK pro odvozování Azure AI, ujistěte se, že je https://<resource>.services.ai.azure.com/model koncový bod v model="<model-deployment-name>" datových částech, nebo koncový bod je https://<resource>.openai.azure.com/deployments/<model-deployment-name>.
Pokud používáte AzureOpenAI třídu, ujistěte se, že koncový bod je https://<resource>.openai.azure.com.

Zakázání ověřování na základě klíčů v prostředku

Zakázání ověřování založeného na klíčích se doporučuje, když jste implementovali ID Microsoft Entra a plně vyřešili problémy kompatibility nebo náhradního prostředku ve všech aplikacích, které službu využívají. Můžete ho dosáhnout změnou vlastnosti 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: {
    customSubDomainName: accountName
    publicNetworkAccess: publicNetworkAccess
    networkAcls: {
      defaultAction: networkAclsDefaultAction
    }
    disableLocalAuth: allowKeys
  }
}

output endpointUri string = 'https://${account.outputs.name}.services.ai.azure.com/models'
output id string = account.id

Další kroky