Uç nokta ve SDK seçme

Tamamlandı

Tavsiye

Daha fazla ayrıntı için Metin ve resimler sekmesine bakın!

Microsoft Foundry, üretken yapay zeka sohbet uygulamaları geliştirmek için esneklik sağlar. Geliştirmeye başlamadan önce, kullanılabilen seçenekleri ve bunların hangilerini kullanacağınıza nasıl karar verebileceğinizi anlamanız önemlidir. Uygulama geliştirmek için dikkat edilmesi gereken bazı noktalar şunlardır:

• Uç noktalar: Microsoft Foundry projeleri, istemci uygulamalarından model dağıtımları gibi proje varlıklarına bağlanmak ve bunları kullanmak için kullanabileceğiniz iki uç nokta sağlar. Her projenin hem Proje uç noktası hem de Azure OpenAI uç noktası vardır.
• İstemci SDK'sı: Seçtiğiniz uç noktaya bağlı olarak, üretken bir yapay zeka sohbet uygulaması geliştirmek için Microsoft Foundry SDK'sını veya OpenAI SDK'sını kullanmayı seçebilirsiniz. Her iki SDK da modellere istem gönderebilen OpenAI API uyumlu bir istemci nesnesini destekler, ancak her SDK'daki belirli işlevlerde bazı farklılıklar vardır.
• Kimlik doğrulaması: Kullanmayı seçtiğiniz uç noktaya ve SDK'ya bağlı olarak, bir istemci uygulamasının varlıklara erişim izni vermek için Foundry tarafından kimliğini doğrulamanın birden çok yolu vardır. Genel olarak üretim uygulamaları, uygulamanın belirli bir kimlik bağlamında çalışmasını gerektiren Microsoft Entra Id kimlik doğrulamasını kullanmalıdır; ancak bazı senaryolarda anahtar tabanlı veya belirteç tabanlı kimlik doğrulaması da kullanabilirsiniz.
• Sohbet API'si: OpenAI istemci API'si iki sohbet API'sini destekler: ChatCompletions ve Responses. Çoğu yeni geliştirme projesi için Yanıtlar API'sinin kullanılması önerilse de , ChatCompletions API'si birçok üretken yapay zeka modeli ve platformunda iyi kurulmuş ve uyumludur.

Kullanılabilir uç noktaları, istemci SDK'larını ve kimlik doğrulama yöntemlerini göz önünde bulundurarak başlayalım. Yanıtları ve ChatCompletions API'lerini daha sonra keşfedeceğiz.

Proje uç noktasıyla DökümHANE SDK'sını kullanma

Microsoft Foundry SDK'sı, REST API ve dile özgü istemci kitaplıkları aracılığıyla projelerinizdeki kaynaklara program aracılığıyla erişim sağlar; Dahil:

• Python için Azure AI Projeleri
• Microsoft .NET için Azure AI Projeleri
• JavaScript için Azure AI Projeleri

Uyarı

Bu modülde yaygın görevler için Python kod örnekleri kullanılmaktadır. Tercih ettiğiniz dilde eşdeğer kod için dile özgü SDK belgelerine başvurabilirsiniz. Her SDK bağımsız olarak geliştirilir ve korunur, bu nedenle bazı işlevler uygulamanın farklı aşamalarında olabilir.

SDK'yi yükleme

Python'da Azure AI Projeleri kitaplığını kullanmak için pypi'den azure-ai-projects paketini ve destekleyici paketleri yükleyin:

pip install azure-ai-projects azure-identity openai

Uyarı

Bir sohbet uygulaması geliştirmek için Foundry SDK'sını kullanırken OpenAI SDK paketini de içeri aktarmanız gerekir. Foundry SDK'sı içindeki sohbet istemcisi işlevselliği OpenAI SDK'sından türetilir.

Proje uç noktasına bağlanma

Her bir Dökümhane projesinin, Dökümhane portalındaki Genel Bakış sayfasında bulabileceğiniz benzersiz bir uç noktası vardır.

project uç noktası şu biçimi izler:

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

AIProjectClient nesnesi oluşturmak için bu uç noktayı kullanın:

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
)

Uyarı

Kod, kimlik doğrulaması için varsayılan Azure kimlik bilgilerini kullanır. Bu kimlik doğrulamasını etkinleştirmek için azure-identity paketini yüklemeniz gerekir (daha önce yükleme komutunda gösterilmiştir).

Tavsiye

Projeye başarıyla erişmek için kodun kimliği doğrulanmış bir Azure oturumunda çalıştırılması gerekir. Örneğin, kodu çalıştırmadan önce oturum açmak için Azure CLI az login komutunu kullanabilirsiniz.

Proje istemcisi (AIProjectClient), OpenAI eşdeğerleri olmayan Foundry yerel işlemlerine erişim sağlar. project istemcisini kullanarak:

• Kaynak bağlantılarını alma
• Proje yapılandırmasına erişme
• İzlemeyi etkinleştir
• Veri kümelerini ve dizinleri yönetme

Sohbet istemcisi oluşturma

Foundry projenizdeki bir modelle sohbet etmek için OpenAI uyumlu bir istemci nesnesine ihtiyacınız vardır. Proje istemcisinin get_openai_client() yöntemini kullanarak aşağıdaki gibi bir yöntem edinebilirsiniz:

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

Ardından bu sohbet istemcisi nesnesini kullanarak modellere istem gönderebilir ve yanıt döndürebilirsiniz.

OpenAI SDK'sını Azure OpenAI uç noktasıyla kullanma

