درس ۱۱ از ۱۱

Module 11

عنوان اصلی: Final Assessment + Wrap-up هدف یادگیری: synthesize کردن همه‌ی ۱۰ ماژول قبل در یک اپلیکیشن production-ready؛ یادگیری چک‌لیست عملی production. مفاهیم کلیدی: end-to-end application, eval harness, prompt caching, RAG + tools + agents, MCP integration, cost monitoring, observability, production checklist.

۱۱.۱ Capstone — اپلیکیشن انتهایی

ایده‌ی capstone این دوره: یک اپ خدمات مشتری فارسی بسازید که همه قابلیت‌های فصل را به‌کار بگیرد:

  1. Routing بر اساس intent (FAQ، refund، product، escalate).
  2. Retrieval با contextual + hybrid + rerank.
  3. Tool use برای refund و lookup.
  4. Prompt caching روی system prompt و KB.
  5. Citations در پاسخ‌های متکی به سند.
  6. Evaluation harness خودکار در CI.
  7. MCP wrapper تا اپ شما داخل Claude Desktop هم قابل استفاده باشد.
  8. multi-tenant safety: metadata.user_id در هر request.
  9. observability: log کامل با prompt version و dataset hash.

اسکلت فشرده:

import anthropic, voyageai
client = anthropic.Anthropic(); vo = voyageai.Client()

def end_to_end_assistant(user_msg, tenant_id, history):
    # 1. Route
    intent = client.messages.create(
        model="claude-haiku-4-5", max_tokens=8, temperature=0,
        messages=[{"role": "user", "content":
            f"Classify: {user_msg}\nReply: faq, refund, product, escalate."}],
    ).content[0].text.strip()
    if intent == "escalate": return handoff_to_human(user_msg)

    # 2. Retrieve (contextual + hybrid + rerank)
    candidates = hybrid_retrieve(user_msg, tenant_id, k=50)
    chunks = rerank(user_msg, candidates, k=8)
    context = "\n\n".join(f"<chunk source='{c.source}'>{c.text}</chunk>" for c in chunks)

    # 3. Generate, with caching, citations, tool use
    history.append({"role": "user", "content": [
        {"type": "text", "text": f"<context>\n{context}\n</context>\n\nUser: {user_msg}"},
    ]})
    return client.messages.create(
        model="claude-opus-4-8", max_tokens=2048,
        metadata={"user_id": f"tenant_{tenant_id}"},
        system=[
            {"type": "text", "text": "You are a Persian customer-service assistant."},
            {"type": "text", "text": LONG_BRAND_GUIDE,
             "cache_control": {"type": "ephemeral", "ttl": "1h"}},
        ],
        tools=REFUND_AND_LOOKUP_TOOLS,
        messages=history,
    )

این ۳۰ خط کد، اگر با eval harness و prompt caching درست همراه شود، یک سرویس واقعی است که می‌توانید روی آن SLA بدهید.

۱۱.۲ Production Checklist (۱۲ نکته)

این چک‌لیست مهم‌ترین دستاورد کل فصل ۴ است. آن را نزدیک دست خود نگه دارید — قبل از هر deployment آن را مرور کنید.

۱. Pin model snapshots

از alias مانند claude-opus-latest در production استفاده نکنید. snapshot دقیق pin کنید: claude-opus-4-8، claude-sonnet-5، claude-haiku-4-5. این کار شما را در برابر تغییرات رفتاری خاموش (silent behavioral drift) محافظت می‌کند. ارتقاء مدل را همیشه با eval pipeline قبل از merge آزمایش کنید.

۲. Define success criteria + eval set

پیش از iterate کردن روی prompt، معیار موفقیت را به‌صورت قابل اندازه‌گیری بنویسید: «دقت classification ≥ ۹۰٪ روی dataset X»، «median answer relevance score ≥ ۴/۵ از judge LLM»، «هیچ refusal روی topic های مجاز». بعد یک eval set ۲۰–۵۰ نمونه‌ای بسازید و قبل از تغییر prompt، eval قبلی را record کنید.

۳. Set max_tokens generously, but cap aggregate spend

