جلسه ۱: شروع به کار با Foundry Local

January 29, 2026 · View on GitHub

مرور کلی

Microsoft Foundry Local قابلیت‌های Azure AI Foundry را مستقیماً به محیط توسعه ویندوز ۱۱ شما می‌آورد و امکان توسعه هوش مصنوعی با حفظ حریم خصوصی، تأخیر کم و ابزارهای سطح سازمانی را فراهم می‌کند. این جلسه شامل نصب کامل، پیکربندی و اجرای عملی مدل‌های محبوب از جمله phi، qwen، deepseek و GPT-OSS-20B است.

اهداف آموزشی

تا پایان این جلسه، شما:

Foundry Local را روی ویندوز ۱۱ نصب و پیکربندی خواهید کرد
دستورات CLI و گزینه‌های پیکربندی را به خوبی یاد خواهید گرفت
استراتژی‌های کش مدل برای عملکرد بهینه را درک خواهید کرد
مدل‌های phi، qwen، deepseek و GPT-OSS-20B را با موفقیت اجرا خواهید کرد
اولین برنامه هوش مصنوعی خود را با استفاده از Foundry Local ایجاد خواهید کرد

پیش‌نیازها

الزامات سیستم

ویندوز ۱۱: نسخه 22H2 یا بالاتر
رم: حداقل ۱۶ گیگابایت، توصیه شده ۳۲ گیگابایت
فضای ذخیره‌سازی: ۵۰ گیگابایت فضای آزاد برای مدل‌ها و کش
سخت‌افزار: دستگاه مجهز به NPU یا GPU ترجیحاً (Copilot+ PC یا GPU انویدیا)
شبکه: اینترنت پرسرعت برای دانلود مدل‌ها

محیط توسعه

# Verify Windows version
winver

# Check available memory
Get-ComputerInfo | Select-Object TotalPhysicalMemory

# Verify PowerShell version (5.1+ required)
$PSVersionTable.PSVersion

# Set up Python environment (recommended)
py -m venv .venv
.venv\Scripts\activate

# Install required dependencies
pip install openai foundry-local-sdk

بخش ۱: نصب و راه‌اندازی

مرحله ۱: نصب Foundry Local

Foundry Local را با استفاده از Winget نصب کنید یا نصب‌کننده را از GitHub دانلود کنید:

# Winget (Windows)
winget install --id Microsoft.FoundryLocal --source winget

# Alternatively: download installer from the official repo
# https://aka.ms/foundry-local-installer

مرحله ۲: تأیید نصب

# Check Foundry Local version
foundry --version

# Verify CLI accessibility and categories
foundry --help
foundry model --help
foundry cache --help
foundry service --help

بخش ۲: درک CLI

ساختار دستورات اصلی

# General command structure
foundry [category] [command] [options]

# Main categories
foundry model   # manage and run models
foundry service # manage the local service
foundry cache   # manage local model cache

# Common commands
foundry model list              # list available models
foundry model run phi-4-mini  # run a model (downloads as needed)
foundry cache ls                # list cached models

بخش ۳: مدیریت و کش مدل‌ها

Foundry Local از کش هوشمند مدل برای بهینه‌سازی عملکرد و ذخیره‌سازی استفاده می‌کند:

# Show cache contents
foundry cache ls

# Optional: change cache directory (advanced)
foundry cache cd "C:\\FoundryLocal\\Cache"
foundry cache ls

بخش ۴: اجرای عملی مدل‌ها

اجرای مدل‌های Microsoft Phi

# List catalog and run Phi (auto-downloads best variant for your hardware)
foundry model list
foundry model run phi-4-mini

کار با مدل‌های Qwen

# Run Qwen2.5 models (downloads on first run)
foundry model run qwen2.5-7b
foundry model run qwen2.5-14b

اجرای مدل‌های DeepSeek

# Run DeepSeek model
foundry model run deepseek-r1-7b

اجرای GPT-OSS-20B

# Run the latest OpenAI open-source model (requires recent Foundry Local and sufficient GPU VRAM)
foundry model run gpt-oss-20b

# Check version if you encounter errors (requires 0.6.87+ per docs)
foundry --version

بخش ۵: ایجاد اولین برنامه شما

برنامه چت مدرن (OpenAI SDK + Foundry Local)

یک برنامه چت آماده تولید با استفاده از OpenAI SDK و یکپارچه‌سازی Foundry Local ایجاد کنید، با الگوهای نمونه ۰۱.

# chat_quickstart.py (Sample 01 pattern)
import os
import sys
from openai import OpenAI

try:
    from foundry_local import FoundryLocalManager
    FOUNDRY_SDK_AVAILABLE = True
