فراخوانی API مدل‌ها و انتزاع ارائه‌دهنده + پروژه ۲

مدل زبانی را از راه API صدا بزن، پشت یک رابط مستقل از ارائه‌دهنده، با اعتبارسنجی خروجی و سیاست خطا؛ و پروژه ۲ را تحویل بده.

بعد از این درس می‌توانی

  • اجزای درخواست و پاسخ یک API گفتگوی مدل (پیام‌ها، مدل، قالب خروجی، مصرف توکن) را در یک تبادل واقعی تشخیص بدهد.
  • یک رابط مستقل از ارائه‌دهنده طراحی کند که تعویض ارائه‌دهنده فقط با پیکربندی یا یک آداپتور انجام شود، و محدودیت لایه‌های «سازگار» را بداند.
  • خروجی مدل را در کد اعتبارسنجی کند (شکل و یک قاعده معنایی) و برای خروجی نامعتبر مسیر روشن بگذارد.
  • پروژه ۲ را با سیاست خطا، کلید ایدمپوتنسی، لاگ بدون داده حساس و گزارش دقت و مصرف تحویل بدهد.

چرا این درس مهم است

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

مدل‌ها و ارائه‌دهنده‌ها سریع عوض می‌شوند: قیمت، دسترسی، کیفیت، شرایط استفاده. این درس یاد می‌دهد مدل را مثل یک وابستگی قابل تعویض صدا بزنی: پشت یک رابط کوچک، با خروجی‌ای که همیشه در کد بررسی می‌شود، و با همان سیاست خطای درس چهارم. در پروژه ۲ همه درس‌های این دوره کنار هم می‌آیند: HTTP، JSON، کلید، خطا و تلاش دوباره، و کلید ایدمپوتنسی.

مفاهیم کلیدی

یادآوری: خروجی ساختاریافته و JSON Schema را در درس پنجم دوره FND-102 دیدی، و انتزاع ارائه‌دهنده را به‌عنوان اصل در دوره پایه؛ اینجا آن‌ها را در کد واقعی می‌سازی.

  • Chat Completions API (API گفتگوی مدل): نقطه پایانی که فهرست پیام‌ها (سیستم، کاربر، دستیار) را می‌گیرد و پاسخ مدل را برمی‌گرداند.
  • OpenAI-compatible Endpoint (نقطه پایانی سازگار با OpenAI): نقطه پایانی ارائه‌دهنده‌ای دیگر که شکل درخواست و پاسخ OpenAI را تقلید می‌کند، معمولاً با تفاوت‌هایی.
  • Provider Abstraction (انتزاع ارائه‌دهنده): لایه‌ای که جزئیات هر ارائه‌دهنده را پنهان می‌کند تا بقیه برنامه فقط با یک رابط کار کند.
  • Adapter (آداپتور): کد کوچکی که رابط مشترک تو را به API یک ارائه‌دهنده مشخص ترجمه می‌کند.
  • Response Format (قالب پاسخ): پارامتری که از مدل خروجی JSON یا منطبق با Schema می‌خواهد، در صورتی که ارائه‌دهنده آن را اجرا کند.
  • Token Usage (مصرف توکن): تعداد توکن‌های ورودی و خروجی که ارائه‌دهنده در پاسخ گزارش می‌کند و مبنای هزینه است.

مدل ذهنی

ارائه‌دهنده مدل را مثل پیمانکار ترجمه ببین. قرارداد تو با تیم خودت ثابت است: «متن می‌دهم، JSON با این شکل می‌گیرم». پشت قرارداد، می‌توانی پیمانکار عوض کنی. ولی هر پیمانکار تازه را با همان آزمون‌ها می‌سنجی، و تحویلی‌اش را همیشه بررسی می‌کنی، حتی اگر قول داده باشد قالب را رعایت می‌کند.

