---
title: "Mastra 커스텀 OpenAI 호환 엔드포인트(model url) | BroadRouter"
description: "id, url, apiKey를 지정한 model 객체로 Mastra 에이전트를 BroadNet Inference에서 실행하는 방법과, 모델 ID에 broadnet/ 접두사를 두 번 써야 하는 이유를 설명합니다."
url: https://broadrouter.com/ko/guides/mastra-openai-compatible/
lang: ko
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

이 페이지는 영어 원문을 AI의 도움을 받아 번역했습니다. [영어 원문 읽기](https://broadrouter.com/guides/mastra-openai-compatible/) (2026-11-16 업데이트).

# BroadNet Inference에서 Mastra 에이전트 사용하기

업데이트 2026-11-16

Mastra Agent에서 model을 객체로 지정하세요. url은 https://inference.broadnet.ai/v1, apiKey는 BROADNET\_API\_KEY에서 읽고, id는 broadnet/broadnet/glm-5.3 형식으로 씁니다. Mastra는 id의 첫 부분을 제공자 이름으로 보고 떼어 내므로, 접두사를 두 번 써야 BroadNet에 broadnet/glm-5.3 값이 전송됩니다. 커스텀 URL은 기본적으로 chat completions를 씁니다. 도구에는 GLM 5.3이나 Qwen3.8 27B를 쓰세요.

Mastra는 AI 에이전트와 워크플로를 위한 TypeScript 프레임워크입니다. 내장 제공자 외에도, 에이전트의 `model`에 `id`와 `url`을 담은 객체를 넘기면 어떤 OpenAI 호환 엔드포인트든 쓸 수 있습니다. BroadNet Inference는 `https://inference.broadnet.ai/v1` 주소에서 표준 chat completions를 제공하므로 이 방식으로 연결되는데, 모델 ID에 주의할 점이 하나 있습니다. BroadRouter는 BroadNet이 운영하는 사이트입니다. 아래 내용은 [Mastra의 모델 문서](https://mastra.ai/models)와 @mastra/core 1.83.0을 따릅니다.

## 설치

```bash
npm install @mastra/core zod
export BROADNET_API_KEY='your-broadnet-key'
```

## 에이전트 연결하기

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

const broadnet = (model: string) => ({
  id: `broadnet/${model}`,              // Mastra strips the first segment
  url: "https://inference.broadnet.ai/v1",
  apiKey: process.env.BROADNET_API_KEY,
});

export const assistant = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a concise assistant.",
  model: broadnet("broadnet/glm-5.3"),     // sends broadnet/glm-5.3
});

const res = await assistant.generate("Give me three names for a Go linting tool.");
console.log(res.text);
```

### 접두사를 두 번 쓰는 이유

Mastra 문서에 따르면 `id`를 `provider/model` 형식으로 쓰면 원격 서버에 모델 이름만 전송되고, `gateway/provider/model` 형식으로 쓰면 이름에 제공자가 남습니다. BroadNet의 ID에는 슬래시가 들어 있으므로 긴 형식이 필요합니다. 저희 테스트 결과는 다음과 같습니다.

| Mastra `id` | BroadNet이 받은 모델 ID |
| --- | --- |
| `broadnet/glm-5.3` | `glm-5.3` (틀림) |
| `broadnet/broadnet/glm-5.3` | `broadnet/glm-5.3` (맞음) |

위의 헬퍼 함수가 이 추가 세그먼트를 자동으로 붙입니다.

## 도구

```ts
import { createTool } from "@mastra/core/tools";
import { z } from "zod";

const weather = createTool({
  id: "get_weather",
  description: "Get the weather for a city",
  inputSchema: z.object({ city: z.string() }),
  execute: async (input) => ({ city: input.city, tempC: 21 }),
});

