البدء باستخدام Langfuse (دليل 2026)

يأتي إنشاء ونشر التطبيقات التي تستخدم نماذج اللغات الكبيرة (LLMs) مع مجموعة المشاكل الخاصة بها. تمتلك LLMs طبيعة غير حتمية، ويمكن أن تولد معلومات معقولة ولكنها خاطئة، ويمكن أن يكون تتبع أفعالها في تسلسلات ملتوية أمرًا مزعجًا للغاية. في هذا الدليل، سنرى كيف يصبح Langfuse أداة أساسية لحل هذه المشكلات، من خلال تقديم أساس قوي لإمكانية المراقبة الكاملة والتقييم والتعامل الفوري مع تطبيقات LLM.

ما هو لانجفيوز؟

Langfuse عبارة عن منصة رائدة للمراقبة والتقييم وهي مفتوحة المصدر وتم إنشاؤها خصيصًا لتطبيقات LLM. إنه الأساس لتتبع وعرض وتصحيح جميع مراحل تفاعل LLM، بدءًا من المطالبة الأولية وانتهاءً بالاستجابة النهائية، سواء كانت مكالمة بسيطة أو محادثة معقدة متعددة المنعطفات بين الوكلاء.

لا تعد Langfuse أداة تسجيل فحسب، بل هي أيضًا وسيلة للتقييم المنهجي لأداء LLM، واختبار A/B للمطالبات، وجمع تعليقات المستخدمين مما يساعد بدوره على إغلاق حلقة التعليقات الضرورية للتحسين التكراري. النقطة الرئيسية لقيمتها هي الشفافية التي توفرها لعالم LLMs، مما يسمح للمطورين بما يلي:

• فهم سلوك LLM: تعرف على المطالبات الدقيقة التي تم إرسالها، والإجابات التي تم تلقيها، والخطوات الوسيطة في تطبيق متعدد المراحل.
• البحث عن القضايا: حدد موقع مصدر الأخطاء أو الأداء المنخفض أو المخرجات غير المتوقعة بسرعة.
• تقييم الجودة: يمكن قياس فعالية استجابات LLM مقابل المقاييس المحددة مسبقًا باستخدام التدابير اليدوية والآلية.
• تحسين وتحسين: يمكن استخدام الرؤى المستندة إلى البيانات لتحسين المطالبات والنماذج ومنطق التطبيق.
• التعامل مع المطالبات: التحكم في إصدار المطالبات واختبارها للحصول على أفضل LLM.

الميزات والمفاهيم الرئيسية

هناك العديد من الميزات الرئيسية التي يقدمها Langfuse مثل:

1. التتبع والرصد

يساعدنا Langfuse في التقاط الآثار التفصيلية لكل تفاعل تقوم به LLM. “التتبع” هو في الأساس تمثيل لطلب المستخدم الشامل أو تدفق التطبيق. ضمن التتبع، يُشار إلى وحدات العمل المنطقية بـ “الامتدادات” وتشير الاستدعاءات إلى LLM إلى “الأجيال”.

2. تقييم

يسمح Langfuse بالتقييم يدويًا وبرمجيًا أيضًا. يمكن للمطورين تحديد المقاييس المخصصة والتي يمكن بعد ذلك استخدامها لإجراء تقييمات لمجموعات بيانات مختلفة ومن ثم دمجها كمقيمين قائمين على LLM.

3. الإدارة الفورية

يوفر Langfuse تحكمًا مباشرًا في الإدارة السريعة بالإضافة إلى إمكانيات التخزين وإصدار الإصدارات. من الممكن اختبار مطالبات مختلفة من خلال اختبار A/B وفي نفس الوقت الحفاظ على الدقة عبر أماكن متنوعة، مما يمهد الطريق للتحسين السريع المستند إلى البيانات أيضًا.

4. جمع ردود الفعل

