LLM

Interfaz unificada para múltiples proveedores de LLM con enrutamiento automático

Descripción general#

La capa de abstracción LLM proporciona una integración fluida con múltiples proveedores de IA, permitiéndote cambiar entre OpenAI, Claude, Gemini y Ollama sin modificar tu código. Se encarga de las implementaciones específicas de cada proveedor, del formateo de mensajes y del streaming, ofreciendo una API coherente en todos los proveedores.

Proveedores soportados#

Astreus soporta cuatro grandes proveedores de LLM con enrutamiento automático de modelos:

Los ejemplos seleccionan modelos explícitamente; los valores predeterminados que siguen siendo compatibles no cambian. Los modelos retirados de las API nativas requieren seleccionar explícitamente un reemplazo vigente.

OpenAI#

Identificadores actuales para la API directa:

  • gpt-6-astra
  • gpt-5.6-sol
  • gpt-5.6-terra
  • gpt-5.6-luna
  • Clave de API: define la variable de entorno OPENAI_API_KEY

En las solicitudes directas a OpenAI, las llamadas a herramientas de GPT-6 Astra requieren la API Responses. El adaptador gestiona ese protocolo; los gateways compatibles con OpenAI configurados utilizan Chat Completions. No establezcas temperature ni top_p para GPT-6 Astra. Consulta la guía de modelos de OpenAI.

Anthropic Claude#

Identificadores actuales para la API directa:

  • claude-fable-5-1
  • claude-opus-5
  • claude-sonnet-5
  • claude-haiku-4-5-20251001
  • Clave de API: define la variable de entorno ANTHROPIC_API_KEY

Google Gemini#

Los 12 modelos soportados:

  • Últimos: gemini-2.5-pro, gemini-2.5-pro-deep-think, gemini-2.5-flash, gemini-2.5-flash-lite
  • Estables: gemini-2.0-flash, gemini-2.0-flash-thinking, gemini-2.0-flash-lite, gemini-2.0-pro-experimental, gemini-1.5-pro, gemini-1.5-flash, gemini-1.5-flash-8b, gemini-pro
  • Clave de API: define la variable de entorno GEMINI_API_KEY

Ollama (local)#

Los 31 modelos soportados:

  • Últimos: deepseek-r1, deepseek-v3, deepseek-v2.5, deepseek-coder, deepseek-coder-v2, qwen3, qwen2.5-coder, llama3.3, gemma3, phi4
  • Populares: mistral-small, codellama, llama3.2, llama3.1, qwen2.5, gemma2, phi3, mistral, codegemma, wizardlm2
  • Adicionales: dolphin-mistral, openhermes, deepcoder, stable-code, wizardcoder, magicoder, solar, yi, zephyr, orca-mini, vicuna
  • Configuración: define OLLAMA_BASE_URL (por defecto: http://localhost:11434)

Configuración#

Variables de entorno#

Configura tus claves de API y ajustes:

Proporciona solo las credenciales del proveedor que utilices mediante el entorno de tu shell o un gestor de secretos. Los comandos siguientes leen valores existentes del entorno; no contienen claves de API.

bash
# OpenAI
export OPENAI_API_KEY="${OPENAI_API_KEY:?Set OPENAI_API_KEY in your environment}"
export OPENAI_BASE_URL="https://api.openai.com/v1"  # Optional

# Anthropic Claude
export ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:?Set ANTHROPIC_API_KEY in your environment}"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"  # Optional

# Google Gemini
export GEMINI_API_KEY="${GEMINI_API_KEY:?Set GEMINI_API_KEY in your environment}"

# Ollama (Local)
export OLLAMA_BASE_URL="http://localhost:11434"  # Optional

Configuración del agente#

Especifica el modelo al crear los agentes:

typescript
import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'MyAgent',
  model: 'gpt-6-astra',  // Explicit selection, not a default change
  maxTokens: 2000
});

Modelos alojados gratuitos a través de OpenRouter#

OpenRouter utiliza el adaptador openai existente, no un quinto proveedor. Configura la URL del gateway y su clave correspondiente antes de crear un agente o una instancia LLM. OPENROUTER_API_KEY es tu variable de entorno y se asigna a OPENAI_API_KEY del adaptador.

bash
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_API_KEY="${OPENROUTER_API_KEY:?Set OPENROUTER_API_KEY in your environment}"

El 2026-09-13, el catálogo de modelos de OpenRouter indicaba precios de tokens de entrada y salida de cero y soporte de herramientas para estos identificadores:

  • openrouter/free
  • nvidia/nemotron-3.5-lightning:free
  • google/gemma-4-31b-it:free
  • google/gemma-4-26b-a4b-it:free
typescript
import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'HostedFreeAgent',
  model: 'openrouter/free',
  maxTokens: 1000
});

const response = await agent.ask('Explain how a hash table works.');
console.log(response);

El acceso alojado gratuito tiene límites de solicitudes y disponibilidad; no es ilimitado. Si un modelo gratuito no está disponible, gestiona el error o elige otro modelo gratuito explícitamente; Astreus no recurre automáticamente a modelos de pago. Una licencia gratuita del framework no convierte las API alojadas en gratuitas, y Ollama local sigue necesitando hardware y electricidad.

Estos identificadores con prefijo requieren el endpoint de OpenRouter. Para volver a OpenAI directo, restablece conjuntamente OPENAI_BASE_URL=https://api.openai.com/v1 y una clave emitida por OpenAI. Cambiar la URL base afecta a todas las solicitudes que utilicen esa instancia del adaptador.

Consultar modelos sin credenciales#

