الانتقال إلى المحتوى الرئيسي
مثالي لتطبيقات SaaS، وروبوتات الدردشة الذكية، وأدوات توليد المحتوى، وأي تطبيق يعتمد على LLM يحتاج إلى فوترة قائمة على الاستخدام.

بدء سريع

ابدأ مع تتبع رموز LLM التلقائي في دقيقتين فقط:
1

Install the SDK

قم بتثبيت المخططات الأساسية لالتقاط بيانات Dodo Payments:
npm install @dodopayments/ingestion-blueprints
2

Get Your API Keys

ستحتاج إلى مفتاحي واجهة برمجة تطبيقات:
احفظ مفاتيح API بأمان في متغيرات البيئة. لا تقم بإدراجها في نظام التحكم في الإصدارات.
3

Create a Meter in Dodo Payments

قبل تتبع الاستخدام، أنشئ مقياسًا في لوحة Dodo Payments:
  1. تسجيل الدخول إلى لوحة Dodo Payments
  2. انتقل إلى Products → Meters
  3. انقر على “Create Meter”
  4. قم بتكوين المقياس الخاص بك:
    • اسم المقياس: اختر اسمًا وصفيًا (مثل “LLM Token Usage”)
    • اسم الحدث: حدد معرف حدث فريد (مثل llm.chat_completion)
    • نوع التجميع: اختر sum لجمع عدد الرموز
    • خاصية التجميع: اختر ما تريد تتبعه:
      • inputTokens - تتبع رموز الإدخال/الموجه
      • outputTokens - تتبع رموز الإخراج/الإكمال (تتضمن رموز الاستدلال عند الاقتضاء)
      • totalTokens - تتبع مجموع رموز الإدخال + الإخراج
يجب أن يتطابق اسم الحدث الذي تحدده هنا تمامًا مع الاسم الذي تمرره إلى SDK (مع مراعاة حالة الأحرف).
لمزيد من التعليمات التفصيلية، راجع دليل الفوترة القائمة على الاستخدام.
4

Track Token Usage

قم بتغليف عميل LLM الخاص بك وابدأ التتبع تلقائيًا:
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const llmTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'aisdk.usage',
});

const client = llmTracker.wrap({
  client: { generateText },
  customerId: 'customer_123'
});

const response = await client.generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Hello!',
  maxOutputTokens: 500
});

console.log('Usage:', response.usage);
هذا كل شيء! الآن كل استدعاء API يتتبع تلقائيًا استخدام الرموز ويرسل الأحداث إلى Dodo Payments للفوترة.

التكوين

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

قم بإنشاء متتبع مرة واحدة عند بدء التطبيق مع هذه المعلمات المطلوبة:
apiKey
string
مطلوب
مفتاح API الخاص بـ Dodo Payments. احصل عليه من صفحة مفاتيح API.
apiKey: process.env.DODO_PAYMENTS_API_KEY
environment
string
مطلوب
وضع البيئة لبرتوكول التتبع.
  • test_mode - استخدمه للتطوير والاختبار
  • live_mode - استخدمه للإنتاج
environment: 'test_mode' // or 'live_mode'
استخدم دائمًا test_mode أثناء التطوير لتجنب التأثير على مقاييس الإنتاج.
eventName
string
مطلوب
اسم الحدث الذي يُشغّل المقياس. يجب أن يتطابق تمامًا مع ما قمت بتكوينه في مقياس Dodo Payments الخاص بك (حساس لحالة الأحرف).
eventName: 'llm.chat_completion'
يربط اسم الحدث هذا الاستخدام المتتبع بالمقياس الصحيح لحسابات الفوترة.

تكوين الغلاف

