Langfuse: قابلية مراقبة LLM مفتوحة المصدر

Langfuse هي المنصة الرائدة مفتوحة المصدر لقابلية مراقبة LLM، تقدم التتبع والتقييم وإدارة المطالبات. في يونيو 2025، أصبحت ميزات Langfuse التجارية السابقة مفتوحة المصدر بما في ذلك تقييمات LLM كحكم، وقوائم انتظار التعليق، وساحة المطالبات تحت ترخيص MIT.

نظرة عامة على المعمارية

┌─────────────────────────────────────────────────────────────┐
│                     منصة Langfuse                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │                   لوحة الويب                         │   │
│  │  ┌──────────┐ ┌──────────┐ ┌────────────────────┐   │   │
│  │  │ التتبعات │ │ الجلسات  │ │ إدارة المطالبات   │   │   │
│  │  └──────────┘ └──────────┘ └────────────────────┘   │   │
│  │  ┌──────────┐ ┌──────────┐ ┌────────────────────┐   │   │
│  │  │ الدرجات │ │مجموعات   │ │ قوائم التعليق     │   │   │
│  │  └──────────┘ └──────────┘ └────────────────────┘   │   │
│  └─────────────────────────────────────────────────────┘   │
│                          ↑ REST API                         │
│  ┌─────────────────────────────────────────────────────┐   │
│  │          الخلفية (TypeScript/Node.js)                │   │
│  │      PostgreSQL + ClickHouse (التحليلات)             │   │
│  └─────────────────────────────────────────────────────┘   │
│                          ↑ SDKs                             │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌──────────┐   │
│  │  Python   │ │TypeScript │ │ LangChain │ │ LlamaIdx │   │
│  └───────────┘ └───────────┘ └───────────┘ └──────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

البداية السريعة مع Python SDK

التثبيت والإعداد

pip install langfuse

# تعيين متغيرات البيئة
export LANGFUSE_SECRET_KEY="sk-lf-..."
export LANGFUSE_PUBLIC_KEY="pk-lf-..."
export LANGFUSE_HOST="https://cloud.langfuse.com"  # أو مستضاف ذاتياً

التتبع الأساسي

from langfuse import Langfuse
from langfuse.decorators import observe, langfuse_context
from openai import OpenAI

langfuse = Langfuse()
client = OpenAI()

@observe()
def process_query(user_question: str) -> str:
    # تتبع توليد التضمين
    with langfuse_context.span(name="embedding") as span:
        embedding_response = client.embeddings.create(
            model="text-embedding-3-small",
            input=user_question
        )
        span.update(
            input=user_question,
            output={"dimensions": len(embedding_response.data[0].embedding)}
        )

    # تتبع إكمال LLM
    with langfuse_context.generation(name="completion") as gen:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=[
                {"role": "system", "content": "أنت مساعد مفيد."},
                {"role": "user", "content": user_question}
            ]
        )
        gen.update(
            model="gpt-4o",
            input=user_question,
            output=response.choices[0].message.content,
            usage={
                "prompt_tokens": response.usage.prompt_tokens,
                "completion_tokens": response.usage.completion_tokens
            }
        )

    return response.choices[0].message.content

# يتم التقاط التتبع تلقائياً
result = process_query("ما هي عاصمة فرنسا؟")

تتبع الجلسات للمحادثات

@observe()
def chat(messages: list, session_id: str, user_id: str):
    # الربط بالجلسة والمستخدم
    langfuse_context.update_current_trace(
        session_id=session_id,
        user_id=user_id,
        metadata={"source": "web_chat"}
    )

    response = client.chat.completions.create(
        model="gpt-4o",
        messages=messages
    )

    return response.choices[0].message.content

تقييمات LLM كحكم (مفتوح المصدر يونيو 2025)

يتضمن Langfuse الآن مقيمات LLM مدمجة:

from langfuse import Langfuse

langfuse = Langfuse()

