Välj en slutpunkt och SDK

Slutförd

Microsoft Foundry ger flexibilitet för att utveckla generativa AI-chattprogram. Innan du börjar utveckla är det viktigt att du förstår vilka alternativ som är tillgängliga och hur du bestämmer vilka av dem som ska användas. Några saker att tänka på när du utvecklar ett program är:

• Slutpunkter: Microsoft Foundry-projekt tillhandahåller två slutpunkter som du kan använda för att ansluta till och använda projekttillgångar, till exempel modelldistributioner, från klientprogram. Varje projekt har både en projektslutpunkt och en Azure OpenAI-slutpunkt.
• Klient-SDK: Beroende på vilken slutpunkt du väljer kan du välja att använda Microsoft Foundry SDK eller OpenAI SDK för att utveckla ett generativt AI-chattprogram. Båda SDK:erna stöder ett OpenAI API-kompatibelt klientobjekt som kan skicka uppmaningar till modeller, men det finns vissa skillnader i de specifika funktioner som är tillgängliga i varje SDK.
• Autentisering: Beroende på vilken slutpunkt och SDK du väljer att använda finns det flera sätt som ett klientprogram kan autentiseras av Foundry för att beviljas åtkomst till tillgångar. I allmänhet bör produktionsprogram använda Microsoft Entra-ID-autentisering , vilket kräver att programmet körs i kontexten för en specifik identitet. men i vissa scenarier kan du också använda nyckelbaserad eller tokenbaserad autentisering.
• Chatt-API: OpenAI-klient-API:et stöder två chatt-API:er: ChatCompletions och Responses. Svars-API:et rekommenderas för de flesta nya utvecklingsprojekt, men ChatCompletions API är väletablerat och kompatibelt för många generativa AI-modeller och plattformar.

Vi börjar med att överväga tillgängliga slutpunkter, klient-SDK:er och autentiseringsmetoder – vi utforskar API:erna Svar och ChatCompletions senare.

Använda Foundry SDK med projektslutpunkten

Microsoft Foundry SDK ger programmatisk åtkomst till resurser i dina projekt via ett REST API och språkspecifika klientbibliotek. Inklusive:

• Azure AI-projekt för Python
• Azure AI-projekt för Microsoft .NET
• Azure AI Projects för JavaScript

Anmärkning

Den här modulen använder Python-kodexempel för vanliga uppgifter. Du kan läsa den språkspecifika SDK-dokumentationen för motsvarande kod på önskat språk. Varje SDK utvecklas och underhålls oberoende av varandra, så vissa funktioner kan finnas i olika skeden av implementeringen.

Installera SDK:t

Om du vill använda biblioteket Azure AI Projects i Python installerar du paketet azure-ai-projects från PyPI tillsammans med stödpaket:

pip install azure-ai-projects azure-identity openai

Anmärkning

När du använder Foundry SDK för att utveckla ett chattprogram måste du också importera OpenAI SDK-paketet – chattklientfunktionerna i Foundry SDK härleds från OpenAI SDK.

Ansluta till projektslutpunkten

Varje Foundry-project har en unik slutpunkt som du hittar på sidan project Overview i Foundry-portalen på https://ai.azure.com.

Projektets slutpunkt följer det här formatet:

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

Använd den här slutpunkten för att skapa ett AIProjectClient-objekt :

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
)

Anmärkning

Koden använder standardautentiseringsuppgifter för Azure för att autentisera. Om du vill aktivera den här autentiseringen måste du installera paketet azure-identity (visas i installationskommandot tidigare).

Tips/Råd

För att få tillgång till projektet måste koden köras i en autentiserad Azure-session. Du kan till exempel använda kommandot Azure CLI az login för att logga in innan du kör koden.

Projektklienten (AIProjectClient) ger åtkomst till Foundry-inbyggda åtgärder som inte har OpenAI-motsvarigheter. Använd project-klienten för att:

• Hämta resursanslutningar
• Åtkomst till projektkonfiguration
• Aktivera spårning
• Hantera datauppsättningar och index

Skapa en chattklient

Om du vill chatta med en modell i ditt Foundry-projekt behöver du ett OpenAI-kompatibelt klientobjekt. Du kan använda metoden get_openai_client() för projektklienten för att hämta en, så här:

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

Du kan sedan använda det här chattklientobjektet för att skicka frågor till modeller och returnera svar.

Använda OpenAI SDK med Azure OpenAI-slutpunkten

