LLM API کے بنیادی اصول: درخواست، جواب، اور پیغام کے کردار

فائدہ:

• LLM API درخواست کے بنیادی ڈھانچے کی وضاحت کر سکتا ہے (اینڈ پوائنٹ، ماڈل، پیغامات، max_tokens)
• سسٹم، صارف اور اسسٹنٹ کے کردار اور بے وطن گفتگو کی تاریخ کے درمیان فرق کو سمجھتا ہے۔
• واپس کیے گئے جواب کے فیلڈز (مواد کے بلاکس، سٹاپ_ریزن، استعمال) کو پڑھ اور تشریح کر سکتے ہیں

پچھلے ماڈیولز میں، ہم نے چیٹ ونڈو سے مصنوعی ذہانت کا استعمال کیا۔ لیکن اگر آپ AI کو اپنے پروڈکٹ، آٹومیشن یا ورک فلو میں شامل کرنا چاہتے ہیں، تو چیٹ انٹرفیس اس میں کمی نہیں کرے گا۔ آپ کو ماڈل سے پروگرامی طور پر جوڑنے کی ضرورت ہے، یعنی کوڈ یا آٹومیشن ٹول کے ساتھ۔ اس پل کا نام API ہے (ایپلی کیشن پروگرامنگ انٹرفیس، وہ معاہدہ جو دو سافٹ ویئر کو کچھ اصولوں کے ساتھ بات کرنے کی اجازت دیتا ہے)۔ جب آپ اس یونٹ کو ختم کریں گے، آپ کو معلوم ہو جائے گا کہ LLM (بڑی زبان کا ماڈل) API کی درخواست کیا ہے، پیغام کے کردار کیا کرتے ہیں، اور جواب کو کیسے پڑھنا ہے۔ یہ وہ بنیاد ہے جس پر باقی ماڈیول بنایا جائے گا۔

API کیسے کام کرتا ہے؟

API میں بنیادی بہاؤ یہ ہے: آپ ایک مخصوص فارمیٹ میں درخواست بھیجتے ہیں۔ سرور ایک مخصوص شکل میں جواب دیتا ہے۔ LLMs میں، یہ عام طور پر ایک HTTP کال ہوتی ہے (HTTP: ویب پر درخواست کے جواب کو لے جانے کے لیے معیاری پروٹوکول) ایک ہی پتے پر (اینڈ پوائنٹ، سرور پر مقررہ پتہ جو آپ کی درخواست کو ہینڈل کرتا ہے)۔ مثال کے طور پر، ایک میسجنگ API میں، تمام درخواستیں ایک ہی ایڈریس پر جاتی ہیں اور JSON (JavaScript آبجیکٹ نوٹیشن — ایک ٹیکسٹ فارمیٹ جس میں کلید/قدر کے جوڑے ہوتے ہیں جسے انسان اور مشین دونوں پڑھ سکتے ہیں) کے طور پر باڈی میں لے جایا جاتا ہے۔

ایک درخواست میں، آپ کم از کم ان تین چیزوں کی وضاحت کریں:

• ماڈل: آپ کون سا ماڈل استعمال کریں گے (جیسے تیز اور سستا ماڈل یا طاقتور ماڈل)۔
• max_tokens: ٹوکنز کی زیادہ سے زیادہ تعداد (سب سے چھوٹی اکائی جس میں متن پر کارروائی کی جاتی ہے، جس پر اگلے یونٹ میں تفصیل سے کارروائی کی جائے گی) جو ماڈل تیار کر سکتا ہے۔ یعنی آؤٹ پٹ کی حد۔
• پیغامات: پیغامات کی فہرست جو گفتگو کو تشکیل دیتے ہیں۔

مرحلہ وار: درخواست کیسے ترتیب دی جائے۔

