Valitse päätepiste ja SDK

Valmis

Microsoft Foundry tarjoaa joustavuutta generatiivisten tekoälychat-sovellusten kehittämiseen. Ennen kehityksen aloittamista on tärkeää ymmärtää saatavilla olevat vaihtoehdot ja päättää, mitä niistä kannattaa käyttää. Joihinkin huomioon otettavia seikkoja sovelluksen kehittämisessä ovat:

• Päätepisteet: Microsoft Foundryn projektit tarjoavat kaksi päätepistettä, joiden avulla voit yhdistää ja käyttää projektiresursseja, kuten mallin käyttöönottoja, asiakassovelluksista. Jokaisella projektilla on sekä Projectin päätepiste että Azure OpenAI -päätepiste.
• Asiakas SDK: Valitsemastasi päätepisteestä riippuen voit valita Microsoft Foundry SDK :n tai OpenAI SDK :n kehittääksesi generatiivisen tekoälychat-sovelluksen. Molemmat SDK:t tukevat OpenAI API -yhteensopivaa asiakasobjektia, joka voi lähettää malleille kehotuksia, mutta kunkin SDK:n erityistoiminnallisuudessa on joitakin eroja.
• Tunnistautuminen: Päätepisteestä ja SDK:sta riippuen Foundry voi todentaa asiakassovelluksen useilla tavoilla, jotta se saa pääsyn assetteihin. Yleisesti tuotantosovellusten tulisi käyttää Microsoft Entra ID -tunnistautumista, joka edellyttää, että sovellus toimii tietyn identiteetin kontekstissa; Mutta joissain tapauksissa voit käyttää myös avain - tai token-pohjaista tunnistautumista.
• Chat API: OpenAI-asiakasrajapinta tukee kahta chat-rajapintaa: ChatCompletions ja Responses. Vaikka Responses-rajapintaa suositellaan useimpiin uusiin kehitysprojekteihin, ChatCompletions-rajapinta on hyvin vakiintunut ja yhteensopiva monien generatiivisten tekoälymallien ja alustojen kesken.

Aloitetaan tarkastelemalla käytettävissä olevia päätepisteitä, asiakas-SDK:ta ja tunnistautumismenetelmiä – tutustumme myöhemmin Responses- ja ChatCompletions-rajapintoihin.

Foundry SDK:n käyttö projektin päätepisteen kanssa

Microsoft Foundry SDK tarjoaa ohjelmallisen pääsyn projektiesi resursseihin REST-rajapinnan ja kielikohtaisten asiakaskirjastojen kautta; mukaan lukien:

• Azure AI-projektit Pythonille
• Azure tekoälyprojektit Microsoft .NET
• Azure AI-projektit JavaScriptille

Muistio

Tämä moduuli käyttää Python-koodiesimerkkejä yleisiin tehtäviin. Voit katsoa kielikohtaista SDK-dokumentaatiota saadaksesi vastaavaa koodia haluamallasi kielellä. Jokainen SDK kehitetään ja ylläpidetään itsenäisesti, joten jotkut toiminnot voivat olla eri toteutusvaiheissa.

SDK:n asennus

Pythonin Azure AI Projects -kirjaston käyttämiseksi asenna PyPI:n azure-ai-projects-paketti sekä tukevat paketit:

pip install azure-ai-projects azure-identity openai

Muistio

Kun käytät Foundry SDK:ta chat-sovelluksen kehittämiseen, sinun täytyy myös tuoda OpenAI SDK -paketti – Foundry SDK:n chat-asiakastoiminnallisuus on johdettu OpenAI SDK:sta.

Yhdistäminen projektin päätepisteeseen

Jokaisella Foundryn project:llä on ainutlaatuinen päätepiste, jonka löydät project:n Overview -sivulta Foundry-portaalissa https://ai.azure.com.

Projectin päätepiste noudattaa tätä muotoa:

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

Käytä tätä päätepistettä luodaksesi AIProjectClient-objektin :

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
)

Muistio

Koodi käyttää oletus-Azure-tunnuksia todennukseen. Tämän tunnistautumisen mahdollistamiseksi sinun täytyy asentaa azure-identity-paketti (joka näkyy aiemmin asennuskomennossa).

Vinkki

Jotta projektiin pääsee access onnistuneesti, koodin on suoritettava autendikoidussa Azure-istunnossa. Esimerkiksi voit käyttää Azure CLI az login-komentoa kirjautuaksesi sisään ennen koodin suorittamista.

Projektiasiakas (AIProjectClient) tarjoaa pääsyn Foundry-natiivitoimintoihin, joilla ei ole OpenAI-vastineita. Käytä project-asiakasta:

• Resurssiyhteyksien hakeminen
• Access-projektin konfiguraatio
• Ota jäljitys käyttöön
• Hallinnoi aineistoja ja indeksejä

Chat-asiakasohjelman luominen

Jotta voit keskustella mallin kanssa Foundry-projektissasi, tarvitset OpenAI-yhteensopivan asiakasobjektin. Voit käyttää projektiasiakkaan get_openai_client() -menetelmää saadaksesi sellaisen, kuten näin:

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

Voit sitten käyttää tätä chat-asiakasobjektia lähettääksesi malleille kehotuksia ja palauttaaksesi vastauksia.

OpenAI SDK:n käyttö Azure OpenAI -päätepisteen kanssa

