Skip to content

README.md

Latest commit

 

History

History
214 lines (166 loc) · 6.7 KB

README.md

File metadata and controls

214 lines (166 loc) · 6.7 KB

Foundry Local ako API ukážka

Táto ukážka demonštruje, ako používať Microsoft Foundry Local ako REST API službu bez závislosti na OpenAI SDK. Ukazuje priame integračné vzory cez HTTP pre maximálnu kontrolu a prispôsobenie.

Prehľad

Na základe oficiálnych vzorov Microsoft Foundry Local táto ukážka poskytuje:

  • Priamu integráciu REST API s FoundryLocalManager
  • Vlastnú implementáciu HTTP klienta
  • Správu modelov a monitorovanie stavu
  • Spracovanie odpovedí v režime streamovania aj bez streamovania
  • Pripravené na produkciu: spracovanie chýb a logika opakovania

Predpoklady

  1. Inštalácia Foundry Local

    # Install from GitHub releases
winget install Microsoft.FoundryLocal

  2. Python závislosti

    pip install foundry-local-sdk requests asyncio aiohttp

Architektúra

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Your App      │───▶│  REST API Client │───▶│  Foundry Local  │
│                 │    │                  │    │   Service       │
│ - Custom Logic  │    │ - HTTP Requests  │    │ - Model Loading │
│ - Business Rules│    │ - Authentication │    │ - Inference     │
│ - Data Pipeline │    │ - Error Handling │    │ - Health Check  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Kľúčové vlastnosti

1. Priama HTTP integrácia

  • Čisté REST API volania bez závislosti na SDK
  • Vlastná autentifikácia a hlavičky
  • Plná kontrola nad spracovaním požiadaviek a odpovedí

2. Správa modelov

  • Dynamické načítanie a odstraňovanie modelov
  • Monitorovanie stavu a kontrola zdravia
  • Zber výkonnostných metrík

3. Produkčné vzory

  • Mechanizmy opakovania s exponenciálnym oneskorením
  • Circuit breaker pre odolnosť voči chybám
  • Komplexné logovanie a monitorovanie

4. Flexibilné spracovanie odpovedí

  • Streamované odpovede pre aplikácie v reálnom čase
  • Batch spracovanie pre scenáre s vysokou priepustnosťou
  • Vlastné parsovanie a validácia odpovedí

Príklady použitia

Základná API integrácia

from api_client import FoundryAPIClient

# Initialize the API client
client = FoundryAPIClient()

# Simple completion
response = await client.complete(
    prompt="Explain quantum computing",
    model="phi-4-mini",
    max_tokens=500
)
print(response.content)

Streamovaná integrácia

# Stream responses for real-time applications
async for chunk in client.stream_complete(
    prompt="Write a story about AI",
    model="phi-4-mini"
):
    print(chunk.content, end="", flush=True)

Monitorovanie stavu

# Check service health
health = await client.health_check()
print(f"Service Status: {health.status}")
print(f"Active Models: {health.loaded_models}")
print(f"Memory Usage: {health.memory_usage}")

Štruktúra súborov

07/
├── README.md              # This documentation
├── requirements.txt       # Python dependencies
├── api_client.py         # Core API client implementation
├── health_monitor.py     # Health checking and monitoring
├── examples/
│   ├── basic_usage.py    # Simple API integration example
│   ├── streaming.py      # Streaming response example
│   ├── batch_processing.py # Batch processing example
│   └── production.py     # Production-ready implementation
└── tests/
    ├── test_api_client.py    # Unit tests for API client
    └── test_integration.py   # Integration tests

Integrácia Microsoft Foundry Local

Táto ukážka nasleduje oficiálne vzory Microsoftu:

  1. SDK integrácia: Používa FoundryLocalManager na správu služieb
  2. REST endpointy: Priame volania na /v1/chat/completions a ďalšie endpointy
  3. Autentifikácia: Správne spracovanie API kľúčov pre lokálne služby
  4. Správa modelov: Zoznam katalógu, sťahovanie a načítanie modelov
  5. Spracovanie chýb: Odporúčané chybové kódy a odpovede od Microsoftu

Začíname

  1. Inštalujte závislosti

    pip install -r requirements.txt

  2. Spustite základný príklad

    python examples/basic_usage.py

  3. Vyskúšajte streamovanie

    python examples/streaming.py

  4. Produkčné nastavenie

    python examples/production.py

Konfigurácia

Premenné prostredia na prispôsobenie:

  • FOUNDRY_MODEL: Predvolený model na použitie (predvolené: "phi-4-mini")
  • FOUNDRY_TIMEOUT: Časový limit požiadavky v sekundách (predvolené: 30)
  • FOUNDRY_RETRIES: Počet pokusov o opakovanie (predvolené: 3)
  • FOUNDRY_LOG_LEVEL: Úroveň logovania (predvolené: "INFO")

Najlepšie postupy

  1. Správa pripojení: Opätovné použitie HTTP pripojení pre lepší výkon
  2. Spracovanie chýb: Implementujte správnu logiku opakovania s exponenciálnym oneskorením
  3. Monitorovanie zdrojov: Sledujte využitie pamäte modelu a výkon
  4. Bezpečnosť: Používajte správnu autentifikáciu aj pre lokálne služby
  5. Testovanie: Zahrňte jednotkové aj integračné testy

Riešenie problémov

Bežné problémy

Služba nebeží

# Check Foundry Local status
foundry status

# Start if needed
foundry start

Problémy s načítaním modelu

# List available models
foundry model list

# Download specific model
foundry model download phi-4-mini

Chyby pripojenia

  • Overte, či Foundry Local beží na správnom porte
  • Skontrolujte nastavenia firewallu
  • Uistite sa, že používate správne autentifikačné hlavičky

Optimalizácia výkonu

  1. Pooling pripojení: Používajte objekty session pre viacero požiadaviek
  2. Asynchrónne operácie: Využívajte asyncio pre súbežné požiadavky
  3. Caching: Cacheujte odpovede modelu, kde je to vhodné
  4. Monitorovanie: Sledujte časy odpovedí a upravujte časové limity

Výsledky učenia

Po dokončení tejto ukážky budete rozumieť:

  • Priamej integrácii REST API s Foundry Local
  • Vzorom implementácie vlastného HTTP klienta
  • Produkčnému spracovaniu chýb a monitorovaniu
  • Architektúre služby Microsoft Foundry Local
  • Technikám optimalizácie výkonu pre lokálne AI služby

Ďalšie kroky

  • Preskúmajte Ukážku 08: Chat aplikácia pre Windows 11
  • Vyskúšajte Ukážku 09: Orchestrácia viacerých agentov
  • Naučte sa Ukážku 10: Foundry Local ako integrácia nástrojov
⚡