دليل Langfuse 2026: مراقبة نماذج اللغة وإدارة الموجهات لتطبيقات Next.js الذكية

بمجرد أن يتخطى تطبيق الذكاء الاصطناعي مرحلة النموذج الأولي، تكتشف سريعًا أن console.log ليس كافيًا. تحتاج إلى الإجابة على أسئلة مثل: أي موجه من المستخدم أدى إلى هذه الاستجابة الفاشلة، كم كلفت تلك المحادثة، لماذا ارتفع زمن الاستجابة في الساعة الثالثة فجرًا، وأي إصدار من الموجه أنتج أفضل درجات التقييم؟

Langfuse هي منصة مراقبة مفتوحة المصدر مبنية خصيصًا لتطبيقات LLM. تتولى التتبع، وتتبع التكاليف والرموز، وإدارة إصدارات الموجهات، والتقييمات، وملاحظات المستخدمين. في هذا الدرس، ستربط Langfuse بتطبيق Next.js 15 يستخدم Vercel AI SDK، وتلتقط كل نداء LLM ببيانات وصفية غنية، وتدير الموجهات كأصول من الدرجة الأولى، وتبني لوحات تحكم تساعدك فعلًا على تصحيح الإنتاج.

المتطلبات الأساسية

قبل البدء، تأكد من امتلاك:

• Node.js 20 أو أحدث
• مشروع Next.js 15 (App Router) — أو يمكنك إنشاء واحد في الخطوة 1
• مفتاح API لـ OpenAI أو Anthropic أو Google (أي مزود LLM يعمل)
• إلمام أساسي بـ TypeScript و React Server Components
• Docker Desktop إذا كنت تخطط لاستضافة Langfuse ذاتيًا (اختياري — Langfuse Cloud يعمل أيضًا)

ما ستبنيه

بنهاية هذا الدرس، سيكون لديك:

1. مسار دردشة Next.js AI مجهز بآثار Langfuse
2. التقاط تلقائي للرموز والتكاليف والزمن لكل نداء LLM
3. سجل موجهات يستطيع غير المطورين تحريره دون نشر
4. تقييم ملاحظات المستخدم (إبهام لأعلى / لأسفل) مرتبط بالآثار
5. خط أنابيب تقييم يعطي درجة للمخرجات عبر LLM كقاض
6. لوحات تحكم وتنبيهات جاهزة للإنتاج

هيا نبدأ.

الخطوة 1: اختيار السحابة أو الاستضافة الذاتية

يوفر Langfuse مسارين للنشر. اختر واحدًا:

الخيار A — Langfuse Cloud (الأسرع): سجل في cloud.langfuse.com، أنشئ مشروعًا، واحصل على مفاتيح API العامة والسرية. الطبقة المجانية تغطي 50 ألف ملاحظة شهريًا، وهذا كافٍ جدًا للتطوير.

الخيار B — الاستضافة الذاتية (تحكم أكبر): شغّل حزمة Docker Compose الرسمية محليًا أو على VPS خاص بك. استنسخ المستودع وشغّله:

git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up -d

سيكون Langfuse متاحًا على http://localhost:3000. أنشئ حسابًا ومشروعًا، وانسخ المفاتيح من صفحة إعدادات المشروع.

سنفترض في هذا الدرس استخدام Cloud، لكن كل مثال برمجي يعمل بشكل متطابق مع الاستضافة الذاتية — فقط LANGFUSE_BASEURL يتغير.

الخطوة 2: إنشاء تطبيق Next.js

تخطَ هذه الخطوة إذا كان لديك مشروع Next.js 15. وإلا:

npx create-next-app@latest langfuse-demo --typescript --app --tailwind
cd langfuse-demo
npm install ai @ai-sdk/openai zod

أضف أسرارك إلى .env.local:

OPENAI_API_KEY=sk-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASEURL=https://cloud.langfuse.com

لا تودع .env.local في Git أبدًا. أضفه إلى .gitignore إن لم يكن موجودًا.

الخطوة 3: تثبيت Langfuse SDK

يوفر Langfuse عدة SDKs. لـ Next.js مع Vercel AI SDK، ثبّت SDK JS الأساسي بالإضافة إلى تكامل Vercel AI SDK:

npm install langfuse langfuse-vercel

توفر حزمة langfuse-vercel مصدّرًا للقياس يرتبط تلقائيًا بنطاقات OpenTelemetry الخاصة بـ AI SDK. لا حاجة إلى تغليف يدوي للنطاقات.

الخطوة 4: تهيئة عميل Langfuse

أنشئ عميلًا مشتركًا في lib/langfuse.ts:

import { Langfuse } from "langfuse";
 
export const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  baseUrl: process.env.LANGFUSE_BASEURL,
  flushAt: 1,
});
 