عند لف عميل LLM الخاص بك، قدم هذه المعلمات:
client
object
مطلوب
مثيل عميل LLM الخاص بك (OpenAI، Anthropic، Groq، إلخ).
client: openai
customerId
string
مطلوب
المعرف الفريد للعميل للفوترة. يجب أن يتطابق مع معرف العميل في Dodo Payments.
customerId: 'customer_123'
استخدم معرف مستخدم التطبيق أو معرف العميل لضمان فوترة دقيقة لكل عميل.
metadata
object
بيانات إضافية اختيارية لإرفاقها بحدث التتبع. مفيدة للتصفية والتحليل.
metadata: {
  feature: 'chat',
  userTier: 'premium',
  sessionId: 'session_123',
  modelVersion: 'gpt-4'
}

مثال كامل على التكوين

import { createLLMTracker } from "@dodopayments/ingestion-blueprints";
import { generateText } from "ai";
import { google } from "@ai-sdk/google";
import "dotenv/config";

async function aiSdkExample() {
  console.log("🤖 AI SDK Simple Usage Example\n");

  try {
    // 1. Create tracker
    const llmTracker = createLLMTracker({
      apiKey: process.env.DODO_PAYMENTS_API_KEY!,
      environment: "test_mode",
      eventName: "your_meter_event_name",
    });

    // 2. Wrap the ai-sdk methods
    const client = llmTracker.wrap({
      client: { generateText },
      customerId: "customer_123",
      metadata: {
        provider: "ai-sdk",
      },
    });

    // 3. Use the wrapped function
    const response = await client.generateText({
      model: google("gemini-2.5-flash"),
      prompt: "Hello, I am a cool guy! Tell me a fun fact.",
      maxOutputTokens: 500,
    });

    console.log(response);
    console.log(response.usage);
    console.log("✅ Automatically tracked for customer\n");
  } catch (error) {
    console.error(error);
  }
}

aiSdkExample().catch(console.error);
التتبع التلقائي: يقوم SDK بتتبع استخدام الرموز تلقائيًا في الخلفية دون تعديل الاستجابة. يظل الكود نظيفًا ومطابقًا لاستخدام SDK الخاص بالمزود الأصلي.

المزودون المدعومون

يعمل مخطط LLM بسلاسة مع جميع مزودي LLM الرئيسيين والمجمعين:
تتبع الاستخدام باستخدام Vercel AI SDK لدعم LLM شامل.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const llmTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'aisdk.usage',
});

const client = llmTracker.wrap({
  client: { generateText },
  customerId: 'customer_123',
  metadata: {
    model: 'gemini-2.0-flash',
    feature: 'chat'
  }
});

const response = await client.generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Explain neural networks',
  maxOutputTokens: 500
});

console.log('Usage:', response.usage);
القياسات المتعقبة:
  • inputTokensinputTokens
  • outputTokens + reasoningTokensoutputTokens
  • totalTokenstotalTokens
  • اسم النموذج
عند استخدام نماذج تدعم الاستدلال عبر AI SDK (مثل Gemini 2.5 Flash من Google مع وضع التفكير)، يتم تضمين رموز الاستدلال تلقائيًا في outputTokens لضمان فوترة دقيقة.
تتبع استخدام الرموز من أكثر من 200 نموذج عبر واجهة OpenRouter الموحدة.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

// OpenRouter uses OpenAI-compatible API
const openrouter = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY
});

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'openrouter.usage'
});

const client = tracker.wrap({ 
  client: openrouter, 
  customerId: 'user_123',
  metadata: { provider: 'openrouter' }
});

const response = await client.chat.completions.create({
  model: 'qwen/qwen3-max',
  messages: [{ role: 'user', content: 'What is machine learning?' }],
  max_tokens: 500
});

console.log('Response:', response.choices[0].message.content);
console.log('Usage:', response.usage);
القياسات المتعقبة:
  • prompt_tokensinputTokens
  • completion_tokensoutputTokens
  • total_tokenstotalTokens
  • اسم النموذج
يوفر OpenRouter الوصول إلى نماذج من OpenAI وAnthropic وGoogle وMeta والعديد من المزودين الآخرين عبر واجهة API واحدة.
تتبع استخدام الرموز من نماذج GPT التابعة لـ OpenAI تلقائيًا.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'openai.usage'
});

const client = tracker.wrap({ 
  client: openai, 
  customerId: 'user_123' 
});

// All OpenAI methods work automatically
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

console.log('Total tokens:', response.usage.total_tokens);
القياسات المتعقبة:
  • prompt_tokensinputTokens
  • completion_tokensoutputTokens
  • total_tokenstotalTokens
  • اسم النموذج
تتبع استخدام الرموز من نماذج Claude التابعة لـ Anthropic.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'anthropic.usage'
});

const client = tracker.wrap({ 
  client: anthropic, 
  customerId: 'user_123' 
});

const response = await client.messages.create({
  model: 'claude-sonnet-4-0',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain machine learning' }]
});

console.log('Input tokens:', response.usage.input_tokens);
console.log('Output tokens:', response.usage.output_tokens);
القياسات المتعقبة:
  • input_tokensinputTokens
  • output_tokensoutputTokens
  • totalTokens المحسوب
  • اسم النموذج
تتبع الاستدلال عالي السرعة لنماذج LLM مع Groq.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import Groq from 'groq-sdk';

const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'groq.usage'
});

const client = tracker.wrap({ 
  client: groq, 
  customerId: 'user_123' 
});

const response = await client.chat.completions.create({
  model: 'llama-3.1-8b-instant',
  messages: [{ role: 'user', content: 'What is AI?' }]
});

console.log('Tokens:', response.usage);
القياسات المتعقبة:
  • prompt_tokensinputTokens
  • completion_tokensoutputTokens
  • total_tokenstotalTokens
  • اسم النموذج
تتبع استخدام الرموز من نماذج Gemini التابعة لـ Google عبر Google GenAI SDK.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { GoogleGenAI } from '@google/genai';

const googleGenai = new GoogleGenAI({ 
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY 
});

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'gemini.usage'
});

const client = tracker.wrap({ 
  client: googleGenai, 
  customerId: 'user_123' 
});

const response = await client.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Explain quantum computing'
});

console.log('Response:', response.text);
console.log('Usage:', response.usageMetadata);
القياسات المتعقبة:
  • promptTokenCountinputTokens
  • candidatesTokenCount + thoughtsTokenCountoutputTokens
  • totalTokenCounttotalTokens
  • إصدار النموذج
وضع التفكير في Gemini: عند استخدام نماذج Gemini التي تدعم التفكير/الاستدلال (مثل Gemini 2.5 Pro)، يقوم SDK تلقائيًا بإضافة thoughtsTokenCount (رموز الاستدلال) إلى outputTokens لتعكس التكلفة الحسابية الكاملة بدقة.

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

مزودون متعددون

تتبع الاستخدام عبر مزودي LLM مختلفين مع متتبعين منفصلين:
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';
import Groq from 'groq-sdk';
import Anthropic from '@anthropic-ai/sdk';
import { GoogleGenAI } from '@google/genai';

// Create separate trackers for different providers
const openaiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'openai.usage'
});

const groqTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'groq.usage'
});

const anthropicTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'anthropic.usage'
});

const geminiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'gemini.usage'
});

const openrouterTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'openrouter.usage'
});

// Initialize clients
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const googleGenai = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY });
const openrouter = new OpenAI({ 
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY 
});

// Wrap clients
const trackedOpenAI = openaiTracker.wrap({ client: openai, customerId: 'user_123' });
const trackedGroq = groqTracker.wrap({ client: groq, customerId: 'user_123' });
const trackedAnthropic = anthropicTracker.wrap({ client: anthropic, customerId: 'user_123' });
const trackedGemini = geminiTracker.wrap({ client: googleGenai, customerId: 'user_123' });
const trackedOpenRouter = openrouterTracker.wrap({ client: openrouter, customerId: 'user_123' });

