خادم VPS لـ Langfuse: اعرف ما فعله وكلاؤك الأذكياء

قيمة الوكيل الذي يعمل في الثالثة فجرًا دون أن يراقبه أحد تساوي قدرتك على أن تعيد لاحقًا بناء ما فعله. «أحرق رموزًا بقيمة 38 دولارًا خلال الليل» صباح سيئ. «أحرق 38 دولارًا لأن أداة البحث أعادت صفحة فارغة فأعاد المخطِّط المحاولة 400 مرة» خطأ برمجي تصلحه قبل الغداء. الجملة الثانية تحتاج إلى تتبّعات.

يسجّل Langfuse كل استدعاء LLM وكل prompt وخطوة أداة وعدد الرموز وزمن الاستجابة على شكل شجرة يمكنك التنقل فيها بالنقر. وحين تستضيفه بنفسك، تبقى هذه الطلبات والردود — وفيها غالبًا بيانات العملاء ومخرجات API وأحيانًا سرّ تسلّل سهوًا — على خادم تتحكم فيه أنت، لا في لوحة شخص آخر.

تكلفة تشغيله

ليس Langfuse v4 ملفًا تنفيذيًا صغيرًا، بل ست حاويات: تطبيق الويب، وworker في الخلفية، وPostgres، وClickHouse للأحداث، وRedis، وMinIO للملفات. ثبّتناه على خادم اختبار وقِسنا نحو 3.5 GB من RAM قيد الاستخدام مع مشروع فارغ. ما يكبر هو ClickHouse، لأن كل span ترسله ينتهي هناك.

على الخطط الأصغر سيُثبَّت، ثم يتعثر ما إن يطلب ClickHouse والـworker الذاكرة في الوقت نفسه. لن أنزل شخصيًا عن 6 GB.

أين يعيش الوكلاء؟ إذا كانوا يعملون على أجهزة أخرى، فاختر خطة بعنوان IPv4 خاص بها: فهم يحتاجون إلى نقطة نهاية HTTPS، وفي خطة NAT لا يكون العنوان الصادر عنوانك الخاص ولا يُوصَل من الخارج إلا إلى منفذ SSH. وإذا كان الوكلاء يعملون على هذا الخادم نفسه، فلا داعي لأن يواجه Langfuse الإنترنت أصلًا: للتجربة تكفي خطة Medium مع NAT (‏12$ شهريًا). هناك موقعان، ألمانيا وفنلندا؛ ويظهر التوفر عند الطلب. اختر الأقرب إلى الوكلاء، لا إليك. يُدفع ثمن الخوادم بالعملات المشفّرة، دون KYC.

التثبيت

على خادم جديد بنظام Ubuntu 24.04 أو Debian 12، بصلاحيات root. أولًا Docker:

curl -fsSL https://get.docker.com | sh

ثم Langfuse، بأسرار حقيقية بدلًا من القيم الافتراضية في ملف compose:

git clone --depth 1 https://github.com/langfuse/langfuse.git
cd langfuse

PG=$(openssl rand -hex 16); MINIO=$(openssl rand -hex 16)
cat > .env <<EOF
NEXTAUTH_URL=https://langfuse.example.com
NEXTAUTH_SECRET=$(openssl rand -hex 32)
SALT=$(openssl rand -hex 32)
ENCRYPTION_KEY=$(openssl rand -hex 32)
POSTGRES_PASSWORD=$PG
DATABASE_URL=postgresql://postgres:$PG@postgres:5432/postgres
CLICKHOUSE_PASSWORD=$(openssl rand -hex 16)
MINIO_ROOT_PASSWORD=$MINIO
LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY=$MINIO
LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY=$MINIO
LANGFUSE_S3_BATCH_EXPORT_SECRET_ACCESS_KEY=$MINIO
REDIS_AUTH=$(openssl rand -hex 16)
TELEMETRY_ENABLED=false
EOF
chmod 600 .env

اثنتان من كلمات المرور هذه تأتيان في أزواج: كلمة مرور Postgres موجودة أيضًا داخل DATABASE_URL، وكلمة مرور MinIO يجب أن تطابق أسطر S3_..._SECRET_ACCESS_KEY الثلاثة. لهذا تأتي كل واحدة من متغيّر واحد.

والآن الفخ. ينشر ملف compose تطبيق الويب على المنفذ 3000 وMinIO على 9090 على جميع الواجهات، والمنافذ التي ينشرها Docker تتجاوز ufw. اربط الاثنين بـ localhost ليبقى الوكيل العكسي هو المدخل الوحيد:

sed -i 's/- 3000:3000/- 127.0.0.1:3000:3000/; s/- 9090:9000/- 127.0.0.1:9090:9000/' docker-compose.yml
docker compose up -d
curl -s http://127.0.0.1:3000/api/public/health

يجب أن يطبع الأمر الأخير {"status":"OK", ...}. في التشغيل الأول تُنفَّذ ترحيلات قاعدة البيانات؛ وفي اختبارنا نجح فحص الصحة بعد نحو 15 ثانية من تشغيل الحاويات.

‏HTTPS في الواجهة

وجّه langfuse.example.com إلى IP الخادم، ثم:

apt install -y caddy
cat > /etc/caddy/Caddyfile <<'EOF'
langfuse.example.com {
    reverse_proxy 127.0.0.1:3000
}
EOF
systemctl reload caddy
ufw allow 22/tcp && ufw allow 80/tcp && ufw allow 443/tcp && ufw enable

يحصل Caddy على الشهادة بنفسه. افتح الموقع، وأنشئ حسابك (يصبح أول مؤسسة)، وأضف مشروعًا، وانسخ مفتاحيه العام والسري.

بعد ذلك أغلق الباب خلفك. يفهم Langfuse المتغيّر AUTH_DISABLE_SIGNUP، لكن ملف compose الافتراضي لا يمرّره إلى حاوية web، لذا يلزم سطر إضافي تحت langfuse-web:

sed -i 's|^      NEXTAUTH_SECRET: \(.*\)$|      NEXTAUTH_SECRET: \1\n      AUTH_DISABLE_SIGNUP: ${AUTH_DISABLE_SIGNUP:-false}|' docker-compose.yml
echo "AUTH_DISABLE_SIGNUP=true" >> .env
docker compose up -d

من الآن فصاعدًا تتلقى أي محاولة تسجيل «Sign up is disabled». أما الزملاء فتضيفهم من داخل المشروع.

إرسال التتبّعات من وكيل

تغلّف مكتبة SDK للغة Python دوالّك، وتتحول الاستدعاءات المتداخلة إلى spans متداخلة:

python3 -m venv venv && . venv/bin/activate
pip install langfuse
export LANGFUSE_PUBLIC_KEY=pk-lf-...
export LANGFUSE_SECRET_KEY=sk-lf-...
export LANGFUSE_BASE_URL=https://langfuse.example.com

from langfuse import get_client, observe

langfuse = get_client()  # يقرأ متغيرات LANGFUSE_*

@observe(name="fetch-prices")
def fetch_prices(pair: str) -> dict:
    return {"pair": pair, "bid": 64210.5}

@observe(name="nightly-agent-run")
def run() -> str:
    data = fetch_prices("BTC/USDT")
    return f"done: {data['pair']}"

print(run())
langfuse.flush()  # السكربتات القصيرة تنتهي قبل أن يكتمل الإرسال في الخلفية

لا تتجاوز LANGFUSE_BASE_URL. من دونه يرسل SDK كل شيء بصمت إلى سحابة Langfuse، ومفاتيحك غير موجودة هناك، فتبقى تحدّق في لوحة فارغة.

للتحقق من الطرفية أن spans وصلت:

curl -s -u "$LANGFUSE_PUBLIC_KEY:$LANGFUSE_SECRET_KEY" \
  "$LANGFUSE_BASE_URL/api/public/v2/observations?limit=5"

في الإصدار v4 تردّ نقطة النهاية القديمة /api/public/traces بخطأ عن وضع events-only. هذا متوقع، وليس تثبيتًا معطّلًا. في وكيل حقيقي تغلّف استدعاء LLM وكل أداة بالطريقة نفسها؛ كما أن لدى Langfuse تكاملات مع مكتبات LLM الشائعة وأطر الوكلاء، فيكفي غالبًا تغيير سطر import بدلًا من نثر المزخرِفات في كل مكان.

ما يجب مراقبته

• القرص. يحتفظ ClickHouse وMinIO بكل ما ترسله. يُظهر docker system df -v أين ذهبت المساحة. إذا كنت تتتبّع طلبات وردودًا طويلة، فستمتلئ مساحة ‎45 GB في Medium-IP خلال أسابيع لا سنوات. افحصها مرة في الشهر؛ وحين تضيق، تتوفر خطة Pro بسعة 400 GB أو أكثر عند الطلب.
• التحديثات. يثبّت ملف compose الإصدار الرئيسي (:4). يجلب docker compose pull && docker compose up -d الإصلاحات ضمنه. اقرأ سجل التغييرات قبل الانتقال إلى إصدار رئيسي آخر: ففي v4 تحديدًا اختفت نقطة نهاية التتبّعات.
• النسخ الاحتياطية. ما يهم موجود في وحدات تخزين Docker: يحفظ Postgres المستخدمين والمشاريع والمفاتيح، ويحفظ ClickHouse وMinIO التتبّعات نفسها. انسخها إلى خارج الخادم وفق جدول.

هل يستحق 20$ شهريًا؟ إذا كان وكلاؤك ينفقون على الرموز أكثر من ذلك — وأغلب الوكلاء غير المراقَبين يفعلون — فإن معرفة أين ذهبت الرموز تسترد ثمنها في أول مرة تخرج فيها حلقة عن السيطرة. أما وكيل صغير يعمل مرة يوميًا فلا يحتاج إلى أي من هذا: يكفيه ملف سجل وعدّاد للرموز.

ذو صلة

• خادم VPS لوكلاء الذكاء الاصطناعي: حيث يعمل الوكلاء أنفسهم
• خادم VPS للأنظمة متعددة الوكلاء: تقدير موارد أسطول كامل
• خادم VPS لوكيل LiteLLM: بوابة واحدة لكل مفاتيح النماذج، مع حدود للإنفاق
• خطط Pro عند الطلب: من 32 إلى 80 GB RAM لأسطول من الوكلاء
• كيف تضبط جدار الحماية ufw