أول استدعاء إنتاجي لواجهتك البرمجية (واعٍ بالتكلفة)

🟡متوسط

استدعاء واجهة برمجية بسيط هو سطر واحد. أما الاستدعاء الإنتاجي فيعالج الأخطاء، ويتدفّق بالمخرجات، ويراقب التكلفة، ويحافظ على أمان الأسرار. لنبنِ ذلك خطوة بخطوة.

الخطوة 1 — الأسرار والنموذج من الإعدادات

export ANTHROPIC_API_KEY="sk-ant-..."   # never in source control

احتفظ بـ معرّف النموذج في الإعدادات، لا حروفاً مبعثرة، حتى تكون الترقية سهلة (لماذا). اخترْه بعناية — اختيار نموذج.

الخطوة 2 — استدعاء مرن ومُتدفّق

Python

import os, time, random, anthropic
client = anthropic.Anthropic()
MODEL = os.environ.get("CLAUDE_MODEL", "claude-sonnet-4-6")

def ask_stream(prompt, system=None, max_tokens=1024):
    for attempt in range(5):
        try:
            with client.messages.stream(
                model=MODEL, max_tokens=max_tokens,
                system=system or anthropic.NOT_GIVEN,
                messages=[{"role": "user", "content": prompt}],
            ) as stream:
                for text in stream.text_stream:
                    print(text, end="", flush=True)
                final = stream.get_final_message()
            print()
            usage = final.usage
            print(f"\n[tokens in/out: {usage.input_tokens}/{usage.output_tokens}]")
            return final
        except (anthropic.RateLimitError, anthropic.APIStatusError):
            if attempt == 4: raise
            time.sleep(min(2 ** attempt + random.random(), 30))

TypeScript

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();
const MODEL = process.env.CLAUDE_MODEL ?? "claude-sonnet-4-6";

export async function askStream(prompt: string, system?: string, maxTokens = 1024) {
  for (let attempt = 0; attempt < 5; attempt++) {
    try {
      const stream = client.messages.stream({ model: MODEL, max_tokens: maxTokens, system,
        messages: [{ role: "user", content: prompt }] });
      for await (const e of stream)
        if (e.type === "content_block_delta") process.stdout.write(e.delta.text ?? "");
      const final = await stream.finalMessage();
      console.error(`\n[tokens in/out: ${final.usage.input_tokens}/${final.usage.output_tokens}]`);
      return final;
    } catch (e: any) {
      if (attempt === 4 || ![429, 500, 529].includes(e?.status)) throw e;
      await new Promise(r => setTimeout(r, Math.min(2 ** attempt * 1000, 30000)));
    }
  }
}

الخطوة 3 — انتبه للتكلفة

• سجّل استخدام الرموز (أعلاه) حتى ترى ما يكلّفه كل استدعاء.
• اضبط حجم max_tokens والنموذج بما يناسب؛ قلّل المدخلات بمطالبات مركّزة.
• للبادئات المستقرة المتكرّرة، أضف تخزين المطالبات مؤقتاً.
• راجع الرموز والتسعير والتكلفة والكُمون.

الخطوة 4 — تعامل مع المسارات غير السعيدة

• أعِد المحاولة للأخطاء العابرة (429/5xx) بتراجع تصاعدي (أعلاه)؛ لا تُعِد المحاولة لأخطاء 400.
• تعامل مع الرفض بلطف.
• اضبط مهلة زمنية وميزانية للتكلفة/التكرار لأي شيء وكيلي.

تحقّق

شغّله: يُفترض أن ترى مخرجات متدفّقة، وسطراً يبيّن استخدام الرموز، وسلوكاً سلساً إذا أجبرت حدوث خطأ (مثلاً مفتاح خاطئ ← رسالة نظيفة، لا انهيار).

التالي

• الأخطاء وحدود المعدّل والموثوقية
• مقتطفات الواجهة البرمجية الإنتاجية
• بناء الوكلاء على الواجهة البرمجية