1. اختتامی نقطہ اور اسناد تیار کریں۔ آپ ہیڈر میں درخواست میں اپنی API کلید (خفیہ تار جو آپ کی شناخت کو ثابت کرتی ہے) شامل کرتے ہیں۔ آپ کوڈ میں کلید کو کبھی شامل نہیں کرتے ہیں۔ ہم یونٹ 9 میں محفوظ اسٹوریج کا احاطہ کریں گے۔
2. ماڈل اور آؤٹ پٹ کی حد منتخب کریں۔ ایک آسان کام کے لیے ہلکا پھلکا ماڈل + چھوٹے میکس_ٹوکن؛ طاقتور ماڈل + ایک پیچیدہ کام کے لیے بڑی حد۔
3. پیغام کی فہرست مرتب کریں۔ List the system instruction, user message, and past rounds (if any).
4. درخواست بھیجیں اور جواب کو پارس کریں۔ واپس کردہ JSON سے متن کا مواد پڑھیں، وجہ روکیں اور ٹوکن کا استعمال کریں۔

پیغام کے کردار: سسٹم، صارف، اسسٹنٹ

گفتگو ایک ترتیب میں ترتیب دیئے گئے پیغامات پر مشتمل ہوتی ہے، اور ہر پیغام کا ایک کردار ہوتا ہے۔ کردار اس بات کا تعین کرتا ہے کہ ماڈل اس متن کے ساتھ کیسا سلوک کرتا ہے۔

کردار

جو لکھتا ہے۔

مقصد

نظام

ڈویلپر/آپریٹر

مستقل ہدایات، شخصیت اور قواعد جو پوری گفتگو میں لاگو ہوتے ہیں۔

صارف

اختتامی صارف

صارف کا موجودہ سوال یا ان پٹ

اسسٹنٹ

ماڈل

ماڈل کے ذریعہ تیار کردہ جواب (اور پچھلے جوابات)

سسٹم رول زیادہ تر فراہم کنندگان میں درخواست کے باڈی میں ایک علیحدہ سسٹم فیلڈ کے طور پر دستیاب ہے۔ صارف اور اسسٹنٹ پیغامات کی فہرست میں ترتیب وار درج ہیں۔ Critical point: the system instruction is the high-level instruction, the user message is the request to be answered at that moment.

{ "model": "claude-opus-4-8", "max_tokens": 1024, "system": "آپ ایک کارپوریٹ سپورٹ اسسٹنٹ ہیں۔ ایک مختصر، رسمی اور تصدیق شدہ جواب دیں۔ ایسی معلومات کو مت بنائیں جس کے بارے میں آپ کو یقین نہیں ہے۔", "messages": [ { "role": "user", "may content" کو واپس کرنا شروع کروں؟ } ]}

تقریر بے وطن ہے۔

یہاں سب سے عام غلط فہمی ہے: LLM API کالیں بے وطن ہیں — سرور دو درخواستوں کے درمیان کوئی میموری نہیں رکھتا ہے۔ ماڈل کو آپ کی پچھلی درخواست یاد نہیں ہے۔ اگر آپ ملٹی راؤنڈ چیٹ ترتیب دے رہے ہیں، تو آپ کو ہر نئی درخواست کے ساتھ ماضی کے راؤنڈز کو دوبارہ بھیجنے کی ضرورت ہوگی۔ ماڈل کی "میموری" آپ کے بھیجے گئے پیغامات کی فہرست پر مشتمل ہے۔

{ "ماڈل": "کلاڈ-اوپس-4-8"، "میکس_ٹوکنز": 512، "پیغامات": [ { "کردار": "صارف"، "مواد": "ہیلو، میرا نام ڈینیز ہے۔" }, { "role": "assistant", "content": "Hello Deniz، میں آپ کی کیسے مدد کر سکتا ہوں؟" }, { "role": "user", "content": "میں نے ابھی اپنا نام کہا، کیا آپ کو یاد ہے؟" } ]}

تیسرے پیغام کا صحیح جواب دینا اس بات پر منحصر ہے کہ آپ پچھلے دونوں پیغامات بھیج رہے ہیں۔ اگر آپ اسے نہیں بھیجتے ہیں، تو ماڈل "سمندر" کو نہیں جان سکے گا اور غلط جواب دے گا۔ اس سے لاگت پر بھی براہ راست اثر پڑتا ہے: بات چیت جتنی لمبی ہوگی، فہرست اتنی ہی بڑی ہوگی، ہر درخواست زیادہ ٹوکن استعمال کرتی ہے۔

