Model 제공자

Mastra는 여러 Provider의 LLM 작업을 위한 통합 인터페이스를 제공하므로 단일 API를 통해 168개 Provider의 5458개 Model에 액세스할 수 있습니다.

특징

• 모든 Model을 위한 하나의 API: 추가 공급자 종속성을 설치하고 관리할 필요 없이 모든 Model에 액세스할 수 있습니다.

• 최신 AI에 액세스: 어떤 Provider에서든 새로운 Model이 출시되는 즉시 사용하세요. Mastra의 공급자 독립적인 인터페이스로 공급업체 종속을 피하세요.

• 믹스 앤 매치 Model: 다양한 작업에 다양한 Model을 사용하세요. 예를 들어 대규모 컨텍스트 처리를 위해 GPT-5-mini를 실행한 다음 추론 작업을 위해 Claude Opus 4.6으로 전환합니다.

• Model 대체: 공급자가 중단을 경험하는 경우 Mastra는 애플리케이션 수준에서 자동으로 다른 공급자로 전환하여 API 게이트웨이에 비해 대기 시간을 최소화할 수 있습니다.

기본 사용법

OpenAI, Anthropic, Google, OpenRouter 같은 게이트웨이 중 무엇을 사용하든 Model을 "provider/model-name" 형식으로 지정하면 나머지는 Mastra가 처리합니다. Mastra는 관련 환경 변수(예: ANTHROPIC_API_KEY)를 읽고 요청을 Provider로 라우팅합니다. API 키가 없으면 어떤 변수를 설정해야 하는지 정확히 알려 주는 명확한 런타임 오류가 발생합니다.

OpenAI

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-5.6-sol"
})

Anthropic

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "anthropic/claude-sonnet-4-6"
})

Google Gemini

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "google/gemini-2.5-flash"
})

xAI

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "xai/grok-4.3"
})

OpenRouter

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "openrouter/anthropic/claude-haiku-4.5"
})

Model 디렉토리

왼쪽 탐색 기능을 사용하여 사용 가능한 Model 디렉터리를 찾아보거나 아래에서 탐색해 보세요.

Gateways

오픈라우터

넷티파이

베르셀

+ 3개 더

Providers

오픈AI

인류학

Google

+ 159개 더

편집기에서 직접 Model을 검색할 수도 있습니다. Mastra는 model 필드에 완전한 자동 완성을 제공합니다. 입력을 시작하기만 하면 IDE에 사용 가능한 옵션이 표시됩니다. 또는 다음에서 Model을 찾아보고 테스트하세요.Studio UI.

정보

개발 중에는 로컬 Model 목록을 매시간 자동으로 새로 고쳐 TypeScript 자동 완성과 Studio의 Model을 최신 상태로 유지합니다. 비활성화하려면 MASTRA_AUTO_REFRESH_PROVIDERS=false로 설정하세요. 프로덕션에서는 자동 새로 고침이 기본적으로 비활성화됩니다.

믹스 앤 매치 Model

일부 Model은 더 빠르지만 성능이 떨어지는 반면 다른 Model은 더 큰 컨텍스트 창이나 더 강력한 추론 기술을 제공합니다. 동일한 공급자의 다양한 Model을 사용하거나 각 작업에 맞게 여러 공급자를 혼합하여 일치시키십시오.

src/mastra/agents/reasoning-agent.ts

import { Agent } from "@mastra/core/agent";

// Use a cost-effective model for document processing
const documentProcessor = new Agent({
  id: "document-processor",
  name: "Document Processor",
  instructions: "Extract and summarize key information from documents",
  model: "openai/gpt-5.6-sol"
})

// Use a powerful reasoning model for complex analysis
const reasoningAgent = new Agent({
  id: "reasoning-agent",
  name: "Reasoning Agent",
  instructions: "Analyze data and provide strategic recommendations",
  model: "anthropic/claude-opus-4-7"
})

동적 Model 선택

Model은 단순한 문자열이므로 요청 컨텍스트, 변수 또는 기타 로직을 기반으로 동적으로 선택할 수 있습니다.

src/mastra/agents/dynamic-assistant-agent.ts

