مراقبة نماذج اللغة مع Langfuse: تتبع وتصحيح وتحسين تطبيقات الذكاء الاصطناعي في Next.js (2026)

npm install langfuse openai

# OpenAI
OPENAI_API_KEY=sk-...
 
# Langfuse — من إعدادات مشروعك في cloud.langfuse.com
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_BASE_URL=https://cloud.langfuse.com

// lib/langfuse.ts
import { Langfuse } from "langfuse";
 
export const langfuse = new Langfuse({
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  baseUrl: process.env.LANGFUSE_BASE_URL ?? "https://cloud.langfuse.com",
  flushAt: 1,       // أرسل فورًا في بيئة serverless
  flushInterval: 0, // أوقف إرسال الدفعات المعتمد على المؤقت
});

// app/api/chat/route.ts
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { langfuse } from "@/lib/langfuse";
 
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
export async function POST(req: NextRequest) {
  const { messages, userId, sessionId } = await req.json();
 
  // 1. ابدأ تتبعًا لهذه الدورة
  const trace = langfuse.trace({
    name: "chat-turn",
    userId: userId ?? "anonymous",
    sessionId: sessionId ?? "default",
    input: { messages },
    tags: ["chat", process.env.NODE_ENV ?? "development"],
  });
 
  // 2. سجّل استدعاء النموذج كـ generation داخل التتبع
  const generation = trace.generation({
    name: "openai-gpt4o",
    model: "gpt-4o",
    modelParameters: {
      temperature: 0.7,
      maxTokens: 1024,
    },
    input: messages,
  });
 
  try {
    const response = await openai.chat.completions.create({
      model: "gpt-4o",
      messages,
      max_tokens: 1024,
      temperature: 0.7,
    });
 
    const content = response.choices[0].message.content ?? "";
 
    // 3. أغلق التوليد مع المخرجات واستخدام التوكن
    generation.end({
      output: content,
      usage: {
        promptTokens: response.usage?.prompt_tokens,
        completionTokens: response.usage?.completion_tokens,
        totalTokens: response.usage?.total_tokens,
      },
    });
 
    trace.update({ output: { content } });
 
    // 4. فرّغ قبل إنهاء الدالة
    await langfuse.flushAsync();
 
    return NextResponse.json({
      content,
      traceId: trace.id,
    });
  } catch (error) {
    generation.end({
      level: "ERROR",
      statusMessage: String(error),
    });
    await langfuse.flushAsync();
    throw error;
  }
}

// app/api/rag-chat/route.ts
import { NextRequest, NextResponse } from "next/server";
import OpenAI from "openai";
import { langfuse } from "@/lib/langfuse";
 
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
async function retrieveDocuments(query: string) {
  return [
    { id: "doc-1", content: "مقطع ذو صلة بالموضوع..." },
    { id: "doc-2", content: "مقطع آخر ذو صلة..." },
  ];
}
 
export async function POST(req: NextRequest) {
  const { query, userId, sessionId } = await req.json();
 
  const trace = langfuse.trace({
    name: "rag-chat",
    userId,
    sessionId,
    input: { query },
  });
 
  // النطاق 1: استرداد الوثائق
  const retrievalSpan = trace.span({
    name: "vector-retrieval",
    input: { query },
  });
  const documents = await retrieveDocuments(query);
  retrievalSpan.end({
    output: { documentCount: documents.length, documentIds: documents.map((d) => d.id) },
  });
 
  // النطاق 2: بناء السياق
  const contextSpan = trace.span({ name: "context-construction" });
  const context = documents.map((d) => d.content).join("\n\n");
  const messages: OpenAI.ChatCompletionMessageParam[] = [
    { role: "system", content: "أجب باستخدام السياق المقدم فقط." },
    { role: "user", content: `السياق:\n${context}\n\nالسؤال: ${query}` },
  ];
  contextSpan.end({ output: { tokenEstimate: context.length / 4 } });
 
  // النطاق 3: توليد الإجابة
  const generation = trace.generation({
    name: "answer-generation",
    model: "gpt-4o",
    input: messages,
  });
 
  const response = await openai.chat.completions.create({
    model: "gpt-4o",
    messages,
  });
 
  const answer = response.choices[0].message.content ?? "";
 
  generation.end({
    output: answer,
    usage: {
      promptTokens: response.usage?.prompt_tokens,
      completionTokens: response.usage?.completion_tokens,
      totalTokens: response.usage?.total_tokens,
    },
  });
 
  trace.update({ output: { answer } });
  await langfuse.flushAsync();
 
  return NextResponse.json({ answer, traceId: trace.id });
}

// app/api/feedback/route.ts
import { NextRequest, NextResponse } from "next/server";
import { langfuse } from "@/lib/langfuse";
 
export async function POST(req: NextRequest) {
  const { traceId, value, comment } = await req.json();
 
  // value: 1 للإعجاب، 0 لعدم الإعجاب
  langfuse.score({
    traceId,
    name: "user-feedback",
    value,
    comment: comment ?? undefined,
    dataType: "BOOLEAN",
  });
 
  await langfuse.flushAsync();
  return NextResponse.json({ ok: true });
}

