Implantação de agentes leves na borda
Executando modelos pequenos em Raspberry Pi e dispositivos de borda para obter respostas de baixa latência.
Implantação de agentes leves na borda é uma aula grátis de AI Agents no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Agents, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Agents inclui 4 aulas no total.
Agentes de IA na Borda
Um agente de borda é executado diretamente no dispositivo de IoT ou no dispositivo de acesso local — um Raspberry Pi, Jetson Nano ou PC industrial — em vez de ser executado na nuvem. Benefícios: menor latência (sem viagem de ida e volta), funcionamento sem conexão e menor custo de largura de banda. Compromisso: a capacidade computacional e a RAM limitadas exigem modelos menores e mais eficientes.
Escolhendo um Modelo para Implantação na Borda
Dispositivos de borda não conseguem executar GPT-4o ou Claude Opus. Modelos pequenos que cabem em um Raspberry Pi 5 (8 GB de RAM): Phi-3-mini (3,8 bilhões de parâmetros), Gemma-2B, TinyLlama-1.1B. Quando quantizados para 4 bits, esses modelos exigem de 1 a 3 GB de RAM e executam de 5 a 15 tokens por segundo na CPU.
# Model size reference for edge selection:
EDGE_MODELS = {
'tinyllama-1.1b-q4': {
'params': '1.1B', 'quantization': 'Q4_K_M',
'ram_gb': 0.8, 'tokens_per_sec_cpu': 15,
'use_case': 'simple classification, keyword detection'
},
'phi-3-mini-q4': {
'params': '3.8B', 'quantization': 'Q4_K_M',
'ram_gb': 2.5, 'tokens_per_sec_cpu': 8,
'use_case': 'reasoning, multi-step decisions'
},
'gemma-2b-q4': {
'params': '2B', 'quantization': 'Q4_K_M',
'ram_gb': 1.5, 'tokens_per_sec_cpu': 10,
'use_case': 'general assistant tasks'
}
}
for name, info in EDGE_MODELS.items():
print(f'{name}: {info["ram_gb"]}GB RAM, '
f'{info["tokens_per_sec_cpu"]} tok/s — {info["use_case"]}')Instalando o Ollama no Raspberry Pi
O Ollama é a maneira mais fácil de executar LLMs pequenos em hardware local. Ele gerencia o download e a quantização dos modelos, além de uma API REST local compatível com o SDK OpenAI. Um comando o instala; outro baixa e inicia o modelo.
# Install Ollama (run on the Raspberry Pi terminal):
# curl -fsSL https://ollama.ai/install.sh | sh
# Pull and run a model:
# ollama pull phi3:mini
# ollama serve (starts API on localhost:11434)
# Python client — uses the OpenAI-compatible endpoint:
from openai import OpenAI
local_client = OpenAI(
base_url='http://localhost:11434/v1',
api_key='ollama' # Ollama ignores this but it is required by the SDK
)
def local_inference(prompt: str, model: str = 'phi3:mini') -> str:
response = local_client.chat.completions.create(
model=model,
messages=[{'role': 'user', 'content': prompt}],
max_tokens=256,
temperature=0.1
)
return response.choices[0].message.content
result = local_inference('Is temperature 45C dangerous for a server room?')
print(result)Quantização GGUF de 4 Bits
GGUF (Formato Unificado Gerado pelo GPT) é o formato de arquivo usado por llama.cpp e pelo Ollama para modelos quantizados. Q4_K_M significa quantização mista de 4 bits — cerca de 75% menor que fp32, com perda mínima de qualidade para tarefas de raciocínio na borda.
# Understanding quantisation quality levels:
QUANTISATION_GUIDE = {
'Q2_K': {'size_multiplier': 0.25, 'quality': 'poor', 'ram': 'minimal'},
'Q4_K_M': {'size_multiplier': 0.45, 'quality': 'good', 'ram': 'low'},
'Q5_K_M': {'size_multiplier': 0.55, 'quality': 'better', 'ram': 'medium'},
'Q8_0': {'size_multiplier': 0.75, 'quality': 'near-original', 'ram': 'high'},
'F16': {'size_multiplier': 1.0, 'quality': 'original', 'ram': 'full'}
}
# For edge: Q4_K_M is the sweet spot
# 7B model: 7B * 4bit/8 = 3.5 GB in Q4 vs 14 GB in F16
def estimate_vram_gb(param_billions: float, quant: str) -> float:
multiplier = QUANT_GUIDE = {
'Q4_K_M': 0.45, 'Q8_0': 0.75, 'F16': 1.0
}
return round(param_billions * multiplier.get(quant, 0.5), 2)
print(f'Phi-3-mini Q4_K_M: {estimate_vram_gb(3.8, "Q4_K_M")} GB')
print(f'Phi-3-mini F16: {estimate_vram_gb(3.8, "F16")} GB')Otimizando a Velocidade de Inferência na CPU
Em dispositivos de borda que usam apenas CPU, a velocidade de inferência depende do número de linhas de execução e do armazenamento em cache das instruções. Defina o número de linhas de execução de acordo com os núcleos da CPU, mantenha a instrução do sistema curta (ela é reprocessada a cada chamada se não estiver em cache) e agrupe consultas repetidas quando possível.
import os
import time
# Ollama environment variables for performance tuning
# Set before starting the Ollama service:
# OLLAMA_NUM_PARALLEL=1 (single request at a time on small devices)
# OLLAMA_MAX_LOADED_MODELS=1 (only keep one model in RAM)
def timed_inference(prompt: str, client, model: str = 'phi3:mini') -> dict:
start = time.time()
response = client.chat.completions.create(
model=model,
messages=[{'role': 'user', 'content': prompt}],
max_tokens=128
)
elapsed = time.time() - start
text = response.choices[0].message.content
tokens = len(text.split()) # approximate
return {
'text': text,
'elapsed_s': round(elapsed, 2),
'approx_tps': round(tokens / elapsed, 1)
}
result = timed_inference('Classify: temperature=45C, normal range 18-30C. Action?',
local_client)
print(result)Arquitetura híbrida de borda e nuvem
A arquitetura ideal utiliza o modelo de borda para decisões rápidas e de baixo risco (classificação, lógica de limiares) e sincroniza com o modelo na nuvem para decisões complexas, raras ou de alto risco. O agente de borda enfileira consultas complexas e as envia quando a conectividade permite.
import anthropic
import time
class HybridAgent:
def __init__(self, edge_client, cloud_api_key: str):
self.edge = edge_client # Ollama local client
self.cloud = anthropic.Anthropic(api_key=cloud_api_key)
self.pending_cloud_queries = []
def decide(self, context: dict) -> str:
# Fast path: edge model for simple binary decisions
simple_prompt = (
f'Sensor: {context}. '
'Respond with exactly one word: NORMAL or ALERT.'
)
edge_result = self.edge.chat.completions.create(
model='phi3:mini',
messages=[{'role': 'user', 'content': simple_prompt}],
max_tokens=5
).choices[0].message.content.strip()
if edge_result == 'ALERT':
# Queue complex analysis for cloud
self.pending_cloud_queries.append(context)
return edge_result
def sync_to_cloud(self):
"""Call when online connectivity is available."""
for ctx in self.pending_cloud_queries:
result = self.cloud.messages.create(
model='claude-opus-4-5', max_tokens=512,
messages=[{'role': 'user', 'content':
f'Full analysis of: {ctx}'}]
)
print('Cloud analysis:', result.content[0].text[:100])
self.pending_cloud_queries.clear()Fila offline para sincronização com a nuvem
Os agentes de borda frequentemente operam em ambientes com conectividade intermitente. Armazene localmente em um buffer as consultas, as leituras dos sensores e os registros de ações; depois, envie-os para a nuvem quando a conectividade for restaurada. Utilize um banco de dados SQLite como buffer local.
import sqlite3
import json
from datetime import datetime
DB_PATH = '/home/pi/agent_buffer.db'
def init_buffer_db():
conn = sqlite3.connect(DB_PATH)
conn.execute("""
CREATE TABLE IF NOT EXISTS sync_queue (
id INTEGER PRIMARY KEY AUTOINCREMENT,
type TEXT NOT NULL,
payload TEXT NOT NULL,
created_at TEXT NOT NULL,
synced INTEGER DEFAULT 0
)
""")
conn.commit()
conn.close()
def buffer_for_sync(record_type: str, payload: dict):
conn = sqlite3.connect(DB_PATH)
conn.execute(
'INSERT INTO sync_queue (type, payload, created_at) VALUES (?, ?, ?)',
(record_type, json.dumps(payload), datetime.utcnow().isoformat())
)
conn.commit()
conn.close()
def flush_to_cloud(cloud_fn):
conn = sqlite3.connect(DB_PATH)
rows = conn.execute(
'SELECT id, type, payload FROM sync_queue WHERE synced=0 LIMIT 100'
).fetchall()
for row_id, r_type, payload in rows:
cloud_fn(r_type, json.loads(payload))
conn.execute('UPDATE sync_queue SET synced=1 WHERE id=?', (row_id,))
conn.commit()
conn.close()
print(f'Synced {len(rows)} records to cloud')
if __name__ == '__main__':
import os, tempfile
DB_PATH = os.path.join(tempfile.gettempdir(), 'agent_buffer_demo.db')
init_buffer_db()
buffer_for_sync('sensor_reading', {'temp': 22.5})
flush_to_cloud(lambda t, p: print(f'Synced to cloud: {t} -> {p}'))
Monitoramento da saúde do agente de borda
Os dispositivos de borda podem superaquecer, ficar com pouca RAM disponível ou ter a inferência do modelo interrompida. Implemente um monitor de integridade que verifique a temperatura da CPU, a RAM livre e a latência da inferência, e publique as métricas de integridade na nuvem.
import subprocess
import psutil # pip install psutil
def get_edge_health() -> dict:
cpu_percent = psutil.cpu_percent(interval=1)
ram = psutil.virtual_memory()
disk = psutil.disk_usage('/')
# Read CPU temperature (Raspberry Pi specific)
try:
temp_output = subprocess.check_output(
['vcgencmd', 'measure_temp'], text=True
)
cpu_temp = float(temp_output.strip().replace("temp=", "").replace("'C", ""))
except Exception:
cpu_temp = -1.0 # not available on non-Pi hardware
return {
'cpu_percent': cpu_percent,
'cpu_temp_c': cpu_temp,
'ram_used_pct': ram.percent,
'ram_available_mb': round(ram.available / 1024 / 1024),
'disk_used_pct': disk.percent,
'timestamp': datetime.utcnow().isoformat()
}
health = get_edge_health()
print('Edge health:', health)Cache de inferência para agentes de borda
Os modelos de borda são lentos; armazene em cache as respostas para entradas idênticas. Em tarefas de classificação de sensores, o mesmo prompt (por exemplo, "temperature=23.5, classify") costuma se repetir. Um cache simples baseado em dicionário, com TTL, evita chamadas de inferência redundantes.
from datetime import datetime, timedelta
import hashlib
class InferenceCache:
def __init__(self, ttl_seconds: int = 60):
self.ttl = timedelta(seconds=ttl_seconds)
self._cache: dict = {} # hash -> {'result', 'expires'}
def _key(self, prompt: str) -> str:
return hashlib.md5(prompt.encode()).hexdigest()
def get(self, prompt: str):
key = self._key(prompt)
entry = self._cache.get(key)
if entry and datetime.utcnow() < entry['expires']:
return entry['result']
return None
def set(self, prompt: str, result: str):
key = self._key(prompt)
self._cache[key] = {
'result': result,
'expires': datetime.utcnow() + self.ttl
}
cache = InferenceCache(ttl_seconds=60)
def cached_edge_inference(prompt: str, client) -> str:
cached = cache.get(prompt)
if cached:
print('Cache hit')
return cached
result = local_inference(prompt, client)
cache.set(prompt, result)
return resultLista de verificação da implantação
Antes de implantar um agente de borda em produção, verifique se: o modelo cabe na RAM disponível com uma margem de 20%; a latência da inferência atende ao requisito de tempo de resposta do evento; o buffer offline foi testado; o monitoramento de integridade está publicando dados; e a reinicialização automática após uma falha está configurada.
# systemd service file for auto-restart (save as /etc/systemd/system/edge-agent.service)
SYSTEMD_SERVICE = '''
[Unit]
Description=IoT Edge Agent
After=network.target ollama.service
Requires=ollama.service
[Service]
User=pi
WorkingDirectory=/home/pi/edge-agent
ExecStart=/usr/bin/python3 /home/pi/edge-agent/agent.py
Restart=always
RestartSec=5
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
'''
# Enable:
# sudo systemctl enable edge-agent
# sudo systemctl start edge-agent
# sudo journalctl -u edge-agent -f (follow logs)
print('Deployment checklist:')
checklist = [
'Model RAM fits with 20% headroom',
'Inference latency < response time requirement',
'Offline SQLite buffer tested',
'Health metrics publishing to cloud',
'systemd auto-restart configured'
]
for item in checklist:
print(f' [ ] {item}')Configuração do hardware do Raspberry Pi
Antes de implantar o software, prepare o hardware. Um Raspberry Pi 5 com 8 GB de RAM é o mínimo recomendado para executar o Phi-3-mini. Ative a divisão de memória da GPU, desative a memória swap (ela degrada o armazenamento flash) e configure um IP estático para garantir acesso remoto confiável.
# Raspberry Pi setup notes (run manually over SSH):
# sudo raspi-config -> System -> GPU Memory -> 256
# Disable swap to protect SD card:
# sudo dphys-swapfile swapoff && sudo dphys-swapfile uninstall
def check_available_ram_mb():
try:
with open('/proc/meminfo') as f:
for line in f:
if line.startswith('MemAvailable'):
return int(line.split()[1]) // 1024
except FileNotFoundError:
return None
ram_mb = check_available_ram_mb()
if ram_mb is None:
print('Could not read /proc/meminfo on this OS — simulated Pi reading: MemAvailable ~ 850 MB')
else:
print(f'Available RAM: {ram_mb} MB')Verificação de conhecimentos
O que a quantização Q4_K_M significa para um modelo de linguagem?
Recapitulação: implantação de agentes leves na borda
O que você aprendeu nesta lição:
- Seleção do modelo: Phi-3-mini, Gemma-2B e TinyLlama para a borda; quantização Q4_K_M
- Ollama: servidor local de LLM com API compatível com a OpenAI na porta 11434
- Arquitetura híbrida: modelo de borda para decisões rápidas e nuvem para análises complexas
- Buffer offline: fila SQLite enviada para a nuvem quando a conexão é restabelecida
- Cache de inferência: o cache com TTL evita inferências repetidas para prompts idênticos
- Implantação: serviço systemd para reinicialização automática após uma falha
Próximo curso: Marketplace de agentes e sistemas de plugins.
Aprenda AI Agents com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 60
- Aulas
- 239
Perguntas Frequentes
A aula “Implantação de agentes leves na borda” é grátis?
Sim — o texto completo de “Implantação de agentes leves na borda” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Agents, atualize para CoddyKit PRO. O curso de AI Agents inclui 4 aulas no total.
O que vou aprender em “Implantação de agentes leves na borda”?
Executando modelos pequenos em Raspberry Pi e dispositivos de borda para obter respostas de baixa latência. Você pratica AI Agents com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Agents?
Nenhuma experiência prévia é necessária. AI Agents no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Implantação de agentes leves na borda”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Agents?
Sim. Cada aula de AI Agents inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Protocolo MQTT para integração de agentes
- Processamento de dados de séries temporais em agentes
- Resposta automatizada a eventos de sensores
- Implantação de agentes leves na borda