إذا كنت تحاول تنزيل نموذج عبر ollama pull
من شبكة الشركات، أو عبر VPN أو من خلال خادم بروكسي خارجي، فمن المؤكد أنك واجهت أخطاء مثل
dial tcp: lookup registry.ollama.ai أو
context deadline exceeded.
لا يقوم Ollama بشكل افتراضي بالتقاط إعدادات البروكسي النظامية بشكل صحيح دائمًا، كما أن الأحجام الكبيرة للنماذج (من 2 إلى 70+ جيجابايت) تفاقم المشكلة -
حيث ينقطع الاتصال في منتصف التنزيل. في هذه المقالة، سنستعرض كيفية تعيين متغيرات البيئة بشكل صحيح، وإعداد البروكسي في Docker وsystemd،
بالإضافة إلى تحليل أكثر أخطاء السحب شيوعًا وطرق إصلاحها.
كيف يعمل Ollama مع الشبكة والبروكسي
Ollama هو تطبيق عميل-خادم: يقوم الخادم المحلي (ollama serve)
باستقبال الأوامر من CLI وتنفيذ الطلبات الشبكية إلى سجل النماذج registry.ollama.ai وإلى CDN، حيث يتم تخزين الطبقات (layers) للنماذج.
تقوم الأمر ollama pull llama3 في الواقع بتنفيذ سلسلة من طلبات HTTPS،
تشبه إلى حد كبير Docker pull: أولاً يتم طلب بيان النموذج، ثم يتم تنزيل الطبقات الثنائية (ملفات GGUF للأوزان) بشكل متتابع أو متوازي.
نقطة مهمة: الطلبات الشبكية يتم تنفيذها بواسطة عملية الخادم لـ Ollama، وليس أمر CLI. وهذا يعني أنه يجب تعيين متغيرات البيئة
مع إعدادات البروكسي في المكان الذي يتم فيه تشغيل عملية ollama serve,
وليس في الطرفية التي تستدعي منها ollama pull.
إذا كانت الخدمة تعمل كوحدة systemd أو في حاوية Docker، فإن تصدير المتغير في جلسة bash العادية لن يؤثر عليها بأي شكل من الأشكال -
هذه هي أكثر الأسباب شيوعًا لسبب "بروكسي يبدو أنه تم إعداده، لكن السحب لا يزال لا يعمل".
متغيرات البيئة HTTP_PROXY، HTTPS_PROXY، NO_PROXY
تم كتابة Ollama بلغة Go، وتقرأ مكتبة HTTP القياسية في Go إعدادات البروكسي من متغيرات البيئة التقليدية:
HTTP_PROXY- بروكسي لطلبات HTTP العاديةHTTPS_PROXY- بروكسي لطلبات HTTPS (هذا هو المطلوب لتنزيل النماذج، حيث يعمل السجل عبر TLS)NO_PROXY- قائمة بالعناوين التي يجب استثناؤها من البروكسي (على سبيل المثال، واجهة برمجة التطبيقات المحلية لـ Ollama على 127.0.0.1:11434)
تنسيق القيمة: http://user:password@host:port لبروكسي يتطلب مصادقة
أو socks5://host:port لبروكسي SOCKS5. تدعم Go كلا الخيارين،
ولكن بالنسبة لـ SOCKS5، من المهم أن يكون البرنامج التنفيذي لـ Ollama قد تم تجميعه مع دعم هذا البروكسي - في معظم الإصدارات الحالية يكون الأمر كذلك، ولكن في حالة حدوث أخطاء، من الأفضل أولاً
اختبار بروكسي HTTP/HTTPS لاستبعاد هذه المتغير.
مهم: يجب تعيين المتغيرات بحروف كبيرة وصغيرة
(http_proxy و HTTP_PROXY).
بعض توزيعات Linux تقرأ فقط الحروف الصغيرة، بينما تتوقع تطبيقات Go أحيانًا الحروف الكبيرة - من الأفضل تعيين كلا الخيارين لتجنب التخمين.
الإعداد على Linux وmacOS
إذا كنت تقوم بتشغيل Ollama مباشرة من الطرفية (وليس كخدمة نظام)، يكفي تصدير المتغيرات قبل بدء الخادم:
export HTTP_PROXY="http://user:[email protected]:8000"
export HTTPS_PROXY="http://user:[email protected]:8000"
export http_proxy="http://user:[email protected]:8000"
export https_proxy="http://user:[email protected]:8000"
export NO_PROXY="localhost,127.0.0.1"
ollama serve &
ollama pull llama3
للحفاظ على الإعدادات بين الجلسات، أضف هذه الأسطر إلى ~/.bashrc,
~/.zshrc أو ~/.profile
حسب القشرة المستخدمة. بعد التحرير، نفذ source ~/.bashrc
وأعد تشغيل عملية Ollama - يتم قراءة متغيرات البيئة فقط عند بدء العملية، ولا يوجد إعادة تحميل ساخنة.
على macOS، إذا تم تثبيت Ollama كتطبيق (وليس عبر Homebrew)، قد لا تصل متغيرات البيئة من الطرفية إلى العملية،
التي تم تشغيلها عبر واجهة المستخدم الرسومية. في هذه الحالة، من الأكثر موثوقية تعيين المتغيرات عبر launchctl setenv:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# بعد ذلك، أعد تشغيل تطبيق Ollama بالكامل (خروج من علبة النظام، وليس مجرد إغلاق النافذة)
الإعداد على Windows
في PowerShell، يتم تعيين المتغيرات للجلسة الحالية بالأمر:
$env:HTTP_PROXY="http://user:[email protected]:8000"
$env:HTTPS_PROXY="http://user:[email protected]:8000"
$env:NO_PROXY="localhost,127.0.0.1"
ollama pull mistral
إذا كانت Ollama تعمل كخدمة في الخلفية (رمز في علبة النظام)، فإن المتغيرات الخاصة بالجلسة غير كافية - تبدأ الخدمة عند تسجيل الدخول
قبل أن تفتح PowerShell. يجب تعيين المتغيرات على مستوى المستخدم أو النظام من خلال
"الإعدادات → النظام → حول → إعدادات النظام المتقدمة → متغيرات البيئة"، ثم إنهاء عملية
ollama.exe بالكامل عبر إدارة المهام وإعادة تشغيل التطبيق.
البروكسي لـ Ollama في Docker
إذا كانت Ollama تعمل في حاوية (وهو أمر شائع في نشرات الخادم)، فإن متغيرات البيئة للمضيف لا تنتقل تلقائيًا إلى داخل الحاوية -
يجب تمريرها بشكل صريح عبر -e أو قسم environment
في docker-compose:
docker run -d \
-e HTTP_PROXY="http://user:[email protected]:8000" \
-e HTTPS_PROXY="http://user:[email protected]:8000" \
-e NO_PROXY="localhost,127.0.0.1" \
-v ollama:/root/.ollama \
-p 11434:11434 \
--name ollama ollama/ollama
وبالمثل في docker-compose.yml:
version: "3.8"
services:
ollama:
image: ollama/ollama
environment:
- HTTP_PROXY=http://user:[email protected]:8000
- HTTPS_PROXY=http://user:[email protected]:8000
- NO_PROXY=localhost,127.0.0.1
volumes:
- ollama:/root/.ollama
ports:
- "11434:11434"
volumes:
ollama:
بعد تغيير المتغيرات، يجب إعادة إنشاء الحاوية (docker compose up -d --force-recreate),
فإعادة التشغيل البسيطة غير كافية، حيث يتم تثبيت متغيرات البيئة عند إنشاء الحاوية.
البروكسي لخدمة systemd لـ Ollama
على خوادم Linux، غالبًا ما يتم تثبيت Ollama كخدمة systemd عبر سكربت التثبيت الرسمي. في هذه الحالة، يتم تعيين متغيرات البيئة
من خلال ملف override، وليس عبر export في الطرفية:
sudo systemctl edit ollama.service
في المحرر الذي يفتح، أضف:
[Service]
Environment="HTTP_PROXY=http://user:[email protected]:8000"
Environment="HTTPS_PROXY=http://user:[email protected]:8000"
Environment="NO_PROXY=localhost,127.0.0.1"
ثم قم بتطبيق التغييرات:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
ستظهر لك الأمر الأخير المتغيرات التي تراها العملية فعليًا - وهي طريقة مريحة للتأكد من أن التكوين قد تم تطبيقه، قبل محاولة تنفيذ السحب مرة أخرى.
تحليل أخطاء السحب وحلولها
سنستعرض أكثر رسائل الأخطاء شيوعًا عند تنزيل النماذج عبر البروكسي وماذا تفعل معها.
dial tcp: lookup registry.ollama.ai: no such host
لا يعمل حل DNS عبر البروكسي - عادةً ما يعني ذلك أن الطلب يحاول الخروج مباشرة، متجاوزًا خادم البروكسي، أو أنه لا يوجد وصول إلى DNS على الجهاز
(شبكة الشركات المغلقة). الحل: تأكد من أن HTTPS_PROXY
يتم التقاطه فعليًا بواسطة العملية (انظر الأمر systemctl show أعلاه)،
وأن خادم البروكسي نفسه قادر على حل المجالات الخارجية (بروكسي SOCKS5 يحل DNS على جانبه، وبروكسي HTTP - أيضًا، لكن بعض البروكسي المحلية لا تفعل ذلك).
proxyconnect tcp: dial tcp: connection refused
يحاول Ollama الاتصال بالبروكسي، لكنه يتلقى رفضًا. تحقق من المنفذ والمضيف بحثًا عن الأخطاء المطبعية، وتأكد من أن خادم البروكسي يستمع فعليًا على المنفذ المحدد من الخارج (وليس فقط على localhost)، وأن جدار الحماية لا يمنع الاتصال الصادر إلى منفذ البروكسي.
407 Proxy Authentication Required
يتطلب البروكسي اسم مستخدم وكلمة مرور، لكن لم يتم تمريرها أو تم تمريرها بشكل غير صحيح. تأكد من أن متغير البيئة يحتوي على اسم المستخدم وكلمة المرور مضمنة في URL
بالتنسيق http://user:password@host:port، وأن الرموز الخاصة في كلمة المرور
(مثل @ أو :)
مشفرة عبر ترميز URL (%40، %3A).
x509: certificate signed by unknown authority
هذه علامة على وجود بروكسي الشركات مع فحص TLS (MITM)، الذي يستبدل شهادة SSL بشهادته الجذرية. لا يثق عميل Go لـ Ollama
بهذه الشهادة. الحل هو إضافة الشهادة الجذرية للشركة إلى مخزن الشهادات الموثوقة في النظام
(على Linux عادةً عبر update-ca-certificates بعد نسخ ملف .crt إلى
/usr/local/share/ca-certificates/). لا يُنصح بإيقاف التحقق من الشهادات على مستوى عالمي - فهذا يفتح الطريق لاعتراض حركة المرور.
context deadline exceeded / i/o timeout عند تنزيل طبقة
ينقطع الاتصال في منتصف تحميل طبقة كبيرة من النموذج (غالبًا ما تكون الملفات من 4-40 جيجابايت). تشير هذه الخطأ تقريبًا دائمًا إلى عدم استقرار أو انخفاض عرض النطاق الترددي لخادم البروكسي، وليس لـ Ollama نفسها. تقوم البروكسي العامة المجانية أو المزدحمة بقطع جلسات TCP الطويلة، خاصة إذا استغرق التنزيل أكثر من بضع دقائق. في مثل هذه الحالات، يساعد الانتقال إلى قناة أكثر استقرارًا - على سبيل المثال، بروكسي مراكز البيانات، التي توفر سرعة عالية واتصال مستقر لتنزيل ملفات كبيرة بدون انقطاع.
أي نوع من البروكسي يجب اختياره لـ Ollama
يعتمد اختيار نوع البروكسي على السبب الذي يجعلك بحاجة إلى بروكسي لـ Ollama. إذا كانت المهمة هي فقط تجاوز قيود جدار الحماية للشركة داخل شبكتك، فإن أي بروكسي HTTP(S) مستقر تقريبًا سيكون مناسبًا. ولكن إذا كان الهدف هو تجاوز حظر الجغرافيا على سجل النماذج أو إخفاء أن الطلب يأتي من مركز البيانات (بعض CDN تحد من السرعة لنطاقات IP المعروفة لمزودي السحابة)، يصبح اختيار نوع البروكسي أمرًا حاسمًا.
| نوع البروكسي | السرعة | متى تستخدمه لـ Ollama |
|---|---|---|
| مركز البيانات | عالية | تنزيل طبقات كبيرة من النماذج (4-40+ جيجابايت) بدون انقطاع، اختبار من مواقع مختلفة لمراكز البيانات |
| سكنية | متوسطة | تجاوز القيود الجغرافية للسجل، عندما يقع IP مركز البيانات تحت معدل محدود إقليمي |
| محمول | متغيرة | حالة قصوى عند الحظر الكامل على نطاقات IP لمزودي الخدمة، أقل فعالية في التحميلات الكبيرة بسبب تقلبات السرعة |
لمعظم السيناريوهات مع Ollama - عندما تحتاج فقط إلى تنزيل نموذج بحجم عشرات الجيجابايت بشكل مستقر - تظل بروكسي مراكز البيانات الخيار الأمثل: فهي توفر أقصى عرض نطاق وأقل تأخير، وهو أمر حاسم عند تنزيل طبقات ثنائية كبيرة. يجب توصيل IP السكنية فقط إذا كانت عناوين مراكز البيانات تقع بالفعل تحت القيود على جانب سجل النماذج.
تشخيص الاتصال
قبل قضاء الوقت في تصحيح Ollama نفسها، تحقق من البروكسي مباشرة عبر curl - هذا سيستبعد الخلط بين مشكلة في التطبيق ومشكلة في خادم البروكسي نفسه:
# التحقق من توفر السجل عبر البروكسي
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# قياس سرعة التنزيل عبر البروكسي
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# تشغيل ollama serve مع سجل مفصل
OLLAMA_DEBUG=1 ollama serve
إذا كانت curl تتلقى استجابة بنجاح، بينما ollama pull لا يزال يفشل -
فإن المشكلة على الأرجح تكمن في أن متغيرات البيئة لم تصل إلى عملية الخادم (الخدمة تعمل مع مستخدم آخر، من shell آخر
أو كوحدة systemd بدون override). ارجع إلى قسم systemd وتحقق من الإخراج systemctl show ollama --property Environment.
إذا كانت curl أيضًا تنقطع عند تنزيل ملف كبير أو تظهر سرعة غير مستقرة - فإن السبب يكون على جانب خادم البروكسي، ويجب التفكير في تغيير مزود البروكسي إلى خيار أكثر استقرارًا، موجه لنقل كميات كبيرة من البيانات.
الخاتمة
يتمحور إعداد Ollama عبر البروكسي حول ثلاث نقاط رئيسية: يجب تعيين متغيرات البيئة بالضبط للعملية
ollama serve، وليس للطرفية التي تستدعي السحب؛
يجب أن يتضمن تنسيق URL للبروكسي اسم المستخدم وكلمة المرور المشفرة بشكل صحيح؛ وعند حدوث أخطاء في الشهادات، يجب إضافة الشهادة الجذرية للشركة إلى المخزن الموثوق،
وليس إيقاف التحقق من TLS. معظم أخطاء السحب ليست أخطاء في Ollama نفسها،
بل نتيجة لعدم تطبيق إعدادات الشبكة على العملية الصحيحة أو عدم قدرة خادم البروكسي على تحمل نقل الملفات الكبيرة لفترة طويلة.
إذا كانت مهمتك الرئيسية هي تنزيل النماذج بحجم عشرات الجيجابايت بشكل مستقر وسريع بدون انقطاع في الاتصال، نوصي بتجربة بروكسي مراكز البيانات - فهي توفر عرض نطاق عالٍ، ضروري لتحميل الطبقات الكبيرة من النماذج. وإذا كان سبب استخدام البروكسي هو تجاوز القيود الجغرافية على سجل النماذج، فانتبه إلى البروكسي السكنية، التي نادرًا ما تقع تحت الحدود الإقليمية المفروضة على نطاقات IP لمزودي السحابة.