معماری پروژه ۲ با رابط مستقل از ارائه‌دهنده: پیام از فایل خوانده می‌شود؛ خط لوله فقط تابع complete_json را صدا می‌زند؛ پشت آن آداپتور سازگار با OpenAI به مدل آزمایشی، Ollama محلی یا ارائه‌دهنده میزبانی‌شده وصل می‌شود؛ خروجی در کد اعتبارسنجی می‌شود؛ خروجی معتبر با کلید ایدمپوتنسی تیکت می‌شود و نامعتبر به صف انسانی می‌رود.

معماری پروژه ۲ با رابط مستقل از ارائه‌دهنده

این تشبیه کجا غلط است؟ پیمانکار انسانی اگر نتواند قالب را رعایت کند، معمولاً می‌گوید. لایه‌های سازگار گاهی بی‌صدا پارامتر را نادیده می‌گیرند: طبق مستندات Anthropic، در لایه سازگار با OpenAI پارامتر response_format نادیده گرفته می‌شود و بیشتر فیلدهای پشتیبانی‌نشده بدون خطا رد می‌شوندsrc-claude-openai-sdk-compat. یعنی «سازگار» همیشه «یکسان» نیست، و اعتبارسنجی در کد تنها تضمین تو است.

گام‌به‌گام

گام ۱: یک تبادل گفتگو با مدل

درخواست (شکل سازگار با OpenAI که مدل آزمایشی، Ollama و چند ارائه‌دهنده می‌پذیرند):

POST /v1/chat/completions
Authorization: Bearer <کلید>
Content-Type: application/json

{"model": "<نام مدل>",
 "messages": [
   {"role": "system", "content": "You classify customer messages ... Return ONLY a JSON object ..."},
   {"role": "user", "content": "<message>سفارش ۴۸۲۱۵ هنوز نرسیده</message>"}
 ]}

پاسخ (مدل آزمایشی):

{"choices": [{"message": {"role": "assistant",
   "content": "{\"category\": \"order_shipping\", \"order_id\": \"48215\", \"urgent\": false, \"summary\": \"...\", \"needs_human\": false}"},
   "finish_reason": "stop"}],
 "usage": {"prompt_tokens": 38, "completion_tokens": 53, "total_tokens": 91}}

دقت کن: JSON مورد نظر تو یک رشته داخل content است و باید جدا تجزیه شود؛ و usage مبنای برآورد هزینه است.

گام ۲: رابط کوچک، آداپتور جدا

در assets/classify_and_ticket.py فقط کلاس ChatJSONProvider جزئیات HTTP ارائه‌دهنده را می‌داند و فقط یک تابع دارد: complete_json(system, user, schema) که یک شیء و مصرف توکن برمی‌گرداند. هر چیز دیگر (خواندن پیام، اعتبارسنجی، ثبت تیکت، گزارش) فقط همین تابع را صدا می‌زند. تعویض ارائه‌دهنده:

  • اگر نقطه پایانی سازگار با OpenAI دارد: فقط سه متغیر محیطی LLM_BASE_URL، LLM_MODEL و LLM_API_KEY.
  • اگر ندارد، یا لایه سازگارش ویژگی لازم را اجرا نمی‌کند: یک آداپتور تازه با همان تابع که API بومی آن ارائه‌دهنده را صدا می‌زند.

لایه‌های سازگار برای شروع و مقایسه خوب‌اند، نه لزوماً برای تولید. Anthropic صریحاً لایه سازگارش را عمدتاً برای آزمودن و مقایسه مدل‌ها می‌داند و برای بیشتر موارد آن را راه‌حل بلندمدت یا آماده تولید نمی‌داندsrc-claude-openai-sdk-compat؛ Google هم پشتیبانی از کتابخانه‌های OpenAI را در مرحله بتا اعلام کرده استsrc-gemini-openai-compat. پس برای تولید، آداپتور بومی را جدی بگیر؛ رابط مشترک همین را ارزان می‌کند.

گام ۳: قالب پاسخ را بشناس، ولی به آن تکیه نکن