يستوعب Langfuse اقتراحات المستخدم ويدمجها مباشرة في مساراتك. ستكون قادرًا على ربط ملاحظات معينة أو تقييمات المستخدمين بتفاعل LLM الدقيق الذي أدى إلى الحصول على مخرجات، مما يمنحنا تعليقات في الوقت الفعلي لاستكشاف الأخطاء وإصلاحها وتحسينها.

لماذا لانجفيوز؟ المشكلة التي يحلها

تتميز أدوات مراقبة البرامج التقليدية بخصائص مختلفة جدًا ولا تفي بمعايير التطبيقات التي تدعمها LLM في الجوانب التالية:

• عدم الحتمية: لن تنتج LLMs دائمًا نفس النتيجة حتى بالنسبة لمدخلات مماثلة مما يجعل تصحيح الأخطاء أمرًا صعبًا للغاية. ويقوم Langfuse بدوره بتسجيل مدخلات ومخرجات كل تفاعل مما يعطي صورة واضحة عن العملية في تلك اللحظة.
• حساسية سريعة: أي تغيير طفيف في الموجه قد يغير إجابة LLM بالكامل. Langfuse موجود للمساعدة في تتبع الإصدارات السريعة بالإضافة إلى مقاييس أدائها.
• السلاسل المعقدة: تتميز غالبية تطبيقات LLM بمزيج من استدعاءات LLM المتعددة والأدوات المختلفة واسترجاع البيانات (على سبيل المثال، بنيات RAG). الطريقة الوحيدة لمعرفة التدفق وتحديد مكان الاختناق أو الخطأ هي التتبع. يقدم Langfuse جدولًا زمنيًا مرئيًا لهذه التفاعلات.
• الجودة الذاتية: غالبًا ما يكون مصطلح “الخير” لإجابة LLM مرادفًا للرأي الشخصي. يتيح Langfuse تقييمات الجودة الموضوعية (على سبيل المثال، زمن الوصول، وعدد الرموز المميزة) والذاتية (التعليقات البشرية، والتقييم القائم على LLM).
• إدارة التكلفة: إن الاتصال بـ LLM APIs له ثمن. سيكون فهم تكاليفك وتحسينها أسهل إذا كان لديك Langfuse لمراقبة استخدام الرمز المميز وحجم المكالمات.
• قلة الرؤية: المطور غير قادر على رؤية كيفية أداء تطبيقات LLM الخاصة به في السوق، وبالتالي يصعب عليه تحسين هذه التطبيقات تدريجيًا بسبب عدم إمكانية المراقبة.

لا يقدم Langfuse طريقة منهجية للتفاعل مع LLM فحسب، بل إنه يحول أيضًا عملية التطوير إلى نظام هندسي تكراري قائم على البيانات بدلاً من التجربة والخطأ.

الشروع في العمل مع لانجفيوز

قبل أن تتمكن من البدء في استخدام Langfuse، يجب عليك أولاً تثبيت مكتبة العميل وإعدادها لنقل البيانات إلى مثيل Langfuse، والذي يمكن أن يكون إما مستضافًا على السحابة أو مستضافًا ذاتيًا.

تثبيت

لدى Langfuse مكتبات عملاء متاحة لكل من Python وJavaScript/TypeScript.

عميل بايثون

pip install langfuse 

جافا سكريبت/عميل تايب سكريبت

npm install langfuse 

أو

yarn add langfuse 

إعدادات

بعد التثبيت، تذكر إعداد العميل باستخدام مفاتيح المشروع والمضيف. يمكنك العثور عليها في إعدادات مشروع Langfuse الخاص بك.

