---
title: "Pydantic AI 커스텀 OpenAI 호환 base_url 설정 | BroadRouter"
description: "OpenAIChatModel과 OpenAICompatibleProvider로 Pydantic AI 에이전트를 BroadNet Inference에서 실행하고, 도구 호출, 구조화된 출력, 모델 프로필 설정까지 다룹니다."
url: https://broadrouter.com/ko/guides/pydantic-ai-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/pydantic-ai-openai-compatible/) (2026-11-16 업데이트).

# BroadNet Inference에서 Pydantic AI 사용하기(OpenAICompatibleProvider)

업데이트 2026-11-16

pydantic-ai-slim\[openai\]를 설치한 뒤, broadnet/glm-5.3 같은 BroadNet 모델 ID와 OpenAICompatibleProvider로 OpenAIChatModel을 만드세요. 제공자의 base URL은 https://inference.broadnet.ai/v1, API 키는 BroadNet 키입니다. 이 모델을 Agent에 넘기면 됩니다. BroadNet은 chat completions를 제공하므로 Responses 모델이 아닌 OpenAIChatModel을 쓰세요. Pydantic AI 문서에 따르면 base\_url을 지정한 OpenAIProvider는 OpenAI 자체용입니다.

Pydantic AI는 Pydantic 팀이 만든 Python 에이전트 프레임워크입니다. 기본 제공자가 없는 서비스라면, Pydantic AI 문서는 해당 서비스의 `base_url`과 함께 `OpenAICompatibleProvider`를 쓰라고 안내합니다. BroadNet Inference는 `https://inference.broadnet.ai/v1` 주소에서 표준 chat completions를 제공하므로 이 방법으로 연결합니다. BroadRouter는 BroadNet이 운영하는 사이트이며, 이 글은 버전 2.68 기준 Pydantic AI 문서를 따릅니다.

## 설치

```bash
pip install "pydantic-ai-slim[openai]"
export BROADNET_API_KEY='your-broadnet-key'
```

## 연결

```python
import os
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIChatModel
from pydantic_ai.providers.openai_compatible import OpenAICompatibleProvider

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider(
        'broadnet',
        base_url='https://inference.broadnet.ai/v1',
        api_key=os.environ['BROADNET_API_KEY'],
    ),
)

agent = Agent(model)
result = agent.run_sync('Give me three names for a Go linting tool.')
print(result.output)
```

이 코드를 실행하는 것이 곧 테스트입니다. 답이 출력되면 키, URL, 모델 ID가 맞는 것입니다.

-   **첫 번째 인자는 BroadNet에 전송되는 모델 ID입니다.** `broadnet/` 접두사까지 정확히 그대로 쓰세요.
-   **제공자 이름**(여기서는 `'broadnet'`)은 모든 응답에 기록됩니다. Pydantic AI 문서는 이 이름을 바꾸지 말라고 합니다. 이전 응답의 어떤 데이터를 서비스로 다시 보낼지가 이 이름으로 결정되기 때문입니다.
-   **`OpenAIChatModel`을 계속 쓰세요.** Pydantic AI 문서는 서비스가 Responses API를 구현한 경우에만 `OpenAIResponsesModel`을 쓰라고 합니다. BroadNet은 이 API를 제공한다고 표기하지 않습니다.

## 도구와 구조화된 출력

```python
from pydantic import BaseModel

class City(BaseModel):
    name: str
    country: str

agent = Agent(model, output_type=City)
print(agent.run_sync('Which city hosts the Burj Khalifa?').output)
```

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

## 모델 프로필을 설정해야 할 때

Pydantic AI는 모델 이름을 보고 요청 프로필을 고릅니다. 어떤 기능이 무시되거나 거부되면, 문서는 직접 만든 `OpenAIModelProfile`을 넘기라고 안내합니다. BroadNet에서 알아 두면 좋은 설정은 두 가지입니다.

```python
from pydantic_ai.profiles.openai import OpenAIModelProfile

model = OpenAIChatModel(
    'broadnet/glm-5.3',
    provider=OpenAICompatibleProvider('broadnet', base_url='https://inference.broadnet.ai/v1', api_key=os.environ['BROADNET_API_KEY']),
    profile=OpenAIModelProfile(
        openai_chat_supports_max_completion_tokens=False,  # send max_tokens, the field BroadNet documents
        openai_supports_strict_tool_definition=False,      # only if strict tool schemas are rejected
    ),
)
```

출력 한도는 모델 설정으로 넘기세요. 예를 들면 `agent.run_sync(prompt, model_settings={'max_tokens': 2000})`입니다. DeepSeek V4.1 Flash, GLM 5.3, Qwen3.8 27B에서는 추론도 이 한도에 포함됩니다.

## 어떤 모델을 고를까

