BroadRouter

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

업데이트

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 문서를 따릅니다.

설치

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

연결

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를 제공한다고 표기하지 않습니다.

도구와 구조화된 출력

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에서 알아 두면 좋은 설정은 두 가지입니다.

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토큰 컨텍스트)

모든 모델의 가격을 확인하세요.

문제 해결

  • 401. 키가 틀렸거나, 만료되었거나, 사용 가능 금액이 소진되었습니다.
  • 404 또는 모델을 찾을 수 없음. base_url은 /v1로 끝나야 합니다. 모델 ID를 확인하세요. 유료 모델은 충전이 필요하며, 초기 크레딧($5 상당)은 broadnet/gemma-4-26b-a4b 모델과 Transcribe 모델 두 개에만 쓸 수 있습니다.
  • 출력이 비어 있거나 검증 재시도가 반복됨. 추론이 출력 예산을 다 썼습니다. max_tokens를 늘리세요. 답변이 비어서 오는 이유를 참고하세요.
  • 도구 정의에서 400. 프로필에 openai_supports_strict_tool_definition=False를 설정하고, BroadNet이 도구 지원을 표기한 모델을 쓰세요.
  • 에이전트를 동시에 실행할 때 429. 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 오류와 재시도를 참고하세요.

자주 묻는 질문

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 레퍼런스가 설명하는 필드가 이것입니다.

Markdown으로 읽기ChatGPT에 질문하기Claude에 질문하기Perplexity에 질문하기