// Use whichever provider you need
const response = await trackedOpenAI.chat.completions.create({...});
// or
const geminiResponse = await trackedGemini.models.generateContent({...});
// or
const openrouterResponse = await trackedOpenRouter.chat.completions.create({...});
استخدم أسماء أحداث مختلفة لمزودين مختلفين لتتبع الاستخدام بشكل منفصل في مقاييسك.

تكامل API مع Express.js

مثال كامل على دمج تتبع LLM في API Express.js:
import express from 'express';
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const app = express();
app.use(express.json());

// Initialize OpenAI client
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// Create tracker once at startup
const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode',
  eventName: 'api.chat_completion'
});

// Chat endpoint with automatic tracking
app.post('/api/chat', async (req, res) => {
  try {
    const { message, userId } = req.body;
    
    // Validate input
    if (!message || !userId) {
      return res.status(400).json({ error: 'Missing message or userId' });
    }
    
    // Wrap client for this specific user
    const trackedClient = tracker.wrap({
      client: openai,
      customerId: userId,
      metadata: { 
        endpoint: '/api/chat',
        timestamp: new Date().toISOString()
      }
    });
    
    // Make LLM request - automatically tracked
    const response = await trackedClient.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: message }],
      temperature: 0.7
    });
    
    const completion = response.choices[0].message.content;
    
    res.json({ 
      message: completion,
      usage: response.usage
    });
  } catch (error) {
    console.error('Chat error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

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

كل استدعاء API لـ LLM يرسل تلقائيًا حدث استخدام إلى مدفوعات Dodo بالهيكل التالي:
{
  "event_id": "llm_1673123456_abc123",
  "customer_id": "customer_123",
  "event_name": "llm.chat_completion",
  "timestamp": "2024-01-08T10:30:00Z",
  "metadata": {
    "inputTokens": 10,
    "outputTokens": 25,
    "totalTokens": 35,
    "model": "gpt-4",
  }
}

حقول الحدث

event_id
string
المعرف الفريد لهذا الحدث المحدد. يتم إنشاؤه تلقائيًا بواسطة SDK.التنسيق: llm_[timestamp]_[random]
customer_id
string
معرف العميل الذي قدمته عند تغليف العميل. يُستخدم للفوترة.
event_name
string
اسم الحدث الذي يُشغّل المقياس. يتطابق مع تكوين المتتبع الخاص بك.
timestamp
string
الطابع الزمني بصيغة ISO 8601 عندما وقع الحدث.
metadata
object
استخدام الرموز وبيانات التتبع الإضافية:
  • inputTokens - عدد رموز الإدخال/الموجه المستخدمة
  • outputTokens - عدد رموز المخرجات/الإكمال المستخدمة (يشمل رموز الاستدلال عند الاقتضاء)
  • totalTokens - إجمالي الرموز (إدخال + إخراج)
  • model - نموذج LLM المستخدم (مثل “gpt-4”)
  • provider - مزود LLM (إذا كان مدرجًا في بيانات الغلاف التعريفية)
  • أي بيانات تعريف مخصصة قدمتها عند تغليف العميل
  • inputTokens - عدد رموز الإدخال/المطالبة المستخدمة
  • outputTokens - عدد رموز الإخراج/الإنجاز المستخدمة (تشمل رموز التفكير عند الاقتضاء)
  • totalTokens - إجمالي الرموز (الإدخال + الإخراج)
  • model - نموذج LLM المستخدم (مثل “gpt-4”)
  • provider - مزود LLM (إذا تم تضمينه في بيانات التعريف الخاصة بالملف)
  • أي بيانات تعريف مخصصة قدمتها عند تغليف العميل
رموز الاستدلال: بالنسبة للنماذج التي تدعم الاستدلال، يتضمن outputTokens تلقائيًا كلًا من رموز الإكمال ورموز الاستدلال.
يستخدم مقياس Dodo Payments الخاص بك الحقول metadata (خاصة inputTokens، outputTokens أو totalTokens) لحساب الاستخدام والفوترة.