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-astragpt-5.6-solgpt-5.6-terragpt-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-1claude-opus-5claude-sonnet-5claude-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.
# 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" # OptionalConfigurazione dell'Agent#
Specifica il modello quando crei gli agent:
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.
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/freenvidia/nemotron-3.5-lightning:freegoogle/gemma-4-31b-it:freegoogle/gemma-4-26b-a4b-it:free
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.
import { getModelsByProvider } from '@astreus-ai/astreus';
const modelIds = getModelsByProvider('openai');
console.log(modelIds);Esempi di utilizzo#
Utilizzo base dell'LLM#
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#
// 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#
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:
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à | OpenAI | Claude | Gemini | Ollama |
|---|---|---|---|---|
| Streaming | ✅ | ✅ | ✅ | ✅ |
| Function Calling | ✅ | ✅ | Limitato | Limitato |
| 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-nanogpt-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-5claude-haiku-4-5-20251001
Gemini Vision#
gemini-1.5-pro,gemini-1.5-flashgemini-1.0-pro-vision-latest,gemini-pro-vision
Ollama Vision#
llava,llava:7b,llava:13b,llava:34bllava-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-004embedding-001
Ollama Embeddings#
nomic-embed-text,mxbai-embed-largeall-minilm,snowflake-arctic-embed
Nota: Claude/Anthropic non supporta gli embedding. Usa OpenAI o Gemini per la generazione di embedding.
Variabili d'ambiente aggiuntive#
# 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