OpenAI SDK är det officiella klientbiblioteket för att anropa OpenAI API. Den hanterar HTTP-begäranden, autentisering, återförsök och svarsparsing. SDK:et fungerar med OpenAI-hostade modeller, Azure OpenAI-implementeringar och Foundry-modeller med samma mönster.

Installera SDK:t

Om du vill använda OpenAI-biblioteket i Python installerar du openai-paketet från PyPI tillsammans med stödpaket:

pip install openai azure-identity

Anmärkning

Azure-identitetspaketet krävs om du tänker använda tokenbaserad autentisering för att ansluta till slutpunkten med autentiseringsuppgifter för Microsoft Entra-ID.

Ansluta till Azure OpenAI-slutpunkten

Varje Foundry-projekt innehåller en Azure OpenAI-slutpunkt som du hittar på projektets översiktssida i Foundry-portalen på https://ai.azure.com.

Azure OpenAI-slutpunkten följer det här formatet:

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

Skapa en OpenAI-klient med dina slutpunkter och Azure-autentiseringsuppgifter:

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

Förutom Microsoft Entra-ID (rekommenderas) kan du autentisera med hjälp av en API-nyckel eller miljövariabler.

API-nyckelautentisering:

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/"
)

Viktigt!

Använd API-nycklar med försiktighet. Lagra dem säkert i Azure Key Vault och inkludera dem aldrig direkt i koden.

Miljövariabler:

Om du anger OPENAI_BASE_URL och OPENAI_API_KEY miljövariabler använder klienten dem automatiskt:

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Oavsett hur du väljer att autentisera hanterar OpenAI-klienten modellinferensåtgärder. Använd den för:

• Generera svar med svars-API:et
• Chattavslut och bildgenerering
• Åtkomst till Foundry-direktmodeller (icke-Azure OpenAI-modeller)

Använda ett AzureOpenAI-klientobjekt

Du bör vanligtvis använda OpenAI-klientobjektet för att chatta med modeller via Azure OpenAI v1-slutpunkten. Du kan dock också skapa ett AzureOpenAI-klientobjekt om du behöver använda funktioner från en specifik version av Azure OpenAI API. Om du vill skapa ett AzureOpenAI-klientobjekt måste du ange API-versionen och Azure-slutpunkten, så här:

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

Välja mellan Foundry SDK och OpenAI SDK

Microsoft Foundry har stöd för två metoder för att skapa AI-program. Var och en har olika syften och att förstå när var och en ska användas hjälper dig att skapa rätt lösning.

När du ska använda Foundry SDK

Använd Foundry SDK när ditt program behöver Foundry-specifika funktioner:

• Foundry Agent Service för att skapa och hantera AI-agenter
• Arbetsflöden för anrop och godkännande av verktyg
• Molnutvärderingar för testning och validering av AI-svar
• Spårning och observerbarhet för övervakning av programbeteende
• Foundry-direktmodeller (icke-Azure OpenAI-modeller tillgängliga via modellkatalogen)
• Projektmetadata, anslutningar och styrningsfunktioner

Microsoft rekommenderar Foundry SDK när du skapar appar med agenter, utvärderingar eller Foundry-specifika funktioner.

När du ska använda OpenAI SDK

Använd OpenAI SDK när du behöver maximal kompatibilitet med OpenAI-API:et:

• Fullständig OpenAI API-kompatibilitet för befintlig kod och verktyg
• Portabilitet mellan OpenAI- och Azure OpenAI-distributioner
• Chattavslutningar: svar och bilder API
• Minimalt beroende av Foundry-specifika begrepp

OpenAI SDK är perfekt för modellinferensarbetsbelastningar där du vill att befintlig OpenAI-kod ska fungera med minimala ändringar. Den här metoden tillhandahåller dock inte Foundry-specifika funktioner som agenter eller utvärderingar.

Microsoft Foundry ger dig flexibilitet i hur du skapar AI-program. Använd Foundry SDK med AIProjectClient när du behöver funktioner på projektnivå som agenter, utvärderingar, spårning och anslutningar. Använd OpenAI SDK när du behöver enkel modellinferens med maximal OpenAI-kompatibilitet. Båda SDK:erna fungerar med slutpunkten för Foundry-projektet, så att du kan kombinera dem efter behov i dina program. Du kan också använda båda SDK:erna tillsammans i samma program – Foundry SDK för projektfunktioner och OpenAI SDK för modellinferens.