• public_key: هذا مخصص لتطبيقات الواجهة الأمامية أو للحالات التي يتم فيها إرسال بيانات محدودة وغير حساسة فقط.
• Secret_key: هذا مخصص للتطبيقات والسيناريوهات الخلفية التي تكون فيها إمكانية المراقبة الكاملة، بما في ذلك المدخلات/المخرجات الحساسة، مطلبًا.
• يستضيف: يشير هذا إلى عنوان URL الخاص بمثيل Langfuse الخاص بك (على سبيل المثال، https://cloud.langfuse.com).
• بيئة: هذه سلسلة اختيارية يمكن استخدامها للتمييز بين البيئات المختلفة (على سبيل المثال، الإنتاج والتجهيز والتطوير).

ولأسباب تتعلق بالأمان والمرونة، يعتبر تعريف هذه المتغيرات كمتغيرات بيئة من الممارسات الجيدة.

export LANGFUSE_PUBLIC_KEY="pk-lf-..." 
export LANGFUSE_SECRET_KEY="sk-lf-..." 
export LANGFUSE_HOST="https://cloud.langfuse.com" 
export LANGFUSE_ENVIRONMENT="development"

بعد ذلك، قم بتهيئة عميل Langfuse في تطبيقك:

مثال بايثون

from langfuse import Langfuse
import os

langfuse = Langfuse(public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),    secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),    host=os.environ.get("LANGFUSE_HOST"))

جافا سكريبت/مثال تايب سكريبت

import { Langfuse } from "langfuse";

const langfuse = new Langfuse({  publicKey: process.env.LANGFUSE_PUBLIC_KEY,  secretKey: process.env.LANGFUSE_SECRET_KEY,  host: process.env.LANGFUSE_HOST});

إعداد التتبع الأول الخاص بك

الوحدة الأساسية لإمكانية الملاحظة في Langfuse هي التتبع. يمثل التتبع عادةً تفاعل مستخدم واحد أو دورة حياة طلب كاملة. ضمن عملية التتبع، يمكنك تسجيل مكالمات LLM الفردية (التوليد) والخطوات الحسابية التعسفية (الامتداد).

دعونا نوضح ذلك باستدعاء LLM بسيط باستخدام OpenAI’s API.

مثال بايثون

import os
from openai import OpenAI
from langfuse import Langfuse
from langfuse.model import InitialGeneration

# Initialize Langfuse
langfuse = Langfuse(
    public_key=os.environ.get("LANGFUSE_PUBLIC_KEY"),
    secret_key=os.environ.get("LANGFUSE_SECRET_KEY"),
    host=os.environ.get("LANGFUSE_HOST"),
)

# Initialize OpenAI client
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

def simple_llm_call_with_trace(user_input: str):
    # Start a new trace
    trace = langfuse.trace(
        name="simple-query",
        input=user_input,
        metadata={"user_id": "user-123", "session_id": "sess-abc"},
    )

    try:
        # Create a generation within the trace
        generation = trace.generation(
            name="openai-generation",
            input=user_input,
            model="gpt-4o-mini",
            model_parameters={"temperature": 0.7, "max_tokens": 100},
            metadata={"prompt_type": "standard"},
        )

        # Make the actual LLM call
        chat_completion = client.chat.completions.create(
            model="gpt-4o-mini",
            messages=({"role": "user", "content": user_input}),
            temperature=0.7,
            max_tokens=100,
        )

        response_content = chat_completion.choices(0).message.content

        # Update generation with the output and usage
        generation.update(
            output=response_content,
            completion_start_time=chat_completion.created,
            usage={
                "prompt_tokens": chat_completion.usage.prompt_tokens,
                "completion_tokens": chat_completion.usage.completion_tokens,
                "total_tokens": chat_completion.usage.total_tokens,
            },
        )

        print(f"LLM Response: {response_content}")
        return response_content

    except Exception as e:
        # Record errors in the trace
        trace.update(
            level="ERROR",
            status_message=str(e)
        )
        print(f"An error occurred: {e}")
        raise

    finally:
        # Ensure all data is sent to Langfuse before exit
        langfuse.flush()


# Example call
simple_llm_call_with_trace("What is the capital of France?")