Schema پروژه همان Schema درس پنجم دوره FND-102 است (assets/ticket-schema.json).

LLM_SCHEMA_MODE می‌گوید نقطه پایانی واقعاً چه چیزی را اجرا می‌کند:

مقداریعنیکجا (مهر ۱۴۰۵)
json_schemaارائه‌دهنده خروجی را به Schema محدود می‌کندOllama از راه response_format سازگارsrc-ollama-structured-outputs؛ OpenAI با Structured Outputssrc-openai-structured-outputs
json_objectفقط JSON معتبر، نه لزوماً با Schemaحالت JSON برخی ارائه‌دهنده‌ها
noneهیچ تضمینی؛ فقط دستور در پرامپتلایه سازگار Claude (response_format نادیده گرفته می‌شود)src-claude-openai-sdk-compat؛ مدل آزمایشی

حتی با json_schema، Schema فقط شکل را تضمین می‌کند، نه درستی مقدار. برای همین تابع validate در پروژه علاوه بر شکل، یک قاعده معنایی دارد: شماره سفارش باید واقعاً در متن پیام باشد (مدل‌ها شماره می‌سازند).

گام ۴: سیاست خطا، همان درس چهارم

  • خطاهای 408، 429، 500، 502، 503، 504 و 529 (شلوغی در Claude APIsrc-claude-api-errors) و خطای شبکه: تلاش دوباره با فاصله افزایشی تصادفی، Retry-After به‌عنوان کمینه، سقف ۴ تلاش و ۶۰ ثانیه.
  • 401 و 403: توقف کل اجرا و هشدار؛ فرستادن همه پیام‌ها به صف انسانی فقط مشکل کلید را پنهان می‌کند.
  • خروجی نامعتبر: یک بار تکرار با یادآوری ایراد، بعد صف انسانی.
  • ثبت تیکت: کلید ایدمپوتنسی از شناسه پیام، تا اجرای دوباره خط لوله تیکت تکراری نسازد.

گام ۵: لاگ و گزارش

هر پیام یک خط لاگ: شناسه، تعداد تلاش، مسیر نهایی، زمان؛ بدون متن پیام. در پایان results.csv با دسته مورد انتظار و پیش‌بینی، مشکلات اعتبارسنجی، و توکن‌ها؛ و یک خلاصه: چند پیام طبقه‌بندی شد، چند درصد درست، چند پیام به صف انسانی رفت، چند توکن مصرف شد.

مثال‌ها

پیاده‌سازی عملی

پروژه ۲: ورک‌فلوی هوشمند مبتنی بر API. حدود ۵۰ دقیقه. خروجی پروژه خط لوله‌ای است که پیام‌ها را با مدل طبقه‌بندی می‌کند، خروجی را بررسی می‌کند، تیکت می‌سازد و گزارش می‌دهد؛ و ثابت می‌کنی با تعویض ارائه‌دهنده هم کار می‌کند.

  1. فایل‌های درس و دو فایل مشترک را در یک پوشه بگذار. API آزمایشی (shared/barg-sabz-mock-api.py) را با MOCK_LLM_FAIL_EVERY=4 اجرا کن (در PowerShell: $env:MOCK_LLM_FAIL_EVERY = "4" پیش از اجرا).
  2. assets/classify_and_ticket.py را بخوان: کلاس ChatJSONProvider، تابع validate، تابع with_retry و تابع create_ticket را پیدا کن و برای هرکدام یک جمله بنویس که چه درسی از این دوره را پیاده می‌کند.
  3. خط لوله را روی بیست پیام اجرا کن (پایین، بسته به مسیرت).
  4. خط لوله را روی assets/failure-test.csv اجرا کن: خروجی خراب (F02)، محدودیت نرخ پایدار (F03)، و دو پیام یکسان با شناسه متفاوت (F01 و F04). توضیح بده چرا F04 تیکت جدا گرفت و چرا این درست است.
  5. اجرای اول را دوباره اجرا کن و نشان بده تیکت تکراری ساخته نشد.
  6. LLM_API_KEY را خالی کن و اجرا کن: کل اجرا باید با پیام STOP متوقف شود.
  7. گزارش پروژه را بنویس (معیار تحویل پایین).
