LLM

Interface unificada para múltiplos provedores de LLM com roteamento automático

Visão Geral

A camada de abstração de LLM fornece integração perfeita com múltiplos provedores de IA, permitindo alternar entre OpenAI, Claude, Gemini e Ollama sem alterar seu código. Ela lida com implementações específicas de cada provedor, formatação de mensagens e streaming, fornecendo uma API consistente entre todos os provedores.

Provedores Suportados

O Astreus suporta quatro principais provedores de LLM com roteamento automático de modelo:

Os exemplos selecionam modelos explicitamente; os padrões que continuam sendo suportados não mudam. Modelos descontinuados nas APIs nativas exigem a seleção explícita de um substituto atual.

OpenAI

IDs atuais de modelos para a API direta:

• gpt-6-astra
• gpt-5.6-sol
• gpt-5.6-terra
• gpt-5.6-luna
• Chave de API: Defina a variável de ambiente OPENAI_API_KEY

Em solicitações diretas à OpenAI, chamadas de ferramentas com GPT-6 Astra exigem a API Responses. O adaptador cuida desse protocolo; gateways compatíveis com OpenAI configurados usam Chat Completions. Não defina temperature nem top_p para GPT-6 Astra. Consulte o guia de modelos da OpenAI.

Anthropic Claude

IDs atuais de modelos para a API direta:

• claude-fable-5-1
• claude-opus-5
• claude-sonnet-5
• claude-haiku-4-5-20251001
• Chave de API: Defina a variável de ambiente ANTHROPIC_API_KEY

Google Gemini

Todos os 12 modelos suportados:

• Mais recentes: gemini-2.5-pro, gemini-2.5-pro-deep-think, gemini-2.5-flash, gemini-2.5-flash-lite
• Estáveis: 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
• Chave de API: Defina a variável de ambiente GEMINI_API_KEY

Ollama (Local)

Todos os 31 modelos suportados:

• Mais recentes: 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
• Adicionais: dolphin-mistral, openhermes, deepcoder, stable-code, wizardcoder, magicoder, solar, yi, zephyr, orca-mini, vicuna
• Configuração: Defina OLLAMA_BASE_URL (padrão: http://localhost:11434)

Configuração

# 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

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 hospedados gratuitos pelo OpenRouter

O OpenRouter usa o adaptador openai existente, não um quinto provedor. Configure a URL do gateway e a chave correspondente antes de criar um agente ou uma instância LLM. OPENROUTER_API_KEY é sua variável de ambiente, mapeada para OPENAI_API_KEY do adaptador.

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

Em 2026-09-13, o catálogo de modelos do OpenRouter listava preços de tokens de entrada e saída iguais a zero e suporte a ferramentas para estes IDs:

• openrouter/free
• nvidia/nemotron-3.5-lightning:free
• google/gemma-4-31b-it:free
• google/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);

O acesso hospedado gratuito tem limites de requisições e disponibilidade, não é ilimitado. Se um modelo gratuito estiver indisponível, trate o erro ou escolha outro modelo gratuito explicitamente; o Astreus não recorre automaticamente a modelos pagos. Uma licença gratuita do framework não torna as APIs hospedadas gratuitas, e o Ollama local ainda exige hardware e eletricidade.

Estes IDs com prefixo exigem o endpoint do OpenRouter. Para voltar à OpenAI direta, restaure OPENAI_BASE_URL=https://api.openai.com/v1 e uma chave emitida pela OpenAI em conjunto. Alterar a URL base afeta todas as solicitações que usam essa instância do adaptador.

Consultar modelos sem credenciais

getModelsByProvider lê o catálogo local do framework sem credenciais de API nem clientes autenticados. Isso não comprova que sua conta tenha acesso ou que um modelo hospedado esteja disponível naquele momento.

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

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

Exemplos de Uso

Uso Básico do 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);

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

Chamada de Funções

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

Opções do LLM

Configure o comportamento do LLM com estas opções:

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
}

Detalhes dos Parâmetros

• temperature: Opcional e dependente do modelo. Omita para GPT-6 Astra; nem todos os modelos aceitam controles de amostragem.
• maxTokens: Número máximo de tokens na resposta (varia de acordo com o modelo)
• stream: Habilita streaming em tempo real para respostas longas
• systemPrompt: Define o comportamento e o contexto do modelo
• tools: Habilita capacidades de chamada de função

Recursos por Provedor

Modelos de Visão

Cada provedor suporta modelos específicos para análise de imagens:

OpenAI Vision

• gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4-vision-preview
• gpt-4o-2024-08-06, gpt-4o-2024-05-13

Claude Vision

• claude-3-5-sonnet-20241022, claude-3-5-sonnet-20240620
• claude-3-opus-20240229, claude-3-sonnet-20240229, claude-3-haiku-20240307

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

Modelos de Embedding

Para base de conhecimento e busca semântica:

OpenAI Embeddings

• text-embedding-3-large (3072 dimensões)
• text-embedding-3-small (1536 dimensões)
• text-embedding-ada-002 (1536 dimensões)

Gemini Embeddings

• text-embedding-004
• embedding-001

Ollama Embeddings

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

Nota: Claude/Anthropic não suporta embeddings. Use OpenAI ou Gemini para geração de embeddings.

Variáveis de Ambiente Adicionais

# 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"

Guia de Seleção de Modelo

Para Geração de Código

• Melhores: gpt-4o, claude-3-5-sonnet-20241022, deepseek-coder
• Rápidos: gpt-4o-mini, claude-3-5-haiku-20241022

Para Tarefas de Raciocínio

• Melhores: claude-opus-4-20250514, gpt-6-astra, o3
• Equilibrados: claude-sonnet-4-20250514, gpt-4o

Para Escrita Criativa

• Melhores: gpt-6-astra, claude-3-opus-20240229
• Rápidos: gemini-2.5-pro, gpt-4o-mini

Para Privacidade/Uso Local

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