الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.

الـ models وجدول الأسعار

دوال مساعدة بدون dependencies، لقرارات الميزانية والسياق.
  • estimateTokens(input, { model?, estimator? }) هو heuristic تقريبي: حوالي 4 محارف لكل token في الإنجليزية، وأكثر للـ CJK وباقي أنظمة الكتابة، زائد overhead لكل رسالة ولـ JSON الخاص بالـ tool calls. توقّع خطأ بحوالي 15-20% في الإنجليزية — يكفي للـ compaction (ضغط السياق) والميزانيات، لكنه لا يصلح للفوترة. وصّل tokenizer حقيقي عبر setTokenEstimator(fn) أو options.estimator.
  • getModelInfo(id) يطابق الـ id كما هو أولًا، ثم provider/id، ثم الـ snapshots المؤرخة (gpt-4o-mini-2024-07-18 ترجع gpt-4o-mini). الـ models غير المعروفة ترجع undefined. (في سلاسل createAgent({ model }) وresolveProvider()، بادئة vendor/ هي التي تختار الـ provider؛ ومع OpenRouter استخدم openrouter/<vendor>/<model>، مثل openrouter/openai/gpt-4o-mini.)
  • registerModel(info) يضيف مدخلًا جديدًا أو يكتب فوق مدخل موجود، وآخر تسجيل هو الذي يُعتمد. سجّل الـ models المحلية (LM Studio وOllama وvLLM) مع الـ context window الذي حُمِّلت به: وإلا فإن الـ compaction والـ tool search يفترضان 128,000 token ويسجّلان تحذيرًا مرة واحدة. الـ models المحلية ليس لها سعر مضمّن (مدخلات Ollama تحمل الـ context window فقط)، لذلك تكون costUsd الخاصة بها undefined ويكتفي limits.maxCostUsd بالتحذير؛ سجّل لها سعرًا، ولو كان 0، لكي تُحسب تكلفتها ويُطبَّق الحد: registerModel({ id: 'llama3', provider: 'ollama', contextWindow: 8192, inputCostPerMTok: 0, outputCostPerMTok: 0 }).
  • estimateCost(usage, model) يرجع التكلفة بالدولار (USD)، أو undefined (وليس 0) إذا كان الـ model أو أسعاره غير معروفة. الحقلان usage.cachedInputTokens وusage.cacheWriteTokens، إذا مُرِّرا، هما الجزءان من inputTokens اللذان قُرئا من الـ prompt cache لدى الـ provider وكُتبا فيه. يُسعَّران بـcachedInputCostPerMTok وcacheWriteCostPerMTok، أو بسعر الـ input إذا لم يكن للـ model هذان السعران. مدخلات OpenAI المضمّنة تحمل سعر الـ cached input الخاص بـ OpenAI (مثلًا 50% على gpt-4o-mini؛ والكتابة بلا تكلفة إضافية). ومدخلات Anthropic تحسب القراءة بـ 10% والكتابة لمدة 5 دقائق بـ 125% من سعر الـ input.
الـ context windows والأسعار المضمّنة snapshot مؤرخة (تاريخ الجلب والمصادر في أعلى src/models/modelData.ts). الـ providers يغيّرون أسعارهم والـ models، فإذا تحتاج أرقامًا بدقة الفوترة اكتب فوق المدخلات بـregisterModel.

الـ usage وتكلفة الـ run

