AI Agents · Lección

Despliegue en el edge de agentes ligeros

Ejecución de modelos pequeños en Raspberry Pi y dispositivos edge para obtener respuestas de baja latencia.

Lección 4 de 413 pasos

Despliegue en el edge de agentes ligeros es una lección gratuita de AI Agents en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de AI Agents, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de AI Agents incluye 4 lecciones en total.

Agentes de IA en el edge

Un agente edge se ejecuta directamente en el dispositivo IoT o la pasarela local —una Raspberry Pi, Jetson Nano o un PC industrial— en lugar de hacerlo en la nube. Ventajas: menor latencia (sin viaje de ida y vuelta), funcionamiento sin conexión y menor costo de ancho de banda. Desventaja: la capacidad limitada de cómputo y RAM exige modelos más pequeños y eficientes.

Elección de un modelo para el despliegue en el edge

Los dispositivos edge no pueden ejecutar GPT-4o ni Claude Opus. Algunos modelos pequeños que caben en una Raspberry Pi 5 (8 GB de RAM) son: Phi-3-mini (3.8B parámetros), Gemma-2B y TinyLlama-1.1B. Cuando se cuantizan a 4 bits, estos modelos requieren entre 1 y 3 GB de RAM y se ejecutan a una velocidad de 5–15 tokens por segundo en la 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"]}')

Instalación de Ollama en Raspberry Pi

Ollama es la forma más sencilla de ejecutar LLM pequeños en hardware local. Gestiona las descargas y la cuantización de modelos, además de proporcionar una API REST local compatible con el OpenAI SDK. Un comando lo instala y otro descarga e inicia el 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)

Cuantización GGUF de 4 bits

GGUF (GPT-Generated Unified Format) es el formato de archivo que utilizan llama.cpp y Ollama para los modelos cuantizados. Q4_K_M significa cuantización mixta de 4 bits: aproximadamente un 75 % más pequeño que fp32, con una pérdida mínima de calidad para tareas de razonamiento en el edge.

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

Optimización de la velocidad de inferencia en la CPU

En dispositivos edge que solo usan CPU, la velocidad de inferencia depende del número de hilos y del almacenamiento en caché del prompt. Establezca el número de hilos para que coincida con los núcleos de la CPU, mantenga corto el prompt del sistema (se vuelve a procesar en cada llamada si no está en caché) y agrupe las consultas repetidas por lotes cuando sea posible.

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)

Arquitectura híbrida edge-cloud

La arquitectura óptima utiliza el modelo edge para decisiones rápidas y de bajo riesgo (clasificación, lógica de umbrales) y se sincroniza con el modelo en la nube para decisiones complejas, poco frecuentes o de alto riesgo. El agente edge pone en cola las consultas complejas y las envía cuando la conectividad lo 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()

Cola sin conexión para la sincronización con la nube

Los agentes edge suelen funcionar en entornos con conectividad intermitente. Almacene temporalmente las consultas, las lecturas de sensores y los registros de acciones de forma local y envíelos a la nube cuando se restablezca la conectividad. Utilice una base de datos SQLite como búfer 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}'))

Supervisión del estado del agente edge

Los dispositivos edge pueden sobrecalentarse, quedarse sin RAM o sufrir bloqueos durante la inferencia del modelo. Implemente un monitor de estado que compruebe la temperatura de la CPU, la RAM libre y la latencia de inferencia, y publique las métricas de estado en la nube.

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)

Caché de inferencias para agentes edge

Los modelos edge son lentos; almacene en caché las respuestas para entradas idénticas. En las tareas de clasificación de sensores, el mismo prompt (por ejemplo, "temperature=23.5, classify") suele repetirse. Un caché sencillo basado en un dict con TTL evita llamadas de inferencia 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 result

Lista de comprobación del despliegue

Antes de desplegar un agente edge en producción, verifique lo siguiente: que el modelo quepa en la RAM disponible con un margen adicional del 20 %, que la latencia de inferencia cumpla el requisito de respuesta del evento, que el búfer sin conexión se haya probado, que la supervisión del estado esté publicando métricas y que esté configurado el reinicio automático en caso de fallo.

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

Configuración del hardware de Raspberry Pi

Antes de desplegar el software, prepare el hardware. Una Raspberry Pi 5 con 8 GB de RAM es el mínimo recomendado para ejecutar Phi-3-mini. Habilite la división de memoria de la GPU, desactive el espacio de intercambio (degrada el almacenamiento flash) y configure una IP estática para permitir un acceso remoto fiable.

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

Comprobación de conocimientos

¿Qué significa la cuantización Q4_K_M para un modelo de lenguaje?

Responde en la lección interactiva

Repaso: despliegue edge de agentes ligeros

Lo que ha aprendido en esta lección:

Selección del modelo: Phi-3-mini, Gemma-2B y TinyLlama para edge; cuantización Q4_K_M
Ollama: servidor LLM local con una API compatible con OpenAI en el puerto 11434
Arquitectura híbrida: modelo edge para decisiones rápidas y nube para análisis complejos
Búfer sin conexión: cola SQLite que se envía a la nube al restablecerse la conexión
Caché de inferencias: el caché con TTL evita repetir inferencias para prompts idénticos
Despliegue: servicio de systemd para reiniciar automáticamente el agente tras un fallo

Siguiente curso: Marketplace de agentes y sistemas de plugins.

Gratis para empezar

Aprende AI Agents con un tutor de IA — gratis

Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.

Cursos: 60
Lecciones: 239

Empezar a aprender gratis Ver el curso completo

Preguntas frecuentes

¿La lección «Despliegue en el edge de agentes ligeros» es gratis?

Sí — el texto completo de «Despliegue en el edge de agentes ligeros» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de AI Agents, actualiza a CoddyKit PRO. El curso de AI Agents incluye 4 lecciones en total.

¿Qué aprenderé en «Despliegue en el edge de agentes ligeros»?

Ejecución de modelos pequeños en Raspberry Pi y dispositivos edge para obtener respuestas de baja latencia. Practicas AI Agents con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.

¿Necesito experiencia previa para empezar AI Agents?

No se requiere experiencia previa. AI Agents en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.

¿Cuánto tiempo toma la lección «Despliegue en el edge de agentes ligeros»?

La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.

¿Puedo escribir y ejecutar código en esta lección de AI Agents?

Sí. Cada lección de AI Agents incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.

Todas las lecciones de este curso

Protocolo MQTT para la integración de agentes
Procesamiento de datos de series temporales en agentes
Respuesta automatizada a eventos de sensores
Despliegue en el edge de agentes ligeros

← Volver a AI Agents