LLM

Interfaccia unificata per più provider LLM con routing automatico

Panoramica#

Il livello di astrazione LLM offre un'integrazione fluida con più provider AI, permettendoti di passare da OpenAI, Claude, Gemini e Ollama senza modificare il tuo codice. Gestisce le implementazioni specifiche di ogni provider, la formattazione dei messaggi e lo streaming, offrendo al contempo un'API coerente su tutti i provider.

Provider supportati#

Astreus supporta quattro provider LLM principali con routing automatico dei modelli:

Gli esempi selezionano i modelli esplicitamente; i valori predefiniti ancora supportati non cambiano. I modelli ritirati dalle API native richiedono la selezione esplicita di un modello attuale in sostituzione.

OpenAI#

ID attuali dei modelli per l’API diretta:

  • gpt-6-astra
  • gpt-5.6-sol
  • gpt-5.6-terra
  • gpt-5.6-luna
  • Chiave API: imposta la variabile d'ambiente OPENAI_API_KEY

Nelle richieste dirette a OpenAI, le chiamate agli strumenti di GPT-6 Astra richiedono l’API Responses. L’adattatore gestisce questo protocollo; i gateway compatibili con OpenAI configurati usano Chat Completions. Non impostare temperature né top_p per GPT-6 Astra. Consulta la guida ai modelli OpenAI.

Anthropic Claude#

ID attuali dei modelli per l’API diretta:

  • claude-fable-5-1
  • claude-opus-5
  • claude-sonnet-5
  • claude-haiku-4-5-20251001
  • Chiave API: imposta la variabile d'ambiente ANTHROPIC_API_KEY

Google Gemini#

Tutti i 12 modelli supportati:

  • Ultimi: gemini-2.5-pro, gemini-2.5-pro-deep-think, gemini-2.5-flash, gemini-2.5-flash-lite
  • Stabili: 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
  • Chiave API: imposta la variabile d'ambiente GEMINI_API_KEY

Ollama (locale)#

Tutti i 31 modelli supportati:

  • Ultimi: deepseek-r1, deepseek-v3, deepseek-v2.5, deepseek-coder, deepseek-coder-v2, qwen3, qwen2.5-coder, llama3.3, gemma3, phi4
  • Popolari: mistral-small, codellama, llama3.2, llama3.1, qwen2.5, gemma2, phi3, mistral, codegemma, wizardlm2
  • Aggiuntivi: dolphin-mistral, openhermes, deepcoder, stable-code, wizardcoder, magicoder, solar, yi, zephyr, orca-mini, vicuna
  • Configurazione: imposta OLLAMA_BASE_URL (predefinito: http://localhost:11434)

Configurazione#

Variabili d'ambiente#

Configura le tue chiavi API e le impostazioni:

Fornisci solo le credenziali del provider utilizzato tramite l’ambiente della shell o un gestore di segreti. I comandi seguenti leggono valori già presenti nell’ambiente; non contengono chiavi 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

Configurazione dell'Agent#

Specifica il modello quando crei gli agent:

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
});

Modelli ospitati gratuiti tramite OpenRouter#

OpenRouter usa l’adattatore openai esistente, non un quinto provider. Imposta l’URL del gateway e la chiave corrispondente prima di creare un agente o un’istanza LLM. OPENROUTER_API_KEY è la tua variabile d’ambiente, assegnata a OPENAI_API_KEY dell’adattatore.

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

Il 2026-09-13, il catalogo dei modelli OpenRouter indicava prezzi dei token di input e output pari a zero e supporto degli strumenti per questi ID:

  • 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);

L’accesso ospitato gratuito ha limiti di richieste e disponibilità, non è illimitato. Se un modello gratuito non è disponibile, gestisci l’errore o scegli esplicitamente un altro modello gratuito; Astreus non passa automaticamente a modelli a pagamento. Una licenza gratuita del framework non rende gratuite le API ospitate, e Ollama in locale richiede comunque hardware ed elettricità.

Questi ID con namespace richiedono l’endpoint OpenRouter. Per tornare a OpenAI diretto, ripristina insieme OPENAI_BASE_URL=https://api.openai.com/v1 e una chiave emessa da OpenAI. Modificare l’URL di base influisce su tutte le richieste che usano quell’istanza dell’adattatore.

Consultare i modelli senza credenziali#

getModelsByProvider legge il catalogo locale del framework senza credenziali API né client autenticati. Non dimostra che il tuo account abbia accesso o che un modello ospitato sia attualmente disponibile.

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

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

Esempi di utilizzo#

Utilizzo base dell'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);

Risposte in 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);
  }
}

Chiamata a funzioni#

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}`);
  });
}

Opzioni LLM#

Configura il comportamento dell'LLM con queste opzioni:

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
}

Dettagli dei parametri#

  • temperature: opzionale e dipendente dal modello. Omettilo per GPT-6 Astra; non tutti i modelli accettano controlli di campionamento.
  • maxTokens: numero massimo di token nella risposta (varia in base al modello)
  • stream: abilita lo streaming in tempo reale per risposte lunghe
  • systemPrompt: imposta il comportamento e il contesto per il modello
  • tools: abilita le capacità di function calling

Funzionalità per provider#

FunzionalitàOpenAIClaudeGeminiOllama
Streaming✅✅✅✅
Function Calling✅✅LimitatoLimitato
Vision✅✅✅✅
Embedding✅❌✅✅
Utilizzo dei token✅✅Limitato✅
Base URL personalizzato✅✅❌✅
Modelli locali❌❌❌✅

Modelli Vision#

Ogni provider supporta modelli specifici per l'analisi delle immagini:

OpenAI Vision#

  • 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

Claude Vision#

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

Gemini Vision#

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

Ollama Vision#

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

Modelli di Embedding#

Per la knowledge base e la ricerca semantica:

OpenAI Embeddings#

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

Gemini Embeddings#

  • text-embedding-004
  • embedding-001

Ollama Embeddings#

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

Nota: Claude/Anthropic non supporta gli embedding. Usa OpenAI o Gemini per la generazione di embedding.

Variabili d'ambiente aggiuntive#

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"

Guida alla selezione del modello#

Per la generazione di codice#

  • Migliori: gpt-6-astra, claude-sonnet-5, deepseek-coder
  • Veloci: gpt-4o-mini, claude-haiku-4-5-20251001

Per task di ragionamento#

  • Migliori: claude-opus-5, gpt-6-astra, o3
  • Bilanciati: claude-sonnet-5, gpt-4o

Per la scrittura creativa#

  • Migliori: gpt-6-astra, claude-opus-5
  • Veloci: gemini-2.5-pro, gpt-4o-mini

Per privacy/uso locale#

  • Migliori: deepseek-r1, llama3.3, qwen3
  • Codice: deepseek-coder, codellama