Örnek 02: OpenAI SDK Entegrasyonu

January 29, 2026 · View on GitHub

Microsoft Foundry Local ve Azure OpenAI ile gelişmiş entegrasyonu, akış yanıtları ve doğru hata yönetimini destekleyen bir örnek.

Genel Bakış

Bu örnek şunları sergiler:

Foundry Local ve Azure OpenAI arasında sorunsuz geçiş
Daha iyi kullanıcı deneyimi için akışlı sohbet tamamlama
FoundryLocalManager SDK'nın doğru kullanımı
Güçlü hata yönetimi ve yedekleme mekanizmaları
Üretime hazır kod kalıpları

Ön Koşullar

Foundry Local: Kurulu ve çalışıyor (yerel çıkarım için)
Python: 3.8 veya üstü, OpenAI SDK ile
Azure OpenAI: Geçerli bir uç nokta ve API anahtarı (bulut çıkarımı için)

Kurulum

Python ortamını ayarlayın:

cd Module08
py -m venv .venv
.venv\Scripts\activate

Bağımlılıkları yükleyin:
```
pip install -r requirements.txt
```
Foundry Local'i başlatın (yerel mod için):
```
foundry model run phi-4-mini
```

Kullanım Senaryoları

Foundry Local (Varsayılan)

Seçenek 1: FoundryLocalManager Kullanımı (Önerilen)

# Automatic service discovery and model management
set MODEL=phi-4-mini
python samples\02\sdk_quickstart.py

Seçenek 2: Manuel Yapılandırma

# Manual endpoint configuration
set BASE_URL=http://localhost:8000
set MODEL=phi-4-mini
set API_KEY=
python samples\02\sdk_quickstart.py

Azure OpenAI

# Azure OpenAI configuration
set AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
set AZURE_OPENAI_API_KEY=your-api-key
set AZURE_OPENAI_API_VERSION=2024-08-01-preview
set MODEL=your-deployment-name
python samples\02\sdk_quickstart.py

Kod Mimarisi

İstemci Fabrika Deseni

Örnek, uygun istemcileri oluşturmak için bir fabrika desenini kullanır:

def create_foundry_client():
    """Create Foundry Local client with SDK management."""
    manager = FoundryLocalManager(alias)
    client = OpenAI(
        base_url=manager.endpoint,
        api_key=manager.api_key
    )
    return client, manager.get_model_info(alias).id

def create_azure_client():
    """Create Azure OpenAI client."""
    client = OpenAI(
        base_url=f"{endpoint}/openai",
        api_key=api_key,
        default_query={"api-version": api_version}
    )
    return client, model

Akış Yanıtları

Örnek, gerçek zamanlı yanıt oluşturma için akışı gösterir:

stream = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": prompt}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Ortam Değişkenleri

Foundry Local Yapılandırması

Değişken	Açıklama	Varsayılan	Gerekli
`MODEL`	Kullanılacak model takma adı	`phi-4-mini`	Hayır
`BASE_URL`	Foundry Local uç noktası	`http://localhost:8000`	Hayır
`API_KEY`	API anahtarı (yerel için isteğe bağlı)	`""`	Hayır

Azure OpenAI Yapılandırması

Değişken	Açıklama	Varsayılan	Gerekli
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI kaynak uç noktası	-	Evet
`AZURE_OPENAI_API_KEY`	Azure OpenAI API anahtarı	-	Evet
`AZURE_OPENAI_API_VERSION`	API sürümü	`2024-08-01-preview`	Hayır
`MODEL`	Azure dağıtım adı	`your-deployment-name`	Evet

Gelişmiş Özellikler

Otomatik Hizmet Keşfi

Örnek, ortam değişkenlerine göre uygun hizmeti otomatik olarak algılar:

Azure Modu: AZURE_OPENAI_ENDPOINT ve AZURE_OPENAI_API_KEY ayarlandığında
Foundry SDK Modu: Foundry Local SDK mevcutsa
Manuel Mod: Manuel yapılandırmaya geri dönüş

Hata Yönetimi

SDK'dan manuel yapılandırmaya zarif bir geçiş
Sorun giderme için net hata mesajları
Ağ sorunları için uygun istisna yönetimi
Gerekli ortam değişkenlerinin doğrulanması

Performans Düşünceleri

Yerel ve Bulut Karşılaştırması

Foundry Local Avantajları:

✅ API maliyeti yok
✅ Veri gizliliği (veriler cihazdan çıkmaz)
✅ Desteklenen modeller için düşük gecikme süresi
✅ Çevrimdışı çalışır

Azure OpenAI Avantajları:

✅ En son büyük modellere erişim
✅ Daha yüksek işlem kapasitesi
✅ Yerel hesaplama gereksinimi yok
✅ Kurumsal düzeyde SLA

Sorun Giderme

Yaygın Sorunlar

"Foundry SDK kullanılamadı" uyarısı:
```
pip install foundry-local-sdk
```

Azure kimlik doğrulama hataları:

# Verify your endpoint format
echo %AZURE_OPENAI_ENDPOINT%
# Should be: https://your-resource.openai.azure.com

Model mevcut değil:

# For Foundry Local
foundry model list
foundry model run your-model-name

# For Azure OpenAI
# Check your deployment name in Azure Portal

Sağlık Kontrolleri

# Foundry Local
foundry service status
curl http://localhost:8000/v1/models

# Azure OpenAI
curl -H "api-key: %AZURE_OPENAI_API_KEY%" "%AZURE_OPENAI_ENDPOINT%/openai/deployments?api-version=2024-08-01-preview"

Sonraki Adımlar

Örnek 03: Model keşfi ve performans testi
Örnek 04: Chainlit RAG uygulaması oluşturma
Örnek 05: Çoklu ajan orkestrasyonu
Örnek 06: Araç olarak modeller yönlendirme