# Сесия 1: Започване с Foundry Local

## Преглед

Microsoft Foundry Local предоставя възможностите на Azure AI Foundry директно във вашата среда за разработка на Windows 11, позволявайки разработка на AI с ниска латентност и запазване на поверителността, използвайки инструменти от корпоративен клас. Тази сесия обхваща пълната инсталация, конфигурация и практическо внедряване на популярни модели, включително phi, qwen, deepseek и GPT-OSS-20B.

## Цели на обучението

До края на тази сесия ще можете:
- Да инсталирате и конфигурирате Foundry Local на Windows 11
- Да овладеете CLI команди и опции за конфигурация
- Да разберете стратегии за кеширане на модели за оптимална производителност
- Успешно да стартирате модели phi, qwen, deepseek и GPT-OSS-20B
- Да създадете своето първо AI приложение с Foundry Local

## Предварителни изисквания

### Системни изисквания
- **Windows 11**: Версия 22H2 или по-нова
- **RAM**: Минимум 16GB, препоръчително 32GB
- **Съхранение**: 50GB свободно пространство за модели и кеш
- **Хардуер**: Устройство с NPU или GPU (Copilot+ PC или NVIDIA GPU) е за предпочитане
- **Мрежа**: Високоскоростен интернет за изтегляне на модели

### Среда за разработка
```powershell
# 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
```

## Част 1: Инсталация и настройка

### Стъпка 1: Инсталиране на Foundry Local

Инсталирайте Foundry Local с Winget или изтеглете инсталатора от GitHub:

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

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

### Стъпка 2: Проверка на инсталацията

```powershell
# Check Foundry Local version
foundry --version

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

## Част 2: Разбиране на CLI

### Основна структура на командите

```powershell
# 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
```


## Част 3: Кеширане и управление на модели

Foundry Local използва интелигентно кеширане на модели за оптимизиране на производителността и съхранението:

```powershell
# Show cache contents
foundry cache ls

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

## Част 4: Практическо внедряване на модели

### Стартиране на Microsoft Phi модели

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

### Работа с Qwen модели

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

### Стартиране на DeepSeek модели

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

### Стартиране на GPT-OSS-20B

```powershell
# 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
```

## Част 5: Създаване на първото ви приложение

### Модерно чат приложение (OpenAI SDK + Foundry Local)

Създайте готово за производство чат приложение, използвайки OpenAI SDK с интеграция на Foundry Local, следвайки шаблоните от нашия Sample 01.

```python
# 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()
```

### Стартиране на чат приложението

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

## Част 6: Отстраняване на проблеми и добри практики

### Често срещани проблеми и решения

```powershell
# 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
```

### Мониторинг на системни ресурси (Windows)

```powershell
# 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` | Основен URL на Foundry Local | `http://localhost:8000` | Не |
| `API_KEY` | API ключ (обикновено не е необходим за локално) | `""` | Не |
| `AZURE_OPENAI_ENDPOINT` | Azure OpenAI крайна точка | - | За Azure |
| `AZURE_OPENAI_API_KEY` | Azure OpenAI API ключ | - | За Azure |
| `AZURE_OPENAI_API_VERSION` | Версия на Azure API | `2024-08-01-preview` | Не |

### Добри практики

- **Използвайте OpenAI SDK**: Предпочитайте OpenAI SDK пред сурови HTTP заявки за по-добра поддръжка
- **FoundryLocalManager**: Използвайте официалния SDK за управление на услугите, когато е наличен
- **Обработка на грешки**: Внедрете подходящи стратегии за резервиране за приложения в производство
- **Редовни актуализации**: Поддържайте Foundry Local актуализиран, за да получите достъп до нови модели и поправки
- **Започнете с малки модели**: Започнете с по-малки модели (Phi mini, Qwen 7B) и постепенно увеличавайте мащаба
- **Мониторинг на ресурси**: Следете CPU/GPU/памет, докато настройвате подканите и настройките

## Част 7: Практически упражнения

### Упражнение 1: Бърз тест с множество модели

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

### Упражнение 2: Тест за интеграция с OpenAI SDK

```python
# 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)
```

### Упражнение 3: Цялостна проверка на здравето на услугата

```python
# 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
- **Microsoft Foundry Local GitHub**: https://github.com/microsoft/Foundry-Local
- **OpenAI Python SDK**: https://github.com/openai/openai-python
- **Sample 01: Бърз чат чрез OpenAI SDK**: samples/01/README.md
- **Sample 02: Разширена интеграция със SDK**: samples/02/README.md

---

**Отказ от отговорност**:  
Този документ е преведен с помощта на AI услуга за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод.