استضافة ‫Langfuse‬ على ‫VPS‬: مراقبة ‫LLM‬ بلا فاتورة ‫SaaS‬

أدوات ‫APM‬ التقليدية (‫Datadog‬ و‫New Relic‬) تلتقط كمون ‫HTTP‬ ومعدلات الأخطاء — لكنها عمياء أمام ما يحدث داخل استدعاء ‫LLM‬. استجابة تصل في 800 ميلي ثانية قد تكون لا تزال خاطئة واقعيًا، أو مبهمة بلا فائدة، أو ثلاثة أضعاف تكلفة استجابة الأمس لأن انتكاسة ‫prompt‬ تسللت دون أن يلاحظها أحد في مراجعة الكود. يحلّ ‫Langfuse‬ هذه المشكلة بمعاملة كل تفاعل مع ‫LLM‬ باعتباره ‫trace‬ منظّمًا: يسجّل الـ ‫prompt‬ الكامل (بما في ذلك رسالة النظام وتاريخ المحادثة) والاستجابة والنموذج المستخدم وعدد الرموز وتفصيل الكمون لكل نطاق وأي درجات تقييم يرفقها فريقك. يمكنك بعد ذلك تصفية أي ‫trace‬ ومقارنته واستنساخه — بشكل فردي أو مجمّع.

يأتي ‫Langfuse v3‬ كـ ‫stack Docker Compose‬ من ستة خدمات: langfuse (واجهة ‫Next.js‬ الأمامية + ‫API‬) وlangfuse-worker (وظائف الخلفية والتقييمات) وpostgres (حالة التطبيق) وclickhouse (تحليلات ‫traces‬ — تخزين عمودي محسّن للسلاسل الزمنية عالية الكثافة) وredis (قائمة انتظار وذاكرة تخزين مؤقت) وminio (تخزين كائنات متوافق مع ‫S3‬ للمرفقات الوسائطية). ‫ClickHouse‬ هو سبب الحدّ الأدنى البالغ 4 GB: يحتاج مترجمه ‫JIT‬ ومحرك التنفيذ المتجّه إلى مساحة كافية. في الخادم الهادئ تستهلك المجموعة الكاملة نحو 1.5-2 GB في وضع الخمول؛ لحركة مرور إنتاجية معتدلة خطّط لـ 4 GB، ومع 8 GB للتتبّع المستمر عالي الإنتاجية.

يقوم تثبيت ‫ServOrbit Marketplace‬ بتهيئة ‫nginx‬ وشهادة ‫TLS‬ تلقائيًا. إذا كنت تُعدّ يدويًا، إليك النقاط الحرجة.

‫Reverse proxy nginx‬. يستمع ‫Langfuse‬ على المنفذ 3000. يجب أن يعيد ‫vhost nginx‬ توجيه هذا المنفذ ويُرسل الترويسات الضرورية لـ ‫NextAuth‬:

