---
title: "Instructor OpenAI 호환 base_url 설정(Pydantic) | BroadRouter"
description: "커스텀 base_url과 from_openai 또는 from_provider로 Instructor를 BroadNet Inference에 연결해 Pydantic 객체를 추출하고, 알맞은 Mode를 고르는 방법입니다."
url: https://broadrouter.com/ko/guides/instructor-structured-output/
lang: ko
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

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

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

업데이트 2026-11-16

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

## 설치

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

## 객체 추출

```python
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를 쓰는 방법

```python
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 모델로 읽어 들일 수 있습니다.

```python
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}},
    ]}],
)
```

종량제 키에서는 이미지가 입력 토큰으로 계산됩니다. [비전으로 아랍어 인보이스 읽기](https://broadrouter.com/ko/guides/read-arabic-invoices-with-vision/)를 참고하세요.

## 테스트 방법

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`에 포함됩니다. 한도가 낮으면 도구 인자가 중간에 잘릴 수 있습니다. 값을 늘리세요. [답변이 비어서 오는 이유](https://broadrouter.com/ko/guides/reasoning-tokens-empty-response/)를 참고하세요.
-   **요청에 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 건까지 허용합니다. 검증 재시도도 한 번 한 번이 별도 요청입니다. [오류와 재시도](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가 선불 잔액에서 차감하거나 정기 청구서를 발행하는 식으로 이렇게 과금합니다.

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

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

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

[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를 그대로 사용할 수 있습니다.

[tool\_choice(도구 선택 파라미터)](https://broadrouter.com/ko/glossary/tool-choice/)

tool\_choice는 도구 사용을 제어하는 요청 파라미터입니다. OpenAI Chat Completions에서는 auto(모델이 결정), required(도구를 하나 이상 반드시 호출), none(도구 사용 안 함), 또는 강제할 함수 이름을 지정할 수 있습니다. Anthropic의 대응 옵션은 auto, any, tool, none입니다.

## 자주 묻는 질문

### 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이 그대로 전송되었습니다.

## 관련 가이드

-   [BroadNet Inference에서 OpenAI Python SDK 사용하기](https://broadrouter.com/ko/guides/openai-python-sdk/)
-   [BroadNet Inference에서 Pydantic AI 사용하기(OpenAICompatibleProvider)](https://broadrouter.com/ko/guides/pydantic-ai-openai-compatible/)
-   [비전 모델로 아랍어 인보이스와 영수증 읽기](https://broadrouter.com/ko/guides/read-arabic-invoices-with-vision/)
-   [추론 모델이 빈 답변을 반환하는 이유](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-instructor-structured-output&utm_content=page-cta) ·

**출처**

-   [Instructor 문서, OpenAI 및 OpenAI 호환 서버(2026-11-15 확인)](https://python.useinstructor.com/integrations/openai/)
-   [PyPI, instructor 1.17.0(2026-11-15 확인)](https://pypi.org/project/instructor/)
-   [BroadNet Inference API 레퍼런스(2026-11-15 확인) (영어)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=ko-guides-instructor-structured-output&utm_content=sources)
