مهندسی سامانه‌های هوش مصنوعی · فصل ۲ — Model Selection، Serving، Cost Governor و Workflow · 138
Ollama Adapter
می‌تواند مدل یا ابزار AI را فراخوانی کند اما contract، qualification، routing، cost، trust و failure را کنترل نمی‌کند. موضوع جاری: «Ollama Adapter». می‌تواند «Ollama Adapter» را در یک workflow AI محدود طراحی کند و validation، authority، cost یا failure controls مرتبط را مشخص کند.
خلاصهٔ درس
می‌تواند مدل یا ابزار AI را فراخوانی کند اما contract، qualification، routing، cost، trust و failure را کنترل نمی‌کند. موضوع جاری: «Ollama Adapter».
می‌تواند «Ollama Adapter» را در یک workflow AI محدود طراحی کند و validation، authority، cost یا failure controls مرتبط را مشخص کند.
خروجی این درس
می‌تواند «Ollama Adapter» را در یک workflow AI محدود طراحی کند و validation، authority، cost یا failure controls مرتبط را مشخص کند.
پیش‌نیازها
1. مسئله واقعی: تعویض base URL یک Adapter تولیدی نمی‌سازد
یک gateway مستقل از provider فقط وقتی می‌تواند Ollama را سالم مصرف کند که قرارداد canonical را به semantics واقعی Ollama نگاشت کند. یک درخواست موفق روی مسیر سازگار با OpenAI فقط happy path را نشان می‌دهد؛ هنوز معلوم نیست fieldهای لازم، usage، پایان stream، خطا، provenance و capabilityهای مورد نیاز چگونه حفظ می‌شوند.
2. Adapter باید مرز domain و provider را نگه دارد
کد domain نباید با done_reason، prompt_eval_count یا شکل خطای Ollama تصمیم کسب‌وکاری بگیرد. Adapter ورودی canonical را دریافت می‌کند، capability را بررسی می‌کند، مسیر native یا compatibility را انتخاب می‌کند و فقط state نرمال‌شده به gateway برمی‌گرداند؛ raw evidence جداگانه برای audit حفظ می‌شود.
3. سطح native /api/chat را صریح مدل کن
قرارداد native فعلی می‌تواند فیلدهایی مانند model، messages، tools، format، options، stream، think و keep_alive بپذیرد. Adapter باید فقط fieldهایی را نگاشت کند که برای نسخه و runtime ثبت‌شده evidence دارد و نباید وجود یک field در docs را با پشتیبانی هر مدل یکسان فرض کند.
4. OpenAI compatibility را «بخشی» در نظر بگیر
Ollama مسیرهای سازگار با OpenAI مثل chat completions و responses را مستند می‌کند، اما خود documentation مرز را compatibility با بخش‌هایی از API می‌نامد. بنابراین mapping باید operation-by-operation و field-by-field باشد؛ نه اینکه همه رفتارهای OpenAI را به‌طور ضمنی supported فرض کند.
5. Capability map قبل از فراخوانی endpoint اجرا می‌شود
برای هر canonical requirement، record کن که capability در adapter/runtime/model fixture SUPPORTED، UNSUPPORTED یا UNKNOWN است. UNSUPPORTED و UNKNOWN نباید با حذف خاموش field یا تغییر prompt به success تبدیل شوند؛ routing باید state تایپ‌شده دریافت کند.
6. Non-stream و stream دو قرارداد terminal متفاوت دارند
در non-stream، HTTP status و body معمولاً با هم قابل ارزیابی‌اند. در stream، ممکن است چند chunk معتبر رسیده باشد و سپس یک object خطا ظاهر شود. Adapter باید partial output را provenance بداند، terminal state را failure ثبت کند و downstream را از مصرف خروجی ناقص به‌عنوان success بازدارد.
7. خطای وسط stream را به HTTP error جعلی تبدیل نکن
بعد از شروع response دیگر status HTTP قابل تغییر نیست. اگر NDJSON stream در انتها object دارای error بدهد، normalized state باید چیزی مانند STREAM_FAILED_AFTER_PARTIAL باشد و raw error و تعداد/نوع chunkهای قبلی نیز ثبت شوند.
8. Usage غایب برابر صفر نیست
مسیر native ممکن است شمارنده‌هایی مثل prompt/eval count و timing metrics بدهد، اما مسیر compatibility یا fixture دیگر ممکن است همان evidence را ندهد. فیلد غایب را UNKNOWN یا UNAVAILABLE نگه دار؛ صفر یعنی اندازه‌گیری واقعی صفر و semantics متفاوتی دارد.
9. Model identity و adapter version جزو evidence هستند
نام mutable مدل برای replay کافی نیست. record باید model identity قابل بازسازی، adapter version، API surface و mapping version را ثبت کند تا بعداً معلوم باشد یک نتیجه با کدام contract تولید شده است.
10. Worked example: یک پاسخ native سالم
فرض کن canonical chat به native /api/chat نگاشت می‌شود، capabilityهای JSON schema و non-stream در fixture پشتیبانی شده‌اند، model identity و adapter version ثبت شده‌اند و پاسخ terminal با usage/timing معتبر می‌رسد. Adapter می‌تواند PASS بدهد، اما فقط برای همان mapping و همان capability set.
11. Worked failure: 404 مدل گم‌شده
404 باید به state نرمال‌شده‌ای مثل MODEL_NOT_FOUND تبدیل شود، در حالی که HTTP status و raw error برای audit حفظ می‌شوند. Adapter حق ندارد این مورد را retry-success، empty completion یا model-selection decision تفسیر کند؛ انتخاب مدل مالک درس دیگر است.
12. Lab: هشت fixture deterministic
در Lab هشت حالت را تحلیل می‌کنی: native success، compatibility با usage ناقص، خطای وسط stream، capability پشتیبانی‌نشده، 404 مدل، provenance ناقص، mapping فرمت ناموجود و transfer با capability جدید. هدف نوشتن state machine است، نه حفظ‌کردن متن documentation.
13. ترتیب تصمیم: provenance → mapping → capability → terminal/error → usage
اول باید بدانیم کدام model/adapter/surface در حال ارزیابی است. بعد mapping و capability بررسی می‌شوند. سپس terminal/error state و در نهایت completeness usage ارزیابی می‌شود. convenience یا وجود متن خروجی نمی‌تواند gate قبلی را دور بزند.
14. Conformance evidence را از product qualification جدا کن
این درس ثابت می‌کند adapter قرارداد خودش را درست نگاشت و stateهای منفی را حفظ می‌کند؛ ثابت نمی‌کند مدل برای یک task/locale/risk کیفیت کافی دارد و route انتخابی هم درست است. آن تصمیم‌ها باید از evidence و policy درس‌های مالک خودشان بیایند.
15. Exit checklist و تمرین انتقال
قبل از خروج بررسی کن: mapping fieldها صریح است؛ capability map نسخه‌دار است؛ raw و normalized error هر دو حفظ می‌شوند؛ mid-stream failure success نمی‌شود؛ usage غایب zero نمی‌شود؛ provenance کامل است؛ و اضافه‌شدن capability جدید بدون mapping به UNSUPPORTED منتهی می‌شود. در تمرین انتقال، یک requirement تازه اضافه کن و دوباره decision را از evidence بساز.
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
Q1 retrieval
Why is changing an OpenAI client base URL to Ollama insufficient as a production adapter?
Q2 application
A canonical requirement has no declared mapping for the current Ollama model/runtime fixture. What state should routing receive?
Q3 diagnosis
A stream emits useful text and then an Ollama error object. Is the call successful?
Q4 evidence
A compatibility response omits native token/timing metrics. Should the adapter fill them with zero?
Q5 transfer
A new canonical capability is added after the old adapter passed. May the old PASS be reused automatically?
ملاک‌های ارزیابی (rubric)
PASS requires exact adapter/model/API-surface provenance, explicit canonical-to-Ollama mappings, a versioned capability map, preservation of raw plus normalized terminal/error state, correct UNKNOWN/UNAVAILABLE handling for absent usage, and deterministic conformance evidence. Unsupported capabilities, missing decisive provenance, or failed terminal state must not be coerced into success.
منابع و تازگی
مطالعهٔ موارد (case studies)
تصاویر درس
فایل‌های آزمایشگاه
Implement evaluate(case) in starter.py. Use only the supplied deterministic fixtures. Return these fields: provenance_state, mapping_state, capability_state, terminal_state, usage_state, error_state, final_decision, reason_class.
Decision discipline: provenance first; an undeclared mapping cannot pass; an unsupported/unknown required capability cannot be silently dropped; a mid-stream error is terminal failure even after partial content; missing optional usage remains unavailable rather than zero. Keep raw provider evidence separate from normalized domain state.
رسانه و اسلایدهای درس
فایل‌های آموزشی (دانلود)