Volba koncového bodu a sady SDK

Dokončeno

Microsoft Foundry poskytuje flexibilitu pro vývoj generovacích chatovacích aplikací umělé inteligence. Než začnete s vývojem, je důležité porozumět dostupným možnostem a rozhodnout se, které z nich se mají použít. Mezi důležité informace při vývoji aplikace patří:

• Koncové body: Projekty Microsoft Foundry poskytují dva koncové body, které můžete použít k připojení a využívání prostředků projektu, jako jsou nasazení modelu, z klientských aplikací. Každý projekt má koncový bod projektu i koncový bod Azure OpenAI.
• Klientská sada SDK: V závislosti na vybraném koncovém bodu můžete použít sadu Microsoft Foundry SDK nebo OpenAI SDK k vývoji chatovací aplikace generující AI. Obě sady SDK podporují klientský objekt kompatibilní s rozhraním OpenAI API, který může odesílat výzvy k modelům, ale existují určité rozdíly v konkrétních funkcích dostupných v každé sadě SDK.
• Ověřování: Podle koncového bodu a použitého SDK existuje několik způsobů, kterými lze klientskou aplikaci autentizovat pomocí Foundry, aby jí byl udělen přístup k aktivům. Produkční aplikace by obecně měly používat ověřování Microsoft Entra ID , které vyžaduje, aby aplikace běžela v kontextu konkrétní identity; v některých scénářích ale můžete použít také ověřování založené na klíčích nebo tokenech .
• Rozhraní API chatu: Rozhraní API klienta OpenAI podporuje dvě rozhraní API chatu: ChatCompletions a Odpovědi. I když se rozhraní API pro odpovědi doporučuje pro většinu nových vývojových projektů, rozhraní API ChatCompletions je dobře zavedené a kompatibilní napříč mnoha modely a platformami generující umělé inteligence.

Začněme zvážením dostupných koncových bodů, klientských sad SDK a metod ověřování – později prozkoumáme rozhraní API pro odpovědi a funkce ChatCompletions.

Použití sady Foundry SDK s koncovým bodem projektu

Sada Microsoft Foundry SDK poskytuje programový přístup k prostředkům ve vašich projektech prostřednictvím rozhraní REST API a klientských knihoven specifických pro jazyk; Včetně:

• Projekty Azure AI pro Python
• Azure projekty umělé inteligence pro Microsoft .NET
• Azure AI projekty pro JavaScript

Poznámka:

Tento modul používá příklady kódu Pythonu pro běžné úlohy. Ekvivalentní kód v preferovaném jazyce najdete v dokumentaci k sadě SDK pro konkrétní jazyk. Každá sada SDK se vyvíjí a udržuje nezávisle, takže některé funkce můžou být v různých fázích implementace.

Instalace sady SDK

Pokud chcete použít knihovnu projektů Azure AI v Pythonu, nainstalujte balíček azure-ai-projects z PyPI spolu s podpůrnými balíčky:

pip install azure-ai-projects azure-identity openai

Poznámka:

Při použití sady Foundry SDK k vývoji chatovací aplikace musíte také importovat balíček OpenAI SDK – funkce chatovacího klienta v sadě Foundry SDK je odvozena ze sady OpenAI SDK.

Připojení ke koncovému bodu projektu

Každý projekt Foundry má jedinečný koncový bod, který najdete na stránce Overview na portálu Foundry na adrese https://ai.azure.com.

Koncový bod project má tento formát:

https://{resource-name}.services.ai.azure.com/api/projects/<project-name>

Pomocí tohoto koncového bodu vytvořte objekt AIProjectClient :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=project_endpoint
)

Poznámka:

Kód používá k ověření výchozí Azure přihlašovací údaje. Pokud chcete povolit toto ověřování, musíte nainstalovat balíček azure-identity (viz předchozí instalační příkaz).

Návod

Aby bylo možné úspěšně přistupovat k projektu, musí kód běžet v ověřeném Azure relaci. Před spuštěním kódu se můžete například přihlásit pomocí příkazu Azure CLI az login.

Klient projektu (AIProjectClient) poskytuje přístup k nativním operacím Foundry, které nemají ekvivalenty OpenAI. Pomocí klienta project můžete:

• Načtení připojení prostředků
• Konfigurace projektu aplikace Access
• Povolit trasování
• Správa datových sad a indexů

Vytvoření chatovacího klienta

Pokud chcete chatovat s modelem v projektu Foundry, potřebujete objekt klienta kompatibilní s OpenAI. Pomocí metody get_openai_client() klienta projektu ho můžete získat takto:

openai_client = project_client.get_openai_client(api_version="2024-10-21")

Pomocí tohoto objektu chatovacího klienta pak můžete odesílat výzvy k modelům a vracet odpovědi.

Použití sady OpenAI SDK s koncovým bodem Azure OpenAI

Sada OpenAI SDK je oficiální klientská knihovna pro volání rozhraní OpenAI API. Zpracovává požadavky HTTP, ověřování, opakování a analýzu odpovědí. Sada SDK funguje s modely hostovanými v OpenAI, nasazeními Azure OpenAI a modely Foundry se stejnými vzory.