export LLM_BASE_URL=http://127.0.0.1:8787/v1
export LLM_MODEL=mock-model
export LLM_API_KEY=local-demo-token
python classify_and_ticket.py barg-sabz-tickets.csv ticket-schema.json
python classify_and_ticket.py failure-test.csv ticket-schema.json
بدون اجرا / شبیه‌ساز

بدون هیچ مدل واقعی: همان دستورهای بالا با مدل آزمایشی. اگر چیزی اجرا نمی‌کنی، assets/sample-run-tickets.txt، assets/sample-results-tickets.csv و assets/sample-run-failures.txt را بخوان و گزارش پروژه را از روی آن‌ها بنویس.

اجرای محلی

با Ollama و یک مدل محلی که پیش‌تر دریافت کرده‌ای:

export LLM_BASE_URL=http://localhost:11434/v1
export LLM_MODEL=<نام مدل محلی>
export LLM_SCHEMA_MODE=json_schema
unset LLM_API_KEY
python classify_and_ticket.py barg-sabz-tickets.csv ticket-schema.json

Ollama کلید را نادیده می‌گیردsrc-ollama-openai-compat و response_format با Schema را از راه لایه سازگار می‌پذیردsrc-ollama-structured-outputs. API آزمایشی هنوز باید برای ثبت تیکت در حال اجرا باشد. دقت و زمان را با اجرای مدل آزمایشی مقایسه کن؛ مدل کوچک محلی ممکن است کند یا کم‌دقت باشد، و همین یافته پروژه است.

سرویس میزبانی‌شده (در دسترس قانونی)

با ارائه‌دهنده‌ای که از نظر قانونی و طبق شرایط استفاده‌اش برای تو در دسترس است و نقطه پایانی سازگار با OpenAI دارد. نشانی پایه، نام مدل و کلید را از مستندات خود ارائه‌دهنده بردار و فقط در متغیر محیطی بگذار. LLM_SCHEMA_MODE را طبق مستندات همان ارائه‌دهنده تنظیم کن: مثلاً برای لایه سازگار Claude مقدار none، چون response_format در آن اجرا نمی‌شودsrc-claude-openai-sdk-compat. فقط داده ساختگی همین درس را بفرست. اگر ارائه‌دهنده در دسترس قانونی نداری، مسیر محلی یا آزمایشی کاملاً پذیرفته است.

بدون کد

اگر کد نمی‌نویسی، همین پروژه را در n8n یا ابزار مشابه بساز: یک گره خواندن فایل، یک گره HTTP Request به LLM_BASE_URL با بدنه گام ۱، یک گره کد یا شرط برای اعتبارسنجی (دست‌کم: دسته در فهرست مجاز، شماره سفارش در متن)، گره HTTP Request برای /tickets با هدر Idempotency-Key، و مسیر خطا به یک فایل «صف انسانی». نشانی و کلید در Credential، نه در گره.

با کد

یک آداپتور دوم بنویس که همان تابع complete_json را دارد ولی API بومی یک ارائه‌دهنده (یا API بومی /api/chat در Ollama با پارامتر format) را صدا می‌زند. خط لوله نباید تغییری کند؛ فقط انتخاب کلاس.

معیار تحویل پروژه (شش معیار قرارداد سنجش، هرکدام ۰ تا ۲): مسیر اصلی قابل بازتولید است (دستورها و متغیرها در گزارش آمده‌اند)؛ حالت‌های شکست آزموده شده‌اند (خروجی خراب، 429 پایدار، کلید نامعتبر، اجرای دوباره)؛ مرز داده رعایت شده است (فقط داده ساختگی، لاگ بدون متن پیام، کلید فقط در محیط)؛ برآورد هزینه یک خطی دارد (توکن کل اجرا و برآورد ماهانه برای حجم واقعی فرضی)؛ سند تصمیم دلیل انتخاب ارائه‌دهنده و LLM_SCHEMA_MODE را می‌گوید؛ و شاهد بررسی (results.csv و خلاصه دقت) وجود دارد.