except ImportError:
    FOUNDRY_SDK_AVAILABLE = False
    print("⚠️ Install foundry-local-sdk: pip install foundry-local-sdk")

def create_client():
    """Create OpenAI client with Foundry Local or Azure OpenAI."""
    # Check for Azure OpenAI configuration
    azure_endpoint = os.environ.get("AZURE_OPENAI_ENDPOINT")
    azure_api_key = os.environ.get("AZURE_OPENAI_API_KEY")
    
    if azure_endpoint and azure_api_key:
        # Azure OpenAI path
        model = os.environ.get("MODEL", "your-deployment-name")
        client = OpenAI(
            base_url=f"{azure_endpoint}/openai",
            api_key=azure_api_key,
            default_query={"api-version": "2024-08-01-preview"},
        )
        print(f"🌐 Using Azure OpenAI with model: {model}")
        return client, model
    
    # Foundry Local path with SDK management
    alias = os.environ.get("MODEL", "phi-4-mini")
    if FOUNDRY_SDK_AVAILABLE:
        try:
            # Use FoundryLocalManager for proper service management
            manager = FoundryLocalManager(alias)
            model_info = manager.get_model_info(alias)
            
            client = OpenAI(
                base_url=manager.endpoint,
                api_key=manager.api_key
            )
            model = model_info.id
            print(f"🏠 Using Foundry Local SDK with model: {model}")
            return client, model
        except Exception as e:
            print(f"⚠️ Foundry SDK failed ({e}), using manual configuration")
    
    # Fallback to manual configuration
    base_url = os.environ.get("BASE_URL", "http://localhost:8000")
    api_key = os.environ.get("API_KEY", "")
    model = alias
    
    client = OpenAI(
        base_url=f"{base_url}/v1",
        api_key=api_key
    )
    print(f"🔧 Manual configuration with model: {model}")
    return client, model

def main():
    """Main chat function."""
    client, model = create_client()
    
    print("Foundry Local Chat Interface (type 'quit' to exit)\n")
    conversation_history = []
    
    while True:
        user_input = input("You: ")
        if user_input.lower() == 'quit':
            break
        
        try:
            # Add user message to history
            conversation_history.append({"role": "user", "content": user_input})
            
            # Create chat completion
            response = client.chat.completions.create(
                model=model,
                messages=conversation_history,
                max_tokens=500,
                temperature=0.7
            )
            
            assistant_message = response.choices[0].message.content
            conversation_history.append({"role": "assistant", "content": assistant_message})
            
            print(f"Assistant: {assistant_message}\n")
            
        except Exception as e:
            print(f"Error: {e}\n")

if __name__ == "__main__":
    main()

اجرای برنامه چت

# Ensure the model is running in another terminal
foundry model run phi-4-mini

# Option 1: Using FoundryLocalManager (recommended)
python chat_quickstart.py "Explain what Foundry Local is"

# Option 2: Manual configuration with environment variables
set BASE_URL=http://localhost:8000
set MODEL=phi-4-mini
set API_KEY=
python chat_quickstart.py "Write a welcome message"

# Option 3: 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 chat_quickstart.py "Hello from Azure OpenAI"

بخش ۶: رفع اشکال و بهترین روش‌ها

مشکلات رایج و راه‌حل‌ها

# Issue: "Could not use Foundry SDK" warning
pip install foundry-local-sdk
# Or set environment variables for manual configuration

# Issue: Connection refused
foundry service status
foundry service ps  # Check loaded models

# Issue: Model not found
foundry model list
foundry model run phi-4-mini

# Issue: Cache problems or low disk space
foundry cache ls
foundry cache clean

# Issue: GPT-OSS-20B not supported on your version
foundry --version
winget upgrade --id Microsoft.FoundryLocal

# Test API endpoint
curl http://localhost:8000/v1/models

نظارت بر منابع سیستم (ویندوز)

# Quick CPU and process view
Get-Process | Sort-Object -Property CPU -Descending | Select-Object -First 10
Get-Counter '\\Processor(_Total)\\% Processor Time' -SampleInterval 1 -MaxSamples 10

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

متغیر	توضیحات	پیش‌فرض	ضروری
`MODEL`	نام یا نام مستعار مدل	`phi-4-mini`	خیر
`BASE_URL`	آدرس پایه Foundry Local	`http://localhost:8000`	خیر
`API_KEY`	کلید API (معمولاً برای محلی نیاز نیست)	`""`	خیر
`AZURE_OPENAI_ENDPOINT`	نقطه پایانی Azure OpenAI	-	برای Azure
`AZURE_OPENAI_API_KEY`	کلید API Azure OpenAI	-	برای Azure
`AZURE_OPENAI_API_VERSION`	نسخه API Azure	`2024-08-01-preview`	خیر

