@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.
3
Create a Meter in Dodo Payments
أنشئ meter قبل تتبّع الاستخدام:للحصول على تعليمات مفصلة، راجع دليل الفوترة القائمة على الاستخدام.
- في لوحة تحكم Dodo Payments، انتقل إلى Products → Meters.
- انقر على Create Meter.
- أعدّ 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.
- Meter Name: اسم وصفي، مثل
- انقر على 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: للإنتاج.
live_mode افتراضيًا بدلًا من ذلك، لذا عيّن live_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_.object
بيانات إضافية اختيارية لإرفاقها بكل حدث تتبّع، لاستخدامها في التصفية والتحليل. يجب أن تكون كل قيمة سلسلة أو رقمًا أو قيمة منطقية. يستبدل مفتاح باسم
inputTokens أو outputTokens أو totalTokens أو model القيمة التي تم تتبعها.مثال على الإعداد الكامل
يتتبع هذا المثال استدعاء AI SDK ويرفق بيانات وصفيةprovider بالحدث:
التتبّع التلقائي: يعيد wrapper استجابة الموفر دون تغيير، لذلك يظل الكود كما هو عند استخدام SDK الأصلي للموفر. يرسل wrapper حدث الاستخدام قبل إعادة الاستجابة، لذا ينتظر كل استدعاء طلب ingestion، ويؤدي فشل طلب ingestion إلى طرح الاستدعاء المغلّف لخطأ حتى إذا نجح استدعاء الموفر. لا تحمل streaming responses أعداد الرموز النهائية في object المُعاد، لذلك لا يتتبعها wrapper.
الموفرون المدعومون
يقرأ tracker أعداد الرموز من تنسيقات الاستجابة الخاصة بهؤلاء الموفرين وSDKs:AI SDK (Vercel)
AI SDK (Vercel)
تتبّع الاستخدام مع Vercel AI SDK، الذي يوفر واجهة واحدة للعديد من موفري LLM.المقاييس المتتبعة:
inputTokens→inputTokensoutputTokens+reasoningTokens→outputTokenstotalTokens→totalTokens- اسم النموذج: لا تحتوي نتائج AI SDK على حقل
modelفي المستوى الأعلى، لذلك يسجل tracker القيمةunknown. لتسجيل النموذج، مرّره باعتبارهmodelفي wrappermetadata، كما في هذا المثال.
عند استخدام نموذج يدعم reasoning عبر AI SDK، مثل Gemini 2.5 Flash من Google مع وضع thinking، يضيف tracker رموز reasoning المُبلغ عنها إلى
outputTokens.OpenRouter
OpenRouter
تتبّع استخدام الرموز عبر أكثر من 200 نموذج من خلال API الموحدة الخاصة بـ OpenRouter.المقاييس المتتبعة:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- اسم النموذج
OpenAI
OpenAI
تتبّع استخدام الرموز من نماذج GPT الخاصة بـ OpenAI.المقاييس المتتبعة:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- اسم النموذج
Anthropic Claude
Anthropic Claude
تتبّع استخدام الرموز من نماذج Claude الخاصة بـ Anthropic.المقاييس المتتبعة:
input_tokens→inputTokensoutput_tokens→outputTokenstotalTokens، ويُحسب باعتبارهinput_tokens+output_tokens- اسم النموذج
Groq
Groq
تتبّع استخدام الرموز من النماذج التي يقدمها Groq.المقاييس المتتبعة:
prompt_tokens→inputTokenscompletion_tokens→outputTokenstotal_tokens→totalTokens- اسم النموذج
Google Gemini
Google Gemini
تتبّع استخدام الرموز من نماذج Gemini الخاصة بـ Google عبر Google GenAI SDK.المقاييس المتتبعة:
promptTokenCount→inputTokenscandidatesTokenCount+thoughtsTokenCount→outputTokenstotalTokenCount→totalTokens- إصدار النموذج، من
modelVersion
وضع Gemini Thinking: بالنسبة إلى نماذج Gemini التي تفكر قبل الإجابة، مثل Gemini 2.5 Pro، يضيف tracker القيمة
thoughtsTokenCount (رموز reasoning) إلى outputTokens، بحيث يعكس الحدث كامل الإخراج الذي أنشأه النموذج.الاستخدام المتقدم
موفرون متعددون
لتتبّع الاستخدام عبر موفري LLM بشكل منفصل، أنشئ tracker لكل موفر:تكامل 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، لحساب الاستخدام والفوترة.