اشتباه‌های رایج

اشتباهنتیجهکار درست
نام مدل و نشانی در کدتعویض ارائه‌دهنده یعنی تغییر کدپیکربندی در محیط یا Credential
فرض اینکه «سازگار» یعنی «یکسان»پارامتر کلیدی بی‌صدا نادیده گرفته می‌شودمستندات تفاوت‌ها را بخوان؛ اعتبارسنجی در کد
اعتماد به Schema برای درستی مقدارشماره سفارش ساختگی یا دسته غلط ولی معتبرقاعده معنایی و مجموعه آزمون
همه پیام‌ها به صف انسانی هنگام 401مشکل کلید ساعت‌ها پنهان می‌ماندتوقف کل اجرا و هشدار
کلید ایدمپوتنسی از زمان یا عدد تصادفیاجرای دوباره تیکت تکراری می‌سازداز شناسه پیام
لاگ متن پیام برای اشکال‌زداییداده مشتری در لاگشناسه و نتیجه
مقایسه ارائه‌دهنده‌ها با یکی دو پیامتصمیم بر اساس شانسهمان مجموعه آزمون برای همه

اشکال‌زدایی

بسیاری از پاسخ‌ها با «content is not JSON» به صف انسانی می‌روند.

مدل JSON را داخل متن توضیحی یا بلوک کد گذاشته، یا ارائه‌دهنده response_format را اجرا نمی‌کند.

چند content خام را (روی داده ساختگی) ببین؛ مستندات ارائه‌دهنده را برای پشتیبانی response_format بخوان.

LLM_SCHEMA_MODE را با توان واقعی ارائه‌دهنده هم‌خوان کن؛ اگر پشتیبانی نمی‌شود، آداپتور بومی با خروجی ساختاریافته، یا دستور روشن‌تر با یک مثال.

پس از تعویض ارائه‌دهنده، دقت از ۸۵ درصد به ۶۰ درصد افتاد، بدون هیچ خطای اجرایی.

پرامپت برای مدل قبلی تنظیم شده بود؛ یا قالب پیام سیستمی در لایه سازگار جابه‌جا می‌شود (مثلاً در Claude پیام‌های سیستمی به ابتدای گفتگو منتقل و به هم چسبانده می‌شوندsrc-claude-openai-sdk-compat).

results.csv دو اجرا را کنار هم بگذار؛ ببین کدام دسته‌ها بیشتر خراب شده‌اند.

پرامپت را برای مدل تازه با همان مجموعه آزمون تنظیم کن؛ تعویض ارائه‌دهنده یک «نسخه تازه» با آزمون رگرسیون است.

اجرا روی صد پیام نیمه‌کاره می‌ماند و چند پیام پس از چهار تلاش به صف می‌روند.

فراخوانی‌ها سریع‌تر از سقف نرخ حساب هستند؛ تلاش‌های دوباره هم در سقف شمرده می‌شوند.

زمان و نتیجه تلاش‌ها را در لاگ ببین؛ اگر Retry-After آمده، مقدارش را.

فاصله ثابت بین پیام‌ها یا سقف هم‌زمانی؛ برای کار دسته‌ای بزرگ، سرویس دسته‌ای ارائه‌دهنده را بررسی کن.

نکته‌های امنیتی

نکته‌های هزینه

تمرین کوتاه

تمرین · 10 دقیقه

هدف: تشخیص آنچه با تعویض ارائه‌دهنده عوض می‌شود.