max_tokens در سطح request را سخاوتمندانه بگذارید (مدل را قطع نکنید مگر برای جلوگیری از فاجعه). اما در سطح workspace یک سقف کلی هزینه روزانه/هفتگی بگذارید (در Console). در کد agent loop، token budget tracking داشته باشید (مثل نمونه‌ی Module 10.4).

۴. Model tiering — Haiku / Sonnet / Opus

از Haiku برای task های ساده (classification، routing، short rewrite) استفاده کنید. Opus را برای استدلال سخت (تحلیل قرارداد، debug کد، تصمیم بزرگ). Sonnet را برای کار میانی، و Fable 5 را فقط برای سخت‌ترین موارد که بالاترین سطح توانایی را می‌خواهند. این یک کاهش هزینه‌ی ۵–۲۰ برابری است که فقط با چند خط تغییر کد به دست می‌آید.

۵. Prompt caching

هر چیز ≥ ۱ MTok که در request های متعدد تکرار می‌شود (KB، long system prompt، tool definitions، documents) را با cache_control کش کنید. TTL مناسب انتخاب کنید: tool ها → 1h، system → ephemeral (5m)، session → ephemeral. متریک cache_read_input_tokens / total_input_tokens را در dashboard ببینید — هدف ≥ ۸۰٪ hit rate.

۶. Stop reason handling

هر stop_reason را handle کنید:

  • end_turn → پاسخ کامل است.
  • tool_use → برو tool را اجرا کن و turn بعدی را بفرست.
  • max_tokens → پاسخ بریده شده. یا continue کنید (مثل multi-turn) یا ارور بدهید.
  • stop_sequence → پاسخ به یک stop sequence رسید (انتظار شما بوده).
  • refusal → مدل به دلایل safety رد کرد. به user به‌درستی نشان دهید.
  • pause_turn → agentic stops برای بعضی tool ها (مثل long-running tasks). turn را با همان history ادامه دهید.

اگر فقط end_turn را handle می‌کنید، بقیه‌ی موارد به‌صورت bug سکوت می‌کنند.

۷. metadata.user_id

در هر request multi-tenant، metadata={"user_id": "tenant_abc"} بگذارید. این کار به Anthropic کمک می‌کند rate limit و abuse detection را per-tenant انجام دهد، و در تحقیقات حادثه به شما کمک می‌کند مشخص کنید کدام tenant مشکل دارد. حتی برای پروژه‌های single-tenant ولی multi-user (مثل یک اپ موبایل با هزاران user)، این فیلد را پر کنید.

۸. Agent loop ceilings

روی هر agent loop سه سقف سخت بگذارید:

  • max_iter (مثلاً ۲۰ iteration).
  • max_tokens aggregate (مثلاً ۲۰۰K token).
  • max_wall_clock (مثلاً ۵ دقیقه).

اگر هر کدام نقض شد، با RuntimeError یا alert خاص exit کنید. حتی الگویی که در test ها بی‌نقص است، در production یک edge case پیدا می‌کند که می‌تواند تا بی‌نهایت loop بزند.

۹. Display citations

اگر API output شما به user نهایی نشان داده می‌شود و از سند استناد می‌کند، citation ها را نمایش دهید. این اعتماد را به شکل قابل توجهی بالا می‌برد، و وقتی پاسخی اشتباه باشد، user می‌تواند سند را خودش چک کند. در فصل ۷.۴ دیدیم که cited_text رایگان است — استفاده نکردن از آن ضرر است.

۱۰. Sandbox computer use و bash tools

computer_20251124 و bash_20250124 همیشه باید در یک Docker container یا VM ایزوله اجرا شوند. هرگز روی host. credentials production را در environment آن sandbox نگذارید. برای action های consequential (delete، transfer مالی، send email خارج از سازمان) human-in-the-loop confirmation بگذارید.

۱۱. Request logging

هر request را با این فیلدها log کنید:

  • prompt_version (یک رشته‌ی semver یا git hash که prompt را شناسایی می‌کند).
  • model (snapshot دقیق).
  • tools_hash (hash از تعریف tool ها).
  • dataset_hash (اگر RAG دارید، hash از dataset version).
  • tenant_id, request_id, latency_ms, usage (input/output/cache token).
  • stop_reason.