export async function flushLangfuse() {
  await langfuse.flushAsync();
}

إعداد flushAt: 1 ممتاز للتطوير لكن يجب رفعه إلى 20 أو 50 في الإنتاج لتجميع نداءات الشبكة. استدعِ دائمًا flushLangfuse() في نهاية معالجات serverless — إذا تخطيت ذلك، يمكن أن تُفقد الأحداث عند تجميد Lambda.

الخطوة 5: تسجيل مصدّر القياس

في Next.js 15، يعيش تجهيز OpenTelemetry في instrumentation.ts في جذر المشروع. أنشئه:

import { registerOTel } from "@vercel/otel";
import { LangfuseExporter } from "langfuse-vercel";
 
export function register() {
  registerOTel({
    serviceName: "langfuse-demo",
    traceExporter: new LangfuseExporter({
      publicKey: process.env.LANGFUSE_PUBLIC_KEY,
      secretKey: process.env.LANGFUSE_SECRET_KEY,
      baseUrl: process.env.LANGFUSE_BASEURL,
    }),
  });
}

ثبّت أيضًا مساعد Vercel OpenTelemetry:

npm install @vercel/otel @opentelemetry/api

فعّل القياس في next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    instrumentationHook: true,
  },
};
 
module.exports = nextConfig;

على Next.js 15.1 والأحدث، يكون instrumentationHook مفعّلًا افتراضيًا وهذه الراية غير ضرورية — تحقق من إصدار Next قبل إضافتها.

الخطوة 6: بناء مسار دردشة متتبع

أنشئ app/api/chat/route.ts:

import { openai } from "@ai-sdk/openai";
import { streamText } from "ai";
import { after } from "next/server";
import { flushLangfuse } from "@/lib/langfuse";
 
export async function POST(req: Request) {
  const { messages, userId, sessionId } = await req.json();
 
  const result = streamText({
    model: openai("gpt-4o-mini"),
    messages,
    experimental_telemetry: {
      isEnabled: true,
      functionId: "chat-completion",
      metadata: {
        langfuseUserId: userId ?? "anonymous",
        langfuseSessionId: sessionId,
        tags: ["production", "chat"],
      },
    },
  });
 
  after(async () => {
    await flushLangfuse();
  });
 
  return result.toDataStreamResponse();
}

كتلة experimental_telemetry هي المفتاح. يقرأ Langfuse قيم langfuseUserId و langfuseSessionId و tags من البيانات الوصفية ويحولها إلى حقول من الدرجة الأولى يمكنك الفلترة عليها. المساعد after() من next/server يشغّل الإفراغ بعد إرسال الاستجابة، لذلك لن تؤخر المستخدم.

الخطوة 7: اختبار أول تتبع

شغّل خادم التطوير وأرسل طلبًا:

npm run dev

ثم من طرفية أخرى:

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{ "role": "user", "content": "اشرح التوليد المعزز بالاسترجاع في فقرة واحدة." }],
    "userId": "user-42",
    "sessionId": "demo-session"
  }'

افتح لوحة تحكم Langfuse. خلال ثوانٍ قليلة يجب أن ترى تتبعًا جديدًا يحوي الموجه الكامل، والاستجابة المبثوثة، واسم النموذج، وعدد الرموز، والتكلفة الإجمالية المحسوبة من جدول التسعير المباشر. انقر على التتبع لتوسيعه وسترى كل نطاق، بما في ذلك نداء OpenAI API المتداخل بالداخل.

الخطوة 8: إدارة الموجهات كأصول بإصدارات

كتابة الموجهات داخل الكود المصدري يجعل تعديلها بلا نشر مستحيلاً. يحل Langfuse ذلك بسجل موجهات.

اذهب إلى Prompts في لوحة التحكم وأنشئ موجهًا اسمه chat-system:

أنت مساعد تقني مختصر للمطورين.
أجب دائمًا بصيغة markdown. عند عرض الكود، استخدم كتل محاطة بوسم لغة.
التاريخ الحالي: {{today}}

يخزنه Langfuse كإصدار 1. اجلبه من المسار:

import { langfuse } from "@/lib/langfuse";
 
async function buildSystemMessage() {
  const prompt = await langfuse.getPrompt("chat-system", undefined, {
    cacheTtlSeconds: 60,
  });
 
  const compiled = prompt.compile({
    today: new Date().toISOString().split("T")[0],
  });
 
  return { role: "system" as const, content: compiled, promptRef: prompt };
}

ثم مرر مرجع الموجه إلى experimental_telemetry ليربط Langfuse التتبع بالإصدار الدقيق المستخدم:

const system = await buildSystemMessage();
 
const result = streamText({
  model: openai("gpt-4o-mini"),
  messages: [{ role: "system", content: system.content }, ...messages],
  experimental_telemetry: {
    isEnabled: true,
    functionId: "chat-completion",
    metadata: {
      langfusePrompt: system.promptRef.toJSON(),
    },
  },
});

