سود:
- می تواند ساختار اصلی یک درخواست LLM API (نقطه پایانی، مدل، پیام ها، max_tokens) را توصیف کند.
- تفاوت بین نقش های سیستم، کاربر و دستیار و تاریخچه مکالمه بدون تابعیت را درک می کند
- می تواند فیلدها (بلوک های محتوا، stop_reason، استفاده) پاسخ برگشتی را بخواند و تفسیر کند
در ماژول های قبلی از هوش مصنوعی از پنجره چت استفاده کردیم. اما اگر میخواهید هوش مصنوعی را در محصول، اتوماسیون یا گردش کار خود جاسازی کنید، رابط چت آن را قطع نمیکند. باید به صورت برنامه نویسی یعنی با کد یا ابزار اتوماسیون به مدل متصل شوید. نام این پل API (Application Programming Interface، قراردادی است که به دو نرم افزار اجازه می دهد تا با قوانین خاصی صحبت کنند). وقتی این واحد را تمام کردید، میدانید که درخواست API LLM (مدل زبان بزرگ) چیست، نقشهای پیام چه کار میکنند و چگونه پاسخ را بخوانید. این پایه ای است که بقیه ماژول بر روی آن ساخته خواهد شد.
API چگونه کار می کند؟
جریان اصلی در API به این صورت است: شما درخواستی را در قالب خاصی ارسال می کنید. سرور پاسخی را در قالب خاصی برمی گرداند. در LLM ها، این معمولاً یک تماس HTTP (HTTP: پروتکل استاندارد برای انتقال درخواست-پاسخ در وب) به یک آدرس واحد (نقطه پایانی، آدرس ثابت روی سروری است که درخواست شما را رسیدگی می کند). به عنوان مثال، در یک API پیامرسانی، همه درخواستها به یک آدرس واحد میروند و در بدنه بهعنوان JSON (جاوا اسکریپت Object Notation - قالب متنی متشکل از جفتهای کلید/مقدار که هم توسط انسانها و هم توسط ماشینها قابل خواندن است) حمل میشوند.
در یک درخواست، حداقل این سه مورد را مشخص می کنید:
- مدل: از کدام مدل استفاده خواهید کرد (مثلاً یک مدل سریع و ارزان یا یک مدل قدرتمند).
- max_tokens: حداکثر تعداد توکنهایی (کوچکترین واحدی که متن در آن پردازش میشود، که در واحد بعدی با جزئیات پردازش میشود) که مدل میتواند تولید کند. یعنی محدودیت خروجی
- پیام ها: فهرست پیام هایی که مکالمه را تشکیل می دهند.
گام به گام: نحوه تنظیم یک درخواست
- نقطه پایانی و اعتبارنامه را آماده کنید. شما کلید API خود را (رشته مخفی که هویت شما را ثابت می کند) به درخواست در هدر اضافه می کنید. شما هرگز کلید را در کد جاسازی نمی کنید. ما ذخیره سازی ایمن را در واحد 9 پوشش خواهیم داد.
- مدل و محدودیت خروجی را انتخاب کنید. مدل سبک وزن + max_tokens کوچک برای یک کار ساده. مدل قدرتمند + محدودیت بزرگتر برای یک کار پیچیده.
- لیست پیام ها را تنظیم کنید. List the system instruction, user message, and past rounds (if any).
- درخواست را ارسال کنید و پاسخ را تجزیه کنید. محتوای متنی را بخوانید، دلیل و استفاده از نشانه را از 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": "شما یک دستیار پشتیبانی شرکتی هستید. پاسخی کوتاه، رسمی و تایید شده بدهید. اطلاعاتی را که در مورد آن مطمئن نیستید ایجاد نکنید." } ]}
گفتار بی حالت است
رایجترین تصور غلط در اینجا وجود دارد: تماسهای API LLM بدون حالت هستند - سرور بین دو درخواست هیچ حافظهای را حفظ نمیکند. مدل درخواست قبلی شما را به خاطر نمی آورد. اگر در حال راهاندازی یک چت چند دور هستید، باید دورهای گذشته را با هر درخواست جدید دوباره ارسال کنید. "حافظه" مدل شامل لیستی از پیام هایی است که شما ارسال کرده اید.
{ "model": "claude-opus-4-8", "max_tokens": 512, "messages": [ { "role": "user", "content": "سلام، نام من دنیز است." }, { "role": "assistant", "content": "سلام دنیز، چگونه می توانم به شما کمک کنم؟" }, { "role": "user", "content": "من فقط اسمم را گفتم، یادت هست؟" } ]}
پاسخ صحیح به پیام سوم بستگی به ارسال هر دو پیام قبلی شما دارد. اگر ارسال نکنید، مدل دریا را نمی شناسد و اشتباه پاسخ می دهد. این نیز مستقیماً بر هزینه تأثیر می گذارد: هر چه مکالمه طولانی تر باشد، فهرست بزرگتر است، هر درخواست توکن های بیشتری مصرف می کند.
نکته: در مکالمات طولانی، خلاصه کردن و جابجایی دورهای قدیمی (خلاصه + چند دور آخر) به جای ارسال کل تاریخچه باعث کاهش هزینه و حفظ پنجره زمینه می شود. این را در واحدهای 6 و 11 تعمیق خواهیم داد.
پاسخ را بخوانید
وقتی مدل پاسخی را برمیگرداند، یک شی ساختار یافته دریافت میکنید، نه متن ساده. مناطق معمولی:
{ "id": "msg_01ABC..."، "model": "claude-opus-4-8"، "role": "assistant"، "content": [ { "type": "text", "text": "برای شروع بازگشت، به صفحه "سفارشهای من" در حساب خود بروید..." } ]_tur"، "stopage"، "stop" "input_tokens": 47، "output_tokens": 88 }}
- محتوا: خود پاسخ. این لیستی از بلوک های محتوا است. فیلد متنی بلوک متنی پاسخ واقعی است.
- stop_reason: چرا مدل متوقف شد. end_turn = پایان طبیعی; max_tokens = در حد خروجی گیر کرده است (پاسخ ممکن است ناقص باشد). امتناع = به دلایل امنیتی رد شد. کد شما همیشه باید ابتدا به stop_reason نگاه کند.
- استفاده: اعداد رمز ورودی و خروجی. اساس ردیابی هزینه و محدودیت است.
توجه: اگر stop_reason max_tokens باشد، پاسخ تکمیل نمی شود. تلقی این به عنوان یک "پاسخ موفق" و نشان دادن نیم متن به کاربر یکی از رایج ترین اشتباهات در تولید است. یا max_tokens را افزایش دهید یا از پخش جریانی استفاده کنید.
اعلان ضعیف / اعلان قوی
کار مشابه با دو دستور مختلف سیستم:
# ضعیف شما یک دستیار هستید. به سوالات پاسخ دهید.
# STRONGشما یک دستیار پشتیبانی شرکتی هستید. قوانین: - فقط به اطلاعات مندرج در سند خط مشی ارائه شده تکیه کنید. اگر در سند نیست بگویید "من این اطلاعات را ندارم، به واحد مربوطه هدایت می کنم." - پاسخ ها نباید بیش از 3 جمله باشد، رسمی و واضح باشند. - اطلاعات شخصی (شماره شناسه TC، شماره کارت) را درخواست نکنید و تکرار نکنید. - وقتی مطمئن نیستید حدس بزنید.
نسخه قدرتمند؛ محدوده، شکل، حاشیه ایمنی و رفتار در عدم قطعیت را تعریف می کند. سازگاری خروجی مدل مستقیماً از این وضوح ناشی می شود.
سه کیف کوچک
مورد 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 می توانم پاسخ کوتاه شده را متوجه شده و مدیریت کنم.