گام‌ها: تیم می‌خواهد پروژه را از مدل محلی Ollama (با json_schema) به لایه سازگار OpenAI در Claude ببرد. فهرست کن: (الف) چه چیزهایی فقط با متغیر محیطی عوض می‌شوند؛ (ب) چه چیزی باید در تنظیم عوض شود چون رفتار ارائه‌دهنده فرق دارد؛ (ج) چه آزمونی پیش از استفاده لازم است.

معیار پذیرش: (الف) نشانی، مدل، کلید؛ (ب) LLM_SCHEMA_MODE به none چون response_format نادیده گرفته می‌شود؛ (ج) اجرای کامل مجموعه آزمون و مقایسه با نتیجه قبلی.

راه‌حل نمونه

(الف) LLM_BASE_URL، LLM_MODEL، LLM_API_KEY. (ب) LLM_SCHEMA_MODE=none، چون در لایه سازگار Claude پارامتر response_format اجرا نمی‌شود و اعتبارسنجی در کد تنها تضمین است؛ اگر تضمین Schema لازم است، آداپتور بومی با خروجی ساختاریافته. (ج) اجرای کل barg-sabz-tickets.csv و failure-test.csv، مقایسه results.csv با اجرای قبلی، و بررسی رگرسیون مورد به مورد.

چالش

تمرین · 45 دقیقه

موقعیت: گامی از طرح خودکارسازی کار خودت که به مدل زبانی نیاز دارد (طبقه‌بندی، استخراج، خلاصه) را با همین خط لوله بساز. داده‌ات را ساختگی یا ناشناس کن.

  1. Schema خروجی خودت را بنویس و یک قاعده معنایی برای آن (مثل «هر عدد استخراج‌شده در متن هست»).
  2. ده نمونه ساختگی یا ناشناس با پاسخ مورد انتظار بساز، شامل دست‌کم دو مورد لبه.
  3. classify_and_ticket.py را (یا معادل بدون کدش را) برای کار خودت تطبیق بده: پرامپت سیستمی، Schema، تابع validate و اقدام پس از خروجی معتبر.
  4. دست‌کم با دو مسیر اجرا کن (مثلاً آزمایشی و محلی، یا محلی و میزبانی‌شده) و نتیجه‌ها را مقایسه کن.

خروجی مورد انتظار: Schema و قاعده معنایی، مجموعه آزمون ده‌موردی، کد یا ورک‌فلوی تطبیق‌یافته، و جدول مقایسه دو اجرا با دقت، تعداد صف انسانی و توکن.

معیار پذیرش:

  • تعویض مسیر فقط با پیکربندی یا یک آداپتور جدا انجام شده است.
  • خروجی در کد اعتبارسنجی می‌شود و نامعتبر به مسیر روشن می‌رود.
  • 401 یا 403 کل اجرا را متوقف می‌کند؛ خطای قابل تکرار با سقف تکرار می‌شود.
  • هیچ داده واقعی حساس یا کلیدی در فایل‌ها و لاگ نیست.

پرسش‌های سنجش

جمع‌بندی

  • API گفتگوی مدل پیام‌ها را می‌گیرد و پاسخ را در content (رشته) با usage برمی‌گرداند.
  • مدل را پشت یک رابط کوچک صدا بزن؛ تعویض ارائه‌دهنده یعنی پیکربندی یا یک آداپتور، نه بازنویسی.
  • «سازگار با OpenAI» یکسان نیست؛ لایه‌ها پارامترها را گاهی بی‌صدا نادیده می‌گیرند و برای تولید، آداپتور بومی را جدی بگیر.
  • خروجی را همیشه در کد اعتبارسنجی کن: شکل و دست‌کم یک قاعده معنایی.
  • 401 و 403 یعنی توقف؛ 429 و 5xx یعنی تکرار محدود؛ خروجی نامعتبر یعنی یک تکرار و بعد صف انسانی.
  • کلید ایدمپوتنسی از شناسه کار؛ لاگ بدون متن و کلید؛ هزینه از usage.

پرسش‌های سنجش