OpenAI SDK on virallinen asiakaskirjasto OpenAI API:n kutsumiseen. Se hoitaa HTTP-pyynnöt, todennuksen, kokeilut ja vastausten jäsennyksen. SDK toimii OpenAI:n isännöimien mallien, Azure OpenAI -käyttöönottojen ja Foundry-mallien kanssa käyttäen samoja malleja.

SDK:n asennus

OpenAI-kirjaston käyttämiseksi Pythonissa asenna PyPI:n openai-paketti sekä tukipaketit:

pip install openai azure-identity

Muistio

Azure-identity -paketti on välttämätön, jos aiot käyttää token-pohjaista tunnistautumista yhdistääksesi päätepisteeseen Microsoft Entra ID -tunnuksia.

Yhdistäminen Azure OpenAI -päätepisteeseen

Jokaisessa Foundry-projektissa on Azure OpenAI -päätepiste, jonka löydät projektin Yleiskatsaussivulta Foundry-portaalissa osoitteessa .https://ai.azure.com

Azure OpenAI:n päätepiste noudattaa tätä muotoa:

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

Luo OpenAI-asiakasohjelma päätepisteesi ja Azure-tunnisteillasi:

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

Microsoft Entra ID:n (suositeltava) lisäksi voit tunnistautua API-avaimella tai ympäristömuuttujilla.

API-avaimen tunnistautuminen:

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

Tärkeää

Käytä API-avaimia varovasti. Säilytä ne turvallisesti Azure Key Vaultissa äläkä koskaan sisällytä niitä suoraan koodiisi.

Ympäristömuuttujat:

Jos asetat OPENAI_BASE_URL ja OPENAI_API_KEY ympäristömuuttujat, asiakas käyttää niitä automaattisesti:

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Riippumatta siitä, miten päätät tunnistautua, OpenAI-asiakas hoitaa mallipäättelytoiminnot. Käytä sitä seuraaviin tarkoituksiin:

• Vastausten tuottaminen Responses API:lla
• Chatin täydentäminen ja kuvanluonti
• Accessing Foundry direct models (ei-Azure OpenAI-mallit)

AzureOpenAI-asiakasobjektin käyttö

Yleensä kannattaa käyttää OpenAI-asiakasobjektia keskustellessaan mallien kanssa Azure OpenAI v1 -päätepisteen kautta. Sinulla on kuitenkin myös mahdollisuus luoda AzureOpenAI-asiakasobjekti , jos tarvitset toiminnallisuutta tietystä Azure OpenAI API:n versiosta. AzureOpenAI-asiakasobjektin luomiseksi sinun täytyy määritellä API-versio ja Azure-päätepiste, kuten näin:

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

Valinta Foundry SDK:n ja OpenAI SDK:n välillä

Microsoft Foundry tukee kahta lähestymistapaa tekoälysovellusten rakentamiseen. Jokainen palvelee eri tarkoituksia, ja ymmärtäminen, milloin kutakin kannattaa käyttää, auttaa rakentamaan oikean ratkaisun.

Milloin käyttää Foundryn SDK:ta

Käytä Foundry-SDK:ta, kun sovelluksesi tarvitsee Foundry-kohtaisia ominaisuuksia:

• Foundry Agent Service tekoälyagenttien rakentamiseen ja hallintaan
• Työkalujen käyttö- ja hyväksyntätyönkulut
• Pilviarvioinnit tekoälyvastausten testaamiseksi ja validointiin
• Jäljitys ja havaittavuus sovelluskäyttäytymisen valvonnassa
• Foundry-suorat mallit (ei-Azure OpenAI -mallit, saatavilla malliluettelon kautta)
• Projektin metatiedot, yhteydet ja hallintaominaisuudet

Microsoft suosittelee Foundry SDK:ta sovellusten rakentamiseen, joissa on agentteja, arviointeja tai Foundry-kohtaisia ominaisuuksia.

Milloin käyttää OpenAI SDK:ta

Käytä OpenAI SDK:ta, kun tarvitset maksimaalisen yhteensopivuuden OpenAI API:n kanssa:

• Täysi OpenAI API -yhteensopivuus olemassa olevalle koodille ja työkaluille
• Siirrettävyys OpenAI:n ja Azure OpenAI:n käyttöönottojen välillä
• Chatin täydentäminen, vastaukset ja kuvat API:t
• Minimaalinen riippuvuus Foundry-kohtaisista käsitteistä

OpenAI SDK on ihanteellinen mallipäättelytehtäviin, joissa halutaan olemassa olevan OpenAI-koodin toimivan mahdollisimman vähäisin muutoksin. Tämä lähestymistapa ei kuitenkaan tarjoa Foundry-kohtaisia ominaisuuksia, kuten agentteja tai arviointeja.

Microsoft Foundry antaa joustavuutta tekoälysovellusten rakentamiseen. Käytä Foundry SDK:ta AIProjectClient silloin, kun tarvitset projektitason ominaisuuksia, kuten agentteja, arviointeja, jäljitystä ja yhteyksiä. Käytä OpenAI SDK:ta, kun tarvitset suoraviivaista mallipäättelyä maksimaalisella OpenAI-yhteensopivuudella. Molemmat SDK:t toimivat Foundry-projektin päätepisteen kanssa, joten voit yhdistää ne tarpeen mukaan sovelluksissasi. Voit myös käyttää molempia SDK:ita yhdessä samassa sovelluksessa—Foundry SDK:ta projektin ominaisuuksiin ja OpenAI SDK:ta mallin päättelyyn.