// components/FeedbackButtons.tsx
"use client";
 
import { useState } from "react";
 
interface FeedbackButtonsProps {
  traceId: string;
}
 
export function FeedbackButtons({ traceId }: FeedbackButtonsProps) {
  const [submitted, setSubmitted] = useState<boolean | null>(null);
 
  const sendFeedback = async (value: 0 | 1) => {
    setSubmitted(value === 1);
    await fetch("/api/feedback", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ traceId, value }),
    });
  };
 
  if (submitted !== null) {
    return <p className="text-sm text-gray-500">شكرًا على ملاحظتك!</p>;
  }
 
  return (
    <div className="flex gap-2 mt-2">
      <button
        onClick={() => sendFeedback(1)}
        className="px-3 py-1 text-sm border rounded hover:bg-green-50"
      >
        👍 مفيد
      </button>
      <button
        onClick={() => sendFeedback(0)}
        className="px-3 py-1 text-sm border rounded hover:bg-red-50"
      >
        👎 غير مفيد
      </button>
    </div>
  );
}

// lib/prompts.ts
import { langfuse } from "@/lib/langfuse";
 
export async function getSystemPrompt(companyName: string): Promise<string> {
  const prompt = await langfuse.getPrompt("chat-system-prompt", undefined, {
    label: "production",
    cacheTtlSeconds: 60,
  });
 
  return prompt.compile({ company_name: companyName });
}

const promptObj = await langfuse.getPrompt("chat-system-prompt", undefined, {
  label: "production",
  cacheTtlSeconds: 60,
});
 
const systemPrompt = promptObj.compile({ company_name: "نقطة" });
 
const generation = trace.generation({
  name: "openai-gpt4o",
  model: "gpt-4o",
  input: [
    { role: "system", content: systemPrompt },
    ...messages,
  ],
  prompt: promptObj,
});

// lib/evaluators.ts
import { langfuse } from "@/lib/langfuse";
 
export async function evaluateResponse(
  traceId: string,
  generationId: string,
  output: string,
  expectedKeywords: string[]
): Promise<void> {
  // النتيجة 1: فحص طول الرد
  const lengthScore = output.split(" ").length > 20 ? 1 : 0;
 
  langfuse.score({
    traceId,
    observationId: generationId,
    name: "response-length-ok",
    value: lengthScore,
    dataType: "BOOLEAN",
  });
 
  // النتيجة 2: تغطية الكلمات المفتاحية
  const covered = expectedKeywords.filter((kw) =>
    output.toLowerCase().includes(kw.toLowerCase())
  ).length;
  const coverageScore = expectedKeywords.length > 0
    ? covered / expectedKeywords.length
    : 1;
 
  langfuse.score({
    traceId,
    observationId: generationId,
    name: "keyword-coverage",
    value: coverageScore,
    dataType: "NUMERIC",
    comment: `${covered}/${expectedKeywords.length} كلمات مفتاحية موجودة`,
  });
 
  await langfuse.flushAsync();
}

// lib/llm-judge.ts
import OpenAI from "openai";
import { langfuse } from "@/lib/langfuse";
 
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
 
export async function llmJudge(
  traceId: string,
  question: string,
  answer: string
): Promise<void> {
  const judgeTrace = langfuse.trace({ name: "llm-judge", tags: ["eval"] });
 
  const judgeGeneration = judgeTrace.generation({
    name: "judge-call",
    model: "gpt-4o-mini",
    input: [
      {
        role: "user",
        content: `قيّم الإجابة التالية على مقياس من 0 إلى 1 من حيث الدقة والفائدة. أعد كائن JSON فقط: {"score": 0.0, "reason": "..."}.
 
السؤال: ${question}
الإجابة: ${answer}`,
      },
    ],
  });
 
  const response = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    messages: [
      {
        role: "user",
        content: `قيّم الإجابة التالية على مقياس من 0 إلى 1 من حيث الدقة والفائدة. أعد كائن JSON فقط بمفتاحَي "score" و"reason".
 
السؤال: ${question}
الإجابة: ${answer}`,
      },
    ],
    response_format: { type: "json_object" },
  });
 
  const raw = response.choices[0].message.content ?? '{"score":0,"reason":"خطأ في التحليل"}';
  const parsed = JSON.parse(raw) as { score: number; reason: string };
 
  judgeGeneration.end({ output: parsed });
 
  langfuse.score({
    traceId,
    name: "llm-judge-quality",
    value: parsed.score,
    dataType: "NUMERIC",
    comment: parsed.reason,
  });
 
  await langfuse.flushAsync();
}

export function shouldTrace(sampleRate = 0.1): boolean {
  return Math.random() < sampleRate;
}

git clone https://github.com/langfuse/langfuse.git
cd langfuse
cp .env.example .env
# عدّل .env: حدد NEXTAUTH_SECRET وDATABASE_URL وSALT
docker compose up -d