این logging به شما اجازه می‌دهد یک ماه بعد بفهمید که regression از prompt آمده یا از مدل یا از dataset.

۱۲. CI eval gating

eval harness شما باید روی هر تغییر prompt یا model خودکار اجرا شود (CI). اگر دقت زیر threshold بیاید، PR merge نشود. این تنها روش معتبر برای جلوگیری از regression های خاموش در LLM-driven systems است. بدون این، شما یا hand-test می‌کنید (که scale نمی‌خورد) یا production می‌فرستید و امیدوارید (که دیر یا زود می‌سوزد).

۱۱.۳ یک یادآوری نهایی از مقاله‌ی Anthropic

شعار محوری مقاله‌ی Building Effective Agents این است: سیستم درست را بسازید، نه پیچیده‌ترین سیستم را. ۹۰ درصد از قابلیت‌های AI تولیدی فقط نیاز دارند به:

  • یک Messages call.
  • prompt engineering خوب.
  • چند tool.
  • prompt caching.

نه multi-agent swarm. نه orchestrator-worker. نه autonomous agent. اگر workflow ساده eval شما را pass می‌کند، متوقف شوید. هر لایه‌ی پیچیدگی یک دلیل برای failure در production می‌سازد.

خلاصه‌ی کامل فصل ۴ — یک نگاه به ۱۱ ماژول

این مرور سریع کل فصل ۴ است (۱۱ ماژول، که در دو بخش بررسی شد):

  1. Introduction. Claude API چیست، تفاوت با Claude.ai، چرا برای production مهم است.
  2. Accessing Claude with the API. Authentication با ANTHROPIC_API_KEY، اولین Messages call، system prompt، max_tokens، sampling params (فقط مدل‌های قدیمی‌تر)، stop sequences، structured outputs، streaming، multi-turn.
  3. Prompt Evaluation. eval set، LLM-as-judge، Batch API، embedding similarity، CI integration.
  4. Prompt Engineering Techniques. clear and direct، XML tags، examples (few-shot)، chain-of-thought، role/persona (prefilling روی مدل‌های فعلی حذف شده؛ جایگزین: structured outputs).
  5. Tool Use. تعریف tool، agent loop، tool_choice، parallel tools، structured output via tools.
  6. RAG and Agentic Search. BM25 vs embeddings، hybrid search، contextual retrieval، reranking با Voyage، agentic retrieval.
  7. Features of Claude. extended thinking (adaptive + مسیر legacy)، image input، PDF input، citations، prompt caching (rules + practice)، Files API، code execution.
  8. Model Context Protocol. مرور سریع — جزئیات در فصل ۵.
  9. Anthropic Apps. Claude Code (CLI)، Computer Use (GUI agent در sandbox).
  10. Agents and Workflows. parallelization، chaining، routing، agents vs workflows، evaluator-optimizer، orchestrator-workers.
  11. Final Assessment. capstone end-to-end + production checklist ۱۲-نکته‌ای.

سه واقعیت که اگر هیچ چیز دیگری از این فصل به یاد نگه ندارید، اینها را نگه دارید:

  • eval قبل از prompt iteration. بدون eval، شما کور بهینه می‌کنید.
  • با prompt ساده شروع کنید، بعد caching، بعد tool ها، بعد agent — اگر eval اصرار کرد.
  • هر stop_reason را handle کنید، هر agent loop را cap کنید، هر prompt را version بزنید.

تمرین‌های پیشنهادی