const agent = new Agent({
  id: "dynamic-assistant",
  name: "Dynamic Assistant",
  model: ({ requestContext }) => {
    const provider = requestContext.get("provider-id");
    const model = requestContext.get("model-id");
    return `${provider}/${model}`;
  },
});

이를 통해 강력한 패턴이 가능해집니다.

• A/B 테스트 - 프로덕션 환경에서 Model 성능을 비교합니다.
• 사용자 선택형 Model - 사용자가 앱에서 선호하는 Model을 선택할 수 있습니다.
• 멀티테넌트 애플리케이션 - 각 고객이 자체 API 키와 Model 기본 설정을 사용할 수 있습니다.

Provider별 옵션

각 Model Provider는 고유한 구성 옵션을 제공합니다. OpenAI에서는 reasoningEffort를 사용할 수 있고 Anthropic에서는 cacheControl을 조정할 수 있습니다. Mastra에서는 이러한 특정 providerOptions를 Agent 수준이나 메시지별로 설정할 수 있습니다.

src/mastra/agents/planner-agent.ts

// Agent level (apply to all future messages)
const planner = new Agent({
  id: "planner",
  name: "Planner",
  instructions: {
    role: "system",
    content: "You are a helpful assistant.",
    providerOptions: {
      openai: { reasoningEffort: "low" }
    }
  },
  model: "openai/gpt-5.6-sol",
});

const lowEffort =
  await planner.generate("Plan a simple 3 item dinner menu");

// Message level (apply only to this message)
const highEffort = await planner.generate([
  {
    role: "user",
    content: "Plan a simple 3 item dinner menu for a celiac",
    providerOptions: {
      openai: { reasoningEffort: "high" }
    }
  }
]);

맞춤 헤더

조직 ID 또는 기타 공급자별 필드와 같은 사용자 정의 헤더를 지정해야 하는 경우 이 구문을 사용하십시오.

src/mastra/agents/custom-agent.ts

const agent = new Agent({
  id: "custom-agent",
  name: "Custom Agent",
  model: {
    id: "openai/gpt-5.6-sol",
    apiKey: process.env.OPENAI_API_KEY,
    headers: {
      "OpenAI-Organization": "org-abc123"
    }
  }
});

정보

구성은 공급자에 따라 다릅니다. 사용자 정의 헤더에 대한 자세한 내용은 왼쪽 탐색의 공급자 페이지를 참조하세요.

Model 대체

단일 Model에 의존하면 애플리케이션에 단일 실패 지점이 생성됩니다. Model 폴백은 Model과 공급자 간의 자동 장애 조치를 제공합니다. 기본 Model을 사용할 수 없게 되면 성공할 때까지 구성된 다음 대체에 대해 요청이 재시도됩니다.

src/mastra/agents/resilient-assistant-agent.ts

import { Agent } from '@mastra/core/agent';

const agent = new Agent({
  id: 'resilient-assistant',
  name: 'Resilient Assistant',
  instructions: 'You are a helpful assistant.',
  model: [
    {
      model: "openai/gpt-5.6-sol",
      maxRetries: 3,
    },
    {
      model: "anthropic/claude-sonnet-4-6",
      maxRetries: 2,
    },
    {
      model: "google/gemini-2.5-pro",
      maxRetries: 2,
    },
  ],
});

Mastra는 기본 Model을 먼저 시도합니다. 500 오류, 속도 제한 또는 시간 초과가 발생하면 자동으로 첫 번째 대체(fallback)로 전환됩니다. 이것도 실패하면 다음으로 넘어갑니다. 각 Model은 계속 진행하기 전에 자체 재시도 횟수를 가져옵니다.

사용자는 중단을 경험하지 않습니다. 응답은 다른 Model에서 동일한 형식으로 반환됩니다. 시스템이 폴백 체인을 통해 이동할 때 오류 컨텍스트가 보존되므로 스트리밍 호환성을 유지하면서 깨끗한 오류 전파가 보장됩니다.

Model별 설정

각 대체 항목에는 자체 modelSettings, providerOptions, headers를 지정할 수 있습니다. 체인에 포함된 Model이 서로 다른 온도나 Provider별 설정을 사용해야 비슷한 출력을 생성할 수 있을 때 유용합니다.

