Skip to main content
يغلّف LLM Blueprint عميل LLM لديك، بحيث يرسل كل استدعاء مكتمل حدث استخدام يتضمن أعداد رموز الإدخال والإخراج والإجمالي إلى Dodo Payments. يجمع meter هذه الأعداد، ما يتيح لك إصدار فاتورة لكل عميل مقابل الرموز التي يستخدمها. تأتي blueprint ضمن حزمة npm‏ @dodopayments/ingestion-blueprints باسم createLLMTracker().

Quick Start

ثبّت SDK، وأنشئ meter، وغلّف عميل LLM لديك.

API Reference - Events Ingestion

نقطة API التي تستقبل أحداث الاستخدام.

API Reference - Meters

أنشئ meters وأعدّها للفوترة.

Usage-Based Billing Guide

أعدّ الفوترة القائمة على الاستخدام باستخدام meters من البداية إلى النهاية.
استخدمه في تطبيقات SaaS وروبوتات المحادثة بالذكاء الاصطناعي وأدوات إنشاء المحتوى وأي تطبيق آخر مدعوم بـ LLM ويصدر فواتير حسب الاستخدام.

البدء السريع

لتتبّع استخدام الرموز، ثبّت الحزمة، وأنشئ meter، وغلّف عميل LLM لديك.
1

Install the SDK

ثبّت حزمة Dodo Payments Ingestion Blueprints:
ثبّت أيضًا SDK الخاص بموفر LLM لديك، مثل openai أو @anthropic-ai/sdk أو groq-sdk أو @google/genai أو ai مع @ai-sdk/google.
2

Get Your API Keys

تحتاج إلى مفتاحي API:
  • مفتاح API الخاص بـ Dodo Payments: أنشئ مفتاحًا ضمن Developer → API Keys في لوحة تحكم Dodo Payments، واحفظه في DODO_PAYMENTS_API_KEY. استخدم مفتاح test mode أثناء التطوير. يعمل مفتاح test mode فقط مع test_mode.
  • مفتاح API الخاص بموفر LLM: المفتاح الخاص بالموفر الذي تستدعيه، مثل OpenAI أو Anthropic أو Groq أو OpenRouter أو Google. تقرأ الأمثلة المفتاح من متغيرات مثل OPENAI_API_KEY.
احفظ مفاتيح API في environment variables. لا تلتزم بها في version control.
3

Create a Meter in Dodo Payments

أنشئ meter قبل تتبّع الاستخدام:
  1. في لوحة تحكم Dodo Payments، انتقل إلى Products → Meters.
  2. انقر على Create Meter.
  3. أعدّ meter:
    • Meter Name: اسم وصفي، مثل LLM Token Usage.
    • Event Name: معرّف حدث فريد، مثل llm.chat_completion.
    • Aggregation Type: Sum، لجمع أعداد الرموز.
    • Over Property: عدد الرموز المطلوب إصدار الفاتورة بناءً عليه:
      • inputTokens: رموز الإدخال (prompt).
      • outputTokens: رموز الإخراج (completion)، بما فيها رموز reasoning عندما يرسلها النموذج.
      • totalTokens: رموز الإدخال والإخراج مجتمعة.
    • Measurement Unit: الوحدة الظاهرة في الفواتير، مثل tokens.
  4. انقر على Create Meter.
يجب أن يطابق Event Name الذي عيّنته هنا قيمة eventName التي تمررها إلى SDK تمامًا، مع مراعاة حالة الأحرف.
للحصول على تعليمات مفصلة، راجع دليل الفوترة القائمة على الاستخدام.
4

Track Token Usage

أنشئ tracker، وغلّف عميل LLM لديك، واستدعِ العميل كالمعتاد:
يرسل كل استدعاء مكتمل عبر العميل المغلّف الآن حدث استخدام يتضمن أعداد رموزه إلى Dodo Payments للفوترة.

التكوين

تكوين المتتبع