ٹپ: طویل گفتگو میں، پوری ہسٹری بھیجنے کے بجائے پرانے راؤنڈز (خلاصہ + آخری چند راؤنڈز) کا خلاصہ اور منتقل کرنا لاگت کو کم کرتا ہے اور سیاق و سباق کی کھڑکی کو محفوظ رکھتا ہے۔ ہم اسے یونٹ 6 اور 11 میں گہرا کریں گے۔

جواب پڑھیں

جب ماڈل جواب دیتا ہے، تو آپ کو ایک منظم آبجیکٹ موصول ہوتا ہے، سادہ متن نہیں۔ عام علاقے:

{ "id": "msg_01ABC...", "model": "claude-opus-4-8", "role": "assistant", "content": [ { "type": "text", "text": "واپسی شروع کرنے کے لیے، اپنے اکاؤنٹ میں 'My Orders' صفحہ پر جائیں..." } ], "stop_reason": "stop_reason:" "input_tokens": 47, "output_tokens": 88 }}

• مواد: جواب خود؛ یہ مواد کے بلاکس کی فہرست ہے۔ ٹیکسٹ بلاک کا ٹیکسٹ فیلڈ اصل جواب ہے۔
• stop_reason: ماڈل کیوں رک گیا؟ end_turn = قدرتی اختتام؛ max_tokens = آؤٹ پٹ کی حد پر پھنس گیا (جواب نامکمل ہو سکتا ہے)؛ انکار = حفاظتی وجوہات کی بنا پر انکار۔ آپ کے کوڈ کو ہمیشہ پہلے stop_reason کو دیکھنا چاہیے۔
• استعمال: ان پٹ اور آؤٹ پٹ ٹوکن نمبر۔ یہ لاگت اور حد سے باخبر رہنے کی بنیاد ہے۔

دھیان دیں: اگر stop_reason max_tokens ہے تو جواب مکمل نہیں ہوتا ہے۔ اسے "کامیاب ردعمل" کے طور پر سمجھنا اور صارف کو آدھا متن دکھانا پروڈکشن میں سب سے عام غلطیوں میں سے ایک ہے۔ یا تو max_tokens میں اضافہ کریں یا سٹریمنگ کا استعمال کریں۔

کمزور فوری / مضبوط اشارہ

دو مختلف سسٹم پرامپٹس کے ساتھ ایک ہی کام:

# کمزور آپ اسسٹنٹ ہیں۔ سوالوں کے جواب دیں۔

# مضبوط آپ کارپوریٹ سپورٹ اسسٹنٹ ہیں۔ قواعد: - فراہم کردہ پالیسی دستاویز میں دی گئی معلومات پر مکمل انحصار کریں؛ اگر یہ دستاویز میں نہیں ہے، تو بولیں "میرے پاس یہ معلومات نہیں ہے، میں اسے متعلقہ یونٹ کو بھیج رہا ہوں۔" - جوابات 3 جملوں سے زیادہ نہیں ہونے چاہئیں، رسمی اور واضح ہوں۔ - ذاتی ڈیٹا (TC ID نمبر، کارڈ نمبر) نہ مانگیں اور نہ دہرائیں۔ - جب آپ کو یقین نہ ہو تو اندازہ نہ لگائیں۔

طاقتور ورژن؛ یہ دائرہ کار، شکل، حفاظتی مارجن، اور غیر یقینی صورتحال میں رویے کی وضاحت کرتا ہے۔ ماڈل آؤٹ پٹ کی مستقل مزاجی اس وضاحت سے براہ راست آتی ہے۔

تین چھوٹے کیسز