الآن عندما يعدل زميل في الفريق الموجه عبر واجهة Langfuse، يستخدم كل طلب جديد النسخة المحدثة خلال 60 ثانية — دون نشر. وتعرض لك صفحة Prompts أي الإصدارات قيد الاستخدام حاليًا وكيف يؤدي كل إصدار على صعيد الزمن والجودة.

الخطوة 9: التقاط ملاحظات المستخدم

التتبع وحده نصف القصة فقط. تحتاج لمعرفة هل أعجبت الإجابة المستخدمين. أضف نقطة نهاية للملاحظات:

// app/api/feedback/route.ts
import { langfuse } from "@/lib/langfuse";
import { after } from "next/server";
 
export async function POST(req: Request) {
  const { traceId, value, comment } = await req.json();
 
  langfuse.score({
    traceId,
    name: "user-feedback",
    value: value === "up" ? 1 : 0,
    dataType: "NUMERIC",
    comment,
  });
 
  after(async () => {
    await langfuse.flushAsync();
  });
 
  return Response.json({ ok: true });
}

في الواجهة الأمامية، اعرض أزرار إبهام لأعلى / لأسفل بعد كل رسالة مساعد وأرسل POST إلى /api/feedback مع traceId الذي أعاده Langfuse في ترويسات الاستجابة. الآن كل تتبع يحمل إشارة جودة تستطيع الفلترة والتجميع عليها.

الخطوة 10: إضافة تقييمات LLM كقاض

الملاحظات اليدوية قيّمة لكن نادرة. لتسجيل كل محادثة تلقائيًا، اضبط مُقيّمًا من نوع LLM كقاض.

في لوحة تحكم Langfuse، اذهب إلى Evaluations، أنشئ مُقيّمًا جديدًا، واختر LLM-as-judge. استخدم قالبًا مثل:

قيّم استجابة المساعد من حيث الفائدة من 0 إلى 1.
ضع في اعتبارك: هل تجيب على سؤال المستخدم؟ هل هي دقيقة؟ هل هي مختصرة؟

سؤال المستخدم: {{input}}
إجابة المساعد: {{output}}

أعد JSON: { "score": number, "reasoning": string }

اختر أي آثار تُسجَّل — مثلًا كل الآثار الموسومة production في آخر 24 ساعة. يشغّل Langfuse المُقيّم في الخلفية ويرفق الدرجة بكل تتبع. يمكنك بعد ذلك رسم الفائدة عبر الزمن، مفصّلة حسب إصدار الموجه، للتحقق من أن تعديلاتك تحسّن الجودة فعلًا.

الخطوة 11: بناء لوحة تحكم إنتاجية

يسمح لك تبويب Dashboards بتأليف مخططات دون كتابة SQL. لوحات مفيدة لتثبيتها:

• التكلفة لكل يوم — اكتشاف انفلات الإنفاق مبكرًا
• زمن P95 حسب النموذج — كشف النماذج البطيئة قبل شكاوى المستخدمين
• استخدام الرموز حسب userId — تحديد المستخدمين الكثيفين الذين قد يحتاجون تحديد معدل
• معدل الأخطاء حسب إصدار الموجه — كشف الموجهات السيئة قبل أن تؤذي الجميع
• متوسط درجة الفائدة باليوم — تتبع انحراف الجودة

أضف تنبيه عتبة على التكلفة ومعدل الأخطاء. يستطيع Langfuse دفع التنبيهات إلى خطافات ويب Slack أو Discord عند تجاوز العتبة.

الخطوة 12: استخدام الجلسات لتجميع المحادثات

تمرير نفس langfuseSessionId عبر طلبات متعددة يجمعها في عرض محادثة واحد. لا غنى عنه عند تصحيح التدفقات متعددة الأدوار. في الواجهة الأمامية، أنشئ معرف جلسة مرة واحدة لكل محادثة (خزنّه في حالة المكوّن أو ملف تعريف ارتباط) وضمّنه في كل طلب /api/chat.

يعرض لك Langfuse حينها المخطط الزمني الكامل للمحادثة، والتكلفة التراكمية لكامل المحادثة، وأين تراكم زمن الاستجابة بين الأدوار.

الخطوة 13: إخفاء البيانات الشخصية قبل الإرسال

إذا كان تطبيقك يتعامل مع بيانات شخصية، يجب حجب المحتوى الحساس قبل أن يغادر خادمك. يدعم Langfuse دالة حجب:

import { Langfuse } from "langfuse";
 
export const langfuse = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  mask: (data) => {
    if (typeof data !== "string") return data;
    return data
      .replace(/\b[\w.-]+@[\w.-]+\.\w+\b/g, "[EMAIL]")
      .replace(/\b(\+?\d{1,3}[ -]?)?\(?\d{3}\)?[ -]?\d{3}[ -]?\d{4}\b/g, "[PHONE]");
  },
});