getModelsByProvider lee el catálogo local del framework sin credenciales de API ni clientes autenticados. No demuestra que tu cuenta tenga acceso ni que un modelo alojado esté disponible en ese momento.

typescript
import { getModelsByProvider } from '@astreus-ai/astreus';

const modelIds = getModelsByProvider('openai');
console.log(modelIds);

Ejemplos de uso#

Uso básico del LLM#

typescript
import { getLLM } from '@astreus-ai/astreus';

const llm = getLLM();

// Generate response
const response = await llm.generateResponse({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: 'Explain quantum computing' }],
  maxTokens: 1000
});

console.log(response.content);

Respuestas en streaming#

typescript
// Stream response in real-time
for await (const chunk of llm.generateStreamResponse({
  model: 'gpt-6-astra',
  messages: [{ role: 'user', content: 'Write a story about AI' }],
  stream: true
})) {
  if (!chunk.done) {
    process.stdout.write(chunk.content);
  }
}

Llamadas a funciones#

typescript
const response = await llm.generateResponse({
  model: 'gpt-6-astra',
  messages: [{ role: 'user', content: 'What\'s the weather in Tokyo?' }],
  tools: [{
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get current weather information',
      parameters: {
        type: 'object',
        properties: {
          location: { 
            type: 'string',
            description: 'City name'
          }
        },
        required: ['location']
      }
    }
  }]
});

// Handle tool calls
if (response.toolCalls) {
  response.toolCalls.forEach(call => {
    console.log(`Tool: ${call.function.name}`);
    console.log(`Args: ${call.function.arguments}`);
  });
}

Opciones del LLM#

Configura el comportamiento del LLM con estas opciones:

typescript
interface LLMRequestOptions {
  model: string;              // Required: Model identifier
  messages: LLMMessage[];     // Required: Conversation history
  temperature?: number;       // Model-dependent; omit for GPT-6 Astra
  maxTokens?: number;         // Max output tokens (default: 4096)
  stream?: boolean;           // Enable streaming responses
  systemPrompt?: string;      // System instructions
  tools?: Tool[];             // Function calling tools
}

Detalle de los parámetros#

  • temperature: opcional y dependiente del modelo. Omítelo para GPT-6 Astra; no todos los modelos admiten controles de muestreo.
  • maxTokens: número máximo de tokens en la respuesta (varía según el modelo)
  • stream: habilita el streaming en tiempo real para respuestas largas
  • systemPrompt: establece el comportamiento y el contexto del modelo
  • tools: habilita las capacidades de llamada a funciones

Funcionalidades por proveedor#

FuncionalidadOpenAIClaudeGeminiOllama
Streaming✅✅✅✅
Llamadas a funciones✅✅LimitadoLimitado
Visión✅✅✅✅
Embeddings✅❌✅✅
Uso de tokens✅✅Limitado✅
URL base personalizada✅✅❌✅
Modelos locales❌❌❌✅

Modelos de visión#

Cada proveedor soporta modelos específicos para el análisis de imágenes:

Visión de OpenAI#

  • gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, gpt-5.4-mini, gpt-5.4-nano
  • gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, gpt-4-turbo

Visión de Claude#

  • claude-fable-5-1, claude-opus-5, claude-sonnet-5
  • claude-haiku-4-5-20251001

Visión de Gemini#

  • gemini-1.5-pro, gemini-1.5-flash
  • gemini-1.0-pro-vision-latest, gemini-pro-vision

Visión de Ollama#

  • llava, llava:7b, llava:13b, llava:34b
  • llava-llama3, llava-phi3, moondream

Modelos de embedding#

Para la base de conocimiento y la búsqueda semántica:

Embeddings de OpenAI#

  • text-embedding-3-large (3072 dimensiones)
  • text-embedding-3-small (1536 dimensiones)
  • text-embedding-ada-002 (1536 dimensiones)

Embeddings de Gemini#

  • text-embedding-004
  • embedding-001

Embeddings de Ollama#

  • nomic-embed-text, mxbai-embed-large
  • all-minilm, snowflake-arctic-embed

Nota: Claude/Anthropic no soporta embeddings. Usa OpenAI o Gemini para la generación de embeddings.

Variables de entorno adicionales#

bash
# Dedicated embedding API keys (optional)
OPENAI_EMBEDDING_API_KEY="your-embedding-key"
OPENAI_EMBEDDING_BASE_URL="https://api.openai.com/v1"
GEMINI_EMBEDDING_API_KEY="your-gemini-embedding-key"

# Dedicated vision API keys (optional)
OPENAI_VISION_API_KEY="your-vision-key"
OPENAI_VISION_BASE_URL="https://api.openai.com/v1"
ANTHROPIC_VISION_API_KEY="your-anthropic-vision-key"
ANTHROPIC_VISION_BASE_URL="https://api.anthropic.com"
GEMINI_VISION_API_KEY="your-gemini-vision-key"

Guía de selección de modelos#

Para generación de código#

  • Mejor: gpt-6-astra, claude-sonnet-5, deepseek-coder
  • Rápido: gpt-4o-mini, claude-haiku-4-5-20251001

Para tareas de razonamiento#

  • Mejor: claude-opus-5, gpt-6-astra, o3
  • Equilibrado: claude-sonnet-5, gpt-4o

Para escritura creativa#

  • Mejor: gpt-6-astra, claude-opus-5
  • Rápido: gemini-2.5-pro, gpt-4o-mini

Para privacidad/uso local#

  • Mejor: deepseek-r1, llama3.3, qwen3
  • Código: deepseek-coder, codellama