كل ExecutionResult (ونتيجة agent.send()) تحمل usage، وهو المجموع التراكمي للـ run كله:
  • reported مقابل estimated. الـ providers يبلّغون عن promptTokens/completionTokens. والـ providers المضمّنون يمرّرون أيضًا cachedInputTokens/cacheWriteTokens/reasoningTokens إذا بلّغ عنها الـ provider — usage.cachedInputTokens وusage.cacheWriteTokens وusage.reasoningTokens لا تظهر إلا في تلك الحالة. وinputTokens يشمل دائمًا الـ tokens المقروءة من الـ cache والمكتوبة فيه أيضًا. الـ backend الذي لا يبلّغ عن شيء يعطي usage بقيمة undefined، لا أصفارًا أبدًا. في تلك الخطوة يستعمل الـ executor الدالة estimateTokens كـ fallback ويضبط usage.estimated (تظهر ~ في بداية ناتج formatUsage). والـ provider المخصص يجب أن يترك GenerateResult.usage غير مضبوط بدل أن يملأه بأصفار.
  • التكلفة. costUsd هو مجموع تكاليف الاستدعاءات: التكلفة التي بلّغ عنها الـ provider (OpenRouter يرجع usage.cost لكل model، مسعَّرًا كان أو لا)، وإلا فـestimateCost للـ model. الاستدعاء الذي ليس له سعر معروف (model غير موجود في الـ registry ولم يبلّغ الـ provider عن تكلفته) يُستبعد من المجموع ويضبط usage.costPartial: true، فيصير المجموع حدًا أدنى بدل أن يُهمل كليًا؛ وbyModel يوضح أي الـ models مسعَّرة (byModel[model].costPartial يعلّم الـ model الذي له استدعاءات مسعَّرة وأخرى غير مسعَّرة، وusage.delegated.costPartial يفعل الشيء نفسه للـ children). لا تكون costUsd بقيمة undefined إلا إذا لم يكن لأي استدعاء تكلفة معروفة. ويُفحص limits.maxCostUsd مقابل المجموع الجزئي. formatUsage يطبع التكلفة بأربع خانات عشرية تحت $1 (وخانتين عند $1 فأكثر)، فالـ run الذي يقل عن $0.00005 يظهر `$0.0000`.
  • hosted tools. usage.hostedToolCalls يحسب الاستدعاءات التي شغّلها الـ provider للـ hosted tools لكل اسم tool (مثل { web_search: 2 }). رسوم الاستدعاء يحاسب عليها الـ provider نفسه وهي ليست ضمن costUsd.
  • التفويض. يُضاف الـ usage الخاص بالـ child المفوَّض إلى مجاميع الأب وbyModel، ويظهر أيضًا منفردًا في usage.delegated ({ inputTokens, outputTokens, totalTokens, costUsd, modelCalls, estimated, runs }، زائد toolErrors: استدعاءات الـ tools في الـ children التي انتهت بنتيجة خطأ، ولا يظهر إذا لم يحدث ذلك). أما الـ usage الخاص بالـremote sub-agent فهو ما يبلّغ عنه الـ agent البعيد، ويُسجَّل تحت byModel['remote:<name>'] مع costUsd الخاصة به.
  • الاستئناف. الـ run الذي يُستأنف من checkpoint أو بعد موافقة يكمل من المجاميع المحفوظة بدل أن يبدأ من الصفر. الـ checkpoints التي كتبتها إصدارات أقدم تبدأ من أعداد الـ tokens المحفوظة فيها وبتكلفة غير معروفة.
  • الأحداث والـ tracing. الحدث finish (وكل lifecycle event كان يحمل usage) يحمل الآن المجاميع التراكمية. وtext-complete يحمل أيضًا stepUsage، وonLLMResponse يستقبل الـ usage الخاص بالاستدعاء كوسيط ثالث. سمات gen_ai.usage.* في الـ span chat تستخدم نفس الأرقام، مع lousho.usage.estimated مضبوطة على true إذا كانت الأرقام تقديرية.
  • streaming. أحداث agent.stream() تحمل نفس المحاسبة: step.done وrun.done فيها usage يضم inputTokens وoutputTokens وestimated وcostUsd، وcostPartial إذا كانت التكلفة جزئية (وعلى مستوى الـ run أيضًا modelCalls)، إلى جانب promptTokens/completionTokens الأقدم.
  • يبقى promptTokens وcompletionTokens على usage اسمين بديلين deprecated لـinputTokens وoutputTokens.
الأسعار تأتي من الـ model registry أعلاه، فإذا أردت تكلفة لـ model مخصص أو fine-tuned، سجّله بنفس الـ id الذي تمرّره كـ model:

الـ prompt caching

Anthropic لا تخزّن بادئة الطلب في الـ cache إلا حتى breakpoint من نوع cache_control يعلّمه الطلب نفسه. أما OpenAI ومعظم الـ providers الآخرين فيخزّنون البادئات الطويلة من تلقاء أنفسهم. مع promptCaching: 'auto' (القيمة الافتراضية)، يعلّم الـ provider المضمّن anthropic والـ provider openrouter الـ breakpoints لـ models Claude (anthropic/... وopenrouter/anthropic/...). ويعلّمان ثلاثة من الأربعة التي تسمح بها Anthropic:
  • الـ system prompt (آخر رسالة system)،
  • تعريف آخر tool،
  • آخر turn للمستخدم. ومع الـ provider anthropic يُعلَّم أيضًا turn نتيجة الـ tool الأخير، فتقرأ كل خطوة في حلقة الـ tools المحادثة حتى تلك اللحظة من الـ cache.
القراءة من الـ cache تكلّف 10% من سعر الـ input. والكتابة فيه تكلّف 125% وتبقى 5 دقائق، فالـ prompt الذي يُرسل مرة واحدة فقط يكلّف أكثر قليلًا مع الـ caching. Anthropic لا تخزّن إلا البادئات التي تتجاوز حدًا أدنى من الطول (من 1,024 إلى 4,096 token حسب الـ model)، والـ prompts الأقصر تُرسل بلا cache. على الـ provider anthropic، تحتاج breakpoints الـ tools والـ system إلى ai 6 أو 7 (@ai-sdk/anthropic 3 أو 4). أما الـ peer @ai-sdk/anthropic 0.0.x المثبّت لـ ai 4 فلا يرسلها. والـ provider المخصص يستقبل هذا الإعداد في GenerateOptions.promptCaching. قياس عبر OpenRouter على anthropic/claude-haiku-4.5، مع prompt من 6,834 token (system prompt وtool واحدة):