در این پاسخ API گفتگو، (الف) خروجی JSON مورد نظر کجاست و چه نوعی دارد؛ (ب) کدام فیلد برای برآورد هزینه به کار می‌رود؛ (ج) کدام فیلد می‌گوید پاسخ به‌طور عادی تمام شده است؟

پاسخ ساختگی از مدل آزمایشی.

{"id": "chatcmpl-mock-1", "object": "chat.completion", "model": "mock-model",
 "choices": [{"index": 0, "message": {"role": "assistant",
   "content": "{\"category\": \"payment\", \"order_id\": null, \"urgent\": true, \"summary\": \"دو برداشت\", \"needs_human\": true}"},
   "finish_reason": "stop"}],
 "usage": {"prompt_tokens": 41, "completion_tokens": 37, "total_tokens": 78}}
پاسخ نمونه و معیار ارزیابی

(الف) در choices[0].message.content و از نوع رشته است؛ باید جدا با تجزیه JSON به شیء تبدیل شود. (ب) usage (prompt_tokens و completion_tokens). (ج) finish_reason برابر stop.

  • content را رشته‌ای می‌داند که باید تجزیه شود (1 امتیاز)
  • usage برای هزینه (1 امتیاز)
  • finish_reason (1 امتیاز)
  • content خودش شیء است ← در شکل سازگار با OpenAI، content رشته است؛ JSON داخل آن.

تیم می‌خواهد برای سرعت، کل پروژه را فقط با لایه سازگار OpenAI یک ارائه‌دهنده دیگر اجرا کند و آداپتور بومی ننویسد. مزیت و هزینه این تصمیم را بنویس و بگو کی آداپتور بومی را لازم می‌دانی.

پاسخ نمونه و معیار ارزیابی

مزیت: تعویض فقط با پیکربندی، کد کمتر، مقایسه سریع چند ارائه‌دهنده. هزینه: برخی پارامترها بی‌صدا نادیده گرفته می‌شوند (مثلاً response_format در لایه سازگار Claude)، برخی ویژگی‌ها در دسترس نیستند، و برخی لایه‌ها بتا یا مخصوص آزمودن‌اند. آداپتور بومی لازم است وقتی به ویژگی‌ای که لایه اجرا نمی‌کند نیاز داری (مثل تضمین Schema)، یا برای تولید طولانی‌مدت روی ارائه‌دهنده‌ای که لایه سازگارش را آماده تولید نمی‌داند. رابط مشترک همین تصمیم را ارزان و برگشت‌پذیر می‌کند.

  • یک مزیت مشخص (1 امتیاز)
  • نادیده‌گرفتن بی‌صدا یا وضعیت بتا و آزمایشی (1 امتیاز)
  • شرط روشن برای آداپتور بومی (1 امتیاز)
  • سازگار یعنی همه چیز یکسان است ← مستندات خود ارائه‌دهنده‌ها تفاوت‌ها را فهرست کرده‌اند.

با Schema سخت‌گیر، همه خروجی‌ها از نظر شکل معتبرند؛ ولی در بررسی دستی، برای پیام «سلام، پرداخت کردم ولی تأیید نیومد» مقدار order_id برابر "10482" است. چه شده و چطور جلویش را می‌گیری؟

پاسخ نمونه و معیار ارزیابی

مدل شماره سفارش ساخته است (پیام شماره‌ای ندارد). Schema فقط نوع رشته یا null را تضمین می‌کند، نه درستی مقدار. جلوگیری: قاعده معنایی در کد که بررسی کند order_id عیناً (با یکسان‌سازی رقم فارسی و لاتین) در متن پیام هست؛ وگرنه آن را null یا خروجی را نامعتبر بدان. و این مورد را به مجموعه آزمون اضافه کن.

  • ساختن مقدار توسط مدل را تشخیص می‌دهد (1 امتیاز)
  • Schema درستی مقدار را تضمین نمی‌کند (1 امتیاز)
  • قاعده معنایی بررسی وجود در متن (1 امتیاز)
  • Schema را سخت‌تر کن ← هیچ Schema‌ای نمی‌داند عدد در متن بوده یا نه؛ این بررسی کار کد است.

