---
title: "Vercel AI SDK createOpenAICompatible로 base URL 변경 | BroadRouter"
description: "@ai-sdk/openai-compatible의 createOpenAICompatible로 Vercel AI SDK에서 BroadNet Inference를 호출합니다. generateText, streamText, 도구, reasoning effort까지 다룹니다."
url: https://broadrouter.com/ko/guides/vercel-ai-sdk-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/vercel-ai-sdk-openai-compatible/) (2026-11-16 업데이트).

# BroadNet Inference에서 Vercel AI SDK 사용하기

업데이트 2026-11-16

ai와 @ai-sdk/openai-compatible을 설치한 뒤, name은 broadnet, baseURL은 https://inference.broadnet.ai/v1, apiKey는 BroadNet 키로 createOpenAICompatible을 호출하세요. 이 제공자에 broadnet/glm-5.3 같은 BroadNet 모델 ID를 넘기고 평소처럼 generateText나 streamText를 쓰면 됩니다. 키는 서버에만 두고, 추론 모델에는 maxOutputTokens를 넉넉히 주세요.

Vercel의 [AI SDK](https://ai-sdk.dev/providers/openai-compatible-providers)는 LLM 앱을 위한 TypeScript 툴킷입니다. 이 SDK의 `@ai-sdk/openai-compatible` 패키지는 OpenAI chat completions 형식을 따르는 API라면 어떤 것이든 제공자로 만들어 줍니다. BroadNet Inference도 이 형식을 따르므로 base URL, 키, 모델 ID만 바꾸면 됩니다. 일반 OpenAI 클라이언트를 쓰려면 [Node SDK 가이드](https://broadrouter.com/ko/guides/openai-node-sdk/)를 참고하세요.

## 설정

1.  **패키지를 설치합니다.** 이 글을 쓰는 시점에 npm의 최신 버전은 `ai` 7.x와 `@ai-sdk/openai-compatible` 3.x입니다.
    
    ```bash
    npm install ai @ai-sdk/openai-compatible
    export BROADNET_API_KEY='your-broadnet-key'
    ```
    
2.  **제공자를 만듭니다.**
    
    ```ts
    // broadnet.ts
    import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
    
    export const broadnet = createOpenAICompatible({
      name: 'broadnet',
      baseURL: 'https://inference.broadnet.ai/v1',
      apiKey: process.env.BROADNET_API_KEY,
      includeUsage: true, // usage data in streaming responses
    });
    ```
    

`includeUsage: true`는 주석대로 스트리밍 응답에 사용량 데이터를 넣어 줍니다.

3.  **텍스트를 생성합니다.**
    
    ```ts
    import { generateText } from 'ai';
    import { broadnet } from './broadnet';
    
    const { text, usage, finishReason } = await generateText({
      model: broadnet('broadnet/glm-5.3'),
      prompt: 'Explain idempotency keys in two sentences.',
      maxOutputTokens: 4000, // reasoning counts toward this
    });
    
    console.log(text, finishReason, usage);
    ```
    
4.  **스트리밍합니다.** `generateText`를 `streamText`로 바꾸고 `textStream`을 읽으세요. 그 아래에서 오가는 데이터 형식은 [스트리밍 가이드](https://broadrouter.com/ko/guides/streaming-chat-completions/)에서 설명합니다.
    

넘긴 `name`은 제공자 옵션과 제공자 메타데이터의 키가 되므로 짧고 바뀌지 않는 이름으로 정하세요. `provider('id')`와 `provider.chatModel('id')`는 둘 다 채팅 모델을 만들며, 모델마다 따로 설정할 필요는 없습니다. 키는 서버에만 두세요. 이 파일을 브라우저에서 실행되는 코드로 가져오면 모든 방문자에게 키가 전달됩니다.

제공자 문서는 텍스트 생성, 스트리밍, 도구 호출, 구조화된 출력, 추론 콘텐츠, 이미지 입력을 지원 기능으로 나열하면서, 일부는 제공업체에 따라 다르다고 밝힙니다. BroadNet에서는 DeepSeek V4.1 Flash, Qwen3.8 27B, Gemma 4 VL 26B가 이미지 입력을 받습니다. GLM 5.3은 텍스트만 받습니다.

## 설정해 둘 만한 옵션

-   **reasoningEffort.** 제공자 이름을 키로 해서 `providerOptions`로 넘기세요. AI SDK 문서는 정확한 값이 제공업체에 따라 다르다고 하며, BroadNet 문서에는 `low`가 나옵니다.

```ts
const result = await generateText({
  model: broadnet('broadnet/deepseek-v4.1-flash'),
  prompt: 'Classify: "refund my order" -> intent?',
  providerOptions: { broadnet: { reasoningEffort: 'low' } },
});
```

-   **supportsStructuredOutputs.** AI SDK는 제공자에서 이 값이 `true`일 때만 JSON 스키마를 보냅니다. BroadNet은 GLM 5.3과 Qwen3.8 27B에 구조화된 출력을 표기합니다. 이 옵션을 켠다면 스키마 출력에는 이 두 모델을 쓰세요.
-   **maxRetries.** `generateText`는 기본적으로 두 번 재시도합니다. 속도 제한에 맞게 조정하세요.
-   **추론 출력.** AI SDK는 제공업체가 추론 콘텐츠를 반환하면 읽어 들입니다. 최상위 결과 필드 `reasoningText`는 이제 deprecated로 표시되어 있으며 `finalStep.reasoningText` 사용이 권장됩니다. 추론 내용이 있다는 전제에 의존하는 로직은 만들지 마세요.

## 어떤 모델을 고를까

| 필요 | 모델 | 컨텍스트 |
| --- | --- | --- |
| 도구 호출, 구조화된 출력 | [`broadnet/glm-5.3`](https://broadrouter.com/ko/models/glm-5.3/) | 1,048,576 |
| 이미지와 도구, 아랍어 | [`broadnet/qwen3.8-27b`](https://broadrouter.com/ko/models/qwen3.8-27b/) | 262,144 |
| 긴 컨텍스트, 정액제 플랜 | [`broadnet/deepseek-v4.1-flash`](https://broadrouter.com/ko/models/deepseek-v4.1-flash/) | 1,048,576 |
| 저렴한 텍스트·이미지 호출 | [`broadnet/gemma-4-26b-a4b`](https://broadrouter.com/ko/models/gemma-4-vl-26b/) | 32,768 |

모델별 토큰당 가격은 [가격 페이지](https://broadrouter.com/ko/pricing/)에 있습니다.

## 문제 해결

-   **401.** 런타임에 `BROADNET_API_KEY`가 없거나(호스팅 업체의 환경 변수 설정을 확인하세요), 틀렸거나, 만료되었거나, 종량제 사용 가능 금액이 소진된 경우입니다.
-   **providerOptions가 무시됨.** 키는 제공자의 `name`을 camelCase로 쓴 것과 같아야 합니다. `name: 'broadnet'`이라면 `providerOptions.broadnet`을 쓰세요.
-   **모델 오류.** ID는 `broadnet/` 접두사까지 포함해 BroadNet의 ID와 정확히 같아야 합니다. GLM 5.3, Qwen3.8 27B, DeepSeek V4.1 Flash는 충전이 필요하며, 초기 크레딧($5 상당)으로는 Gemma 4 VL 26B와 Transcribe 모델 두 개만 쓸 수 있습니다.
-   **텍스트가 비어 있고 finishReason이 “length”.** 추론이 예산을 다 썼습니다. `maxOutputTokens`를 늘리거나 `reasoningEffort`를 낮추세요. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **부하가 걸릴 때 429.** 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 서버리스 함수는 빠르게 확장되므로 앱에서 동시 실행 수에 상한을 두세요. [오류와 재시도](https://broadrouter.com/ko/guides/errors-and-retries/)를 참고하세요.
-   **플랜 키로 에이전트 병렬 실행.** [무제한 플랜 세션](https://broadrouter.com/ko/guides/unlimited-llm-api-sessions/) 하나는 한 번에 요청 하나를 처리합니다. 여러 에이전트를 `Promise.all`로 돌리려면 에이전트마다 세션이 하나씩 필요하며, 그렇지 않으면 요청이 대기열에 쌓입니다.

## 이 가이드의 용어

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

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

[구조화된 출력(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가 반환됩니다.

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

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

[base URL(베이스 URL)](https://broadrouter.com/ko/glossary/base-url/)

base URL은 https://api.example.com/v1처럼 API의 고정된 루트 주소로, 클라이언트가 /chat/completions 같은 모든 엔드포인트 경로 앞에 붙입니다. OpenAI 호환 SDK에서는 base URL을 API 키, 모델 ID와 함께 바꾸면 같은 코드로 다른 제공업체를 호출할 수 있습니다.

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

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

## 자주 묻는 질문

### @ai-sdk/openai와 @ai-sdk/openai-compatible 중 무엇을 써야 하나요?

서드파티 OpenAI 호환 API에는 @ai-sdk/openai-compatible을 쓰세요. 이 패키지는 chat completions 엔드포인트를 호출하며, BroadNet Inference가 제공하는 것도 바로 이 엔드포인트입니다.

### 생성된 텍스트가 비어 있는 이유는 무엇인가요?

BroadNet에서는 추론도 max\_tokens에 포함됩니다. maxOutputTokens가 작으면 답변을 시작하기 전에 모델이 전부 써 버릴 수 있습니다. 값을 늘리거나 reasoningEffort를 low로 설정하세요.

### 스트리밍 중에 토큰 사용량을 받으려면 어떻게 하나요?

제공자를 만들 때 includeUsage를 true로 설정하세요. AI SDK 문서에 따르면 스트리밍 응답에 사용량 데이터가 추가됩니다. 기본값은 false입니다.

### BroadNet 모델마다 따로 설정해야 하나요?

아닙니다. createOpenAICompatible 제공자 하나로 모든 모델을 쓸 수 있습니다. 어떤 BroadNet 채팅 모델 ID든 broadnet('model-id') 또는 broadnet.chatModel('model-id')로 호출하세요.

## 관련 가이드

-   [BroadNet Inference에서 OpenAI Node.js SDK 사용하기](https://broadrouter.com/ko/guides/openai-node-sdk/)
-   [채팅 완성 스트리밍과 끊긴 연결 처리하기](https://broadrouter.com/ko/guides/streaming-chat-completions/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [opencode에 BroadNet Inference를 커스텀 제공자로 추가하기](https://broadrouter.com/ko/guides/opencode-custom-provider/)
-   [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-vercel-ai-sdk-openai-compatible&utm_content=page-cta) ·

**출처**

-   [AI SDK 문서, OpenAI Compatible 제공자(2026-11-14 확인)](https://ai-sdk.dev/providers/openai-compatible-providers)
-   [AI SDK 문서, generateText 레퍼런스(2026-11-14 확인)](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)
-   [npm, @ai-sdk/openai-compatible 패키지(3.x, 2026-11-14 확인)](https://www.npmjs.com/package/@ai-sdk/openai-compatible)
-   [BroadNet Inference API 레퍼런스 (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-vercel-ai-sdk-openai-compatible&utm_content=sources)