# إنشاء قالب تقييم
langfuse.create_prompt(
    name="helpfulness-evaluator",
    prompt="""قيّم فائدة رد الذكاء الاصطناعي هذا على مقياس من 1-5.

سؤال المستخدم: {{question}}
رد الذكاء الاصطناعي: {{response}}

المعايير:
- 1: غير مفيد على الإطلاق، غير صحيح أو غير ذي صلة
- 2: مفيد بشكل ضئيل، يعالج السؤال جزئياً
- 3: مفيد بشكل معتدل، يعالج السؤال بشكل كافٍ
- 4: مفيد جداً، يعالج السؤال جيداً مع تفاصيل جيدة
- 5: مفيد للغاية، شامل وعميق

قدم تقييمك كرقم واحد.""",
    config={
        "model": "gpt-4o-mini",
        "temperature": 0
    }
)

# تشغيل التقييم الآلي على التتبعات
evaluation_results = langfuse.evaluate(
    evaluator_name="helpfulness-evaluator",
    trace_filter={
        "created_at": {"gte": "2026-01-01"},
        "tags": ["production"]
    },
    sample_size=100
)

وظائف المقيم المخصصة

from langfuse.decorators import observe

@observe(as_type="generation")
def evaluate_response(trace_id: str, response: str) -> dict:
    # منطق التقييم المخصص الخاص بك
    evaluation = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "قيّم الرد التالي..."},
            {"role": "user", "content": response}
        ]
    )

    score = extract_score(evaluation.choices[0].message.content)

    # تسجيل الدرجة إلى التتبع
    langfuse.score(
        trace_id=trace_id,
        name="custom-quality",
        value=score,
        comment="تقييم آلي"
    )

    return {"score": score}

قوائم انتظار التعليق (مفتوح المصدر يونيو 2025)

إنشاء سير عمل المراجعة البشرية:

# إنشاء قائمة انتظار التعليق
queue = langfuse.create_annotation_queue(
    name="low-confidence-reviews",
    description="مراجعة التتبعات حيث كانت ثقة النموذج منخفضة",
    filter={
        "metadata.confidence": {"lt": 0.7}
    }
)

# المراجعون يراجعون في لوحة التحكم ويضيفون درجات
# الدرجات ترتبط تلقائياً بالتتبعات

إدارة المطالبات

مطالبات متحكم بالإصدارات

# جلب مطالبة الإنتاج
prompt = langfuse.get_prompt("customer-support-v2")

# الاستخدام في تطبيقك
response = client.chat.completions.create(
    model=prompt.config["model"],
    messages=[
        {"role": "system", "content": prompt.compile()},
        {"role": "user", "content": user_message}
    ]
)

# ربط التوليد بإصدار المطالبة لاختبار A/B
with langfuse_context.generation(name="completion") as gen:
    gen.update(prompt=prompt)

الاستضافة الذاتية لـ Langfuse

# docker-compose.yml للاستضافة الذاتية لـ Langfuse
version: "3.8"
services:
  langfuse:
    image: langfuse/langfuse:latest
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/langfuse
      - CLICKHOUSE_URL=http://clickhouse:8123
      - NEXTAUTH_SECRET=${NEXTAUTH_SECRET}
      - SALT=${SALT}
    depends_on:
      - db
      - clickhouse

  db:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=langfuse
    volumes:
      - postgres_data:/var/lib/postgresql/data

  clickhouse:
    image: clickhouse/clickhouse-server:latest
    volumes:
      - clickhouse_data:/var/lib/clickhouse

volumes:
  postgres_data:
  clickhouse_data:

التكامل مع LangChain

from langchain_openai import ChatOpenAI
from langchain.callbacks import LangfuseCallbackHandler

# التتبع التلقائي لـ LangChain
handler = LangfuseCallbackHandler(
    public_key="pk-lf-...",
    secret_key="sk-lf-..."
)

llm = ChatOpenAI(
    model="gpt-4o",
    callbacks=[handler]
)

# جميع عمليات LangChain يتم تتبعها
response = llm.invoke("ما هو التعلم الآلي؟")

:::