server {
    listen 443 ssl;
    server_name your-domain.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

إذا لم يُرسَل X-Forwarded-Proto، يولّد ‫NextAuth‬ روابط ‫callback‬ عبر http:// ولا تُرفق ملفات تعريف ارتباط الجلسة على استجابة ‫HTTPS‬ — العَرَض: حلقة إعادة توجيه بعد تسجيل الدخول.

متغيرات البيئة الأساسية. يحتوي ملف .env للـ ‫stack‬ على ثلاثة متغيرات يجب تخصيصها قبل التشغيل الأول:

- NEXTAUTH_SECRET: سلسلة عشوائية طويلة (32 حرفًا كحدٍّ أدنى). بدونها لا تستمر الجلسات عبر إعادة التشغيل.
- NEXTAUTH_URL: عنوان ‫URL‬ العلني الكامل لمثيلك (https://your-domain.com). يجب أن يطابق نطاق ‫nginx‬ تمامًا.
- LANGFUSE_INIT_ORG_ID وLANGFUSE_INIT_PROJECT_ID وLANGFUSE_INIT_PROJECT_PUBLIC_KEY وLANGFUSE_INIT_PROJECT_SECRET_KEY: اختيارية، لكنها مفيدة لتوفير المؤسسة والمشروع عند التشغيل الأول دون واجهة المستخدم.

‫TLS‬. تستخدم عمليات نشر ‫ServOrbit‬ ‫Let's Encrypt‬ عبر ‫certbot‬ في وضع ‫DNS-01‬ — لا حاجة لفتح المنفذ 80. إذا هيّأت الشهادة يدويًا، أشر توجيهات ssl_certificate وssl_certificate_key إلى الملفات الصادرة عن ‫certbot‬ وفعّل التجديد التلقائي.

يوفّر ‫Langfuse‬ اثنين من ‫SDK‬ الرسميين يغطيان أبرز أطر عمل الوكلاء.

‫Python‬ — مزخرف @observe().
أبسط طريقة لتتبّع وكيل:

from langfuse.decorators import observe, langfuse_context

@observe()
def run_agent(user_message: str) -> str:
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": user_message}]
    )
    return response.choices[0].message.content

كل دالة متداخلة مزخرفة بـ @observe() تظهر كـ ‫span‬ فرعي في نفس الـ ‫trace‬. لإرفاق بيانات وصفية:

langfuse_context.update_current_trace(
    user_id="user-42",
    session_id="session-abc",
    tags=["production", "agent-v2"]
)

‫LangChain‬. التكامل الأصلي يُفعَّل بسطر واحد:

from langfuse.callback import CallbackHandler
handler = CallbackHandler()
chain.invoke({"input": query}, config={"callbacks": [handler]})

‫TypeScript / JavaScript‬.
تهيئة العميل:

import Langfuse from "langfuse";
const lf = new Langfuse({
  publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
  secretKey: process.env.LANGFUSE_SECRET_KEY!,
  baseUrl: process.env.LANGFUSE_HOST,
});

إنشاء ‫trace‬ وجيل:

const trace = lf.trace({ name: "agent-run", userId: "user-42" });
const generation = trace.generation({ name: "llm-call", model: "gpt-4o", input: messages });
// … استدعاء LLM …
generation.end({ output: result, usage: { input: 120, output: 45 } });
await lf.shutdownAsync();

يؤثّر خلل نشط على واجهة ‫Tracing v4‬ في ‫Langfuse‬ (مُتابَع في ‫issue #16077‬، 17 تعليقًا في أغسطس 2026): يعرض عمود Cost ($) دائمًا $0.00 لجميع الـ ‫traces‬.

السبب بنيوي. تقرأ الواجهة ‫v4‬ التكلفة على الملاحظة الجذرية (‫SPAN‬) — لا يحمل ‫SPAN‬ تكلفة ذاتية. التكلفة الفعلية موزّعة على ‫GENERATION‬ الأبناء، لكن الواجهة لا تجمعها.

بياناتك سليمة. ثلاثة حلول مؤقتة:

1. تبويب ‫Analytics / Metrics‬ — يحسب التكاليف على جميع عمليات التوليد.

2. التصفية حسب ‫GENERATION‬ في ‫Traces‬ — أضف observation_type = GENERATION. كل صف يعرض تكلفته الحقيقية.

3. فتح لوحة تفاصيل الـ ‫trace‬ — تعرض التوزيع الكامل بالتكاليف الصحيحة.

الـ ‫issue‬ مفتوحة ومتابَعة من فريق ‫Langfuse‬.

1. حاوية langfuse لا تبدأ — Error: NEXTAUTH_SECRET مفقود.
تحقق من ملف .env:

docker compose config | grep NEXTAUTH_SECRET

إذا كان السطر غائبًا أو فارغًا، أنشئ قيمة وأعد التشغيل:

openssl rand -base64 32
# الصق النتيجة في .env: NEXTAUTH_SECRET=<value>
docker compose up -d langfuse

2. رفض الاتصال بقاعدة البيانات — ECONNREFUSED postgres:5432.
هذا في الغالب مشكلة توقيت عند بدء التشغيل. تأكد من أن docker-compose.yml يُعلن depends_on مع condition: service_healthy لخدمة postgres. تفقّد سجلات ‫postgres‬ إذا استمرت المشكلة:

docker compose logs postgres --tail=50

3. لا تظهر ‫traces‬ في لوحة التحكم.
تحقق: (أ) هل متغيرات البيئة LANGFUSE_HOST وLANGFUSE_PUBLIC_KEY وLANGFUSE_SECRET_KEY مضبوطة في تطبيقك؟ (ب) هل يشير ‫host‬ إلى عنوان ‫URL‬ ‫HTTPS‬ العلني لا إلى localhost:3000؟ (ج) هل ‫Python SDK‬ يُفرغ مخزنه المؤقت قبل انتهاء العملية (langfuse.flush())؟

اختبار سريع:

from langfuse import Langfuse
lf = Langfuse()
lf.trace(name="test-connection")
lf.flush()
print("تم إرسال الـ trace — تحقق من لوحة التحكم.")

4. حلقة إعادة توجيه بعد تسجيل الدخول.
السبب الأكثر شيوعًا: NEXTAUTH_URL لا يطابق النطاق المستخدم، أو لم يُرسَل X-Forwarded-Proto من ‫nginx‬. تحقق من أن NEXTAUTH_URL=https://your-domain.com وأن إعداد ‫nginx‬ يتضمن proxy_set_header X-Forwarded-Proto $scheme;.

5. ‫ClickHouse‬ يستهلك كل ذاكرة ‫RAM‬ المتاحة.
حدّ استهلاك الذاكرة بإضافة إلى .env:

CLICKHOUSE_MAX_MEMORY_USAGE=2000000000

هذه القيمة (2 GB) نقطة بداية معقولة لـ ‫VPS‬ بـ 8 GB يُشغّل ‫Langfuse‬ وحده.

‫Langsmith‬ (منتج ‫LangChain‬ المستضاف) و‫Helicone‬ هما البديلان السحابيان الرئيسيان. كلاهما ممتاز — وكلاهما يتطلب توجيه ‫traces‬ الخاصة بك عبر خوادمهم. للفرق التي تتعامل مع ‫prompts‬ حساسة (قانونية، مالية، طبية)، أو لبيئات الامتثال التي تحظر تسرّب البيانات إلى طرف ثالث، الاستضافة الذاتية ليست خيارًا. يمنحك ‫Langfuse‬ نفس مجموعة الميزات (التتبّع، التقييمات، إدارة الـ ‫prompts‬، تحليلات التكاليف) على بنية تحتية تتحكم فيها.