أنشئ tracker مرة واحدة عند بدء تشغيل التطبيق وأعد استخدامه لكل عميل. يقبل createLLMTracker() هذه الخيارات، ويطرح خطأً إذا كانت apiKey أو eventName مفقودة أو فارغة:
string
مطلوب
مفتاح API الخاص بـ Dodo Payments. احصل عليه من صفحة مفاتيح API.
string
وضع البيئة الخاص بـ tracker:
  • test_mode: للتطوير والاختبار. هذا هو الوضع الافتراضي.
  • live_mode: للإنتاج.
تستخدم Dodo Payments SDKs الوضع live_mode افتراضيًا بدلًا من ذلك، لذا عيّن live_mode صراحةً في الإنتاج.
استخدم test_mode أثناء التطوير، حتى لا تنشئ حركة الاختبار أحداث استخدام مباشرة.
string
مطلوب
اسم الحدث الذي يفعّل meter لديك. يجب أن يطابق Event Name الخاص بـ meter في Dodo Payments تمامًا، مع مراعاة حالة الأحرف.
يربط اسم الحدث هذا الاستخدام الذي تتبعه بـ meter الصحيح لحسابات الفوترة.
بالإضافة إلى wrap()، يحتوي tracker على track(response, customerId, metadata)، الذي يسجل الاستخدام من response لديك مسبقًا، وعلى healthCheck()، الذي يعيد true عندما تكون Dodo Payments API قابلة للوصول.

إعداد Wrapper

مرّر هذه المعلمات إلى wrap():
object
مطلوب
مثيل عميل LLM لديك، مثل عميل OpenAI أو Anthropic أو Groq أو Google GenAI، أو object يحتوي على وظائف AI SDK، مثل { generateText }.
string
مطلوب
معرّف عميل Dodo Payments المطلوب إصدار الفاتورة له. يبدأ بـ cus_.
احفظ معرّف عميل Dodo Payments لكل مستخدم مع سجل المستخدم، ومرّره هنا. لا يطابق معرّف المستخدم الخاص بتطبيقك عميلًا في Dodo Payments.
object
بيانات إضافية اختيارية لإرفاقها بكل حدث تتبّع، لاستخدامها في التصفية والتحليل. يجب أن تكون كل قيمة سلسلة أو رقمًا أو قيمة منطقية. يستبدل مفتاح باسم inputTokens أو outputTokens أو totalTokens أو model القيمة التي تم تتبعها.

مثال على الإعداد الكامل

يتتبع هذا المثال استدعاء AI SDK ويرفق بيانات وصفية provider بالحدث:
التتبّع التلقائي: يعيد wrapper استجابة الموفر دون تغيير، لذلك يظل الكود كما هو عند استخدام SDK الأصلي للموفر. يرسل wrapper حدث الاستخدام قبل إعادة الاستجابة، لذا ينتظر كل استدعاء طلب ingestion، ويؤدي فشل طلب ingestion إلى طرح الاستدعاء المغلّف لخطأ حتى إذا نجح استدعاء الموفر. لا تحمل streaming responses أعداد الرموز النهائية في object المُعاد، لذلك لا يتتبعها wrapper.

الموفرون المدعومون

يقرأ tracker أعداد الرموز من تنسيقات الاستجابة الخاصة بهؤلاء الموفرين وSDKs:
تتبّع الاستخدام مع Vercel AI SDK، الذي يوفر واجهة واحدة للعديد من موفري LLM.
المقاييس المتتبعة:
  • inputTokens → inputTokens
  • outputTokens + reasoningTokens → outputTokens
  • totalTokens → totalTokens
  • اسم النموذج: لا تحتوي نتائج AI SDK على حقل model في المستوى الأعلى، لذلك يسجل tracker القيمة unknown. لتسجيل النموذج، مرّره باعتباره model في wrapper metadata، كما في هذا المثال.
