← بازگشت به وبلاگ

اولاما از طریق پروکسی: چگونه HTTP_PROXY را تنظیم کنیم و خطاهای کشیدن مدل‌ها را برطرف کنیم

بررسی دقیق تنظیمات Ollama از طریق پروکسی سرور - از متغیرهای محیطی تا تشخیص خطاهای کشیدن مدل‌ها و انتخاب نوع مناسب پروکسی.

📅۲۵ آبان ۱۴۰۵

اگر شما در حال تلاش برای دانلود مدل از طریق ollama pull از شبکه شرکتی، از طریق VPN یا از طریق یک سرور پروکسی خارجی هستید، مطمئناً با خطاهایی مانند dial tcp: lookup registry.ollama.ai یا context deadline exceeded مواجه شده‌اید. Ollama به طور پیش‌فرض همیشه تنظیمات پروکسی سیستم را به درستی شناسایی نمی‌کند و وزن‌های بالای مدل‌ها (از 2 تا 70+ گیگابایت) مشکل را تشدید می‌کند — اتصال در میانه دانلود قطع می‌شود. در این مقاله بررسی خواهیم کرد که چگونه متغیرهای محیطی را به درستی تنظیم کنیم، پروکسی را در Docker و systemd پیکربندی کنیم، و همچنین رایج‌ترین اشکالات pull و روش‌های رفع آن‌ها را تجزیه و تحلیل خواهیم کرد.

چگونه Ollama با شبکه و پروکسی کار می‌کند

Ollama یک برنامه کلاینت-سرور است: سرور محلی (ollama serve) دستورات را از CLI دریافت کرده و درخواست‌های شبکه‌ای به رجیستری مدل‌ها registry.ollama.ai و به CDN که لایه‌های مدل‌ها را ذخیره می‌کند، انجام می‌دهد. دستور ollama pull llama3 در واقع یک سری درخواست‌های HTTPS را انجام می‌دهد، مشابه با Docker pull: ابتدا مانیفست مدل درخواست می‌شود، سپس لایه‌های باینری (فایل‌های GGUF وزن‌ها) به صورت متوالی یا موازی دانلود می‌شوند.

نکته مهم: درخواست‌های شبکه‌ای به طور خاص توسط فرآیند سرور Ollama انجام می‌شود، نه دستور CLI. این بدان معناست که متغیرهای محیطی با تنظیمات پروکسی باید در جایی که فرآیند ollama serve اجرا می‌شود، تنظیم شوند، نه در ترمینالی که از آن ollama pull را فراخوانی می‌کنید. اگر سرویس به عنوان یک واحد systemd یا در یک کانتینر Docker اجرا شده باشد، صادرات متغیر در یک جلسه bash عادی هیچ تأثیری بر آن نخواهد داشت — این شایع‌ترین دلیل است که چرا "پروکسی به نظر می‌رسد تنظیم شده است، اما pull هنوز کار نمی‌کند".

متغیرهای محیطی HTTP_PROXY، HTTPS_PROXY، NO_PROXY

Ollama به زبان Go نوشته شده است و کتابخانه HTTP استاندارد Go تنظیمات پروکسی را از متغیرهای محیطی کلاسیک می‌خواند:

  • HTTP_PROXY — پروکسی برای درخواست‌های HTTP عادی
  • HTTPS_PROXY — پروکسی برای درخواست‌های HTTPS (این پروکسی برای دانلود مدل‌ها ضروری است، زیرا رجیستری بر روی TLS کار می‌کند)
  • NO_PROXY — لیست میزبان‌هایی که باید از پروکسی‌سازی مستثنی شوند (به عنوان مثال، API محلی 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) نصب شده باشد، متغیرهای محیطی از ترمینال ممکن است به فرآیند اجرا شده از طریق GUI نرسند. در این صورت بهتر است متغیرها را از طریق 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

دستور آخر نشان می‌دهد که چه متغیرهایی واقعاً توسط فرآیند مشاهده می‌شوند — یک روش راحت برای اطمینان از اینکه پیکربندی اعمال شده است، قبل از اینکه دوباره تلاش کنید تا pull را انجام دهید.

تجزیه و تحلیل اشکالات pull و راه‌حل‌های آن‌ها

بیایید رایج‌ترین پیام‌های خطا هنگام دانلود مدل‌ها از طریق پروکسی و اینکه چه کاری باید با آن‌ها انجام داد را بررسی کنیم.

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-encoding کدگذاری شده‌اند (%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 هنوز هم دچار مشکل شود — مشکل تقریباً مطمئناً در این است که متغیرهای محیطی به فرآیند سرور نرسیده‌اند (سرویس با کاربر دیگری، از شل دیگری یا به عنوان واحد systemd بدون override اجرا شده است). به بخش مربوط به systemd برگردید و خروجی systemctl show ollama --property Environment را بررسی کنید.

اگر curl نیز در دانلود فایل بزرگ قطع می‌شود یا سرعت ناپایدار را نشان می‌دهد — دلیل آن در سمت پروکسی است، و باید به فکر تغییر ارائه‌دهنده پروکسی به گزینه‌ای پایدارتر باشید که به انتقال حجم بالای داده‌ها متمرکز است.

نتیجه‌گیری

تنظیم Ollama از طریق پروکسی به سه نکته کلیدی محدود می‌شود: متغیرهای محیطی باید به طور خاص برای فرآیند ollama serve تنظیم شوند، نه برای ترمینالی که از آن pull را فراخوانی می‌کنید؛ فرمت URL پروکسی باید شامل نام کاربری و رمز عبور به درستی کدگذاری شده باشد؛ و در صورت بروز خطاهای گواهی، باید گواهی ریشه شرکتی را به مخزن معتبر اضافه کنید، نه اینکه بررسی TLS را غیرفعال کنید. بیشتر اشکالات pull — این‌ها باگ‌های خود Ollama نیستند، بلکه نتیجه این است که تنظیمات شبکه به فرآیند مورد نظر اعمال نشده‌اند یا پروکسی نمی‌تواند انتقال طولانی مدت فایل‌های بزرگ را تحمل کند.

اگر هدف اصلی شما دانلود پایدار و سریع مدل‌هایی با وزن ده‌ها گیگابایت بدون قطع شدن اتصال است، توصیه می‌کنیم پروکسی‌های دیتا سنتر را امتحان کنید — آن‌ها پهنای باند بالایی را فراهم می‌کنند، که برای بارگذاری لایه‌های بزرگ مدل‌ها ضروری است. و اگر دلیل استفاده از پروکسی دور زدن محدودیت‌های جغرافیایی رجیستری مدل‌هاست، به پروکسی‌های رایج توجه کنید که کمتر تحت محدودیت‌های منطقه‌ای قرار می‌گیرند که به دامنه‌های IP ارائه‌دهندگان ابری اعمال می‌شود.