const agent = new Agent({
  id: "weather",
  name: "Weather",
  instructions: "Use the weather tool to answer.",
  tools: { weather },
  model: broadnet("broadnet/glm-5.3"),
});
```

도구를 쓰는 에이전트에는 `broadnet/glm-5.3` 또는 `broadnet/qwen3.8-27b` 모델을 쓰세요. BroadNet 문서는 도구와 구조화된 출력을 이 두 모델에만 표기합니다.

## 스트리밍

```ts
const stream = await assistant.stream("Explain vector search in two sentences.");
for await (const chunk of stream.textStream) process.stdout.write(chunk);
```

## 중요한 설정

-   **`url`** 값은 `/v1`로 끝나는 base URL입니다. `/chat/completions`는 Mastra가 붙입니다.
-   **`api: "responses"`를 추가하지 마세요.** Mastra 문서에 따르면 이 설정은 `/v1/responses`로 전환합니다. BroadNet은 Responses API를 표기하지 않습니다.
-   **출력 한도.** DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B는 답하기 전에 추론하며, 그 추론도 출력 한도에 포함됩니다. 출력 토큰에 상한을 둔다면 2,000 이상으로 남겨 두세요.

## 어떤 모델을 고를까

| 에이전트 | 모델 |
| --- | --- |
| 도구, 구조화된 출력, 워크플로 | `broadnet/glm-5.3` |
| 도구와 이미지 입력 또는 아랍어 텍스트 | `broadnet/qwen3.8-27b` |
| 정액 플랜의 텍스트 전용 단계 | `broadnet/deepseek-v4.1-flash` |

[모든 모델의 가격](https://broadrouter.com/ko/pricing/)을 확인하세요. Mastra 없이 Vercel AI SDK를 쓰려면 [AI SDK 가이드](https://broadrouter.com/ko/guides/vercel-ai-sdk-openai-compatible/)를 참고하세요.

## 테스트 방법

2026-11-15에 Node 24로 @mastra/core 1.83.0을 설치하고, BroadNet의 chat completions 형식을 흉내 내며 도구 호출을 돌려주는 로컬 모의 서버를 대상으로 `generate`, `stream`, 도구 에이전트를 실행했습니다. 기록된 요청을 읽어 보니 모든 호출이 `apiKey`의 Bearer 키와 함께 `/v1/chat/completions`로 갔습니다. 위 표의 접두사 규칙도 이렇게 찾았습니다. BroadNet 키가 없었기 때문에 실제 모델 출력은 테스트하지 않았습니다.

## 문제 해결

-   **404 또는 모델을 찾을 수 없음.** 모델 ID에서 접두사가 빠졌을 가능성이 큽니다. `id`를 `broadnet/broadnet/glm-5.3` 형식으로 쓰세요. 그다음 `url`이 `/v1`로 끝나는지 확인하세요. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)으로는 `broadnet/gemma-4-26b-a4b` 모델과 Transcribe 모델 두 개만 쓸 수 있습니다.
-   **401.** 프로세스에 `BROADNET_API_KEY`가 설정되지 않았거나, 키가 잘못되었거나 사용 가능 금액이 소진된 것입니다.
-   **빈 응답.** 출력 예산을 추론에 다 썼습니다. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **병렬 단계가 있는 워크플로에서 429.** 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용하고, 플랜 세션은 한 번에 하나씩 실행합니다. [오류와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를 참고하세요.

## 이 가이드의 용어

[종량제(Pay-as-you-go)](https://broadrouter.com/ko/glossary/pay-as-you-go/)

종량제(pay-as-you-go)는 구독이나 최소 약정 없이 토큰, 요청, 오디오 분 같은 단위로 사용량을 측정해 쓴 만큼만 내는 요금 방식입니다. 대부분의 LLM API가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

[AI 에이전트(AI agent)](https://broadrouter.com/ko/glossary/agent/)

AI 에이전트는 언어 모델이 목표를 향해 스스로 단계를 정하는 시스템입니다. 어떤 도구를 호출할지 결정하고, 결과를 읽고, 최종 답변을 내거나 한도에 닿을 때까지 이를 반복합니다. 정해진 지점에서 모델을 호출하는 고정된 스크립트는 보통 워크플로라고 부릅니다.

[구조화된 출력(Structured output)](https://broadrouter.com/ko/glossary/structured-output/)

구조화된 출력(structured output)은 모델의 응답을 개발자가 지정한 형식, 주로 JSON Schema에 맞추도록 제한해 코드가 안정적으로 파싱할 수 있게 하는 LLM API 기능입니다. 유효한 JSON만 보장하고 특정 구조는 보장하지 않는 JSON 모드보다 더 엄격합니다.

[동시 처리(concurrency)](https://broadrouter.com/ko/glossary/concurrency/)

동시 처리(concurrency)는 클라이언트가 같은 시점에 진행 중인 요청 수입니다. LLM API는 분당 요청 수와 별도로 키나 플랜마다 이를 제한하는 경우가 많습니다. 열려 있는 요청은 응답이 끝날 때까지 GPU 용량을 차지하기 때문입니다.

[속도 제한(rate limit)](https://broadrouter.com/ko/glossary/rate-limit/)

속도 제한(rate limit)은 API가 일정 시간 동안 클라이언트가 사용할 수 있는 양에 두는 상한으로, 분당 요청 수나 분당 토큰 수 같은 기준이 있습니다. 한도를 넘은 요청은 사용량이 다시 한도 아래로 내려갈 때까지 거부되며, 보통 HTTP 429 Too Many Requests가 반환됩니다.

[Chat Completions API](https://broadrouter.com/ko/glossary/chat-completions-api/)

Chat Completions API는 OpenAI의 HTTP 엔드포인트인 POST /v1/chat/completions로, 모델 이름과 역할이 붙은 메시지 목록을 받아 모델의 다음 메시지를 반환합니다. 이 요청과 응답 구조는 OpenAI 호환 제공업체와 SDK가 재사용하는 공통 형식이 되었습니다.

[OpenAI 호환 API(OpenAI-compatible API)](https://broadrouter.com/ko/glossary/openai-compatible-api/)

OpenAI 호환 API는 POST /v1/chat/completions처럼 OpenAI API와 같은 요청 및 응답 형식을 받는 HTTP API입니다. 그래서 OpenAI SDK와 도구는 base URL, API 키, 모델 이름만 바꾸면 이 API를 그대로 사용할 수 있습니다.

## 자주 묻는 질문

### Mastra가 broadnet/glm-5.3 대신 glm-5.3을 보내는 이유는 무엇인가요?

Mastra는 모델 id를 provider/model로 읽고 첫 번째 슬래시 뒤의 부분만 보냅니다. 저희 테스트에서 id를 broadnet/glm-5.3으로 쓰면 glm-5.3이 전송되었고, BroadNet은 이를 인식하지 못합니다. id를 broadnet/broadnet/glm-5.3 형식으로 쓰세요.

### Mastra의 url에는 base URL과 chat completions URL 중 무엇을 넣나요?

base URL입니다. Mastra 문서는 OpenAI 호환 엔드포인트의 base URL을 쓰라고 안내하므로, /chat/completions 없이 https://inference.broadnet.ai/v1 값을 넣으세요.

### Mastra는 커스텀 URL에서 Responses API를 쓰나요?

기본적으로는 아닙니다. Mastra 문서에 따르면 api를 responses로 설정하지 않는 한 커스텀 엔드포인트는 chat completions를 씁니다. BroadNet은 chat completions를 제공하므로 이 설정을 추가하지 마세요.

### Mastra 도구가 BroadNet에서 작동하나요?

네. BroadNet이 도구 지원으로 표기한 GLM 5.3이나 Qwen3.8 27B에서 작동합니다. 저희 모의 테스트에서 에이전트는 도구 스키마를 보내고, 도구를 실행하고, 결과를 돌려주었습니다.

## 관련 가이드

-   [BroadNet Inference에서 Vercel AI SDK 사용하기](https://broadrouter.com/ko/guides/vercel-ai-sdk-openai-compatible/)
-   [BroadNet Inference에서 OpenAI Node.js SDK 사용하기](https://broadrouter.com/ko/guides/openai-node-sdk/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [BroadNet Inference 오류 코드와 재시도해야 하는 경우](https://broadrouter.com/ko/guides/errors-and-retries/)
-   [BroadNet Inference와 함께 쓸 수 있는 모든 도구 (영어)](https://broadrouter.com/integrations/): SDK, 코딩 에이전트, 채팅 UI, 자동화 도구와 각 도구의 정확한 설정

실제 워크로드로 테스트해 보세요. 신규 계정에는 US$5 상당의 초기 크레딧이 제공되며 Gemma 및 음성 전사에 사용할 수 있습니다. DeepSeek, GLM 및 Qwen3.8 모델은 충전이 필요합니다.

[시작하기](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-mastra-openai-compatible&utm_content=page-cta) ·

**출처**

-   [Mastra 문서, Models(커스텀 OpenAI 호환 엔드포인트)(2026-11-15 확인)](https://mastra.ai/models)
-   [GitHub의 Mastra, @mastra/core 1.83.0 릴리스, 2026-11-13(2026-11-15 확인)](https://github.com/mastra-ai/mastra/releases/tag/%40mastra%2Fcore%401.83.0)
-   [BroadNet Inference API 레퍼런스(2026-11-15 확인) (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-mastra-openai-compatible&utm_content=sources)