OpenAI SDK'sı, OpenAI API'sini çağırmak için kullanılan resmi istemci kitaplığıdır. HTTP isteklerini, kimlik doğrulamasını, yeniden denemeleri ve yanıt ayrıştırma işlemlerini işler. SDK, OpenAI tarafından barındırılan modellerle, Azure OpenAI dağıtımlarıyla ve Aynı desenleri kullanan Foundry modelleriyle çalışır.

SDK'yi yükleme

Python'da OpenAI kitaplığını kullanmak için openai paketini PyPI'dan ve destekleyici paketleriyle birlikte yükleyin:

pip install openai azure-identity

Uyarı

Microsoft Entra Id kimlik bilgilerini kullanarak uç noktaya bağlanmak için belirteç tabanlı kimlik doğrulaması kullanmak istiyorsanız azure-identity paketi gereklidir.

Azure OpenAI uç noktasına bağlanma

Her Foundry projesinde, konumundaki Foundry portalında projenin https://ai.azure.com sayfasında bulabileceğiniz bir Azure OpenAI uç noktası bulunur.

Azure OpenAI uç noktası şu biçimi izler:

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

Uç noktanız ve Azure kimlik bilgilerinizle bir OpenAI istemcisi oluşturun:

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'ye (önerilen) ek olarak, API anahtarı veya ortam değişkenleri kullanarak kimlik doğrulaması yapabilirsiniz.

API anahtarı kimlik doğrulaması:

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

Önemli

API anahtarlarını dikkatli kullanın. Bunları Azure Key Vault'ta güvenli bir şekilde depolayın ve hiçbir zaman doğrudan kodunuza eklemeyin.

Ortam değişkenleri:

OPENAI_BASE_URL ve OPENAI_API_KEY ortam değişkenlerini ayarlarsanız, istemci bunları otomatik olarak kullanır.

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Kimlik doğrulamayı nasıl seçerseniz seçin, OpenAI istemcisi model çıkarım işlemlerini işler. Aşağıdakiler için kullanın:

• Yanıtlar API'siyle yanıt oluşturma
• Sohbet tamamlamaları ve görüntü oluşturma
• Foundry doğrudan modellerine erişme (Azure OpenAI olmayan modeller)

AzureOpenAI istemci nesnesi kullanma

Genellikle Azure OpenAI v1 uç noktası üzerinden modellerle sohbet etmek için OpenAI istemci nesnesini kullanmanız gerekir. Bununla birlikte, Azure OpenAI API'sinin belirli bir sürümündeki işlevleri kullanmanız gerekiyorsa bir AzureOpenAI istemci nesnesi oluşturma seçeneğiniz de vardır. AzureOpenAI istemci nesnesi oluşturmak için API sürümünü ve Azure uç noktasını şöyle belirtmeniz gerekir:

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

DökümHANE SDK'sı ile OpenAI SDK'sı arasında seçim

Microsoft Foundry, yapay zeka uygulamaları oluşturmaya yönelik iki yaklaşımı destekler. Her biri farklı amaçlara hizmet eder ve her birinin ne zaman kullanılacağını anlamak doğru çözümü oluşturmanıza yardımcı olur.

Foundry SDK'sı ne zaman kullanılır?

Uygulamanızın Foundry'ye özgü özelliklere ihtiyacı olduğunda Foundry SDK'sını kullanın:

• Yapay zeka aracıları oluşturmak ve yönetmek için Döküm Aracı Hizmeti
• Araç çağırma ve onay iş akışları
• Yapay zeka yanıtlarını test etmek ve doğrulamak için bulut değerlendirmeleri
• İzleme ve gözlemlenebilirlik ile uygulama davranışını izleme
• Dökümhane doğrudan modelleri (Azure OpenAI olmayan modeller model kataloğu aracılığıyla kullanılabilir)
• Proje meta verileri, bağlantılar ve idare özellikleri

Microsoft aracılar, değerlendirmeler veya Foundry'ye özgü özelliklerle uygulama oluştururken Foundry SDK'sını önerir.

OpenAI SDK'sı ne zaman kullanılır?

OpenAI API'siyle maksimum uyumluluk gerekiyorsa OpenAI SDK'sını kullanın:

• Mevcut kod ve araçlar için tam OpenAI API uyumluluğu
• OpenAI ile Azure OpenAI dağıtımları arasında taşınabilirlik
• Sohbet Tamamlamaları, Yanıtlar ve Görüntüler Apı 'leri
• Foundry'ye özgü kavramlara en az bağımlılık

OpenAI SDK'sı, mevcut OpenAI kodunun en az değişiklikle çalışmasını istediğiniz model çıkarım iş yükleri için idealdir. Ancak bu yaklaşım aracılar veya değerlendirmeler gibi Foundry'ye özgü özellikler sağlamaz.

Microsoft Foundry, yapay zeka uygulamaları oluşturma konusunda size esneklik sağlar. Proje düzeyinde, aracılar, değerlendirmeler, izleme ve bağlantılar gibi özelliklere ihtiyacınız olduğunda Döküm SDK'sını AIProjectClient ile kullanın. En yüksek OpenAI uyumluluğuna sahip basit model çıkarımına ihtiyacınız olduğunda OpenAI SDK'sını kullanın. Her iki SDK da Foundry proje uç noktanızla birlikte çalışarak uygulamalarınızda gerektiğinde bunları birleştirebilirsiniz. Ayrıca her iki SDK'yı da aynı uygulamada birlikte kullanabilirsiniz: proje özellikleri için Döküm SDK'sı ve model çıkarımı için OpenAI SDK.