الذكاء الاصطناعي المحلي في ONLYOFFICE مع Ollama أو vLLM: البنية والإعداد والمراقبة

الذكاء الاصطناعي المحلي في ONLYOFFICE: اربط Docs 10.0 بـ Ollama أو vLLM، واضبط aiSettings والوسيط /ai-proxy، وراقب TTFT وStatsD عبر OpenTelemetry.
ONLYOFFICE IA locale avec Ollama ou vLLM : architecture, configuration et supervision

الذكاء الاصطناعي المحلي في ONLYOFFICE يعني تلخيص مستند أو ترجمته من دون أن يغادر أي بايت الشبكة. وبالنسبة إلى فريق التشغيل هو قبل كل شيء مسار حرج جديد: محرر ويب، ووسيط (relay) من جهة الخادم، ومحرك استدلال على GPU. وحين ينقر مستخدم على «Summarize» ولا يأتي شيء، يجب أن تعرف أي حلقة من الثلاث انقطعت.

يصف هذا المقال بنية ONLYOFFICE Docs 10.0 (الإصدار الموثّق وقت الكتابة) موصولًا بـ Ollama أو vLLM، وإعدادات الخادم المهمة، ثم المراقبة من البداية إلى النهاية. كل الإعدادات المذكورة مأخوذة من وثائق ONLYOFFICE وvLLM وOllama. وفي ما يخص Dynatrace فالطريقة تصلح لـ Dynatrace SaaS وكذلك لـ Dynatrace Managed: لا يتغير سوى عنوان OTLP.

إذا كنت تبدأ من الصفر مع النماذج المحلية، فابدأ بـ تثبيت Ollama ومراقبته أو بـ vLLM في الإنتاج؛ نفترض هنا أن المحرك جاهز.

البنية: الذكاء الاصطناعي المحلي في ONLYOFFICE بثلاث حلقات

تعيش ميزات الذكاء الاصطناعي في ONLYOFFICE داخل إضافة (plugin) تسمى AI Tools في سجل تغييرات الإصدار 10.0. تعمل الإضافة داخل المحرر، أي في متصفح المستخدم. ويمكنها الوصول إلى النموذج بطريقتين:

  • مباشرة من المتصفح: يخرج الطلب من جهاز المستخدم إلى Ollama. ولهذه الحالة تطلب الوثائق ضبط OLLAMA_ORIGINS (ترويسات CORS)؛
  • عبر الوسيط /ai-proxy في خادم Docs: تصف وثائق إعداد الخادم نقطة الدخول هذه ومهلتها (aiSettings.timeout) وأن الطلبات الصادرة تمر عبر مرشح externalRequest.

الاختيار يغيّر كل شيء في المراقبة. في الوصول المباشر لا يرى خادم Docs شيئًا يمر، ويجب أن يصل كل جهاز إلى المحرك. وعبر الوسيط يصبح خادم Docs نقطة عبور وحيدة: تقرأ فيه الأخطاء وتطبق الترشيح، ولا يلزم أن يكون المحرك قابلًا للوصول إلا من الخادم.

