Tokens للمبتدئ: ازاي تحسب تكلفة Claude API قبل ما تبعت أول request

لو بتحضّر تربط أول شات بوت بـ Claude وخايف الفاتورة تيجي مفاجأة، خد رقم: سؤال عربي بـ 40 كلمة بيكلّفك أكتر من سؤال إنجليزي بنفس المعنى بحوالي 2.4 ضعف على نفس النموذج. مش لأن العربية أصعب على النموذج، لكن لأن الـ tokenizer بيقطّعها لقطع أكتر. لو فهمت ازاي الـ tokens بتتحسب، تقدر تتوقّع فاتورة الشهر بفرق ±8% قبل ما تبعت request واحد.

المشكلة باختصار

الـ APIs بتاعت LLMs (Claude, GPT, Gemini) كلها بتفوتر بالـ tokens مش بالكلمات. والـ tokens مش حروف ولا كلمات، هي وحدات وسط بين الاتنين. ده اللي بيخلّي أي محاولة تحسب التكلفة بـ "متوسط 5 حروف للكلمة" تطلع غلط بنسبة 40–300%، خصوصاً على نصوص عربية وكود برمجي.

النتيجة العملية: مطوّر بيبني MVP بميزانية $50 للشهر، بيلاقي نفسه دفع $180 في 18 يوم، فبيوقّف المشروع. والسبب الحقيقي إنه ما حسبش الـ system prompt اللي بيتبعت مع كل رسالة، ولا فرّق بين سعر input وسعر output.

أول، اتفرّج على مثال بسيط جداً (مثال محل العصير)

تخيّل إنك دخلت محل عصير، والمحل ده مالوش قائمة أسعار بالعصير الجاهز. عنده قائمة بأسعار المكونات:

• كل قطعة برتقال: 2 جنيه
• كل قطعة جزر: 1.5 جنيه
• السكر: 0.5 جنيه للملعقة

لما تطلب "كوباية برتقال متوسطة"، البائع بيقطّعها لمكوناتها: 4 برتقالات + ملعقة سكر = 8.5 جنيه. لو طلبت "كوكتيل كبير" نفس البائع بيقطّعه: 3 برتقال + 4 جزر + ملعقتين سكر = 13 جنيه. انت طلبت بالكوب، هو حسبلك بالمكون.

الـ Claude API نفس الفكرة بالظبط. انت بتبعت "جملة"، هو بيقطّعها لـ tokens (المكونات)، وبيحسب فاتورتك على عدد المكونات مش طول الجملة. الفرق إن أسعار "المكونات" بتختلف حسب اللغة وحسب نوع النص (كود، نص طبيعي، أرقام).

التعريف العلمي الدقيق: ما هو الـ Token؟

الـ Token هو أصغر وحدة معالجة بيشتغل عليها النموذج. مش حرف، ومش كلمة. هي قطعة بين الاتنين بتطلع من خوارزمية اسمها Byte-Pair Encoding (BPE) — اتنشرت في ورقة Sennrich 2016 وبتستخدمها كل النماذج التجارية حالياً مع تعديلات.

BPE بتبص على مليارات الجمل في بيانات التدريب، وبتجمع أكتر زوج حروف ظهر مع بعض، وبتحوّله لـ token واحد. تعيد العملية لحد ما توصل لحجم قاموس محدد (عادة 100k لـ 200k token). النتيجة: الكلمات الشائعة بتبقى token واحد، والكلمات النادرة بتتقسّم لقطع أصغر.

مثال محسوس على Claude tokenizer (مبني على cl100k العائلة):

• "hello" → ["hello"] = 1 token
• "unhappy" → ["un", "happy"] = 2 tokens
• "مرحبا" → ["م", "ر", "ح", "با"] ≈ 4–5 tokens
• "تشغيل" → ["تش", "غيل"] ≈ 2–3 tokens

السبب إن العربية مش موجودة بكثافة كافية في بيانات تدريب الـ tokenizer (الغالبية إنجليزية + كود). فالكلمات العربية بتتقسّم لقطع أكتر. متوسط 2.4 token لكل كلمة عربية مقابل 1.3 token لكل كلمة إنجليزية، حسب دراسة Petrov 2023 "All Languages Are Not Created (Tokenized) Equal".

ليه ده مهم بالظبط للفاتورة؟

أسعار Claude Sonnet 4.6 الرسمية على Anthropic API (مايو 2026):

• Input tokens: $3 لكل مليون token
• Output tokens: $15 لكل مليون token (خمسة أضعاف الـ input)
• Cached input: $0.30 لكل مليون token (10% بس من سعر الـ input العادي)

دلوقتي، تخيّل شات بوت دعم فني عربي بيتعامل مع 200 سؤال في اليوم:

• System prompt: 1,800 token (بيتبعت مع كل request)
• متوسط سؤال المستخدم: 60 كلمة عربية ≈ 145 tokens
• متوسط رد Claude: 180 كلمة عربية ≈ 430 tokens

حساب فاتورة الشهر (30 يوم × 200 سؤال = 6,000 request):

• Input: 6,000 × (1,800 + 145) = 11,670,000 token × $3/M = $35.01
• Output: 6,000 × 430 = 2,580,000 token × $15/M = $38.70
• المجموع: $73.71 شهرياً

لو نفس النشاط بالإنجليزي:

• السؤال هيبقى ≈ 80 token بدل 145 (–45%)
• الرد هيبقى ≈ 235 token بدل 430 (–45%)
• المجموع: $42.30 شهرياً

الفرق: $31.41 شهرياً = 74% زيادة على نفس الـ workload، مجرد لأن اللغة عربي. ده اللي بيفاجئ المطوّرين العرب اللي بيقروا تكلفة Claude على benchmarks إنجليزية.

