BroadRouter
시작하기

BroadNet Inference에서 Instructor로 구조화된 출력 받기

업데이트

base_url이 https://inference.broadnet.ai/v1이고 BroadNet 키를 쓰는 OpenAI 클라이언트를 instructor.from_openai로 감싼 다음, response_model에 Pydantic 클래스를, model에 broadnet/glm-5.3 또는 broadnet/qwen3.8-27b를 지정해 chat.completions.create를 호출하세요. 이 두 모델이 BroadNet이 도구와 구조화된 출력을 표기한 모델입니다. 기본값은 Mode.TOOLS이고, Mode.JSON_SCHEMA도 작동합니다.

Instructor는 LLM 응답을 검증된 Pydantic 객체로 바꿔 주고, 검증에 실패하면 재시도할 수 있는 Python 라이브러리입니다. OpenAI 클라이언트를 패치하는 방식이며, 문서에서 base_url을 통한 OpenAI 호환 서버 연결을 다룹니다. BroadNet Inference는 https://inference.broadnet.ai/v1 주소에서 chat completions를 제공하고, 도구와 구조화된 출력을 GLM 5.3과 Qwen3.8 27B에 표기합니다. BroadRouter는 BroadNet이 운영하는 사이트이며, 이 글은 버전 1.17.0 기준 Instructor 문서를 따릅니다.

설치

pip install instructor
export BROADNET_API_KEY='your-broadnet-key'

객체 추출

import os
import instructor
from openai import OpenAI
from pydantic import BaseModel

class Invoice(BaseModel):
    vendor: str
    total: float
    currency: str

client = instructor.from_openai(
    OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"]),
    mode=instructor.Mode.TOOLS,
)

invoice = client.chat.completions.create(
    model="broadnet/glm-5.3",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": "Acme Trading invoice, total 1,250.00 SAR"}],
)
print(invoice)

Instructor는 Invoice를 도구 스키마로 바꾸고, tool_choice로 모델이 그 도구를 반드시 호출하게 한 뒤, 인자를 검증합니다. 객체가 검증을 통과하지 못하면 검증 오류를 담아 다시 요청하는데, 그 횟수는 max_retries로 정합니다.

from_provider를 쓰는 방법

pclient = instructor.from_provider(
    "openai/broadnet/glm-5.3",
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
)
invoice = pclient.create(response_model=Invoice, max_tokens=4000,
                         messages=[{"role": "user", "content": "Acme Trading, 1,250.00 SAR"}])

openai/ 부분이 클라이언트를 고릅니다. 나머지인 broadnet/glm-5.3 부분이 모델 ID로 전송됩니다.

어떤 모드를 쓸까

모드 보내는 내용 BroadNet에서 사용
Mode.TOOLS (기본값) 스키마를 담은 강제 도구 호출 가능, GLM 5.3 또는 Qwen3.8 27B에서
Mode.JSON_SCHEMA json_schema 유형의 response_format 가능, GLM 5.3 또는 Qwen3.8 27B에서
Mode.MD_JSON 일반 요청, 텍스트에서 JSON 파싱 다른 모델용 대안, 먼저 테스트
Mode.RESPONSES_TOOLS Responses API 불가: BroadNet은 chat completions 제공

이미지

Qwen3.8 27B는 도구와 함께 이미지도 받으므로, 사진이나 스캔본을 곧바로 Pydantic 모델로 읽어 들일 수 있습니다.

import base64
img = base64.b64encode(open("invoice.jpg", "rb").read()).decode()
invoice = client.chat.completions.create(
    model="broadnet/qwen3.8-27b",
    response_model=Invoice,
    max_tokens=4000,
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Extract the invoice fields."},
        {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + img}},
    ]}],
)

종량제 키에서는 이미지가 입력 토큰으로 계산됩니다. 비전으로 아랍어 인보이스 읽기를 참고하세요.

테스트 방법

2026-11-15에 깨끗한 가상 환경에 instructor 1.17.0과 openai 3.3.0을 설치하고, 위 예제를 BroadNet의 chat completions 형식을 흉내 내는 로컬 모의 서버에 대고 실행했습니다. 기록된 요청을 확인해 보니 Mode.TOOLS는 강제 tool_choice와 함께 스키마를 도구로 보냈고, Mode.JSON_SCHEMA는 json_schema 응답 형식을 보냈으며, 둘 다 유효한 Invoice를 반환했습니다. from_provider는 모델 ID를 바꾸지 않고 보냈습니다. 모의 서버는 자유 텍스트 JSON을 생성하지 않으므로 Mode.MD_JSON은 테스트하지 않았고, 이미지 예제도 보내지 않았습니다. BroadNet 키가 없었기 때문에 실제 모델 출력은 테스트하지 않았습니다.

문제 해결

  • 검증 재시도가 끝내 성공하지 않음. GLM 5.3과 Qwen3.8 27B에서는 추론도 max_tokens에 포함됩니다. 한도가 낮으면 도구 인자가 중간에 잘릴 수 있습니다. 값을 늘리세요. 답변이 비어서 오는 이유를 참고하세요.
  • 요청에 400. GLM 5.3이나 Qwen3.8 27B를 쓰고 있는지 확인하세요. 강제 tool_choice가 거부되면 Mode.JSON_SCHEMA를 써 보세요.
  • 401. 키가 틀렸거나 만료되었거나 사용 가능 금액이 소진되었습니다.
  • 404. base_url은 /v1로 끝나야 합니다. GLM 5.3과 Qwen3.8 27B는 충전이 필요하며, 초기 크레딧($5 상당)으로는 쓸 수 없습니다.
  • 일괄 추출 중 429. 종량제 키는 분당 30 요청, 동시 처리 4 건까지 허용합니다. 검증 재시도도 한 번 한 번이 별도 요청입니다. 오류와 재시도를 참고하세요.

자주 묻는 질문

BroadNet에서는 Instructor의 어떤 모드를 써야 하나요?

기본값인 Mode.TOOLS를 GLM 5.3이나 Qwen3.8 27B에서 쓰세요. BroadNet이 도구와 구조화된 출력을 표기한 모델입니다. Mode.JSON_SCHEMA는 대신 json_schema response_format을 보냅니다. 모의 서버 테스트에서는 두 모드 모두 유효한 객체를 만들었습니다.

Mode.RESPONSES_TOOLS를 써도 되나요?

아니요. Instructor 문서는 서버가 Responses API를 구현하지 않았다면 이 모드를 고르지 말라고 합니다. BroadNet은 chat completions만 제공합니다.

BroadNet의 DeepSeek V4.1 Flash나 Gemma에서도 Instructor가 작동하나요?

BroadNet은 이 모델들에 도구나 구조화된 출력을 표기하지 않습니다. Mode.MD_JSON은 일반 텍스트로 JSON을 요청해 파싱하므로 작동할 수도 있지만, 의존하기 전에 자신의 데이터로 테스트하세요.

from_provider에는 모델 문자열을 어떻게 쓰나요?

openai/broadnet/glm-5.3으로 쓰세요. Instructor는 첫 번째 부분을 제공자로 떼어 내며, 테스트에서 서버에는 broadnet/glm-5.3이 그대로 전송되었습니다.

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