| 에이전트 | 모델 |
| --- | --- |
| 도구, 구조화된 출력 | `broadnet/glm-5.3` |
| 이미지나 아랍어 텍스트, 도구 사용 | `broadnet/qwen3.8-27b` |
| 긴 문서, 정액 플랜 | `broadnet/deepseek-v4.1-flash` |
| 무료 초기 크레딧 | `broadnet/gemma-4-26b-a4b`(32,768토큰 컨텍스트) |

[모든 모델의 가격](https://broadrouter.com/ko/pricing/)을 확인하세요.

## 문제 해결

-   **401.** 키가 틀렸거나, 만료되었거나, 사용 가능 금액이 소진되었습니다.
-   **404 또는 모델을 찾을 수 없음.** `base_url`은 `/v1`로 끝나야 합니다. 모델 ID를 확인하세요. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)은 `broadnet/gemma-4-26b-a4b` 모델과 Transcribe 모델 두 개에만 쓸 수 있습니다.
-   **출력이 비어 있거나 검증 재시도가 반복됨.** 추론이 출력 예산을 다 썼습니다. `max_tokens`를 늘리세요. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **도구 정의에서 400.** 프로필에 `openai_supports_strict_tool_definition=False`를 설정하고, BroadNet이 도구 지원을 표기한 모델을 쓰세요.
-   **에이전트를 동시에 실행할 때 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가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

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

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

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

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

[도구 호출(tool calling)](https://broadrouter.com/ko/glossary/tool-calling/)

도구 호출(tool calling)은 함수 호출(function calling)이라고도 하며, 모델이 개발자가 정의한 함수를 실행해 달라는 구조화된 요청을 JSON 인자와 함께 반환하는 LLM API 기능입니다. 함수는 애플리케이션이 실행하고 그 결과를 다시 보냅니다. 모델이 직접 코드를 실행하지는 않습니다.

[동시 처리(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가 반환됩니다.

[LLM 정액 플랜(Flat-rate LLM plan)](https://broadrouter.com/ko/glossary/flat-rate-llm-plan/)

LLM 정액 플랜은 언어 모델 API를 토큰당 과금하지 않고, 한 달 같은 기간 단위로 고정 요금을 받는 요금제입니다. 이런 플랜은 보통 동시 실행 수, 속도, 모델, 사용 시간대 같은 다른 항목을 제한하므로 가격만큼 제한 조건도 중요합니다.

## 자주 묻는 질문

### BroadNet에는 OpenAIProvider와 OpenAICompatibleProvider 중 무엇을 써야 하나요?

OpenAICompatibleProvider를 쓰세요. Pydantic AI 문서에 따르면 OpenAIProvider도 base\_url을 받지만, OpenAI 자체나 OpenAI로 그대로 전달하는 프록시용이며 OpenAI의 모델과 기능을 전제로 합니다.

### 기본 OpenAI 모델이 아니라 OpenAIChatModel을 쓰는 이유는 무엇인가요?

Pydantic AI의 기본 OpenAI 모델은 Responses API를 씁니다. BroadNet은 /v1/chat/completions에서 chat completions를 제공하며, OpenAIChatModel이 호출하는 것이 바로 이 엔드포인트입니다.

### 도구와 구조화된 출력이 작동하나요?

BroadNet이 도구와 구조화된 출력을 표기한 GLM 5.3과 Qwen3.8 27B에서는 작동합니다. BroadNet 문서는 DeepSeek V4.1 Flash의 도구 지원을 표기하지 않으므로, 이 모델에서는 도구를 쓰는 에이전트를 먼저 테스트하세요.

### Pydantic AI가 max\_completion\_tokens를 보내지 않게 하려면 어떻게 하나요?

OpenAIChatModel에 profile=OpenAIModelProfile(openai\_chat\_supports\_max\_completion\_tokens=False)를 넘기세요. 그러면 Pydantic AI는 예전 필드인 max\_tokens를 보냅니다. BroadNet API 레퍼런스가 설명하는 필드가 이것입니다.

## 관련 가이드

-   [BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [BroadNet Inference에서 LangChain 사용하기](https://broadrouter.com/ko/guides/langchain-openai-base-url/)
-   [CrewAI에서 BroadNet Inference를 커스텀 OpenAI 엔드포인트로 쓰기](https://broadrouter.com/ko/guides/crewai-custom-openai-endpoint/)
-   [추론 모델이 빈 답변을 반환하는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)
-   [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-pydantic-ai-openai-compatible&utm_content=page-cta) ·

**출처**

-   [Pydantic AI 문서, 기타 호환 API(Other endpoints, Model profile)(2026-11-15 확인)](https://pydantic.dev/docs/ai/models/compatible-apis/)
-   [Pydantic AI 문서, OpenAI 모델(2026-11-15 확인)](https://pydantic.dev/docs/ai/models/openai/)
-   [PyPI, pydantic-ai 2.68.0, Python 3.11 이상(2026-11-15 확인)](https://pypi.org/project/pydantic-ai/)
-   [BroadNet Inference API 레퍼런스(2026-11-15 확인) (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-pydantic-ai-openai-compatible&utm_content=sources)