کیس 1 - سپورٹ بوٹ (بے وطنی کا جال)۔ ایک ای کامرس ٹیم نے بوٹ کو لائیو لیا؛ جب صارف نے کہا کہ "پچھلے آرڈر کو منسوخ کریں"، بوٹ آرڈر نمبر کو "بھول گیا"۔ وجہ: وہ ہر درخواست کو صرف آخری پیغام کے ساتھ بھیج رہے تھے۔ حل: انہوں نے پیغامات کی فہرست میں آخری 6 راؤنڈ شامل کیے ہیں۔ نتیجہ: سیاق و سباق کو محفوظ کیا گیا، لیکن ان پٹ فی درخواست 40 ٹوکنز سے بڑھ کر ~600 ٹوکنز تک پہنچ گئی — ہم یونٹ 2 میں لاگت کے سبق کا احاطہ کریں گے۔

کیس 2 - معاہدے کا نامکمل خلاصہ۔ ایک قانونی ٹیم کے پاس 10 صفحات پر مشتمل معاہدے تھے۔ max_tokens: 300 کم رہے، خلاصے وسط جملے کو کاٹ رہے تھے۔ stop_reason ہر بار max_tokens تھا لیکن کوئی نہیں دیکھ رہا تھا۔ max_tokens کو بڑھا کر 1500 کر دیا اور stop_reason چیک شامل کیا کٹے ہوئے سمری کی شرح 18% سے کم ہو کر 0% ہو گئی۔

کیس 3 - مکسنگ رولز۔ ایک مارکیٹنگ ٹیم سسٹم کو خالی چھوڑ کر صارف کے پیغام میں تمام ہدایات لکھ رہی تھی۔ جب صارف کے ان پٹ کو ہدایات کے ساتھ ملایا جاتا ہے، تو ماڈل بعض اوقات صارف کے حکم کی تعمیل کرتا ہے کہ "پچھلے اصولوں کو بھول جائیں۔" انہوں نے مستقل قوانین کو نظام میں منتقل کر دیا۔ صارف کے ان پٹ کو ہدایات سے الگ کرنے سے، اصول کی خلاف ورزیوں میں نمایاں کمی واقع ہوئی۔

عام غلطیاں

• ماضی کو بھیجنا بھول جانا: ماڈل کے بارے میں سوچا جاتا ہے کہ "یاد نہیں ہے"؛ جبکہ یہ بے وطن ہے۔ آپ سیاق و سباق کو لے.
• `stop_reason` کو نہیں دیکھ رہا: max_tokens کے ساتھ روکے گئے جواب کو مکمل سمجھا جاتا ہے۔
• 'صارف' میں ہدایات کو سرایت کرنا: سسٹم میں مستقل قواعد؛ فوری ان پٹ صارف کو جاتا ہے۔ اختلاط حفاظتی کمزوریاں پیدا کرتا ہے۔
• ایک سادہ سٹرنگ کے لیے 'مواد' کو غلط سمجھنا: جواب بلاکس کی فہرست ہے۔ پہلے ٹیکسٹ بلاک کے ٹیکسٹ فیلڈ کو پڑھیں، بلائنڈ انڈیکس کے ساتھ مواد[0] حاصل کرنے سے پہلے اس کی قسم کی تصدیق کریں۔
• کوڈ میں کلید کو سرایت کرنا: ماحولیاتی متغیر (یونٹ 9) کا استعمال کریں۔

گہرا: مواد کے بلاکس اور ملٹی پارٹ جوابات

اس بات کو سمجھنا کہ جواب میں مواد کی فیلڈ ایک فہرست کیوں ہے ان جدید خصوصیات کے لیے بنیادی ہے جن کا آپ بعد میں سامنا کریں گے۔ بعض اوقات ماڈل متن کا ایک بلاک نہیں بلکہ کئی بلاکس واپس کرتا ہے: سوچ کا ایک بلاک، اس کے بعد متن کا ایک بلاک؛ یا متن کا ایک بلاک جس کے بعد ٹول استعمال بلاک ہوتا ہے۔ اسی لیے آنکھیں بند کرکے مواد[0] کو "جواب" کے طور پر شمار کرنا نازک ہے۔ صحیح نقطہ نظر یہ ہے کہ فہرست میں جائیں اور اسے قسم کے مطابق ترتیب دیں: آپ ان بلاکس کے متنی مواد کو جمع کرتے ہیں جن کی قسم کی فیلڈ ٹیکسٹ ہے، اور دوسری اقسام (سوچ، ٹول) کو الگ سے علاج کریں۔

