Nếu bạn đang cố gắng tải xuống mô hình qua ollama pull
từ mạng doanh nghiệp, qua VPN hoặc qua máy chủ proxy bên ngoài, bạn chắc chắn đã gặp phải các lỗi như
dial tcp: lookup registry.ollama.ai hoặc
context deadline exceeded.
Ollama theo mặc định không phải lúc nào cũng nhận đúng cấu hình proxy hệ thống, và kích thước lớn của các mô hình (từ 2 đến 70+ GB) làm trầm trọng thêm vấn đề —
kết nối thường bị ngắt giữa chừng khi tải xuống. Trong bài viết này, chúng ta sẽ xem xét cách đặt biến môi trường đúng cách, cấu hình proxy trong Docker và systemd,
cũng như giải mã các lỗi pull thường gặp và cách khắc phục chúng.
Cách Ollama hoạt động với mạng và proxy
Ollama là một ứng dụng client-server: máy chủ cục bộ (ollama serve)
nhận lệnh từ CLI và thực hiện các yêu cầu mạng đến registry mô hình registry.ollama.ai và CDN, nơi lưu trữ các lớp (layers) của mô hình.
Lệnh ollama pull llama3 thực sự thực hiện một loạt các yêu cầu HTTPS,
tương tự như Docker pull: trước tiên yêu cầu bản mô tả của mô hình, sau đó lần lượt hoặc song song tải xuống các lớp nhị phân (tệp GGUF của trọng số).
Một điểm quan trọng: các yêu cầu mạng được thực hiện bởi quá trình máy chủ của Ollama, không phải lệnh CLI. Điều này có nghĩa là các biến môi trường
với cấu hình proxy cần được đặt ở nơi quá trình ollama serve đang chạy,
không phải trong terminal mà bạn gọi ollama pull.
Nếu dịch vụ được khởi động như một unit systemd hoặc trong một container Docker, việc xuất biến trong một phiên bash thông thường sẽ không ảnh hưởng đến nó —
đây là lý do phổ biến nhất khiến "proxy dường như đã được cấu hình, nhưng pull vẫn không hoạt động".
Biến môi trường HTTP_PROXY, HTTPS_PROXY, NO_PROXY
Ollama được viết bằng Go, và thư viện HTTP chuẩn của Go đọc cấu hình proxy từ các biến môi trường cổ điển:
HTTP_PROXY— proxy cho các yêu cầu HTTP thông thườngHTTPS_PROXY— proxy cho các yêu cầu HTTPS (điều này cần thiết để tải xuống mô hình, vì registry hoạt động qua TLS)NO_PROXY— danh sách các máy chủ cần loại trừ khỏi việc proxy (ví dụ, API cục bộ của Ollama tại 127.0.0.1:11434)
Định dạng giá trị: http://user:password@host:port cho proxy có xác thực
hoặc socks5://host:port cho SOCKS5. Go hỗ trợ cả hai tùy chọn,
nhưng đối với SOCKS5, điều quan trọng là nhị phân Ollama phải được biên dịch với hỗ trợ cho proxy này — trong hầu hết các bản build hiện tại là như vậy, nhưng nếu có lỗi, trước tiên
hãy thử nghiệm với HTTP/HTTPS proxy để loại trừ biến này.
Quan trọng: hãy chỉ định các biến cả ở dạng chữ thường và chữ hoa
(http_proxy và HTTP_PROXY).
Một số bản phân phối Linux chỉ đọc chữ thường, trong khi các ứng dụng Go đôi khi mong đợi chữ hoa — tốt hơn là nên đặt cả hai biến để không phải đoán.
Cấu hình trên Linux và macOS
Nếu bạn khởi động Ollama trực tiếp từ terminal (không phải như một dịch vụ hệ thống), chỉ cần xuất các biến trước khi khởi động máy chủ:
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
Để các cấu hình được lưu giữa các phiên, hãy thêm các dòng này vào ~/.bashrc,
~/.zshrc hoặc ~/.profile
tùy thuộc vào shell bạn đang sử dụng. Sau khi chỉnh sửa, hãy thực hiện source ~/.bashrc
và khởi động lại quá trình Ollama — các biến môi trường chỉ được đọc khi khởi động quá trình, không có khả năng tải lại nóng.
Trên macOS, nếu Ollama được cài đặt như một ứng dụng (không phải qua Homebrew), các biến môi trường từ terminal có thể không đến được quá trình,
được khởi động qua GUI. Trong trường hợp này, tốt hơn là đặt các biến thông qua launchctl setenv:
launchctl setenv HTTPS_PROXY "http://user:[email protected]:8000"
launchctl setenv HTTP_PROXY "http://user:[email protected]:8000"
# Sau đó, hãy khởi động lại ứng dụng Ollama hoàn toàn (thoát khỏi khay, không chỉ đóng cửa sổ)
Cấu hình trên Windows
Trong PowerShell, các biến được đặt cho phiên hiện tại bằng lệnh:
$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
Nếu Ollama được khởi động như một dịch vụ nền (biểu tượng trong khay hệ thống), các biến phiên không đủ — dịch vụ khởi động khi bạn đăng nhập vào hệ thống
trước khi bạn mở PowerShell. Cần phải đặt các biến ở cấp độ người dùng hoặc hệ thống thông qua
"Cài đặt → Hệ thống → Về máy tính → Cài đặt nâng cao → Biến môi trường", sau đó hoàn toàn kết thúc quá trình
ollama.exe qua trình quản lý tác vụ và khởi động lại ứng dụng.
Proxy cho Ollama trong Docker
Nếu Ollama được khởi động trong một container (trường hợp phổ biến cho triển khai máy chủ), các biến môi trường của máy chủ sẽ không tự động vào bên trong container —
chúng cần được truyền rõ ràng qua -e hoặc phần environment
trong 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
Tương tự trong 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:
Sau khi thay đổi các biến, container cần được tái tạo (docker compose up -d --force-recreate),
chỉ khởi động lại đơn giản là không đủ, vì các biến môi trường được cố định khi tạo container.
Proxy cho dịch vụ systemd của Ollama
Trên các máy chủ Linux, Ollama thường được cài đặt như một dịch vụ systemd thông qua script cài đặt chính thức. Trong trường hợp này, các biến môi trường
được đặt qua tệp override, không phải qua export trong terminal:
sudo systemctl edit ollama.service
Trong trình chỉnh sửa mở ra, hãy thêm:
[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"
Sau đó, áp dụng các thay đổi:
sudo systemctl daemon-reload
sudo systemctl restart ollama
systemctl show ollama --property Environment
Lệnh cuối cùng sẽ cho thấy các biến mà quá trình thực sự nhìn thấy — một cách tiện lợi để đảm bảo rằng cấu hình đã được áp dụng, trước khi thử lại việc thực hiện pull.
Phân tích lỗi pull và cách giải quyết
Chúng ta sẽ xem xét các thông báo lỗi thường gặp khi tải xuống mô hình qua proxy và cách xử lý chúng.
dial tcp: lookup registry.ollama.ai: no such host
DNS resolution không hoạt động qua proxy — thường có nghĩa là yêu cầu đang cố gắng đi trực tiếp, bỏ qua máy chủ proxy, hoặc máy không có quyền truy cập
vào DNS (mạng doanh nghiệp kín). Giải pháp: hãy đảm bảo rằng HTTPS_PROXY
thực sự được quá trình nhận (xem lệnh systemctl show ở trên),
và rằng máy chủ proxy có khả năng giải quyết các miền bên ngoài (proxy SOCKS5 giải quyết DNS ở phía của nó, proxy HTTP cũng vậy, nhưng một số proxy cục bộ không làm điều này).
proxyconnect tcp: dial tcp: connection refused
Ollama đang cố gắng kết nối với proxy nhưng bị từ chối. Kiểm tra cổng và máy chủ để tìm lỗi chính tả, đảm bảo rằng máy chủ proxy thực sự đang lắng nghe cổng đã chỉ định từ bên ngoài (không chỉ trên localhost), và rằng tường lửa không chặn kết nối ra ngoài đến cổng proxy.
407 Proxy Authentication Required
Proxy yêu cầu đăng nhập và mật khẩu, nhưng chúng không được cung cấp hoặc được cung cấp không chính xác. Hãy đảm bảo rằng trong biến môi trường, tên người dùng và mật khẩu được nhúng vào URL
theo định dạng http://user:password@host:port, và các ký tự đặc biệt trong mật khẩu
(ví dụ, @ hoặc :)
được mã hóa thông qua URL-encoding (%40, %3A).
x509: certificate signed by unknown authority
Đây là dấu hiệu của một proxy doanh nghiệp với TLS inspection (MITM), thay thế chứng chỉ SSL bằng chứng chỉ gốc của nó. Khách hàng Go của Ollama không tin tưởng
chứng chỉ này. Giải pháp — thêm chứng chỉ gốc của doanh nghiệp vào kho chứng chỉ tin cậy của hệ thống
(trên Linux thường thông qua update-ca-certificates sau khi sao chép tệp .crt vào
/usr/local/share/ca-certificates/). Không nên tắt kiểm tra chứng chỉ toàn cầu — điều này mở ra con đường cho việc chặn lưu lượng.
context deadline exceeded / i/o timeout khi tải xuống lớp
Kết nối bị ngắt giữa chừng khi tải xuống một lớp lớn của mô hình (thường là các tệp từ 4-40 GB). Lỗi này gần như luôn chỉ ra sự không ổn định hoặc băng thông thấp của máy chủ proxy, không phải do chính Ollama. Các proxy công cộng miễn phí hoặc quá tải thường ngắt các phiên TCP dài, đặc biệt nếu việc tải xuống mất hơn vài phút. Trong những trường hợp như vậy, việc chuyển sang một kênh ổn định hơn sẽ giúp ích — chẳng hạn như proxy trung tâm dữ liệu, cung cấp tốc độ cao và kết nối ổn định để tải xuống các tệp lớn mà không bị ngắt.
Loại proxy nào nên chọn cho Ollama
Việc chọn loại proxy phụ thuộc vào lý do bạn cần proxy cho Ollama. Nếu mục tiêu chỉ là vượt qua các hạn chế của tường lửa doanh nghiệp trong mạng của bạn, bất kỳ proxy HTTP(S) ổn định nào cũng đều phù hợp. Nhưng nếu mục tiêu là vượt qua geo-blocking của registry mô hình hoặc ẩn đi rằng yêu cầu đến từ trung tâm dữ liệu (một số CDN giới hạn tốc độ cho các dải IP của nhà cung cấp đám mây nổi tiếng), việc chọn loại proxy trở nên quan trọng.
| Loại proxy | Tốc độ | Khi nào sử dụng cho Ollama |
|---|---|---|
| Trung tâm dữ liệu | Cao | Tải xuống các lớp lớn của mô hình (4-40+ GB) mà không bị ngắt, thử nghiệm từ các vị trí DC khác nhau |
| Nhà ở | Trung bình | Vượt qua geo-giới hạn của registry, khi IP của trung tâm dữ liệu bị giới hạn theo khu vực |
| Di động | Biến đổi | Trường hợp cuối cùng khi bị chặn hoàn toàn theo dải IP của nhà cung cấp, kém hiệu quả hơn cho các tải lớn do sự biến động về tốc độ |
Đối với hầu hết các kịch bản với Ollama — khi cần tải xuống mô hình nặng hàng chục gigabyte một cách ổn định — lựa chọn tối ưu vẫn là proxy trung tâm dữ liệu: chúng cung cấp băng thông tối đa và độ trễ tối thiểu, điều này rất quan trọng khi tải xuống các lớp nhị phân lớn. IP nhà ở chỉ nên được kết nối nếu địa chỉ của trung tâm dữ liệu thực sự bị giới hạn ở phía registry mô hình.
Chẩn đoán kết nối
Trước khi dành thời gian để gỡ lỗi chính Ollama, hãy kiểm tra proxy trực tiếp qua curl — điều này sẽ loại trừ sự nhầm lẫn giữa vấn đề trong ứng dụng và vấn đề trong chính máy chủ proxy:
# Kiểm tra khả năng truy cập registry qua proxy
curl -v -x http://user:[email protected]:8000 https://registry.ollama.ai/v2/
# Đo tốc độ tải xuống qua proxy
curl -x http://user:[email protected]:8000 -o /dev/null -w "%{speed_download}\n" https://registry.ollama.ai/v2/
# Khởi động ollama serve với log chi tiết
OLLAMA_DEBUG=1 ollama serve
Nếu curl nhận được phản hồi thành công, nhưng ollama pull vẫn gặp lỗi —
vấn đề gần như chắc chắn là các biến môi trường không đến được quá trình máy chủ (dịch vụ được khởi động với người dùng khác, từ shell khác
hoặc như một unit systemd mà không có override). Quay lại phần về systemd và kiểm tra đầu ra systemctl show ollama --property Environment.
Nếu curl cũng bị ngắt khi tải xuống tệp lớn hoặc cho thấy tốc độ không ổn định — nguyên nhân nằm ở phía máy chủ proxy, và bạn nên xem xét việc chuyển nhà cung cấp proxy sang một tùy chọn ổn định hơn, tập trung vào việc truyền tải khối lượng dữ liệu lớn.
Kết luận
Cấu hình Ollama qua proxy xoay quanh ba điểm chính: các biến môi trường phải được đặt chính xác cho quá trình
ollama serve, không phải cho terminal mà bạn gọi pull;
định dạng URL của proxy phải bao gồm tên người dùng và mật khẩu được mã hóa chính xác; và khi gặp lỗi chứng chỉ, cần thêm chứng chỉ gốc của doanh nghiệp vào kho tin cậy,
không phải tắt kiểm tra TLS. Hầu hết các lỗi pull không phải là lỗi của chính Ollama,
mà là hậu quả của việc cấu hình mạng không được áp dụng cho quá trình cần thiết hoặc máy chủ proxy không chịu được việc truyền tải lâu dài các tệp lớn.
Nếu nhiệm vụ chính của bạn là tải xuống ổn định và nhanh chóng các mô hình nặng hàng chục gigabyte mà không bị ngắt kết nối, chúng tôi khuyên bạn nên thử proxy trung tâm dữ liệu — chúng cung cấp băng thông cao, cần thiết để tải xuống các lớp lớn của mô hình. Và nếu lý do sử dụng proxy là để vượt qua geo-giới hạn của registry mô hình, hãy chú ý đến proxy nhà ở, chúng ít bị rơi vào các giới hạn khu vực áp dụng cho các dải IP của nhà cung cấp đám mây.