CLI رایگان محلی برای LLM: نصب و استفاده امن از Ollama و llama.cpp

پاسخ سریع: اگر می‌خواهید یک مدل زبانی را بدون API Key و بدون فرستادن Prompt به یک API ابری اجرا کنید، از یک CLI محلی استفاده کنید. Ollama برای شروع سریع و مدیریت سادهٔ مدل مناسب است؛ llama.cpp برای کنترل بیشتر روی فایل‌های GGUF، سخت‌افزار و یک API محلی مناسب‌تر است. خود ابزارها رایگان و متن‌باز یا قابل‌دریافت رایگان‌اند، اما مجوز مدل، فضای دیسک، RAM/VRAM و دسترسی به منبع دانلود مدل باید جدا بررسی شود.

این راهنما Provider رایگان ابری معرفی نمی‌کند. اگر به API رسمی، سهمیه و Model ID نیاز دارید، از کاتالوگ APIهای رایگان LLM استفاده کنید؛ اگر دنبال Proxy، Router یا ابزارهای واسط هستید، ابتدا کاتالوگ CLI و ابزارها و ریسک Credential آن‌ها را ببینید.

ابزار رایگان دقیقاً چه چیزی را رایگان می‌کند؟

در اجرای محلی، نرم‌افزار CLI روی دستگاه شما اجرا می‌شود و برای گفت‌وگوی پایه معمولاً کلید API لازم ندارد. این به معنی «رایگان بودن همه‌چیز» نیست:

• مدل ممکن است مجوز استفاده یا محدودیت تجاری جداگانه داشته باشد.
• دانلود اولیهٔ مدل می‌تواند چند گیگابایت باشد.
• اجرای مدل بزرگ RAM، VRAM، باتری و زمان پردازش مصرف می‌کند.
• دسترسی به Registry یا Hugging Face از شبکهٔ شما باید جداگانه و طبق سیاست همان سرویس بررسی شود.
• اگر قابلیت Cloud یا Web Search را فعال کنید، دیگر مسیر کاملاً محلی نیست.

برای دادهٔ محرمانه، قبل از واردکردن متن بررسی کنید که ابزار واقعاً در حالت محلی است و افزونه، Cloud model یا ابزار خارجی فعال نیست.

مراحل ثبت‌نام: برای اجرای محلی لازم نیست

برای اجرای پایهٔ Ollama یا llama.cpp روی دستگاه خودتان، حساب کاربری و API Key لازم نیست. فقط installer و فایل مدل را از منبع رسمی دریافت کنید. اگر یک Registry، مدل یا قابلیت Cloud از شما ورود به حساب خواست، آن مسیر دیگر بخشی از اجرای کاملاً محلی نیست؛ شرایط، حریم خصوصی و هزینهٔ همان سرویس را جداگانه بررسی کنید.

انتخاب سریع: Ollama یا llama.cpp؟

هیچ‌کدام کیفیت فارسی، سرعت یا سازگاری مدل را تضمین نمی‌کنند؛ این موارد به مدل، quantization و سخت‌افزار شما وابسته‌اند.

نصب Ollama و اولین درخواست

مستندات رسمی Ollama برای Linux فرمان زیر را ارائه می‌کند. پیش از اجرای هر اسکریپت نصب، URL و محتوای آن را از صفحهٔ رسمی بررسی کنید:

curl -fsSL https://ollama.com/install.sh | sh
ollama

در macOS و Windows از صفحهٔ دانلود رسمی Ollama استفاده کنید. بعد از نصب، یک مدل را اجرا کنید. طبق Quickstart رسمی، این دستور در صورت نیاز مدل را دریافت و یک گفت‌وگوی تعاملی باز می‌کند:

ollama run gemma4

سپس یک درخواست کوتاه وارد کنید:

در سه جمله تفاوت API و SDK را به فارسی توضیح بده.

برای خروج از گفت‌وگو، /bye را وارد کنید. قبل از دانلود مدل بزرگ، فضای آزاد دیسک و حافظهٔ دستگاه را بررسی کنید. نام مدل را از کتابخانهٔ رسمی مدل‌های Ollama انتخاب کنید، نه از یک دستور ناشناس در شبکه‌های اجتماعی.

اجرای llama.cpp با مدل GGUF

llama.cpp یک موتور سبک C/C++ برای inference محلی است. پروژهٔ رسمی روش‌های نصب با package manager، binary آماده، Docker یا build از source را فهرست می‌کند. برای شروع کم‌ریسک، binary رسمی منتشرشده را از Releases llama.cpp دریافت کنید و checksum یا امضای منتشرشده را—اگر ارائه شده—بررسی کنید.

پس از در دسترس بودن فرمان llama-cli، می‌توانید یک فایل محلی GGUF را اجرا کنید:

llama-cli -m /path/to/model.gguf

مستندات رسمی همچنین نمونهٔ دریافت و اجرای مستقیم یک مدل سازگار از Hugging Face را نشان می‌دهد:

llama-cli -hf ggml-org/gemma-3-1b-it-GGUF

برای سرویس محلیِ سازگار با OpenAI، همان پروژه فرمان زیر را مستند کرده است:

llama-server -hf ggml-org/gemma-3-1b-it-GGUF

این سرویس را پیش‌فرض فقط روی دستگاه یا شبکهٔ قابل‌اعتماد خود نگه دارید. بازکردن یک API محلی روی اینترنت بدون احراز هویت، محدودسازی نرخ و کنترل دسترسی انتخاب مناسبی نیست.

نمونهٔ استفادهٔ برنامه‌نویسی از API محلی

