LLM

자동 라우팅을 지원하는 여러 LLM 프로바이더를 위한 통합 인터페이스

Overview

LLM 추상화 계층은 여러 AI 프로바이더와의 원활한 통합을 제공하여, 코드를 변경하지 않고도 OpenAI, Claude, Gemini, Ollama 간에 전환할 수 있게 합니다. 프로바이더별 구현, 메시지 포맷팅, 스트리밍을 처리하면서 모든 프로바이더에 걸쳐 일관된 API를 제공합니다.

Supported Providers

Astreus는 자동 모델 라우팅을 지원하는 4개의 주요 LLM 프로바이더를 지원합니다.

예제는 모델을 명시적으로 선택하며, 계속 지원되는 기존 기본값은 변경되지 않습니다. 네이티브 API에서 지원이 종료된 모델은 현재 사용 가능한 대체 모델을 명시적으로 선택해야 합니다.

OpenAI

직접 API용 현재 모델 ID:

• gpt-6-astra
• gpt-5.6-sol
• gpt-5.6-terra
• gpt-5.6-luna
• API Key: OPENAI_API_KEY 환경 변수를 설정하세요

OpenAI에 직접 요청할 때 GPT-6 Astra의 도구 호출에는 Responses API가 필요합니다. 어댑터가 이 프로토콜을 처리하며, 설정된 OpenAI 호환 게이트웨이는 Chat Completions를 사용합니다. GPT-6 Astra에는 temperature와 top_p를 설정하지 마세요. OpenAI 모델 가이드를 참고하세요.

Anthropic Claude

직접 API용 현재 모델 ID:

• claude-fable-5-1
• claude-opus-5
• claude-sonnet-5
• claude-haiku-4-5-20251001
• API Key: ANTHROPIC_API_KEY 환경 변수를 설정하세요

Google Gemini

지원되는 12개 모델 전체:

• Latest: gemini-2.5-pro, gemini-2.5-pro-deep-think, gemini-2.5-flash, gemini-2.5-flash-lite
• Stable: 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
• API Key: GEMINI_API_KEY 환경 변수를 설정하세요

Ollama (Local)

지원되는 31개 모델 전체:

• Latest: deepseek-r1, deepseek-v3, deepseek-v2.5, deepseek-coder, deepseek-coder-v2, qwen3, qwen2.5-coder, llama3.3, gemma3, phi4
• Popular: mistral-small, codellama, llama3.2, llama3.1, qwen2.5, gemma2, phi3, mistral, codegemma, wizardlm2
• Additional: dolphin-mistral, openhermes, deepcoder, stable-code, wizardcoder, magicoder, solar, yi, zephyr, orca-mini, vicuna
• Configuration: OLLAMA_BASE_URL을 설정하세요 (기본값: http://localhost:11434)

Configuration

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

OpenRouter를 통한 무료 호스팅 모델

OpenRouter는 기존 openai 어댑터를 사용하며 다섯 번째 프로바이더가 아닙니다. 에이전트나 LLM 인스턴스를 생성하기 전에 게이트웨이 URL과 해당 키를 함께 설정하세요. OPENROUTER_API_KEY는 사용자가 설정하는 환경 변수이며 어댑터의 OPENAI_API_KEY에 할당됩니다.

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

2026-09-13 기준 OpenRouter 모델 카탈로그는 다음 ID의 입력 및 출력 토큰 가격을 0으로, 도구 지원을 제공하는 것으로 표시했습니다.

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

무료 호스팅에는 요청 속도 및 가용성 제한이 있으며 무제한 서비스가 아닙니다. 무료 모델을 사용할 수 없으면 오류를 처리하거나 다른 무료 모델을 명시적으로 선택하세요. Astreus는 자동으로 유료 모델로 전환하지 않습니다. 무료 프레임워크 라이선스가 호스팅 API의 무료 사용을 의미하지는 않으며, 로컬 Ollama에도 하드웨어와 전력이 필요합니다.

이 네임스페이스가 포함된 ID에는 OpenRouter 엔드포인트가 필요합니다. OpenAI 직접 연결로 돌아가려면 OPENAI_BASE_URL=https://api.openai.com/v1과 OpenAI에서 발급한 키를 함께 복원하세요. 기본 URL을 바꾸면 해당 어댑터 인스턴스를 사용하는 모든 요청에 영향을 줍니다.

인증 정보 없이 모델 조회하기

getModelsByProvider는 API 인증 정보나 인증된 클라이언트 없이 프레임워크의 로컬 카탈로그를 읽습니다. 계정의 접근 권한이나 호스팅 모델의 현재 가용성을 보장하지는 않습니다.

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

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

Usage Examples

Basic LLM Usage

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

Streaming Responses

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

Function Calling

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

LLM Options

다음 옵션으로 LLM 동작을 설정하세요.

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
}

Parameter Details

• temperature: 선택 사항이며 모델에 따라 다릅니다. GPT-6 Astra에서는 생략하세요. 모든 모델이 샘플링 설정을 지원하는 것은 아닙니다.
• maxTokens: 응답의 최대 토큰 수입니다 (모델별로 다름)
• stream: 긴 응답에 대해 실시간 스트리밍을 활성화합니다
• systemPrompt: 모델의 동작과 컨텍스트를 설정합니다
• tools: 함수 호출 기능을 활성화합니다

Provider Features

Vision Models

각 프로바이더는 이미지 분석을 위한 특정 모델을 지원합니다.

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

Embedding Models

지식 베이스와 시맨틱 검색을 위한 모델입니다.

OpenAI Embeddings

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

Gemini Embeddings

• text-embedding-004
• embedding-001

Ollama Embeddings

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

참고: Claude/Anthropic은 임베딩을 지원하지 않습니다. 임베딩 생성에는 OpenAI 또는 Gemini를 사용하세요.

Additional Environment Variables

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

Model Selection Guide

For Code Generation

• Best: gpt-4o, claude-3-5-sonnet-20241022, deepseek-coder
• Fast: gpt-4o-mini, claude-3-5-haiku-20241022

For Reasoning Tasks

• Best: claude-opus-4-20250514, gpt-6-astra, o3
• Balanced: claude-sonnet-4-20250514, gpt-4o

For Creative Writing

• Best: gpt-6-astra, claude-3-opus-20240229
• Fast: gemini-2.5-pro, gpt-4o-mini

For Privacy/Local Use

• Best: deepseek-r1, llama3.3, qwen3
• Code: deepseek-coder, codellama