> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Model 제공자

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

## 특징

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

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

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

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

## 기본 사용법

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

**OpenAI**:

```typescript
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**:

```typescript
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**:

```typescript
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**:

```typescript
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**:

```typescript
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](https://mastra.ai/ko/models/gateways)
- [Providers](https://mastra.ai/ko/models/providers)

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

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

## 믹스 앤 매치 Model

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

```typescript
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은 단순한 문자열이므로 [요청 컨텍스트](https://mastra.zisheng.pro/ko/docs/server/request-context), 변수 또는 기타 로직을 기반으로 동적으로 선택할 수 있습니다.

```typescript
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 수준이나 메시지별로 설정할 수 있습니다.

```typescript
// 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 또는 기타 공급자별 필드와 같은 사용자 정의 헤더를 지정해야 하는 경우 이 구문을 사용하십시오.

```typescript
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을 사용할 수 없게 되면 성공할 때까지 구성된 다음 대체에 대해 요청이 재시도됩니다.

```typescript
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별 설정을 사용해야 비슷한 출력을 생성할 수 있을 때 유용합니다.

```typescript
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](https://lmstudio.ai/) 사용을 권장합니다([LMStudio 서버 실행](https://lmstudio.ai/docs/developer/core/server) 참조). 사용자 정의 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을 지정하는 것이 **중요**합니다.

```typescript
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`:

```typescript
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}`)를 사용할 수 있습니다.

```typescript
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 공급자 모듈을 지원합니다.

```typescript
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 라우터 대체 항목과 [채점기](https://mastra.zisheng.pro/ko/docs/evals/overview)가 포함됩니다.