نمونه ۰۲: یکپارچه‌سازی SDK OpenAI

نمایش یکپارچه‌سازی پیشرفته با SDK پایتون OpenAI، پشتیبانی از Foundry Local مایکروسافت و Azure OpenAI با پاسخ‌های استریم و مدیریت صحیح خطا.

مرور کلی

این نمونه موارد زیر را نشان می‌دهد:

• تغییر بدون مشکل بین Foundry Local و Azure OpenAI
• تکمیل چت استریم برای تجربه بهتر کاربر
• استفاده صحیح از SDK FoundryLocalManager
• مدیریت خطاهای قوی و مکانیزم‌های جایگزین
• الگوهای کدنویسی آماده برای تولید

پیش‌نیازها

• Foundry Local: نصب شده و در حال اجرا (برای استنتاج محلی)
• پایتون: نسخه ۳.۸ یا بالاتر با SDK OpenAI
• Azure OpenAI: نقطه پایانی معتبر و کلید API (برای استنتاج ابری)

نصب

۱. راه‌اندازی محیط پایتون:

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

۲. نصب وابستگی‌ها:

pip install -r requirements.txt

۳. شروع Foundry Local (برای حالت محلی):

foundry model run phi-4-mini

سناریوهای استفاده

Foundry Local (پیش‌فرض)

گزینه ۱: استفاده از FoundryLocalManager (توصیه‌شده)

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

گزینه ۲: پیکربندی دستی

# 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

معماری کد

الگوی کارخانه کلاینت

این نمونه از الگوی کارخانه برای ایجاد کلاینت‌های مناسب استفاده می‌کند:

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

پاسخ‌های استریم

این نمونه استریم را برای تولید پاسخ‌های بلادرنگ نشان می‌دهد:

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)

متغیرهای محیطی

پیکربندی Foundry Local

متغیر	توضیحات	پیش‌فرض	ضروری
MODEL	نام مستعار مدل برای استفاده	phi-4-mini	خیر
BASE_URL	نقطه پایانی Foundry Local	http://localhost:8000	خیر
API_KEY	کلید API (اختیاری برای حالت محلی)	""	خیر

پیکربندی Azure OpenAI

متغیر	توضیحات	پیش‌فرض	ضروری
AZURE_OPENAI_ENDPOINT	نقطه پایانی منبع Azure OpenAI	-	بله
AZURE_OPENAI_API_KEY	کلید API Azure OpenAI	-	بله
AZURE_OPENAI_API_VERSION	نسخه API	2024-08-01-preview	خیر
MODEL	نام استقرار Azure	your-deployment-name	بله

ویژگی‌های پیشرفته

کشف خودکار سرویس

این نمونه به‌طور خودکار سرویس مناسب را بر اساس متغیرهای محیطی تشخیص می‌دهد:

۱. حالت Azure: اگر AZURE_OPENAI_ENDPOINT و AZURE_OPENAI_API_KEY تنظیم شده باشند ۲. حالت SDK Foundry: اگر SDK Foundry Local در دسترس باشد ۳. حالت دستی: بازگشت به پیکربندی دستی

مدیریت خطا

• بازگشت بدون مشکل از SDK به پیکربندی دستی
• پیام‌های خطای واضح برای رفع اشکال
• مدیریت صحیح استثناها برای مشکلات شبکه
• اعتبارسنجی متغیرهای محیطی ضروری

ملاحظات عملکرد

مزایا و معایب محلی در مقابل ابری

مزایای Foundry Local:

• ✅ بدون هزینه API
• ✅ حفظ حریم خصوصی داده‌ها (هیچ داده‌ای دستگاه را ترک نمی‌کند)
• ✅ تأخیر کم برای مدل‌های پشتیبانی‌شده
• ✅ کارکرد آفلاین

مزایای Azure OpenAI:

• ✅ دسترسی به مدل‌های بزرگ جدید
• ✅ توان عملیاتی بالاتر
• ✅ بدون نیاز به محاسبات محلی
• ✅ SLA در سطح سازمانی

رفع اشکال

مشکلات رایج

۱. هشدار "امکان استفاده از SDK Foundry وجود ندارد":

pip install foundry-local-sdk

۲. خطاهای احراز هویت Azure:

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

۳. مدل در دسترس نیست:

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

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

بررسی سلامت

# 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"

مراحل بعدی

• نمونه ۰۳: کشف مدل و ارزیابی عملکرد
• نمونه ۰۴: ساخت یک برنامه Chainlit RAG
• نمونه ۰۵: هماهنگی چند عامل
• نمونه ۰۶: مسیریابی مدل‌ها به‌عنوان ابزار

منابع

• مستندات Azure OpenAI
• مرجع SDK Foundry Local
• مستندات SDK پایتون OpenAI
• راهنمای تکمیل‌های استریم

---