Modelos Locales con Ollama
Ejecuta modelos de pesos abiertos como Google Gemma 2, Llama 3 y Mistral en hardware local sin costos de nube.
chatflow-agent soporta modelos de lenguaje locales a través de su motor universal compatible con OpenAI. Al combinar el framework con Ollama, puedes construir flujos de trabajo de agentes autónomos, herramientas y handoffs multi-agente que se ejecutan enteramente sobre GPUs locales o chips Apple Silicon, con cero costos de API, cero egreso de datos y total capacidad offline.
Configuración Rápida
Instalar e Iniciar Ollama
Descarga e instala Ollama desde ollama.com. Descarga un modelo que soporte llamadas estructuradas a herramientas de forma nativa (como Google Gemma 2 o Meta Llama 3.2):
ollama pull gemma2:9b
ollama pull llama3.2Ollama expone un endpoint de API compatible con OpenAI por defecto en http://localhost:11434/v1.
Definir un Agente Local
chatflow-agent enruta automáticamente los nombres de modelos que comienzan con gemma, llama, mistral, qwen o phi al preajuste del motor Ollama:
from chatflow_agent import Agent, Runner
# Enrutado automáticamente a http://localhost:11434/v1
local_agent = Agent(
name="LocalAssistant",
model="gemma2:9b",
instructions="You are a helpful offline assistant.",
)
runner = Runner(starting_agent=local_agent)Configuración Explícita del Motor
Si tu servidor de Ollama se ejecuta en una máquina remota de tu red local (por ejemplo, una estación de trabajo con GPU dedicada o servidor homelab), configura OpenAIEngine explícitamente:
from chatflow_agent import Agent, Runner
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine
# Conectando a un servidor Ollama remoto en red local (LAN)
remote_ollama = OpenAIEngine(
base_url="http://192.168.1.50:11434/v1",
provider="ollama",
api_key="ollama", # Clave ficticia para endpoints locales no autenticados
timeout=120.0, # Tiempo límite ampliado para inferencia local en GPU
)
gpu_agent = Agent(
name="GPUAssistant",
model="llama3.1:70b",
engine=remote_ollama,
instructions="Analyze complex local datasets without cloud egress.",
)
runner = Runner(starting_agent=gpu_agent)Regla de Seguridad: Exención para Conexiones Locales (Loopback)
El framework protege tus credenciales en la nube durante el desarrollo local:
- Detección de Loopback: Cuando
base_urlapunta alocalhost,127.0.0.1,::1o0.0.0.0,OpenAIEnginedetecta un entorno local. - Aislamiento de Credenciales: Nunca enviará tu
OPENAI_API_KEYniANTHROPIC_API_KEYa endpoints locales. - Clave de Respaldo Automática: Dado que los servidores locales no suelen requerir autenticación pero el cliente HTTP de OpenAI exige una cabecera
Authorizationno vacía, el motor proporciona automáticamente"ollama"como clave ficticia si no se especifica ninguna.
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine
# Seguro: utiliza automáticamente la clave ficticia "ollama" sin acceder a credenciales de la nube
engine = OpenAIEngine(
base_url="http://localhost:11434/v1",
provider="ollama",
)
assert engine.api_key == "ollama"Llamadas a Funciones con Modelos Locales
Los modelos abiertos modernos (como llama3.1, llama3.2 y qwen2.5) soportan llamadas estructuradas a herramientas de forma nativa:
from chatflow_agent import Agent, Runner, tool
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine
@tool
def calculate_vat(amount: float, rate_pct: float = 21.0) -> float:
"""Calculate the VAT amount for a given base price.
Args:
amount: Base monetary amount before tax.
rate_pct: VAT rate percentage (defaults to 21.0).
"""
return round(amount * (rate_pct / 100.0), 2)
ollama_engine = OpenAIEngine(
base_url="http://localhost:11434/v1",
provider="ollama",
timeout=90.0,
)
finance_agent = Agent(
name="FinanceAgent",
model="llama3.2",
engine=ollama_engine,
tools=[calculate_vat],
instructions="Calculate tax obligations using the calculate_vat tool.",
)
runner = Runner(starting_agent=finance_agent)Buenas Prácticas para Inferencia Local
Consejos para una Ejecución Fiable de Agentes Locales
- Tamaño del Modelo y Cuantización: Para agentes con múltiples herramientas, utiliza modelos con al menos 8B parámetros (
qwen2.5:7b,llama3.1:8b,gemma2:9b). Modelos más pequeños de 1B a 3B pueden presentar dificultades ocasionales con esquemas complejos de herramientas JSON. - Ajuste de Tiempos Límite: La velocidad de inferencia local depende del hardware. Configura
timeout=90.0o120.0enOpenAIEnginepara evitar tiempos límite agotados durante la evaluación de prompts en historiales largos. - Descripciones Concisas: Asegúrate de que los docstrings en funciones
@toolsean descriptivos pero concisos para minimizar el consumo de tokens en ventanas de contexto locales.
Arquitectura Híbrida: Enjambres Locales y en la Nube
Puedes combinar agentes locales y en la nube dentro del mismo enjambre multi-agente. Por ejemplo, un modelo local maneja el triaje de datos privados y transfiere el diálogo a un modelo de frontera en la nube solo para síntesis compleja:
import os
from chatflow_agent import Agent, Runner
from chatflow_agent.core.engines.openai_compatible import OpenAIEngine
from chatflow_agent.core.engines.gemini import GeminiEngine
# Agente local para triaje privado
triage_agent = Agent(
name="PrivateTriage",
model="gemma2:9b",
provider="ollama",
instructions="Filter PII and categorize queries locally.",
)
# Agente en la nube para síntesis
synthesis_agent = Agent(
name="CloudSynthesis",
model="gemini-2.5-flash",
engine=GeminiEngine(api_key=os.environ.get("GEMINI_API_KEY")),
instructions="Synthesize public knowledge into structured reports.",
)
triage_agent.add_handoff(synthesis_agent)
runner = Runner(starting_agent=triage_agent)Google Gemini y Anthropic Claude
Integración de modelos fundacionales de alto rendimiento con Google Gemini REST v1beta y Anthropic Claude Messages API.
Integración con Bots de Telegram
Despliega asistentes de IA multi-agente en Telegram con python-telegram-bot, memoria de sesión, división de mensajes y controles de administración para grupos.