src/mastra/agents/tuned-resilient-agent.ts

import { Agent } from '@mastra/core/agent';

const agent = new Agent({
  id: 'tuned-resilient',
  name: 'Tuned Resilient Agent',
  instructions: 'You are a helpful assistant.',
  model: [
    {
      model: 'google/gemini-2.5-flash',
      maxRetries: 2,
      modelSettings: { temperature: 0.3 },
      providerOptions: { google: { thinkingConfig: { thinkingBudget: 0 } } },
    },
    {
      model: 'openai/gpt-5-mini',
      maxRetries: 2,
      modelSettings: { temperature: 0.7 },
      providerOptions: { openai: { reasoningEffort: 'low' } },
    },
  ],
});

상위:

• modelSettings그리고providerOptions: 각 fallback 항목의 설정이 호출 시 옵션보다 우선하며, 호출 시 옵션은 Agent의 defaultOptions. modelSettings shallow-merges by key. providerOptions 를 재귀적으로 심층 병합하므로 중첩된 Provider 구성(예: google.thinkingConfig) preserves sibling keys across layers.
• headers: 통화 시간modelSettings.headers overrides per-fallback headers이며, 이는 Model 라우터 Model에서 추출한 헤더보다 우선합니다. 런타임 헤더(추적, 인증, 테넌시)는 의도적으로 Model 수준 헤더보다 우선합니다.

동적 Model을 확인하는 방식과 동일하게 각 필드에서 requestContext를 사용할 수도 있습니다.

Mastra와 함께 로컬 Model 사용

Mastra는 자체 하드웨어에서 실행하는 gpt-oss, Qwen3, DeepSeek 등의 다양한 로컬 Model도 지원합니다. Mastra가 연결할 수 있도록 로컬 Model을 실행하는 애플리케이션에서 OpenAI 호환 API 서버를 제공해야 합니다. LMStudio 사용을 권장합니다(LMStudio 서버 실행 참조). 사용자 정의 OpenAI 호환 엔드포인트에서 id는 Mastra가 Model 라우터를 통해 전송하는 라우팅 형식입니다. 원격 서비스가 직접 연결하는 Provider처럼 동작하고 llama3.2 같은 단순 Model 이름을 요구한다면 provider/model을 사용하세요. 원격 서비스가 Model 게이트웨이처럼 동작하고 업스트림 Model 네임스페이스에 mastra/google/gemini-2.5-flash 또는 openrouter/google/gemini-2.5-flash처럼 Provider가 포함된다면 gateway/provider/model을 사용하세요. url에는 개별 채팅 엔드포인트가 아니라 Mastra의 model 설정과 함께 사용할 OpenAI 호환 엔드포인트의 기본 URL을 지정하는 것이 중요합니다.

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: {
    id: "custom/my-qwen3-model",
    url: "http://your-custom-openai-compatible-endpoint.com/v1"
  }
})

원격 장치가 Model 게이트웨이처럼 작동하는 경우 게이트웨이 접두사를id:

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: {
    id: "mastra/google/gemini-2.5-flash",
    url: "http://your-custom-openai-compatible-endpoint.com/v1"
  }
})

예: LM스튜디오

LMStudio 서버를 시작하면 http://localhost:1234에서 로컬 서버를 사용할 수 있으며 /v1/models, /v1/chat/completions 등의 엔드포인트가 제공됩니다. url은 http://localhost:1234/v1입니다. id에는 LMStudio 인터페이스에 표시되는 (lmstudio/${modelId})를 사용할 수 있습니다.

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: {
    id: "lmstudio/qwen/qwen3-30b-a3b-2507",
    url: "http://localhost:1234/v1"
  }
})

Mastra와 함께 AI SDK 사용

Mastra는 직접 사용해야 하는 경우 AI SDK 공급자 모듈을 지원합니다.

src/mastra/agents/my-agent.ts

import { groq } from '@ai-sdk/groq';
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  model: groq('gemma2-9b-it')
})

"provider/model" 문자열을 허용하는 모든 위치에서 AI SDK Model(예: groq('gemma2-9b-it'))을 사용할 수 있습니다. 여기에는 Model 라우터 대체 항목과 채점기가 포함됩니다.