Skip to content

README.md

Latest commit

 

History

History
214 lines (166 loc) · 6.89 KB

README.md

File metadata and controls

214 lines (166 loc) · 6.89 KB

Exemplo de Foundry Local como API

Este exemplo demonstra como usar o Microsoft Foundry Local como um serviço de API REST sem depender do SDK OpenAI. Mostra padrões de integração direta via HTTP para máximo controlo e personalização.

Visão Geral

Baseado nos padrões oficiais do Microsoft Foundry Local, este exemplo fornece:

  • Integração direta com API REST usando FoundryLocalManager
  • Implementação personalizada de cliente HTTP
  • Gestão de modelos e monitorização de saúde
  • Manipulação de respostas em streaming e não-streaming
  • Tratamento de erros e lógica de repetição pronta para produção

Pré-requisitos

  1. Instalação do Foundry Local

    # Install from GitHub releases
winget install Microsoft.FoundryLocal

  2. Dependências Python

    pip install foundry-local-sdk requests asyncio aiohttp

Arquitetura

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

Funcionalidades Principais

1. Integração Direta via HTTP

  • Chamadas API REST puras sem dependências de SDK
  • Autenticação e cabeçalhos personalizados
  • Controlo total sobre o tratamento de pedidos/respostas

2. Gestão de Modelos

  • Carregamento e descarregamento dinâmico de modelos
  • Monitorização de saúde e verificações de estado
  • Coleta de métricas de desempenho

3. Padrões de Produção

  • Mecanismos de repetição com backoff exponencial
  • Circuit breaker para tolerância a falhas
  • Registo e monitorização abrangentes

4. Manipulação Flexível de Respostas

  • Respostas em streaming para aplicações em tempo real
  • Processamento em lote para cenários de alta capacidade
  • Análise e validação personalizada de respostas

Exemplos de Utilização

Integração Básica com API

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)

Integração com Streaming

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

Monitorização de Saúde

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

Estrutura de Ficheiros

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

Integração com Microsoft Foundry Local

Este exemplo segue os padrões oficiais da Microsoft:

  1. Integração com SDK: Usa FoundryLocalManager para gestão de serviços
  2. Endpoints REST: Chamadas diretas para /v1/chat/completions e outros endpoints
  3. Autenticação: Gestão adequada de chaves API para serviços locais
  4. Gestão de Modelos: Listagem de catálogo, download e padrões de carregamento
  5. Tratamento de Erros: Códigos de erro e respostas recomendados pela Microsoft

Primeiros Passos

  1. Instalar Dependências

    pip install -r requirements.txt

  2. Executar Exemplo Básico

    python examples/basic_usage.py

  3. Experimentar Streaming

    python examples/streaming.py

  4. Configuração para Produção

    python examples/production.py

Configuração

Variáveis de ambiente para personalização:

  • FOUNDRY_MODEL: Modelo padrão a usar (padrão: "phi-4-mini")
  • FOUNDRY_TIMEOUT: Tempo limite de pedido em segundos (padrão: 30)
  • FOUNDRY_RETRIES: Número de tentativas de repetição (padrão: 3)
  • FOUNDRY_LOG_LEVEL: Nível de registo (padrão: "INFO")

Melhores Práticas

  1. Gestão de Conexões: Reutilizar conexões HTTP para melhor desempenho
  2. Tratamento de Erros: Implementar lógica de repetição adequada com backoff exponencial
  3. Monitorização de Recursos: Acompanhar o uso de memória e desempenho dos modelos
  4. Segurança: Usar autenticação adequada mesmo para serviços locais
  5. Testes: Incluir testes unitários e de integração

Resolução de Problemas

Problemas Comuns

Serviço Não Está a Funcionar

# Check Foundry Local status
foundry status

# Start if needed
foundry start

Problemas no Carregamento de Modelos

# List available models
foundry model list

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

Erros de Conexão

  • Verificar se o Foundry Local está a funcionar na porta correta
  • Verificar configurações de firewall
  • Garantir cabeçalhos de autenticação adequados

Otimização de Desempenho

  1. Pooling de Conexões: Usar objetos de sessão para múltiplos pedidos
  2. Operações Assíncronas: Utilizar asyncio para pedidos concorrentes
  3. Caching: Cache de respostas de modelos onde apropriado
  4. Monitorização: Acompanhar tempos de resposta e ajustar tempos limite

Resultados de Aprendizagem

Após completar este exemplo, irá compreender:

  • Integração direta com API REST do Foundry Local
  • Padrões de implementação de cliente HTTP personalizado
  • Tratamento de erros e monitorização prontos para produção
  • Arquitetura de serviços Microsoft Foundry Local
  • Técnicas de otimização de desempenho para serviços de IA locais

Próximos Passos

  • Explorar Exemplo 08: Aplicação de Chat no Windows 11
  • Experimentar Exemplo 09: Orquestração Multi-Agente
  • Aprender Exemplo 10: Foundry Local como Integração de Ferramentas
⚡