يعمل الحجب على المدخلات والمخرجات قبل إرسال الحدث. للامتثال الأصرم، شغّل مصنّف PII أقوى مثل Microsoft Presidio داخل دالة الحجب.

الخطوة 14: النشر إلى الإنتاج

بعض نصائح تقوية الإنتاج:

• تجميع الأحداث: ارفع flushAt إلى 20 و flushInterval إلى 5000 مللي ثانية. يقلل هذا حمل الشبكة بشدة.
• التعامل مع الإيقاف: على Vercel، يغطي مساعد after() الإفراغ. على خوادم Node طويلة الأمد، سجّل process.on("SIGTERM", flushLangfuse).
• فصل البيئات: استخدم مشروع Langfuse مختلف لكل بيئة (dev, staging, prod). يحافظ ذلك على لوحات تحكم نظيفة.
• تدوير الأسرار: يمكن تدوير مفاتيح Langfuse من إعدادات المشروع دون توقف. أدر كل ربع.
• أخذ العينات: إذا كان لديك حجم عالٍ جدًا، استخدم sampleRate: 0.1 على العميل لالتقاط 10 بالمئة فقط من الآثار. يمكنك دائمًا أخذ عينات أكثر على فئات مستخدمين محددة.

اختبار تطبيقك

قبل الإطلاق:

1. أرسل طلب دردشة. تأكد من ظهور تتبع بإصدار الموجه الصحيح ومعرف المستخدم والجلسة.
2. أرسل ملاحظة إبهام لأعلى. تأكد من إرفاق درجة بالتتبع.
3. حاكِ خطأ (ألغِ تعيين مفتاح OpenAI مؤقتًا). تأكد من التقاط Langfuse للخطأ مع تتبع المكدس الكامل.
4. حرّر الموجه عبر واجهة Langfuse. تأكد من استخدام الطلب التالي للإصدار الجديد خلال 60 ثانية.
5. تحقق من توافق أرقام التكلفة مع لوحة فواتير OpenAI بهامش نسبي قليل.

استكشاف الأخطاء

لا تظهر آثار في لوحة التحكم. تحقق من أن instrumentation.ts في جذر المشروع وأن experimental_telemetry.isEnabled يساوي true. شغّل بـ NODE_OPTIONS=--trace-warnings لاصطياد أخطاء المُصدّر.

تظهر الأحداث فقط بعد البدء البارد. نسيت استدعاء flushLangfuse() داخل after(). على Vercel، تتجمد وظائف serverless فور الاستجابة ولا تُرسل الأحداث المخزنة.

التكاليف تظهر صفرًا. النموذج الذي تستخدمه غير موجود بعد في فهرس تسعير Langfuse. أضف تسعيرًا مخصصًا في Settings, Models أو افتح PR على مستودع Langfuse.

إصدار الموجه لا يتحدث أبدًا. تحقق من أن cacheTtlSeconds ليس عاليًا جدًا في getPrompt(). سلوك الرجوع الافتراضي يقدم آخر نسخة معروفة للأبد إذا كانت واجهة API غير متاحة — تحقق جيدًا من اتصال الشبكة في منطقة النشر.

الخطوات التالية

• ادمج Langfuse مع حلقات وكلاء Vercel AI SDK لتتبع نداءات الأدوات والتسليمات
• أضف Langfuse إلى مشروع Claude Agent SDK لمراقبة موحدة
• اضبط حزمة Langfuse + Next.js جنبًا إلى جنب مع OpenTelemetry للآثار التطبيقية
• استكشف Langfuse Datasets لبناء مجموعة اختبارات انحدار تعمل مع كل تغيير موجه
• تكامل مع Inngest durable functions لتظهر سير العمل الخلفي أيضًا في عرض الآثار

الخلاصة

مراقبة LLM ليست اختيارية بمجرد أن يصل مستخدمون حقيقيون إلى تطبيق الذكاء الاصطناعي. يمنحك Langfuse الآثار والتكاليف وإدارة إصدارات الموجهات وملاحظات المستخدمين والتقييم المؤتمت في منصة واحدة مفتوحة المصدر تتصل بنظافة مع Next.js و Vercel AI SDK. يستغرق الإعداد أقل من ساعة، والعائد هو القدرة على الإجابة عن كل سؤال يمكن أن يطرحه مدير منتج أو مهندس أو عضو في فريق المالية عن نظام الذكاء الاصطناعي — ببيانات حقيقية بدلاً من التخمين.

اربطه مرة واحدة، وسيشكرك نفسك المستقبلي في أول مرة يتصرف فيها الإنتاج بشكل غير متوقع.