خط لوله برای اولین پیام 401 از ارائه‌دهنده مدل می‌گیرد. بهترین رفتار کدام است؟

  • چهار بار با فاصله افزایشی تکرار و بعد صف انسانی، برای هر پیام.
  • توقف کل اجرا و هشدار درباره کلید یا اختیار.
  • رفتن به پیام بعدی و ادامه اجرا.
  • تعویض خودکار به ارائه‌دهنده دیگر.
پاسخ نمونه و معیار ارزیابی
  • a ← 401 قابل تکرار نیست.
  • c ← پیام بعدی هم همان کلید را دارد.
  • d ← تعویض خودکار ارائه‌دهنده بدون آزمون، کیفیت و قواعد داده را بی‌صدا عوض می‌کند؛ تصمیمی برای انسان است.

پس از اجرای پروژه روی ۲۰ پیام، مصرف کل ۱۹۰۰ توکن گزارش شده است. برگ سبز ماهانه حدود ۳۰۰۰ پیام دارد. چطور هزینه ماهانه را برآورد می‌کنی و چه چیزهایی را باید جداگانه حساب کنی؟

پاسخ نمونه و معیار ارزیابی

میانگین حدود ۹۵ توکن برای هر پیام × ۳۰۰۰ ≈ ۲۸۵ هزار توکن در ماه؛ ولی ورودی و خروجی را جدا حساب کن چون قیمتشان فرق دارد، و قیمت را از صفحه قیمت همان ارائه‌دهنده با تاریخ بردار. جداگانه: تلاش‌های دوباره و تکرار پس از خروجی نامعتبر، تفاوت توکن‌شمار مدل‌ها (عدد مدل آزمایشی تقریبی است)، و زمان بازبینی انسانی پیام‌های صف.

  • ضرب میانگین در حجم ماهانه (1 امتیاز)
  • جدا کردن ورودی و خروجی و قیمت تاریخ‌دار (1 امتیاز)
  • تلاش دوباره یا بازبینی انسانی یا تفاوت توکن‌شمار (1 امتیاز)
  • عدد مدل آزمایشی همان هزینه واقعی است ← مدل آزمایشی توکن را تقریبی گزارش می‌کند؛ با مدل واقعی دوباره بسنج.

فایل‌های درس

API آزمایشی با نقطه ثبت تیکت و مدل آزمایشی سازگار با OpenAI

barg-sabz-mock-api.py

بیست پیام پشتیبانی ساختگی با دسته مورد انتظار

barg-sabz-tickets.csv

خط لوله پروژه ۲ با رابط مستقل از ارائه‌دهنده

classify_and_ticket.py

Schema خروجی طبقه‌بندی (همان درس پنجم دوره FND-102)

ticket-schema.json

چهار پیام برای آزمودن خروجی خراب، محدودیت نرخ و تکرار

failure-test.csv

خروجی نمونه اجرا روی بیست پیام با مدل آزمایشی

sample-run-tickets.txt

جدول نتیجه نمونه برای مسیر بدون اجرا

sample-results-tickets.csv

خروجی نمونه آزمون شکست

sample-run-failures.txt

ابزارها و جایگزین‌ها

  • Python 3.9 یا بالاتر — اجرای پروژه و API آزمایشی — مسیر بدون اجرا با نتیجه‌های نمونه

منابع

OpenAI SDK compatibility Anthropic accessed 2026-10-16

OpenAI compatibility Google AI for Developers accessed 2026-10-16

Structured outputs Ollama docs 2026-10

Structured model outputs OpenAI docs 2026-10

Claude API errors Anthropic accessed 2026-10-16

OpenAI compatibility Ollama Responses non-stateful since v0.13.3

دوره

زبان مشترک نرم‌افزارها: HTTP، JSON و API