عند استخدام نموذج يدعم reasoning عبر AI SDK، مثل Gemini 2.5 Flash من Google مع وضع thinking، يضيف tracker رموز reasoning المُبلغ عنها إلى outputTokens.
تتبّع استخدام الرموز عبر أكثر من 200 نموذج من خلال API الموحدة الخاصة بـ OpenRouter.
المقاييس المتتبعة:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • اسم النموذج
يتيح OpenRouter الوصول إلى نماذج من OpenAI وAnthropic وGoogle وMeta وموفرين آخرين من خلال API واحدة.
تتبّع استخدام الرموز من نماذج GPT الخاصة بـ OpenAI.
المقاييس المتتبعة:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • اسم النموذج
تتبّع استخدام الرموز من نماذج Claude الخاصة بـ Anthropic.
المقاييس المتتبعة:
  • input_tokens → inputTokens
  • output_tokens → outputTokens
  • totalTokens، ويُحسب باعتباره input_tokens + output_tokens
  • اسم النموذج
تتبّع استخدام الرموز من النماذج التي يقدمها Groq.
المقاييس المتتبعة:
  • prompt_tokens → inputTokens
  • completion_tokens → outputTokens
  • total_tokens → totalTokens
  • اسم النموذج
تتبّع استخدام الرموز من نماذج Gemini الخاصة بـ Google عبر Google GenAI SDK.
المقاييس المتتبعة:
  • promptTokenCount → inputTokens
  • candidatesTokenCount + thoughtsTokenCount → outputTokens
  • totalTokenCount → totalTokens
  • إصدار النموذج، من modelVersion
وضع Gemini Thinking: بالنسبة إلى نماذج Gemini التي تفكر قبل الإجابة، مثل Gemini 2.5 Pro، يضيف tracker القيمة thoughtsTokenCount (رموز reasoning) إلى outputTokens، بحيث يعكس الحدث كامل الإخراج الذي أنشأه النموذج.

الاستخدام المتقدم

موفرون متعددون

لتتبّع الاستخدام عبر موفري LLM بشكل منفصل، أنشئ tracker لكل موفر:
استخدم اسم حدث مختلفًا لكل موفر، مع meter لكل واحد، لتتبّع الاستخدام بشكل منفصل.

تكامل Express.js API

تتتبّع Express.js API هذه كل إكمال محادثة للعميل الذي أجرى الطلب. وللاختصار، تقرأ userId من request body. يجب أن تكون userId معرّف عميل المستخدم في Dodo Payments. في الإنتاج، اقرأه من الجلسة الموثّقة بدلًا من الوثوق في request body.

ما الذي يتم تتبعه

يرسل كل استدعاء متتبَّع حدث استخدام واحدًا إلى Dodo Payments بهذا الهيكل:

حقول الحدث

string
معرّف فريد لهذا الحدث. ينشئه SDK.التنسيق: llm_[timestamp]_[random]، حيث إن timestamp هو الوقت بالميلي ثانية، وrandom ستة أحرف عشوائية.
string
معرّف العميل الذي مرّرته عند تغليف العميل. تصدر Dodo Payments فاتورة لهذا العميل.
string
اسم الحدث الذي يفعّل meter لديك. يأتي من إعداد tracker.
string
طابع زمني بتنسيق ISO 8601، يُعيّن عندما يرسل tracker الحدث بعد استجابة الموفر.
object
استخدام الرموز وبيانات التتبع الإضافية:
  • inputTokens: عدد رموز الإدخال (prompt) المستخدمة.
  • outputTokens: عدد رموز الإخراج (completion) المستخدمة، بما فيها رموز reasoning عند انطباق ذلك.
  • totalTokens: إجمالي الرموز (الإدخال + الإخراج).
  • model: نموذج LLM المستخدم، مثل gpt-4، أو unknown إذا لم تسمِّ الاستجابة نموذجًا.
  • provider: موفر LLM، إذا أدرجته في metadata الخاصة بـ wrapper.
  • أي metadata مخصصة قدّمتها عند تغليف العميل.
رموز Reasoning: بالنسبة إلى النماذج التي تدعم reasoning، تتضمن outputTokens رموز completion ورموز reasoning معًا.
يستخدم meter الخاص بـ Dodo Payments الحقول metadata، وعادةً inputTokens أو outputTokens أو totalTokens، لحساب الاستخدام والفوترة.
آخر تعديل في ٢٦ سبتمبر ٢٠٢٦