BroadRouter
ابدأ الآن

مخرجات منظَّمة باستخدام Instructor على BroadNet Inference

آخر تحديث

غلّف عميل OpenAI مضبوطًا على base_url هو https://inference.broadnet.ai/v1 ومفتاح BroadNet بالدالة instructor.from_openai، ثم استدعِ chat.completions.create مع response_model على صنف Pydantic الخاص بك، وmodel على broadnet/glm-5.3 أو broadnet/qwen3.8-27b. هذان هما النموذجان اللذان تُدرج لهما BroadNet الأدوات والمخرجات المنظَّمة. الوضع الافتراضي Mode.TOOLS، ويعمل Mode.JSON_SCHEMA أيضًا.

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 قيد التنفيذ. وكل إعادة تحقق طلب إضافي. راجع الأخطاء وإعادة المحاولة.

أسئلة شائعة

أي وضع من Instructor أستخدم مع BroadNet؟

الوضع Mode.TOOLS، وهو الافتراضي، على GLM 5.3 أو Qwen3.8 27B، وهما النموذجان اللذان تُدرج لهما BroadNet الأدوات والمخرجات المنظَّمة. أما Mode.JSON_SCHEMA فيرسل response_format من نوع json_schema بدلًا من ذلك. وقد أنتج كلاهما كائنات صالحة في اختبارنا على خادم وهمي (mock).

هل يمكنني استخدام Mode.RESPONSES_TOOLS؟

لا. يقول توثيق Instructor ألا تختاره ما لم يكن الخادم يطبّق Responses API. وBroadNet تقدّم chat completions فقط.

هل يعمل Instructor مع DeepSeek V4.1 Flash أو Gemma على BroadNet؟

لا تُدرج BroadNet الأدوات ولا المخرجات المنظَّمة لهذين النموذجين. الوضع Mode.MD_JSON يطلب JSON في نص عادي ثم يحلّله، وقد ينجح، لكن اختبره على بياناتك قبل الاعتماد عليه.

كيف أكتب سلسلة النموذج في from_provider؟

اكتب openai/broadnet/glm-5.3. يفصل Instructor المقطع الأول بوصفه المزوّد، وفي اختبارنا أرسل broadnet/glm-5.3 إلى الخادم دون تغيير.

اقرأها بصيغة Markdownاسأل ChatGPTاسأل Claudeاسأل Perplexity