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 건까지 허용합니다. 검증 재시도도 한 번 한 번이 별도 요청입니다. 오류와 재시도를 참고하세요.
