Módulo 3.2 — Configurar providers

📄 config.yaml estrutura

O arquivo aios/config/config.yaml centraliza tudo que o kernel precisa: API keys, scheduler escolhido, storage path, política de retry. É a primeira coisa a editar depois de instalar.

# aios/config/config.yaml (exemplo mínimo)
api_keys:
  openai: "sk-..."
  anthropic: "sk-ant-..."
  gemini: "AIza..."
  groq: "gsk_..."
  huggingface:
    auth_token: "hf_..."
    cache_dir: "/data/hf-cache"
  novita: "..."

scheduler:
  policy: "fifo"   # ou "round_robin"
storage:
  path: "./data/storage"

💡 Dica

Mantenha o config.yaml fora do git (já está no .gitignore oficial). Vaza key, vira drama. Use template config.example.yaml com placeholders e copie localmente.

🔐 OpenAI / Anthropic — Os padrão

São os providers mais maduros e os primeiros que vale conectar. OpenAI dá GPT-4o, GPT-4.1, o3. Anthropic dá Claude Sonnet/Opus 4.x. Ambos têm SDK estável e o LLM Core ativa automaticamente quando detecta a key.

OpenAI

Onde pegar key: platform.openai.com/api-keys
Modelos top: gpt-4o, gpt-4.1, o3
Forte em: tool-use, function calling
Custo: alto em modelos top

Anthropic

Onde pegar key: console.anthropic.com
Modelos top: claude-sonnet-4.x, claude-opus-4.x
Forte em: raciocínio longo, prompt caching
Custo: médio com cache

💡 Dica

Configure os dois. Custa zero adicional — você só paga pelo que usar. Tendo ambos disponíveis, dá pra trocar de modelo por tarefa sem dor.

🌐 Gemini / Groq / Novita

Providers adicionais que cobrem cenários complementares. Gemini (Google) tem context window enorme. Groq oferece Llama/Mixtral em hardware acelerado, latência muito baixa. Novita é proxy para modelos open-source.

📊 Quando usar cada um

Gemini 2.5 — quando precisa de 1M+ tokens de contexto
Groq — quando precisa resposta < 1s (chat de UX)
Novita — quando quer rotear para vários modelos open com uma key

💡 Dica

Não configure todos no dia 1. Comece com OpenAI + Anthropic. Adicione Gemini quando bater limite de contexto. Adicione Groq quando perceber lentidão de UX. Adicione Novita quando experimentar modelos open.

🤗 HuggingFace local — Cache + auth

Para rodar modelos open localmente (via HuggingFace ou vLLM), configure dois campos: auth_token (alguns modelos exigem autorização) e cache_dir (pasta onde pesos ficam armazenados).

api_keys:
  huggingface:
    auth_token: "hf_xxxxxxxxxxxx"
    cache_dir: "/data/hf-cache"   # disco grande, pesos somam GBs

📊 Considerações

Modelos > 7B precisam GPU NVIDIA + CUDA 11+
Token só é necessário para modelos restritos (Llama 3.1 70B, etc)
Cache evita re-download; planeje 50-200GB para variados modelos
vLLM acelera inferência em ~3x sobre transformers puro

🚀 Lançar kernel — Foreground vs background

Em dev, rode em foreground: você vê o log na hora e mata com Ctrl+C. Em produção, background com log + supervisor para reiniciar automaticamente em caso de crash.

# Foreground (dev)
$ python -m aios.kernel

# Background com log persistente (prod simples)
$ nohup python -m aios.kernel > kernel.log 2>&1 &
$ tail -f kernel.log

# Como serviço (prod robusto) — systemd unit example
$ sudo systemctl enable aios-kernel
$ sudo systemctl start aios-kernel
$ journalctl -u aios-kernel -f

💡 Dica

Para dev mais ergonômico que nohup, use tmux ou screen — fácil reattach quando quiser ver o que está acontecendo.

💬 Terminal UI — Primeira interação

Com kernel rodando, rode python scripts/run_terminal.py em outro shell. Aparece prompt — digite uma query, recebe resposta. Esse é o "hello world" do AIOS e a forma mais rápida de validar setup completo.

$ python scripts/run_terminal.py
AIOS Terminal UI — type 'help' for commands
> explique em uma frase o que é AIOS
<agente responde via LLM Core configurado>
> quit

📊 Sintomas comuns

"Connection refused" — kernel não está rodando
"No provider configured" — config.yaml vazio ou key inválida
"Timeout" — provider lento, suba o limite no config
Resposta vazia — modelo escolhido não suportado pelo provider

💡 Próximo passo

Funcionou? Ótimo — você venceu 80% da curva. Próxima trilha você sai do agente default e cria o seu via Cerebrum SDK.

✅ Resumo do Módulo

✓

config.yaml é o source of truth. Tudo passa por ele.

✓

OpenAI + Anthropic primeiro. Os mais maduros.

✓

Gemini/Groq/Novita por necessidade. Contexto, latência, modelos open.

✓

HuggingFace exige cache_dir. Sem cache, baixa toda vez.

✓

Terminal UI valida tudo. Smoke test do setup completo.

Próxima trilha:

Trilha 4 — 🧰 SDK Cerebrum. Como criar seu próprio agente que fala com o kernel.

← Anterior: 3.1 Próxima: Trilha 4 →