Instructor مكتبة Python تحوّل ردود نماذج LLM إلى كائنات Pydantic متحقَّق منها، ويمكنها إعادة المحاولة حين يفشل التحقق. وهي تعدّل عميل OpenAI (patch)، ويغطي توثيقها الخوادم المتوافقة مع OpenAI عبر base_url. وBroadNet Inference تقدّم chat completions على https://inference.broadnet.ai/v1، وتُدرج الأدوات والمخرجات المنظَّمة لنموذجَي GLM 5.3 وQwen3.8 27B. BroadRouter هو موقع BroadNet نفسها؛ ويتبع هذا الدليل توثيق Instructor كما هو في الإصدار 1.17.0.
التثبيت
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، يُرسَل كمعرّف النموذج.
أي وضع تختار
| الوضع | ما يرسله | الاستخدام مع BroadNet |
|---|---|---|
Mode.TOOLS (الافتراضي) |
استدعاء أداة إلزامي بمخططك | نعم، على GLM 5.3 أو Qwen3.8 27B |
Mode.JSON_SCHEMA |
response_format من نوع json_schema |
نعم، على 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 في بيئة افتراضية نظيفة، وشغّلنا الأمثلة أعلاه على خادم وهمي (mock) محلي يتحدث بنية chat completions الخاصة بـ BroadNet، ثم قرأنا الطلبات المسجّلة. أرسل Mode.TOOLS المخطط كأداة مع tool_choice إلزامي، وأرسل Mode.JSON_SCHEMA صيغة استجابة json_schema، وأعاد كلاهما كائن Invoice صالحًا. وأرسل from_provider معرّف النموذج دون تغيير. خادمنا الوهمي لا يكتب JSON في نص حر، لذا لم نختبر Mode.MD_JSON، ولم نرسل مثال الصورة. لم يكن لدينا مفتاح BroadNet، لذا لم نختبر مخرجات نموذج حقيقية.
حل المشكلات
- إعادات تحقق لا تنجح أبدًا. يُحتسب الاستدلال المنطقي ضمن
max_tokensفي GLM 5.3 وQwen3.8 27B، وقد يقطع الحد المنخفض وسائط الأداة. ارفعه. راجع لماذا تعود الإجابات فارغة. - 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 قيد التنفيذ. وكل إعادة تحقق طلب إضافي. راجع الأخطاء وإعادة المحاولة.