في النهاية، ستكون خطوتك التالية بعد تنفيذ هذا الرمز هي الانتقال إلى واجهة Langfuse. سيكون هناك تتبع جديد “استعلام بسيط” يتكون من جيل واحد “جيل openai”. من الممكن أن تنقر عليه لعرض المدخلات والمخرجات والنموذج المستخدم والبيانات التعريفية الأخرى.

الوظائف الأساسية بالتفصيل

يعد تعلم كيفية العمل مع كائنات التتبع والامتداد والتوليد هو المطلب الرئيسي للاستفادة من Langfuse.

تتبع مكالمات LLM

• langfuse.trace(): هذا الأمر يبدأ عملية تتبع جديدة. حاوية المستوى الأعلى للعملية بأكملها.
  • اسم: اسم التتبع وصفي للغاية.
  • مدخل: الإدخال الأول للإجراء بأكمله.
  • البيانات الوصفية: قاموس لأي أزواج ذات قيمة رئيسية للتصفية والتحليل (على سبيل المثال، user_id, session_id, AB_test_variant).
  • معرف الجلسة: (اختياري) معرف مشترك بين جميع التتبعات التي تأتي من نفس جلسة المستخدم.
  • معرف المستخدم: (اختياري) معرف مشترك بين جميع تفاعلات مستخدم معين.

• trace.span(): هذه خطوة منطقية أو عملية بسيطة ضمن تتبع لا يمثل تفاعلًا مباشرًا بين المدخلات والمخرجات مع LLM. يمكن تتبع استدعاءات الأدوات أو عمليات البحث في قاعدة البيانات أو الحسابات المعقدة بهذه الطريقة.
  • اسم: اسم النطاق (على سبيل المثال “retrieve-docs”، “parse-json”).
  • مدخل: المدخلات ذات الصلة بهذا النطاق.
  • الإخراج: الإخراج الذي تم إنشاؤه بواسطة هذا النطاق.
  • البيانات الوصفية: يتم تنسيق البيانات الوصفية الممتدة كبيانات إضافية.
  • مستوى: مستوى الخطورة (معلومات، تحذير، خطأ، تصحيح).
  • Status_message: رسالة مرتبطة بالحالة (مثل تفاصيل الخطأ).
  • parent_observation_id: يربط هذا الامتداد بالامتداد الأصلي أو التتبع للهياكل المتداخلة.

• trace.generation(): يدل على استدعاء LLM معين.
  • اسم: اسم الجيل (على سبيل المثال، “الاستجابة الأولية”، “خطوة التحسين”).
  • مدخل: المطالبة أو الرسائل التي تم إرسالها إلى LLM.
  • الإخراج: الرد الوارد من LLM.
  • نموذج: نموذج LLM الدقيق الذي تم استخدامه (على سبيل المثال، “gpt-4o-mini“،”إغلاق-3-العمل“).
  • model_parameters: قاموس لمعلمات نموذجية معينة (مثل temperature, max_tokens, top_p).
  • الاستخدام: قاموس يعرض عدد الرموز المستخدمة (prompt_tokens, completion_tokens, total_tokens).
  • البيانات الوصفية: بيانات تعريف إضافية لاستدعاء LLM.
  • parent_observation_id: يربط هذا الجيل بمدى أصل أو أثر.
  • اِسْتَدْعَى: (اختياري) يمكن تحديد قالب مطالبة معين يخضع للإدارة في Langfuse.

خاتمة

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

علاوة على ذلك، فهو يشجع المطورين على تصحيح أخطاء عملهم بشكل مؤكد، وتسريع عملية التكرار، ومواصلة تحسين منتجات الذكاء الاصطناعي الخاصة بهم من حيث الجودة والأداء. ومن ثم، توفر Langfuse الأدوات اللازمة للتأكد من أن تطبيقات LLM جديرة بالثقة وفعالة من حيث التكلفة وقوية حقًا، بغض النظر عما إذا كنت تقوم بتطوير chatbot أساسي أو وكيل مستقل متطور.

الأسئلة المتداولة