این تمرین‌ها به ترتیب از ساده به پیچیده هستند. هدف، تثبیت مفاهیم Module 7–11 است.

  1. Extended thinking benchmark. سه سوال ریاضی Olympiad (یا حقوقی پیچیده) انتخاب کنید. هر کدام را سه بار اجرا کنید: (الف) با Sonnet 4.6 بدون thinking، (ب) با Sonnet 4.6 + budget_tokens=10000 (مسیر legacy)، (ج) با Opus 4.8 (adaptive). دقت پاسخ‌ها و هزینه‌ی هر کدام را مقایسه کنید. کدام بهترین cost/quality است؟

  2. Vision OCR مقایسه‌ای. ۱۰ فاکتور فارسی scan شده را به Claude بدهید (با Tesseract یک baseline OCR هم بسازید). از Claude بخواهید vendor، total، تاریخ Jalali و VAT را extract کند. خروجی JSON بگیرید. accuracy هر دو روش را روی همین ۱۰ فاکتور اندازه بگیرید.

  3. PDF + citations روی قرارداد. یک قرارداد ۲۰ صفحه‌ای انگلیسی (یا فارسی OCR شده) را با citations.enabled = true بفرستید. ۵ سوال بپرسید (limit liability، term length، indemnification، governing law، termination). برای هر سوال، citation برگشتی را با متن واقعی قرارداد چک کنید — درست استناد می‌کند؟

  4. Prompt caching ROI. یک system prompt ۵۰K-token‌ای بسازید. ۱۰۰ سوال متفاوت روی همین system بپرسید: یک بار بدون caching، یک بار با cache_control ephemeral. هزینه‌ی کل و latency متوسط را مقایسه کنید. درصد cache hit rate را گزارش کنید.

  5. Files API + code execution. یک CSV فروش (یا داده‌ی واقعی sales-report Pippa) upload کنید. از Claude با code_execution بخواهید: (الف) درآمد ماهانه per category، (ب) top 5 SKU، (ج) trend (نمودار). خروجی نمودار را ذخیره کنید.

  6. Routing chatbot. یک router با Haiku بسازید که intent ها را به ۴ دسته (FAQ، refund، technical، escalate) classify کند. برای هر intent یک handler با Opus بنویسید. روی ۲۰ پیام نمونه eval کنید. accuracy classifier را اندازه بگیرید.

  7. Chaining email writer. یک pipeline سه‌مرحله‌ای: outline (Haiku) → draft (Opus) → polish (Haiku). آن را برای ۵ موضوع مختلف اجرا کنید. خروجی نهایی را با یک baseline single-call Opus مقایسه کنید — کیفیت کجا بهتر است؟ هزینه؟

  8. Evaluator-optimizer روی پاسخ فنی. یک سوال فنی (مثلاً «Postgres را چگونه برای write-heavy tune کنیم؟») بپرسید. evaluator-optimizer با ۳ round پیاده کنید. هر round، نقدها و revisions را log کنید. آیا کیفیت round به round واقعاً بهتر می‌شود یا plateau می‌زند؟

  9. Agent با ceilings. یک agent ساده بسازید با tool های read_file, write_file, run_shell. هدف: «فایل‌های .py در یک پوشه را linter (ruff) با آن اجرا کن و خطاها را report کن». سقف‌های ۲۰ iteration و ۱۰۰K token را اعمال کنید. Test کنید که سقف‌ها واقعاً اعمال می‌شوند (با شبیه‌سازی tool هایی که ناتمام برمی‌گردانند).

  10. Capstone end-to-end. اپ Module 11 را پیاده کنید: routing + RAG + tool use + caching + citations + eval + logging. آن را روی ۲۰ سوال واقعی customer-service فارسی eval کنید. dashboard ساده‌ای بسازید که cache hit rate، median latency، per-tenant cost را نمایش دهد.

منابع تکمیلی

مستندات رسمی Anthropic

مقالات engineering و research

Open source

پروتکل MCP

ارجاع متقابل به فصل‌های دیگر

  • فصل ۳ — Claude Code: راه‌اندازی، slash command ها، subagent ها، skills، plan mode.
  • فصل ۵ — Model Context Protocol: ساخت server با @mcp.tool()، client سفارشی، resource ها، prompt ها، transport ها، MCP Inspector.
  • فصل ۶ — Cloud (Bedrock + Vertex): تفاوت Anthropic API مستقیم با AWS Bedrock و Google Vertex AI، Converse API، Guardrails، IAM.

این پایان فصل ۴ است. در فصل ۵ به سراغ Model Context Protocol می‌رویم — یعنی پروتکلی که در ماژول ۸ این فصل خیلی کوتاه مرور کردیم. اگر قصد ساخت یک MCP server دارید، فصل ۵ پیش‌نیاز شماست.