ولا يتصل Ollama وvLLM بالطريقة نفسها. يظهر Ollama في قائمة مزودي الإضافة: تُدخل عنوان URL أساسيًا (http://localhost:11434 في الدليل الرسمي) بدل مفتاح API. أما vLLM فيعرض واجهة API متوافقة مع OpenAI تحت /v1؛ ولا تذكر وثائق ONLYOFFICE vLLM، لكنها تصف إضافة مزود مخصص عبر ملف JavaScript يوسّع AI.Provider بعنوان URL ومفتاح اختياري ولاحقة مثل v1. وهذا هو المسار الذي يجب اختباره مع vLLM.

إعدادات الخادم التي يجب معرفتها

يقرأ ONLYOFFICE Docs إعداداته بواسطة node-config من /etc/onlyoffice/documentserver/ على Linux. لا تعدّل default.json: ضع قيمك في local.json الذي يتجاوزه. أربع كتل تخص الذكاء الاصطناعي ومراقبته.

مقتطفات من وثائق ONLYOFFICE Server configuration: كتلة statsd بالقيمة useMetrics false والمنفذ 8125 والبادئة ds.، وكتلة aiSettings بالحقول enable وtimeout بقيمة 5m وallowedCorsOrigins وallowBrowserProxy، وكتلة externalRequest.action بالقيمة blockPrivateIP true
  • aiSettings.enable (القيمة الافتراضية true): عند false تُزال الإضافة من /plugins.json وتتلقى طلبات /ai-proxy الرمز HTTP 403. إنه مفتاح الطوارئ.
  • aiSettings.timeout ("5m"): مهلة الوسيط. قد يبلغها نموذج بطيء على CPU.
  • aiSettings.allowBrowserProxy (true): يمرّر الوسيط أيضًا طلبًا لا يطابق هدفه أي مزود مهيأ، مثل خادم MCP معرَّف في المتصفح. لا يضيف الخادم أي معرّف، ويشترط رمز جلسة صالحًا، ولا يقبل إلا أهدافًا مطلقة بـ http أو https. وعند false تتلقى هذه الطلبات 403.
  • externalRequest.action.blockPrivateIP (true): عناوين IP الخاصة محجوبة. فقد يرفض الوسيط محركًا موضوعًا على 10.x أو 192.168.x. وتخفيف هذا قرار أمني، يُتخذ مع فريق الشبكات.
  • statsd.useMetrics (false) وstatsd.host وstatsd.port ("8125") وstatsd.prefix ("ds."): تصدير مقاييس خادم Docs.

أما معامل التكامل editorConfig.customization.ai.disabled المضاف في 10.0 فيعطّل الذكاء الاصطناعي لفتح مستند محدد. ويمكن أيضًا إدخال مفاتيح النماذج وإعداداتها في صفحة /info بالخادم منذ الإصدار 9.0.

عمليًا: الربط والتحقق

الخطوة 1 — فتح Ollama للمحرر

إذا كانت الإضافة تستدعي Ollama من المتصفح، فيجب أن يعيد Ollama ترويسات CORS الصحيحة. تقدّم وثائق ONLYOFFICE إجراء systemd وأمر التحقق:

أوامر من وثائق ONLYOFFICE Configuring Ollama with CORS: systemctl edit ollama مع OLLAMA_ORIGINS، ثم إعادة التشغيل، ثم طلب OPTIONS على /api/tags والاستجابة المتوقعة 204 مع ترويسات Access-Control-Allow

الرمزان الشاملان http://* وhttps://* يناسبان جهاز اختبار لا خادمًا مشتركًا: توصي الصفحة نفسها بسرد الأصول (origins) صراحةً في الإنتاج. وافتراضيًا يستمع Ollama على localhost فقط؛ وفتحه على الشبكة (OLLAMA_HOST=0.0.0.0) يفرض بحسب الوثائق خادمًا وكيلًا عكسيًا مع TLS ومصادقة.

الخطوة 2 — تشغيل vLLM بمفتاح

vllm serve NousResearch/Meta-Llama-3-8B-Instruct \
  --dtype auto \
  --api-key token-abc123

curl http://localhost:8000/v1/models -H "Authorization: Bearer token-abc123"

يستمع vLLM افتراضيًا على http://localhost:8000. انتبه: تنص الوثائق على أن --api-key (أو VLLM_API_KEY) لا يحمي سوى المسارات /v1 و/v2 و/inference؛ ويبقى /invocations مفتوحًا. ضع vLLM خلف خادم وكيل عكسي ولا تعرض المنفذ مباشرةً للأجهزة.

الخطوة 3 — التقييد وضبط الوسيط

{
  "aiSettings": {
    "timeout": "2m",
    "allowBrowserProxy": false
  },
  "statsd": {
    "useMetrics": true,
    "host": "localhost",
    "port": "8125",
    "prefix": "ds."
  }
}

يقصّر ملف local.json هذا المهلة (فالفشل السريع أفضل من مستخدم ينتظر خمس دقائق)، ويقطع الوسيط نحو الأهداف غير المعلنة، ويفعّل StatsD. وإيقاف allowBrowserProxy يعطّل أيضًا الأهداف المهيأة في المتصفح، مثل خادم MCP: تحقق من أن أحدًا لا يستخدمها. أعد تشغيل خدمات Docs بعد التعديل.

الخطوة 4 — التحقق من كل حلقة

# Serveur Docs : bases, broker, Redis et stockage (réponse attendue : true)
curl -s https://docs.example.com/healthcheck

# Ollama : modèles disponibles
curl -s http://localhost:11434/api/tags

# vLLM : métriques Prometheus
curl -s http://localhost:8000/metrics | grep vllm:time_to_first_token_seconds

يفحص /healthcheck بحسب الوثائق قواعد البيانات ووسيط الرسائل وRedis والتخزين؛ ولا يختبر محرك الذكاء الاصطناعي. فتلزم إذن مجسّة خاصة بالمحرك.

مراقبة السلسلة بواسطة OpenTelemetry وDynatrace

يستطيع OpenTelemetry Collector واحد جمع المصدرين: مستقبِل statsd من توزيعة contrib (استقرار beta، ويستمع افتراضيًا على localhost:8125 عبر UDP) لـ ONLYOFFICE، ومستقبِل prometheus لـ vLLM. ومكونات Collector وصيغة التصدير مفصلة في مكونات Collector contrib.

receivers:
  statsd:
    endpoint: localhost:8125
  prometheus:
    config:
      scrape_configs:
        - job_name: vllm
          static_configs:
            - targets: ["localhost:8000"]
exporters:
  otlphttp:
    endpoint: https://<env-id>.live.dynatrace.com/api/v2/otlp   # SaaS
    # Managed : https://<votre-domaine>/e/<env-id>/api/v2/otlp
    headers:
      Authorization: "Api-Token ${env:DT_API_TOKEN}"
service:
  pipelines:
    metrics:
      receivers: [statsd, prometheus]
      exporters: [otlphttp]

يجب أن يحمل الرمز المميز النطاق metrics.ingest. وفي جهة vLLM تكفي ثلاثة مقاييس للوحة معلومات أولى: vllm:time_to_first_token_seconds وvllm:e2e_request_latency_seconds وvllm:num_requests_waiting. ويبيّن مخطط وثائق تصميم vLLM ما يقيسه كل منها:

مخطط من وثائق vLLM عن فترات الطلب: الطابور ثم prefill ثم decode في Engine Core، وقياس TTFT من جهة API Server، وزمن التأخر بين الرموز ITL
Source : github.com

TTFT هو ما يحسّه المستخدم في المحرر: التأخر قبل أن يبدأ النص بالظهور. وارتفاع الطابور (num_requests_waiting) مع صعود TTFT يدل على GPU مشبعة لا على عطل في ONLYOFFICE. أما Ollama الذي لا يعرض هذه المدرجات التكرارية، فتعيد فيه مجسّة اصطناعية على /api/generate القيم total_duration وeval_count وeval_duration بالنانوثانية.

هدف مستوى خدمة (SLO) يفهمه الدعم

صِغ الهدف من وجهة نظر المستخدم: «95% من طلبات التلخيص تنتج أول كلمة في أقل من 3 ثوان على مدى 28 يومًا». العتبة مثال يجب معايرته على عتادك. يُستخدم TTFT في vLLM مؤشرَ مستوى خدمة (SLI)؛ ويفيد الرمز 403 من /ai-proxy و/healthcheck في التشخيص. وبهذه الإشارات الثلاث تعرف المناوبة (on-call) في دقيقة هل المشكلة في الشبكة أم في خادم Docs أم في المحرك، فيقل MTTR.

أفضل الممارسات

  • فضّل الوسيط /ai-proxy على الوصول المباشر: مسار شبكي واحد ونقطة ترشيح واحدة.
  • أبقِ blockPrivateIP مفعّلًا ما لم يبرر تحليل الشبكة استثناءً.
  • قلّل aiSettings.timeout لتفشل سريعًا بدل أن تعطّل المحرر.
  • لا تعتمد على --api-key وحده مع vLLM: الخادم الوكيل العكسي إلزامي.
  • وثّق مفتاح aiSettings.enable في دليل تشغيل الحوادث (runbook).
  • راقب المحرك على حدة: /healthcheck لا يغطيه.

الأسئلة الشائعة

هل يعمل الذكاء الاصطناعي المحلي في ONLYOFFICE مع النسخة المتصفحية؟

تتناول الصفحة الحالية عن وكيل الإضافة Ollama وLM Studio مزودين محليين يُدخلان بعنوان URL، دون تمييز بين سطح المكتب والويب. وكان دليل قديم يقصر Ollama على Desktop Editors: اختبر على إصدارك قبل إعلان ذلك للمستخدمين.

هل يمكن ربط vLLM دون مزود مخصص؟

لا تذكر وثائق ONLYOFFICE vLLM. والمزود المخصص (ملف JavaScript يوسّع AI.Provider) هو المسار الموثّق لواجهة API متوافقة مع OpenAI.

هل يرسل خادم Docs تتبعات؟

توثّق الإعدادات تصدير StatsD، لا تتبعات OpenTelemetry. وتُبنى التتبعات الشاملة من جهة المحرك أو بمجسّة اصطناعية.

الخلاصة

يُبقي الذكاء الاصطناعي المحلي في ONLYOFFICE المستندات عندك، لكنه يضيف محرك استدلال إلى المسار الحرج لأدوات المكتب. اختر وسيط الخادم، وأبقِ المرشحات الافتراضية، وقصّر المهلة، وتابع TTFT مؤشرًا رئيسيًا. ولتحديد موضع هذا المكوّن في الصورة الكاملة، راجع مكدس الذكاء الاصطناعي مفتوح المصدر المستضاف ذاتيًا، ولأهداف MCP في الوسيط راجع تأمين خادم MCP. المراجع: إعداد خادم ONLYOFFICE Docs وإعداد Ollama مع CORS.

span.observer مدوّنة مجتمعية مستقلة وغير تابعة لشركة Dynatrace LLC ولا للمشاريع المذكورة. العلامات التجارية المذكورة ملك لأصحابها. الأدوات تتطور بسرعة، لذا تحقق دائمًا من الأوامر والخيارات في وثائقها الرسمية.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

Previous Post
Ghidra MCP : brancher un agent IA sur des outils locaux, isolation et traçabilité des appels

Ghidra MCP: ربط وكيل ذكاء اصطناعي بأدوات محلية مع العزل وتتبع الاستدعاءات

Next Post
MCP grand public : ce que Google Home MCP apprend aux SRE sur l'authentification, les permissions et l'audit des agents

MCP للمستهلكين: ما يعلّمه Google Home MCP لفرق SRE عن المصادقة والصلاحيات وتدقيق الوكلاء

Related Posts