بهترین روش‌ها

استفاده از OpenAI SDK: به جای درخواست‌های خام HTTP، از OpenAI SDK برای نگهداری بهتر استفاده کنید
FoundryLocalManager: از SDK رسمی برای مدیریت سرویس استفاده کنید، در صورت موجود بودن
مدیریت خطا: استراتژی‌های جایگزین مناسب برای برنامه‌های تولیدی پیاده‌سازی کنید
به‌روزرسانی منظم: Foundry Local را به‌روز نگه دارید تا به مدل‌ها و اصلاحات جدید دسترسی داشته باشید
شروع کوچک: با مدل‌های کوچک‌تر (Phi mini، Qwen 7B) شروع کنید و به تدریج مقیاس را افزایش دهید
نظارت بر منابع: هنگام تنظیم درخواست‌ها و تنظیمات، CPU/GPU/رم را پیگیری کنید

بخش ۷: تمرین‌های عملی

تمرین ۱: تست سریع چند مدل

# deploy-models.ps1
$models = @(
    "phi-4-mini",
    "qwen2.5-7b"
)
foreach ($model in $models) {
    Write-Host "Running $model..."
    foundry model run $model --verbose
}

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

# sdk_integration_test.py (matching Sample 01 pattern)
import os
from openai import OpenAI
from foundry_local import FoundryLocalManager

def test_model_integration(model_alias):
    """Test OpenAI SDK integration with different models."""
    try:
        # Use FoundryLocalManager for proper setup
        manager = FoundryLocalManager(model_alias)
        model_info = manager.get_model_info(model_alias)
        
        client = OpenAI(
            base_url=manager.endpoint,
            api_key=manager.api_key
        )
        
        # Test basic completion
        response = client.chat.completions.create(
            model=model_info.id,
            messages=[{"role": "user", "content": "Say hello and state your model name."}],
            max_tokens=50
        )
        
        print(f"✅ {model_alias}: {response.choices[0].message.content}")
        return True
    except Exception as e:
        print(f"❌ {model_alias}: {e}")
        return False

# Test multiple models
models_to_test = ["phi-4-mini", "qwen2.5-7b"]
for model in models_to_test:
    test_model_integration(model)

تمرین ۳: بررسی جامع سلامت سرویس

# health_check.py
from openai import OpenAI
from foundry_local import FoundryLocalManager

def comprehensive_health_check():
    """Perform comprehensive health check of Foundry Local service."""
    try:
        # Initialize with a common model
        manager = FoundryLocalManager("phi-4-mini")
        client = OpenAI(
            base_url=manager.endpoint,
            api_key=manager.api_key
        )
        
        # 1. Check service connectivity
        models_response = client.models.list()
        available_models = [model.id for model in models_response.data]
        print(f"✅ Service healthy - {len(available_models)} models available")
        
        # 2. Test each available model
        for model_id in available_models:
            try:
                response = client.chat.completions.create(
                    model=model_id,
                    messages=[{"role": "user", "content": "Test"}],
                    max_tokens=10
                )
                print(f"✅ {model_id}: Working")
            except Exception as e:
                print(f"❌ {model_id}: {e}")
        
        return True
    except Exception as e:
        print(f"❌ Service check failed: {e}")
        return False

comprehensive_health_check()

منابع

شروع به کار با Foundry Local: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/get-started
مرجع CLI و مرور دستورات: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/reference/reference-cli
یکپارچه‌سازی OpenAI SDK: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/how-to/how-to-integrate-with-inference-sdks
کامپایل مدل‌های Hugging Face: https://learn.microsoft.com/en-us/azure/ai-foundry/foundry-local/how-to/how-to-compile-hugging-face-models
GitHub Microsoft Foundry Local: https://github.com/microsoft/Foundry-Local
OpenAI Python SDK: https://github.com/openai/openai-python
نمونه ۰۱: چت سریع با OpenAI SDK: samples/01/README.md
نمونه ۰۲: یکپارچه‌سازی پیشرفته SDK: samples/02/README.md

سلب مسئولیت:
این سند با استفاده از سرویس ترجمه هوش مصنوعی Co-op Translator ترجمه شده است. در حالی که ما تلاش می‌کنیم ترجمه‌ها دقیق باشند، لطفاً توجه داشته باشید که ترجمه‌های خودکار ممکن است شامل خطاها یا نادرستی‌ها باشند. سند اصلی به زبان اصلی آن باید به عنوان منبع معتبر در نظر گرفته شود. برای اطلاعات حساس، توصیه می‌شود از ترجمه انسانی حرفه‌ای استفاده کنید. ما مسئولیتی در قبال سوء تفاهم‌ها یا تفسیرهای نادرست ناشی از استفاده از این ترجمه نداریم.