بتل کد Battle Codeدارد باز می‌شود…

جلسه‌ی 68: خروجی ساخت‌یافته Structured Output

برنامه نمی‌تواند با جمله‌ی آزاد کار کند؛ از مدل JSON می‌خواهیم، با json.loads بازش می‌کنیم و برای جواب خراب آماده‌ایم: نجات، بررسی و یک بار دوباره پرسیدن. تمرین‌ها قدم به قدم یک کارت‌ساز لغت و یک آزمون‌ساز می‌سازند.

در این جلسه یاد می‌گیری

درس

فرض کن از مدل یک کارت لغت می‌خواهی و جواب می‌دهد: «حتماً! کلمه‌ی brave یعنی شجاع، مثلاً...». برای آدم عالی است، اما برنامه‌ی تو از کجا بفهمد معنی کجای جمله است؟ وقتی جواب مدل باید به دست یک برنامه برسد، از او خروجی ساخت‌یافته می‌خواهیم: JSON با کلیدهای مشخص.

در پرامپت سیستم قالب را دقیق بگو و یک نمونه بده. «فقط JSON» را صریح بنویس، چون مدل‌ها دوست دارند مقدمه اضافه کنند. بعضی API‌ها (از جمله DeepSeek و OpenAI) گزینه‌ای هم دارند که مدل را مجبور به JSON می‌کند، ولی باز هم کد تو باید آماده‌ی جواب خراب باشد.

SYSTEM = '''You make vocabulary cards for teenagers.
Reply ONLY with JSON, no other text, in exactly this shape:
{"word": "brave", "meaning": "showing no fear", "example": "She was brave at the dentist."}'''

جواب خوب را با json.loads به دیکشنری تبدیل کن. اما سه جور جواب خراب را حتماً می‌بینی: ۱) با مقدمه: Sure! {...}؛ ۲) نیمه‌کاره، چون به سقف max_tokens خورده: {"word": "calm", "meaning": "peac؛ ۳) JSON درست ولی بدون یک کلید. اگر json.loads متن خراب بگیرد، خطای json.JSONDecodeError می‌دهد و برنامه می‌شکند، مگر این‌که آن را بگیری.

import json

def safe_parse(text):
    try:
        return json.loads(text)
    except json.JSONDecodeError:
        return None

print(safe_parse('{"word": "calm"}'))    # {'word': 'calm'}
print(safe_parse('{"word": "calm'))      # None, and no crash

JSON از پایتون سخت‌گیرتر است و مدل‌ها همین‌جا زیاد اشتباه می‌کنند: متن فقط با کوتیشن دوتایی " (نه ')، بعد از آخرین مورد کاما نمی‌آید، و به جای True، False و None می‌نویسد true، false و null. json.loads این‌ها را به معادل پایتونی‌شان تبدیل می‌کند؛ و یک لیست [...] هم JSON درست است.

import json

print(json.loads('{"ok": true, "n": null}'))   # {'ok': True, 'n': None}
print(json.loads('[1, 2, 3]'))                 # [1, 2, 3]
json.loads("{'word': 'calm'}")                 # JSONDecodeError: single quotes

نجات دادن: اگر مقدمه یا پایان اضافه دارد، تکه‌ی بین اولین { و آخرین } را بردار و دوباره امتحان کن: text[text.find("{"): text.rfind("}") + 1]. بررسی کردن: JSON سالم هنوز ممکن است کلید کم داشته باشد یا عدد به جای متن داشته باشد؛ پس هر کلید لازم را چک کن. دوباره پرسیدن: اگر خراب بود، یک پیام اضافه کن («جواب قبلی‌ات JSON درست نبود؛ فقط JSON بفرست») و یک بار دیگر بپرس. بعد از دو بار، کنار بگذار و گزارش کن؛ حلقه‌ی بی‌پایان پول و توکن می‌سوزاند.

⚠️ هرگز جواب مدل را با eval یا exec اجرا نکن، حتی اگر شبیه پایتون است. فقط json.loads: داده را می‌خواند و هیچ کدی اجرا نمی‌کند. جواب مدل از بیرون آمده و مثل هر ورودی دیگری قابل اعتماد نیست (همان «ورودی را باور نکن» دوره‌ی امنیت سایبری).

⚠️ قالب درست یعنی شکل درست، نه حرف درست. کارتی که کاملاً JSON سالم است هنوز ممکن است معنی غلط یا جمله‌ی نمونه‌ی ساختگی داشته باشد. قبل از این‌که با کارت‌ها درس بخوانی، چند تایشان را با فرهنگ لغت چک کن.

تمرین‌های امروز یک کارت‌ساز لغت می‌سازند: باز کردن یک جواب سالم، شناختن JSON خراب، safe_parse با نجات، check_card برای کلیدها، کارت‌ساز کامل با دو بار تلاش، و در آخر یک آزمون‌ساز که لیستی از سؤال‌ها را بررسی می‌کند. 🏁 اگر زود تمام کردی: در خانه همین برنامه را با مدل واقعی اجرا کن و بشمار از ۱۰ درخواست، چندتا JSON سالم برگشت.

مثال‌های این جلسه

چالش‌ها

  1. Open a Card (آسان)
  2. Which Replies Open? (آسان)
  3. Parse Safely, with Rescue (متوسط)
  4. Check the Card (متوسط)
  5. The Card Maker (سخت)
  6. A Quiz as a JSON List (سخت)

بیشتر بخوان

← جلسه‌ی 67: پرامپت سیستم و نقش جلسه‌ی 69: ابزار دادن به مدل →