Instalace sady SDK

Pokud chcete použít knihovnu OpenAI v Pythonu, nainstalujte balíček Openai z PyPI spolu s podpůrnými balíčky:

pip install openai azure-identity

Poznámka:

Balíček azure-identity se vyžaduje, pokud máte v úmyslu použít ověřování na základě tokenu pro připojení ke koncovému bodu pomocí přihlašovacích údajů Microsoft Entra ID.

Připojení ke koncovému bodu Azure OpenAI

Každý projekt Foundry obsahuje koncový bod Azure OpenAI, který najdete na stránce Přehled projektu na portálu Foundry na adrese https://ai.azure.com.

Koncový bod Azure OpenAI se řídí tímto formátem:

https://{resource-name}.openai.azure.com/openai/v1

Vytvořte klienta OpenAI s koncovým bodem a přihlašovacími údaji Azure:

from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

openai_client = OpenAI(  
  base_url = "https://{resource-name}.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

Kromě Microsoft Entra ID (doporučeno) můžete provést ověření pomocí klíče rozhraní API nebo proměnných prostředí.

Ověřování klíče rozhraní API:

import os
from openai import OpenAI

openai_client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)

Důležité

Používejte klíče rozhraní API s opatrností. Bezpečně je ukládejte ve službě Azure Key Vault a nikdy je nezahrnujte přímo do kódu.

Proměnné prostředí:

Pokud nastavíte proměnné prostředí OPENAI_BASE_URL a OPENAI_API_KEY, klient je použije automaticky.

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Bez ohledu na to, jak se rozhodnete ověřit, klient OpenAI zpracovává operace odvozování modelů. Použijte ho pro:

• Generování odpovědí pomocí rozhraní API pro odpovědi
• Dokončování chatu a generování obrázků
• Přístup k přímým modelům Foundry (modely mimo Azure OpenAI)

Použití objektu klienta AzureOpenAI

K chatování s modely prostřednictvím koncového bodu Azure OpenAI v1 byste obecně měli použít objekt klienta OpenAI . Pokud ale potřebujete používat funkce z konkrétní verze rozhraní API Azure OpenAI, máte také možnost vytvořit objekt klienta AzureOpenAI . Pokud chcete vytvořit objekt klienta AzureOpenAI , musíte zadat verzi rozhraní API a koncový bod Azure, například takto:

import os
from openai import AzureOpenAI
    
openai_client = AzureOpenAI(
    azure_endpoint = "https://{resource-name}.openai.azure.com"
    api_key=os.getenv("AZURE_OPENAI_KEY"),  
    api_version="2024-10-21",
)

Volba mezi sadou Foundry SDK a sadou OpenAI SDK

Microsoft Foundry podporuje dva přístupy k vytváření aplikací AI. Každý z nich slouží k různým účelům a porozumění tomu, kdy každý z nich použít, vám pomůže vytvořit správné řešení.

Kdy použít sadu Foundry SDK (Software Development Kit)

Sadu Foundry SDK použijte, když vaše aplikace potřebuje funkce specifické pro Foundry:

• Služba Foundry Agent pro vytváření a správu agentů AI
• Pracovní postupy volání a schvalování nástrojů
• Vyhodnocení cloudu pro testování a ověřování odpovědí na AI
• Trasování a pozorovatelnost pro monitorování chování aplikací
• Přímé modely Foundry (modely mimo Azure OpenAI dostupné prostřednictvím katalogu modelů)
• Metadata projektu, připojení a řízení

Microsoft doporučuje sadu Foundry SDK při vytváření aplikací pomocí agentů, vyhodnocení nebo funkcí specifických pro Foundry.

Kdy použít sadu OpenAI SDK

Sadu OpenAI SDK použijte v případě, že potřebujete maximální kompatibilitu s rozhraním OpenAI API:

• Úplná kompatibilita rozhraní OPENAI API pro stávající kód a nástroje
• Přenositelnost mezi nasazeními OpenAI a Azure OpenAI
• Dokončování chatu, odpovědi a obrázky Rozhraní api
• Minimální závislost na konceptech specifických pro Foundry

Sada OpenAI SDK je ideální pro úlohy odvozování modelů, ve kterých chcete, aby stávající kód OpenAI fungoval s minimálními změnami. Tento přístup ale neposkytuje funkce specifické pro Foundry, jako jsou agenti nebo hodnocení.

Microsoft Foundry poskytuje flexibilitu při vytváření aplikací AI. Používejte sadu Foundry SDK s AIProjectClient, když potřebujete funkce na úrovni projektu, jako jsou agenti, vyhodnocení, trasování a připojení. Sadu OpenAI SDK použijte v případě, že potřebujete jednoduchou odvozování modelu s maximální kompatibilitou OpenAI. Obě sady SDK pracují s koncovým bodem projektu Foundry, takže je můžete v aplikacích kombinovat podle potřeby. Obě sady SDK můžete také použít společně ve stejné aplikaci – Sadu Foundry SDK pro funkce projektu a sadu OpenAI SDK pro odvozování modelů.