بعد از راه‌اندازی server، ابتدا مستندات نسخهٔ نصب‌شده را بخوانید و با یک درخواست حداقلی تست کنید. نمونهٔ زیر فقط الگوی Client است؛ Host، مسیر و نام مدل باید با خروجی خودتان هماهنگ شوند:

from typing import Final

from openai import OpenAI

BASE_URL: Final = "http://127.0.0.1:8080/v1"
MODEL: Final = "local-model"

client = OpenAI(base_url=BASE_URL, api_key="not-used-by-local-server")
response = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "سلام، یک پاسخ کوتاه بده."}],
)
print(response.choices[0].message.content)

این نمونه به معنی سازگاری خودکار هر نسخه از llama.cpp با هر SDK نیست. اگر پاسخ نگرفتید، ابتدا Log محلی، پورت، مسیر API و نام مدل را بررسی کنید و هیچ Token، Prompt خصوصی یا پاسخ خام حساس را در Issue عمومی قرار ندهید.

خطاهای رایج و رفع اشکال

دانلود مدل یا اتصال ناموفق است

فضای دیسک، DNS/شبکه و دسترسی به منبع رسمی مدل را بررسی کنید. این خطا به‌تنهایی اثبات محدودیت ایران یا مسدودسازی Provider نیست؛ نتیجهٔ شبکه، حساب و سیاست سرویس را جدا ثبت کنید.

مدل کند است یا حافظه تمام می‌شود

مدل کوچک‌تر یا quantization مناسب‌تر انتخاب کنید، برنامه‌های سنگین دیگر را ببندید و Context را کوتاه‌تر نگه دارید. کیفیت فارسی را با Promptهای واقعی خودتان بسنجید.

API محلی از دستگاه دیگر قابل دسترس نیست

پیش از تغییر bind address یا firewall، مشخص کنید آیا واقعاً به دسترسی شبکه نیاز دارید. سرویس بدون احراز هویت را عمومی نکنید؛ برای Production به کنترل دسترسی، TLS، محدودیت نرخ و پایش نیاز دارید.

چه زمانی CLI محلی انتخاب مناسبی نیست؟

• به مدل بسیار بزرگ نیاز دارید ولی سخت‌افزار کافی ندارید.
• باید SLA، مقیاس‌پذیری، تیم چندنفره یا پردازش هم‌زمان بالا داشته باشید.
• مجوز مدل با استفادهٔ شما سازگار نیست.
• می‌خواهید API را روی اینترنت باز کنید اما هنوز امنیت و عملیات آن را طراحی نکرده‌اید.
• به قابلیت ابری خاص نیاز دارید که ابزار محلی ارائه نمی‌دهد.

در این وضعیت‌ها، Provider رسمی و حساب‌شده را با API Finder مقایسه کنید.

وضعیت ایران با شواهد

اجرای فایل مدل پس از دانلود، روی دستگاه شما انجام می‌شود؛ با این حال دانلود installer یا model به دسترسی شبکه به میزبان مربوط وابسته است. این راهنما دسترسی از ایران را برای Ollama، llama.cpp، GitHub یا Hugging Face تأیید یا رد نمی‌کند. برای گزارش تاریخ‌دار و پاک‌سازی‌شده، از فرم گزارش دسترسی ایران استفاده کنید.

منابع رسمی بررسی‌شده

تاریخ بررسی: ۲۲ ژوئیهٔ ۲۰۲۶.

• Quickstart رسمی Ollama — نصب، اجرای CLI و شروع گفت‌وگو.
• صفحهٔ دانلود رسمی Ollama — روش دریافت برای سیستم‌عامل‌های پشتیبانی‌شده.
• README رسمی llama.cpp — روش‌های نصب، llama-cli و llama-server.
• راهنمای build رسمی llama.cpp — جزئیات build و backendهای سخت‌افزاری.

راهنماهای مرتبط

• ساخت چت‌بات فارسی با Python — اتصال امن Client به API.
• رفع خطاهای 401، 403 و model-not-found — تفکیک خطاهای تنظیمات و دسترسی.
• کاتالوگ CLI و ابزارها — ریسک Credential و Terms ابزارهای واسط.

پرسش‌های متداول

آیا Ollama و llama.cpp جایگزین API رایگان هستند؟

نه لزوماً. آن‌ها ابزار اجرای محلی‌اند؛ هزینه و محدودیت به سخت‌افزار، مجوز مدل و دانلود مدل وابسته است. برای API رسمی به کاتالوگ مراجعه کنید.

آیا برای اجرای محلی API Key لازم است؟

برای گفت‌وگوی محلی پایه معمولاً نه، اما قابلیت‌های Cloud، افزونه‌ها یا سرویس‌های خارجی ممکن است احراز هویت جداگانه بخواهند.

آیا می‌توانم API محلی را عمومی کنم؟

بدون طراحی احراز هویت، TLS، محدودیت نرخ و کنترل شبکه نباید این کار را انجام دهید.

جمع‌بندی

برای شروع سریع، Ollama مسیر ساده‌تری دارد؛ برای کنترل فایل GGUF و سرور محلی، llama.cpp انعطاف بیشتری می‌دهد. هر دو را با مدل و سخت‌افزار خودتان آزمایش کنید، منبع دانلود و مجوز مدل را بررسی کنید و ابزار محلی را با Provider یا دسترسی تأییدشده از ایران یکی نگیرید. برای اصلاح این راهنما یا ثبت شواهد امن، به Repository پروژه در GitHub مراجعه کنید.