تستدعي شيفرتك json.loads() على رد النموذج فتحصل على JSONDecodeError: Expecting value: line 1 column 1. أو يُحلَّل الرد، لكن حقلًا ما يأتي سلسلةً نصية حيث أردت رقمًا. يرتّب هذا المقال الأسباب بحسب ما يمكنك فعله بأمان حيال كل منها، ويقدّم دالة Python مُختبرة لا تصلح إلا الحالات الواضحة، ويعرض حلقة إعادة محاولة تعرف متى لا تفيد الإعادة.
أما الاختيار بين وضع JSON وjson_schema فيشرحه مقال وضع JSON مقابل json_schema. وهذا المقال عمّا تفعله بالرد الذي وصلك فعلًا.
لماذا تُعيد نماذج اللغة JSON غير صالح؟
يكتب النموذج النص رمزًا بعد رمز. وما لم يقيّد الخادم عملية فك الترميز، فلا شيء يمنعه من إضافة جملة ودّية أو من نفاد المساحة. أشيع حالات الفشل:
| ما تراه | السبب | هل يمكن إصلاحه بأمان في الشيفرة؟ |
|---|---|---|
```json … ``` حول الكائن |
عادة التنسيق في المحادثة | نعم: أزل السور |
| “Here is the JSON:” قبله، و”Let me know…” بعده | العادة نفسها | نعم: اقرأ القيمة الأولى فقط |
<think>...</think> قبل الكائن |
نص الاستدلال المنطقي داخل حقل المحتوى على بعض الخوادم | نعم: أزل الكتلة |
| ينتهي في منتصف سلسلة والأقواس مفتوحة | بلغ max_tokens |
لا: أعد الإرسال بمساحة أكبر |
| محتوى فارغ | الاستدلال المنطقي استهلك الميزانية كلها | لا: أعد الإرسال بمساحة أكبر |
{"a": 1,} |
فاصلة زائدة؛ تسمح بها JavaScript ولا يسمح بها RFC 8259 | نعم: معنى واحد |
{'a': True, 'b': None} |
صياغة Python | نعم: ast.literal_eval يقرؤها بأمان |
NaN، Infinity |
ليست JSON؛ وPython تقبلها افتراضيًا | لا: ارفض |
| JSON صالح بأنواع خاطئة أو حقول ناقصة | المخطط غير مفروض | لا: أعد الطلب مع الخطأ |
الحد الفاصل هو الغموض. فإن كان هناك معنى واحد فقط يمكن أن يقصده النموذج، فأصلحه في الشيفرة وسجّل أنك فعلت. وإن كنت ستضطر إلى التخمين، فارفض الرد.
لماذا لا تصلح JSON المقطوع؟
لأن النسخة المُصلَحة تبدو صحيحة وهي ليست كذلك. شغّلنا json_repair 0.64.9، وهي مكتبة شائعة بترخيص MIT، على رد مقطوع في منتصف كلمة:
'{"name": "Omar", "city": "Jed' -> {'name': 'Omar', 'city': 'Jed'}
أعادت JSON صالحًا بمدينة “Jed”. وملف README الخاص بها صريح في ذلك: فهي “automatically completes missing values in JSON fields with reasonable defaults” (الترجمة: «تكمل تلقائيًا القيم الناقصة في حقول JSON بقيم افتراضية معقولة»). وهذا مفيد لقراءة السجلات. أما للبيانات التي تخزّنها أو تتصرف بناءً عليها، فهو يحوّل فشلًا ظاهرًا إلى فشل صامت.
افحص finish_reason قبل التحليل. فالقيمة "length" تعني أن الرد بلغ max_tokens. وإعادة إرسال الطلب نفسه بالحد نفسه تفشل بالطريقة نفسها، فضاعف الحد أو اطلب أقل في كل استدعاء. ونماذج الاستدلال المنطقي تجعل هذا أكثر شيوعًا: إذ يقول المرجع التقني لواجهة BroadNet إن DeepSeek V4.1 Flash وGLM 5.3 وQwen3.8 27B تستدل قبل أن تجيب، وإن الاستدلال يُحتسب ضمن max_tokens. ومع حد صغير قد تعود الإجابة فارغة. اترك 1,000 رمز أو أكثر، أو اضبط reasoning_effort على low؛ وتجد الأرقام في مقال ميزانية الاستدلال المنطقي.
دالة إصلاح لا تعالج إلا الحالات الآمنة
تستخدم هذه الدالة المكتبة القياسية فقط. وتُعيد القيمة المحلَّلة وقائمة بالإصلاحات التي أجرتها، لتتمكن من عدّها.
import ast, json, re
class Truncated(Exception): pass
class NotJSON(Exception): pass
FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)
def _reject_constant(name): # NaN, Infinity: Python accepts them, JSON does not
raise NotJSON(f"non-standard constant {name}")
_decoder = json.JSONDecoder(parse_constant=_reject_constant)
def _first_value(s):
"""Decode the first JSON object or array in s, ignoring prose before and after it."""
for i, ch in enumerate(s):
if ch in "{[":
try:
return _decoder.raw_decode(s, i)[0]
except json.JSONDecodeError:
continue # a stray brace in prose; try the next one
raise NotJSON("no JSON object or array found")
def _scan(s):
"""Drop commas before } or ] outside strings; report brackets left open."""
out, stack, in_str, esc = [], [], False, False
for i, ch in enumerate(s):
if in_str:
if esc:
esc = False
elif ch == "\\":
esc = True
elif ch == '"':
in_str = False
elif ch == '"':
in_str = True
elif ch in "{[":
stack.append(ch)
elif ch in "}]" and stack:
stack.pop()
elif ch == ",":
rest = s[i + 1:].lstrip()
if rest[:1] in ("}", "]"):
continue # trailing comma: skip it
out.append(ch)
return "".join(out), len(stack) + (1 if in_str else 0)
def _python_literal(s):
"""Output in Python syntax: single quotes, True/False/None, trailing commas."""
start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
end = max(s.rfind("}"), s.rfind("]"))
if start < 0 or end <= start:
raise NotJSON("no braces")
value = ast.literal_eval(s[start:end + 1]) # literals only; never runs code
if not isinstance(value, (dict, list)):
raise NotJSON("not an object or array")
json.dumps(value, allow_nan=False) # must round-trip as strict JSON
return value
def parse_llm_json(content, finish_reason=None):
"""Return (value, repairs). Raises Truncated or NotJSON."""
if finish_reason == "length":
raise Truncated("hit max_tokens; raise the limit or shorten the output")
if not content or not content.strip():
raise NotJSON("empty content (reasoning may have used the whole budget)")
repairs = []
s = content.strip().lstrip("\ufeff")
if THINK.search(s):
s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
m = FENCE.search(s)
if m:
s = m.group(1).strip(); repairs.append("removed code fence")
try:
value = _decoder.decode(s)
return value, repairs
except json.JSONDecodeError:
pass
try:
value = _first_value(s); repairs.append("ignored text around JSON")
return value, repairs
except NotJSON:
pass
fixed, open_count = _scan(s)
if open_count:
raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
if fixed != s:
try:
value = _first_value(fixed); repairs.append("removed trailing commas")
return value, repairs
except NotJSON:
pass
try:
value = _python_literal(s); repairs.append("parsed Python-style literal")
return value, repairs
except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
raise NotJSON(f"unrepairable: {e}") from None
كيف تعمل كل خطوة:
- القطع والردود الفارغة تُطلق استثناءً قبل أي تحليل، فلا تتحول أبدًا إلى بيانات.
- الأسوار وكتل الاستدلال المنطقي تُزال بتعبيرين نمطيين.
- الدالة
raw_decodeهي الأداة الأساسية. تقول وثائق Python إنها تفك مستندًا “from a string that may have extraneous data at the end” (الترجمة: «من سلسلة قد تحتوي على بيانات زائدة في نهايتها»)، وتُعيد الموضع الذي توقفت عنده. وبالبدء من أول{أو[تتخطى النص قبل الكائن وتتجاهل النص بعده. وإن فشل فك قوس وارد في النص، تجرّب القوس التالي. - مسح الأقواس يمرّ على النص متتبّعًا السلاسل وعلامات الهروب. والأقواس المتروكة مفتوحة تعني أن الرد قُطع حتى لو لم تقل
finish_reasonذلك؛ فيُطلق استثناء. وتُحذف الفواصل الواقعة مباشرة قبل}أو]خارج السلاسل. - الدالة
ast.literal_evalتقرأ مخرجات بأسلوب Python فيها علامات اقتباس مفردة وTrueوNone. وهي تقيّم القيم الحرفية فقط ولا تشغّل شيفرة أبدًا. ثم يجب أن تتحوّل النتيجة إلى JSON صارم. NaNوInfinityتُطلقان استثناءً عبرparse_constant. فوحدةjsonفي Python تقبلهما افتراضيًا؛ بينما يقول RFC 8259 إنهما “are not permitted” (الترجمة: «غير مسموح بهما»)، والدالةJSON.parseفي JavaScript ترفضهما.
شغّلناها على 17 سلسلة اختبار: JSON سليم، وJSON داخل سور، ومفاتيح وقيم عربية داخل سور، ونص قبل الكائن وبعده، وعنصر نائب {name} في نص قبل الكائن، وكتلة <think>، وفواصل زائدة في الكائنات والمصفوفات، وفواصل وأقواس داخل السلاسل، وعلامات اقتباس مهرَّبة، ومسار Windows ينتهي بشرطة مائلة عكسية، وقيم Python حرفية، وNaN، وردًا فارغًا، وردًا مقطوعًا مع finish_reason: "length" ودونها، وكائنين متتاليين. وتصرّفت كلها كما يصف الجدول أعلاه. وكشف أحد الاختبارات خطأً حقيقيًا: فقد كانت نسخة مبكرة تقلب علامة الهروب قبل التحقق من علامة الاقتباس الختامية، فخسرت "he said \"hi,]\"" فاصلتها. اختبر شيفرة الإصلاح لديك على علامات الاقتباس المهرَّبة.
هناك حدّان يجب معرفتهما. عند وجود كائنين متتاليين تُعيد الدالة الأول؛ فإن أردت عدة عناصر فاطلب مصفوفة JSON واحدة. ومخرجات Python بعلامات اقتباس مفردة تحتوي على علامة اقتباس مزدوجة داخل سلسلة قد يسيء مسح الأقواس قراءتها فيرفضها. والرفض هو الفشل الآمن.
كيف تعيد المحاولة بعد فشل الإصلاح؟
الإصلاح يعالج الصيغة، والتحقق يعالج المحتوى: الحقول الصحيحة، والأنواع الصحيحة، والقيم المعقولة. هذه الحلقة تتحقق بحزمة jsonschema وتختار طريقة الإعادة بحسب السبب:
import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON
client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
"required": ["name", "city", "amount"],
"properties": {"name": {"type": "string", "minLength": 1},
"city": {"type": ["string", "null"]},
"amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)
def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
"Schema: " + json.dumps(SCHEMA)},
{"role": "user", "content": text}]
for attempt in range(1, attempts + 1):
r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
reasoning_effort="low", temperature=0)
c = r.choices[0]
try:
value, repairs = parse_llm_json(c.message.content, c.finish_reason)
errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
if not errors:
log({"attempt": attempt, "repairs": repairs, "ok": True})
return value
problem = "The JSON does not match the schema: " + "; ".join(errors)
except Truncated:
log({"attempt": attempt, "ok": False, "why": "truncated"})
max_tokens *= 2 # same prompt, more room; a re-ask would be cut off too
continue
except NotJSON as e:
problem = f"That reply was not valid JSON ({e})."
log({"attempt": attempt, "ok": False, "why": problem})
messages += [{"role": "assistant", "content": c.message.content or ""},
{"role": "user", "content": problem + " Return the corrected JSON object only."}]
raise RuntimeError(f"no valid JSON after {attempts} attempts")
القواعد في هذه الحلقة:
- مقطوع: أعد إرسال الرسائل نفسها بضعف الحد. فإضافة رسالة «أصلِح من فضلك» تجعل الأمر أطول ولا تجعل الإخراج أقصر.
- ليس JSON أو شكله خاطئ: أرسل الخطأ نفسه. فرسالة مثل “amount: ‘1200’ is not of type ‘number’” تعطي النموذج شيئًا محددًا يصلحه. أما الإعادة المجرّدة فكثيرًا ما تكرّر الخطأ.
- حدّ المحاولات بثلاث. فكل إعادة ترسل المحادثة كاملة بوصفها رموز إدخال. وبعد ثلاث محاولات سجّل المُدخل ووجّهه إلى مسار آخر.
- سجّل قائمة الإصلاحات. فارتفاع عدد “removed code fence” بعد تغيير في الأمر يخبرك أن الأمر ساء، حتى لو لم يفشل شيء.
شغّلنا هذه الحلقة مقابل خادم وهمي محلي يعيد ردودًا مكتوبة سلفًا. فرد داخل سور فيه فاصلة زائدة و"amount": "1200" بوصفه سلسلة أُصلح، ثم فشل في التحقق، ثم صُحّح في الاستدعاء الثاني بعد إرسال الخطأ. ورد مقطوع مع finish_reason: "length" أُعيد إرساله بعد رفع max_tokens من 1,500 إلى 3,000 فنجح. وسجّل الخادم الوهمي الطلب في كل مرة، مؤكدًا عدد الرسائل والحد اللذين أرسلتهما الحلقة. وقد يفشل نموذج حقيقي بطريقة مختلفة، فشغّلها على 100 من مُدخلاتك قبل أن تثق بالأرقام.
هل تجعل المخرجات المهيكلة هذا كله غير ضروري؟
تزيل معظمه. فالخادم الذي يقيّد فك الترميز بمخططك لا يستطيع إخراج سور ولا فاصلة زائدة ولا حقل ناقص. ويفعل vLLM، وهو خادم شائع للنماذج المفتوحة، ذلك عبر الواجهتين الخلفيتين xgrammar أو guidance. لكن حالتي فشل تبقيان حتى حينها: القطع عند max_tokens، والرفض. إذ تشير OpenAI إلى أن مخرجات وضع JSON صالحة “except for in some edge cases” (الترجمة: «إلا في بعض الحالات الحدّية»)، وأن تطبيقك “must detect and handle” (الترجمة: «يجب أن يكتشف ويعالج») المخرجات التي ليست كائنًا مكتملًا. لذا أبقِ فحص finish_reason والمُتحقِّق، حتى مع json_schema.
ما يمنعه كل نهج:
| النهج | الأسوار والنص المحيط | أخطاء الصياغة | الشكل الخاطئ | القطع |
|---|---|---|---|---|
| الأمر فقط (“reply with JSON”) | يقلّ | يقلّ | يقلّ | لا |
وضع JSON (json_object) |
نعم | نعم | لا | لا |
المخرجات المهيكلة (json_schema، مفروضة) |
نعم | نعم | نعم | لا |
ومع وضع JSON تقول OpenAI أيضًا إنك “must always instruct the model to produce JSON” (الترجمة: «يجب دائمًا أن توجّه النموذج لإنتاج JSON») في إحدى الرسائل؛ وإلا فقد يُخرج مسافات بيضاء حتى يبلغ حد الرموز. والخوادم الأخرى المتوافقة مع OpenAI تتفاوت، فاختبر الوضع على النموذج الذي تطلقه. والاختبار موجود في مقال المخرجات المهيكلة.
ولفحص رد يدويًا، الصقه في أداة التحقق من مخرجات JSON لنماذج اللغة، أو ابنِ مخططًا صارمًا من كائن نموذجي باستخدام مولّد مخطط JSON.
أين تقع BroadNet Inference من هذا؟
BroadRouter هو موقع BroadNet. ويذكر المرجع التقني لواجهة BroadNet المخرجات المهيكلة لـ GLM 5.3 وQwen3.8 27B فقط، ولا يسمّي معامل الطلب، فاختبر json_schema على النموذج قبل الاعتماد عليه. وعلى DeepSeek V4.1 Flash وGemma 4 VL 26B استخدم JSON عبر الأمر فقط مع دالة الإصلاح والمُتحقِّق أعلاه. وثلاثة من النماذج الأربعة تستدل قبل الإجابة، فخصّص لذلك ميزانية في max_tokens. وللاستخراج بالجملة يبيّن مقال مشغّل الدفعات كيف تسجّل finish_reason لكل عنصر. ولا يُحتفظ بالأوامر والردود بعد كل طلب.