ازاي تحسب التكلفة بنفسك قبل ما تبعت أول request

فيه طريقتين عمليتين:

الطريقة 1: تقدير سريع بـ rule of thumb

1. عد الكلمات في النص.
2. اضرب × 2.4 لو عربي، × 1.3 لو إنجليزي، × 2.0 لو كود.
3. هتطلع تقدير tokens بفرق ±15%.

كافي للتقدير المبدئي قبل ما تكتب أي كود.

الطريقة 2: حساب فعلي بـ anthropic SDK

Anthropic بتوفّر endpoint مجاني اسمه count_tokens بيرجّعلك العدد الحقيقي بدون ما تستهلك tokens فعلية ولا تدفع. ده الكود الفعلي:

# pip install anthropic==0.49.0
import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY من environment

def estimate_cost(system_prompt: str, user_message: str, expected_output_words: int = 200) -> dict:
    # عد الـ input tokens بدقة 100%
    response = client.messages.count_tokens(
        model="claude-sonnet-4-6",
        system=system_prompt,
        messages=[{"role": "user", "content": user_message}],
    )
    input_tokens = response.input_tokens
    
    # تقدير الـ output (مفيش endpoint للـ output لأنه لسه ما اتولدش)
    # rule of thumb: كلمة عربية ≈ 2.4 token
    output_tokens = int(expected_output_words * 2.4)
    
    input_cost = (input_tokens / 1_000_000) * 3.00
    output_cost = (output_tokens / 1_000_000) * 15.00
    
    return {
        "input_tokens": input_tokens,
        "output_tokens_estimated": output_tokens,
        "cost_usd": round(input_cost + output_cost, 5),
    }

result = estimate_cost(
    system_prompt="انت مساعد دعم فني لمتجر إلكتروني مصري.",
    user_message="إزاي أرجّع منتج اشتريته من 3 أيام ولسه ما وصلش؟",
    expected_output_words=180,
)
print(result)
# {'input_tokens': 87, 'output_tokens_estimated': 432, 'cost_usd': 0.00674}

كل request هيكلّفك أقل من سنت. لكن لما تضرب في 6,000 request شهرياً، الـ $0.00674 بيبقى $40.44. وده الرقم اللي لازم تحسبه قبل ما تنشر.

الـ trade-offs اللي محدش بيقولك عليها

الحساب اللي فوق دقيق، لكن فيه 4 حاجات بتغيّر الرقم في الإنتاج:

1. السياق التراكمي: في شات multi-turn، انت بتبعت كل المحادثة السابقة في كل request. محادثة بـ 10 رسائل بتكلّفك أكتر بكثير من 10 رسائل منفصلة. التكلفة بتزيد بشكل تربيعي تقريباً.
2. Prompt Caching بيقلب اللعبة: لو الـ system prompt ثابت، استخدم cache_control فالـ 1,800 token تكلفتها هتنزل من $3 لكل مليون لـ $0.30 لكل مليون (90% توفير) بعد أول request. ده ممكن يخفّض المثال اللي فوق من $73 لـ $18 شهرياً.
3. Output أغلى بـ 5 أضعاف: أي توفير لازم يركّز على output الأول. max_tokens=300 أفضل من max_tokens=2000 لو ردودك ما بتعدّيش 300 token عادةً. مفيش refund لو ما استخدمتش الـ max.
4. الـ tokenizer بيتغيّر: Anthropic بتحدّث الـ tokenizer مع كل generation من الموديل (Claude 3 vs Claude 4 مختلفين). حسابات قديمة من 2024 ممكن تكون منحرفة 8–12% على الموديلات الحالية.

متى ما تتعبش نفسك في الحساب أصلاً

الحساب التفصيلي ده مهم في الحالات دي:

• مشروع متوقّع > 1,000 request يومياً.
• محتوى عربي أو متعدد اللغات (الفرق بيكون كبير عن الإنجليزي).
• system prompt > 500 token (الـ caching هيوفّر فلوس فعلية).

لكن لو انت بتعمل prototype في الأسبوعين الأولين وبتختبر فكرة على 50 request في اليوم، حط حد $20 على Anthropic Console وكمّل. الوقت اللي هتضيّعه في الحساب المسبق أغلى من الفاتورة المتوقّعة. الحساب الجاد بييجي لما يكون فيه قرار scaling حقيقي.

الخطوة التالية

افتح terminal دلوقتي، نزّل pip install anthropic==0.49.0، انسخ الـ function estimate_cost اللي فوق، واكتب الـ system prompt اللي ناوي تستخدمه فعلاً. لو طلع > 1,000 token، ده مؤشّر إنك محتاج تفعّل cache_control من أول يوم. ابعتلي الرقم اللي طلعلك في تعليق وأقولك لو في فرصة تخفّضه قبل ما تبدأ.

المصادر

• Anthropic — Pricing Page (Claude Sonnet 4.6 input/output/cached rates): anthropic.com/pricing
• Anthropic — Token Counting API documentation: docs.claude.com
• Sennrich, R., Haddow, B., & Birch, A. (2016). Neural Machine Translation of Rare Words with Subword Units (الورقة الأصلية لـ BPE) — arXiv:1508.07909.
• Petrov, A., La Malfa, E., Torr, P., & Bibi, A. (2023). Language Model Tokenizers Introduce Unfairness Between Languages — NeurIPS 2023. (الدراسة اللي قاست الفرق بين العربية والإنجليزية في tokenization).
• Anthropic — Prompt Caching guide (تفاصيل cache_control وأسعار 10%): docs.claude.com/prompt-caching