یہ فرق عملی طور پر کیا کرتا ہے کہ آپ ماڈل کے استدلال (اگر کوئی ہے) کو صارف پر ظاہر کیے بغیر لاگ ان کر سکتے ہیں، ٹول کالز کو الگ منطق کی طرف ری ڈائریکٹ کر سکتے ہیں، اور صرف اصل جواب کو سکرین پر پرنٹ کر سکتے ہیں۔ جیسے جیسے ماڈیول ترقی کرتا ہے (خاص طور پر یونٹس 4 اور 11 میں) آپ دیکھیں گے کہ یہ بلاک ڈھانچہ آؤٹ پٹ کی توثیق اور ہدایت کے لیے کتنا مفید ہے۔

ایک اور عملی نکتہ: آپ مختلف فراہم کنندہ پلیٹ فارمز (براہ راست API، کلاؤڈ فراہم کنندہ کے ذریعے) سے ایک ہی ماڈل تک رسائی حاصل کر سکتے ہیں۔ اگرچہ اختتامی پتہ اور توثیق کی شکل بدل سکتی ہے، لیکن بنیادی تصورات جیسے کہ پیغام کے کردار، بے وطنی، اور ردعمل کا ڈھانچہ وہی رہتا ہے۔ لہذا اس یونٹ میں بنیادی باتیں لاگو ہوتی ہیں اس سے کوئی فرق نہیں پڑتا ہے کہ آپ کون سا پلیٹ فارم استعمال کرتے ہیں۔

خلاصہ میں

LLM API کی درخواست ماڈل، آؤٹ پٹ کی حد، اور پیغام کی فہرست پر مشتمل ہوتی ہے۔ کردار (نظام، صارف، معاون) ماڈل کے رویے کا تعین کرتے ہیں۔ کالیں بے وطن ہیں: آپ ہر درخواست کے ساتھ سیاق و سباق رکھتے ہیں۔ جواب ایک منظم اعتراض ہے؛ مواد، stop_reason اور استعمال کے شعبوں کو پڑھنا اور تشریح کرنا پیداوار میں پائیداری کی بنیاد ہے۔

درخواست کا کام

اپنے پیشہ سے ایک کام کا انتخاب کریں (مثلاً آنے والے ای میل کو چھانٹنا، مختصر خلاصے بنانا)۔ کاغذ کے ٹکڑے پر: (1) سسٹم پرامپٹ کو 4-5 اصولوں کے ساتھ لکھیں، (2) صارف کا ایک نمونہ پیغام اور اگر کوئی ہو تو 2-راؤنڈ ہسٹری ترتیب دیں، (3) max_tokens کے لیے ایک معقول قدر کا تعین کریں اور جواز لکھیں، (4) فہرست جو stop_reason اقدار آپ واپس کیے گئے جواب میں سنبھالیں گے اور کیسے۔

چیک لسٹ

• میں درخواست کے تین لازمی حصوں کو شمار کر سکتا ہوں (ماڈل، max_tokens، پیغامات)۔
• میں سسٹم، صارف اور اسسٹنٹ کے کردار کے درمیان فرق کی وضاحت کر سکتا ہوں۔
• میں جانتا ہوں کہ کالیں بے وطن ہیں اور مجھے ماضی کو لے جانے کی ضرورت ہے۔
• میں [ ] مواد، stop_reason اور استعمال کے شعبوں کو پڑھ اور تبصرہ کر سکتا ہوں۔
• max_tokens کے ساتھ میں تراشے ہوئے جواب کو دیکھ سکتا ہوں اور اسے سنبھال سکتا ہوں۔