الـ 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.
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.*في الـ spanchatتستخدم نفس الأرقام، مع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.
الـ 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.
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 واحدة):