Ollama چیست؟ آموزش کامل نصب، اجرای مدل‌های هوش مصنوعی محلی و استفاده از API

Ollama یکی از محبوب‌ترین ابزارها برای دانلود و اجرای مدل‌های زبانی بزرگ یا LLM روی کامپیوتر شخصی و سرور است. با استفاده از Ollama می‌توانید بعضی مدل‌های متن‌باز را بدون ارسال دائمی اطلاعات به یک سرویس خارجی، روی ویندوز، لینوکس یا macOS اجرا کنید.

پس از نصب Ollama، یک مدل سازگار را دانلود می‌کنید و از طریق Terminal، رابط API یا ابزارهایی مانند Open WebUI، VS Code، Python و Node.js با آن کار می‌کنید.

Ollama برای این گروه‌ها جذاب است:

• برنامه‌نویسانی که می‌خواهند LLM را روی سیستم خود اجرا کنند.
• توسعه‌دهندگانی که به محیط آزمایشی آفلاین نیاز دارند.
• تیم‌هایی که می‌خواهند هزینه بعضی وظایف ساده را کاهش دهند.
• دانشجویانی که می‌خواهند کار با مدل‌های زبانی را یاد بگیرند.
• توسعه‌دهندگان RAG و جست‌وجوی معنایی
• سازندگان ابزارهای برنامه‌نویسی هوشمند
• افرادی که می‌خواهند API محلی سازگار با OpenAI داشته باشند.
• تیم‌هایی که به معماری ترکیبی Local و Cloud نیاز دارند.

بااین‌حال، اجرای مدل محلی همیشه بهترین انتخاب نیست. مدل‌های بزرگ به حافظه، کارت گرافیک و توان پردازشی زیادی نیاز دارند و کیفیت یک مدل کوچک محلی ممکن است با مدل‌های قدرتمند ارائه‌شده از طریق API برابر نباشد.

در این مقاله یاد می‌گیریم:

• Ollama چیست و چگونه کار می‌کند.
• چگونه Ollama را روی ویندوز، لینوکس و macOS نصب کنیم.
• چگونه مدل محلی دانلود و اجرا کنیم.
• چگونه از Ollama API استفاده کنیم.
• چگونه Python و Node.js را به Ollama متصل کنیم.
• چگونه از OpenAI SDK با Ollama استفاده کنیم.
• چگونه Structured Output و Embedding بگیریم.
• چگونه یک مدل سفارشی با Modelfile بسازیم.
• چگونه معماری ترکیبی Ollama و API درواره طراحی کنیم.
• چه زمانی مدل محلی و چه زمانی مدل ابری مناسب‌تر است.

Ollama چیست؟

Ollama یک Runtime و ابزار مدیریت مدل‌های هوش مصنوعی است که دانلود، نگهداری و اجرای مدل‌های سازگار را ساده می‌کند.

در حالت معمول، اجرای یک مدل متن‌باز می‌تواند شامل مراحل مختلفی باشد:

• پیدا‌کردن فایل‌های مدل
• انتخاب Quantization مناسب
• نصب Runtime
• تنظیم GPU
• مدیریت حافظه
• آماده‌سازی Template گفتگو
• تنظیم پارامترهای تولید
• ساخت API
• مدیریت نسخه‌های مختلف مدل

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

Ollama روی Windows، Linux و macOS اجرا می‌شود و پس از نصب می‌توان از مدل‌ها در Terminal، Integrationها یا API استفاده کرد. راهنمای رسمی شروع کار با Ollama

Ollama چگونه کار می‌کند؟

معماری ساده Ollama به شکل زیر است:

برنامه کاربر
    ↓
Ollama API
    ↓
Ollama Runtime
    ↓
مدل محلی
    ↓
CPU یا GPU

Ollama معمولاً یک سرویس محلی اجرا می‌کند و درخواست‌ها را روی آدرس زیر دریافت می‌کند:

http://localhost:11434

API اصلی Ollama در این Base URL قرار دارد:

http://localhost:11434/api

همچنین Ollama بخشی از ساختار OpenAI API را پشتیبانی می‌کند و می‌توان از این آدرس برای ابزارهای سازگار استفاده کرد:

http://localhost:11434/v1

براساس مستندات رسمی Ollama API، API محلی پس از نصب به‌صورت پیش‌فرض روی پورت 11434 در دسترس است.

تفاوت Ollama با ChatGPT و API هوش مصنوعی

Ollama، ChatGPT و یک زیرساخت API چندمدلی مانند درواره، نقش یکسانی ندارند.

Ollama برای اجرای Local LLM مناسب است. درواره برای زمانی مناسب است که نرم‌افزار شما به مدل‌های قدرتمند‌تر، چند نوع مدل یا زیرساخت مدیریت‌شده API نیاز دارد.

در بسیاری از پروژه‌ها بهترین انتخاب، ترکیب این دو است:

وظایف ساده و حساس → Ollama محلی
وظایف پیچیده و سنگین → API درواره

Ollama چه کاربردهایی دارد؟

ساخت چت‌بات محلی

می‌توانید یک مدل را روی سیستم اجرا و رابط گفت‌وگو برای آن بسازید.

کمک به برنامه‌نویسی

مدل‌های مناسب کدنویسی می‌توانند برای توضیح کد، تولید تست، Refactor و مستندسازی استفاده شوند.

ساخت RAG محلی

می‌توان متن‌ها را به Embedding تبدیل کرد، در یک Vector Database ذخیره کرد و پاسخ‌ها را با اطلاعات بازیابی‌شده ساخت.

خلاصه‌سازی اسناد

برای اسناد کوچک یا محرمانه می‌توان خلاصه‌سازی را روی سیستم داخلی انجام داد.

پردازش دسته‌ای

می‌توان تعداد زیادی متن را برای دسته‌بندی، استخراج اطلاعات یا اصلاح ساختار پردازش کرد.

آزمایش Agent

Ollama می‌تواند مدل محلی موردنیاز برای نمونه اولیه یک Agent یا ابزار خودکار را فراهم کند؛ البته قابلیت Tool Calling و کیفیت اجرای Agent به مدل انتخاب‌شده بستگی دارد.

توسعه بدون مصرف API

بخشی از توسعه و تست را می‌توان با مدل محلی انجام داد و در محیط Production از مدل‌های API استفاده کرد.

پیش‌نیازهای اجرای Ollama

پیش از نصب، این موارد را بررسی کنید:

• سیستم‌عامل ۶۴ بیتی
• فضای ذخیره‌سازی کافی
• حافظه RAM متناسب با مدل
• کارت گرافیک سازگار در صورت نیاز
• درایور مناسب GPU
• دسترسی به Terminal یا PowerShell
• اینترنت برای دانلود اولیه مدل
• زمان کافی برای دریافت فایل‌های چندگیگابایتی

چه مقدار RAM و VRAM نیاز داریم؟

نیاز سخت‌افزاری به عوامل مختلفی وابسته است:

• تعداد پارامترهای مدل
• نوع Quantization
• طول Context
• تعداد کاربران هم‌زمان
• CPU یا GPU بودن اجرا
• معماری مدل
• حجم KV Cache
• ورودی متنی یا تصویری
• Batch Size

جدول زیر فقط یک تخمین اولیه است:

این اعداد قطعی نیستند. یک نسخه Quantized ممکن است حافظه کمتری مصرف کند، اما افزایش Context یا تعداد درخواست هم‌زمان مصرف حافظه را بیشتر می‌کند.

اگر GPU نداشته باشیم چه می‌شود؟

بسیاری از مدل‌ها می‌توانند با CPU اجرا شوند، اما سرعت پاسخ معمولاً پایین‌تر خواهد بود. مدل‌های کوچک برای آزمایش روی CPU مناسب‌تر هستند.

برای برنامه تعاملی، سرعت تولید Token اهمیت زیادی دارد. مدلی که از نظر حافظه روی سیستم اجرا می‌شود، الزاماً سرعت قابل قبولی ندارد.

نصب Ollama در ویندوز

Ollama به‌صورت برنامه Native روی ویندوز اجرا می‌شود و API محلی آن روی پورت 11434 قرار می‌گیرد. نسخه ویندوز از GPUهای سازگار NVIDIA و AMD پشتیبانی می‌کند. مستندات رسمی Ollama برای Windows

مراحل نصب

۱. وارد وب‌سایت رسمی Ollama شوید.

۲. نسخه Windows را دانلود کنید.

۳. فایل نصب را اجرا کنید.

۴. مراحل نصب را کامل کنید.

۵. PowerShell یا Command Prompt را باز کنید.

۶. نسخه نصب‌شده را بررسی کنید:

ollama --version

۷. وضعیت CLI را بررسی کنید:

ollama

Ollama پس از نصب معمولاً در پس‌زمینه اجرا می‌شود.

بررسی API در ویندوز

در PowerShell اجرا کنید:

curl http://localhost:11434/api/tags

اگر سرویس در حال اجرا باشد، فهرست مدل‌های نصب‌شده به‌صورت JSON برگردانده می‌شود.

نصب Ollama در macOS

در macOS می‌توانید برنامه رسمی Ollama را دانلود و نصب کنید.

مراحل نصب

۱. نسخه macOS را از وب‌سایت رسمی دریافت کنید.

۲. برنامه را به پوشه Applications منتقل کنید.

۳. Ollama را اجرا کنید.

۴. Terminal را باز کنید.

۵. نصب را بررسی کنید:

ollama --version

۶. یک مدل سازگار را دریافت کنید:

ollama pull YOUR_LOCAL_MODEL

۷. مدل را اجرا کنید:

ollama run YOUR_LOCAL_MODEL

در سیستم‌های Apple Silicon، اندازه مدل را متناسب با Unified Memory دستگاه انتخاب کنید.

نصب Ollama در لینوکس

روش نصب ممکن است با نسخه و توزیع تغییر کند؛ بنابراین دستور نهایی را با مستندات رسمی Linux تطبیق دهید.

روش رایج نصب:

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

پس از نصب، سرویس را بررسی کنید:

sudo systemctl status ollama

در صورت نیاز آن را اجرا کنید:

sudo systemctl start ollama

فعال‌سازی هنگام Boot:

sudo systemctl enable ollama

بررسی نسخه:

ollama --version

بررسی API:

curl http://localhost:11434/api/tags

بررسی GPU انویدیا

nvidia-smi

اگر GPU نمایش داده نشود، درایور کارت گرافیک را پیش از عیب‌یابی Ollama بررسی کنید.

دانلود اولین مدل

برای دریافت یک مدل از دستور pull استفاده کنید:

ollama pull YOUR_LOCAL_MODEL

پس از پایان دانلود، آن را اجرا کنید:

ollama run YOUR_LOCAL_MODEL

یک پیام آزمایشی بنویسید:

یک تابع Python برای محاسبه میانگین اعداد بنویس و آن را توضیح بده.

برای خروج از محیط گفتگو:

/bye

مهم‌ترین دستورات Ollama CLI

نمایش راهنما

ollama --help

دریافت مدل

ollama pull YOUR_LOCAL_MODEL

اجرای مدل

ollama run YOUR_LOCAL_MODEL

مشاهده مدل‌های نصب‌شده

ollama list

مشاهده مدل‌های در حال اجرا

ollama ps

مشاهده اطلاعات مدل

ollama show YOUR_LOCAL_MODEL

توقف مدل

ollama stop YOUR_LOCAL_MODEL

حذف مدل

ollama rm YOUR_LOCAL_MODEL

اجرای سرویس

ollama serve

کپی مدل

ollama cp SOURCE_MODEL TARGET_MODEL

پیش از حذف مدل، نام آن را با ollama list بررسی کنید تا نسخه اشتباهی حذف نشود.

استفاده از Ollama API

Ollama دو Endpoint اصلی برای تولید پاسخ دارد:

POST /api/generate
POST /api/chat

generate برای یک Prompt مستقیم مناسب است و chat ساختار پیام‌های چندمرحله‌ای با Roleهای مختلف را دریافت می‌کند.

ارسال درخواست Generate با cURL

curl http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_LOCAL_MODEL",
    "prompt": "سه کاربرد Python در هوش مصنوعی را توضیح بده.",
    "stream": false
  }'

براساس مستندات Generate API، این Endpoint علاوه بر Prompt از گزینه‌هایی مانند System Prompt، Streaming و قالب Structured Output پشتیبانی می‌کند.

ارسال پیام Chat با cURL

curl http://localhost:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_LOCAL_MODEL",
    "messages": [
      {
        "role": "system",
        "content": "شما یک مدرس حرفه‌ای Python هستید."
      },
      {
        "role": "user",
        "content": "تفاوت list و tuple را با مثال توضیح بده."
      }
    ],
    "stream": false
  }'

ساختار messages برای برنامه‌های گفت‌وگومحور مناسب‌تر است. مستندات Chat API در Ollama

Streaming در Ollama

Ollama به‌صورت پیش‌فرض می‌تواند پاسخ را تدریجی ارسال کند. این روش برای رابط گفت‌وگو مناسب است؛ چون کاربر لازم نیست تا پایان تولید پاسخ منتظر بماند.

در حالت Streaming، چند JSON پشت سر هم دریافت می‌شود.

برای غیرفعال‌کردن Streaming:

{
  "stream": false
}

طبق راهنمای Streaming در Ollama، Streaming برای پاسخ‌های طولانی و کاهش تأخیر ادراکی مناسب است، درحالی‌که حالت غیرجریانی برای پاسخ کوتاه و Structured Output ساده‌تر است.

اتصال Python به Ollama API

ابتدا کتابخانه requests را نصب کنید:

pip install requests

سپس فایل ollama_chat.py را بسازید:

import requests

OLLAMA_URL = "http://localhost:11434/api/chat"
LOCAL_MODEL = "YOUR_LOCAL_MODEL"

payload = {
    "model": LOCAL_MODEL,
    "messages": [
        {
            "role": "system",
            "content": (
                "شما یک دستیار برنامه‌نویسی هستید. "
                "پاسخ‌ها را دقیق و همراه مثال بده."
            )
        },
        {
            "role": "user",
            "content": (
                "یک تابع Python برای حذف مقادیر تکراری "
                "از لیست بنویس."
            )
        }
    ],
    "stream": False
}

try:
    response = requests.post(
        OLLAMA_URL,
        json=payload,
        timeout=120
    )

    response.raise_for_status()
    data = response.json()

    print(data["message"]["content"])

except requests.exceptions.ConnectionError:
    print("اتصال به Ollama برقرار نشد. سرویس را بررسی کنید.")

except requests.exceptions.Timeout:
    print("مدل در زمان تعیین‌شده پاسخ نداد.")

except requests.exceptions.HTTPError as error:
    print("HTTP Error:", error)
    print(response.text)

except (KeyError, ValueError) as error:
    print("ساختار پاسخ نامعتبر است:", error)

اجرا:

python ollama_chat.py

دریافت پاسخ Streaming در Python

import json
import requests

OLLAMA_URL = "http://localhost:11434/api/chat"
LOCAL_MODEL = "YOUR_LOCAL_MODEL"

payload = {
    "model": LOCAL_MODEL,
    "messages": [
        {
            "role": "user",
            "content": "یک آموزش کوتاه درباره FastAPI بنویس."
        }
    ],
    "stream": True
}

with requests.post(
    OLLAMA_URL,
    json=payload,
    stream=True,
    timeout=180
) as response:
    response.raise_for_status()

    for line in response.iter_lines():
        if not line:
            continue

        chunk = json.loads(line.decode("utf-8"))
        content = chunk.get("message", {}).get("content", "")

        print(content, end="", flush=True)

print()

در برنامه Production باید قطع اتصال کاربر، Timeout، لغو درخواست و خطاهای وسط Stream نیز مدیریت شوند.

اتصال Node.js به Ollama

در Node.js جدید می‌توان از fetch داخلی استفاده کرد.

فایل ollama-chat.mjs:

const OLLAMA_URL = "http://localhost:11434/api/chat";
const LOCAL_MODEL = "YOUR_LOCAL_MODEL";

const payload = {
  model: LOCAL_MODEL,
  messages: [
    {
      role: "system",
      content: "شما یک دستیار متخصص JavaScript هستید."
    },
    {
      role: "user",
      content: "تفاوت Promise.all و Promise.allSettled را توضیح بده."
    }
  ],
  stream: false
};

try {
  const response = await fetch(OLLAMA_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload),
    signal: AbortSignal.timeout(120000)
  });

  if (!response.ok) {
    const details = await response.text();

    throw new Error(
      `Ollama HTTP ${response.status}: ${details}`
    );
  }

  const data = await response.json();

  console.log(data.message.content);
} catch (error) {
  console.error("Ollama request failed:", error.message);
}

اجرا:

node ollama-chat.mjs

استفاده از OpenAI SDK با Ollama

Ollama با بخشی از OpenAI API سازگار است. این قابلیت اجازه می‌دهد بعضی برنامه‌هایی را که از OpenAI SDK استفاده می‌کنند، با تغییر Base URL به مدل محلی متصل کنید. مستندات OpenAI Compatibility در Ollama

نصب SDK:

pip install openai

نمونه کد:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

response = client.chat.completions.create(
    model="YOUR_LOCAL_MODEL",
    messages=[
        {
            "role": "system",
            "content": "شما یک متخصص توسعه Backend هستید."
        },
        {
            "role": "user",
            "content": (
                "ساختار یک REST API ساده با FastAPI را پیشنهاد بده."
            )
        }
    ],
    temperature=0.2
)

print(response.choices[0].message.content)

Ollama برای API محلی به API Key واقعی نیاز ندارد؛ اما OpenAI SDK انتظار دارد مقدار api_key وجود داشته باشد، بنابراین یک مقدار غیرحساس مانند ollama قرار می‌دهیم.

چرا سازگاری با OpenAI API مهم است؟

فرض کنید برنامه شما از قبل چنین معماری دارد:

client = OpenAI(
    base_url=BASE_URL,
    api_key=API_KEY
)

با تغییر base_url و model می‌توانید بین Ollama و یک API سازگار مانند درواره جابه‌جا شوید.

مدل محلی:

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

API درواره:

client = OpenAI(
    base_url="https://api.darvareh.ir/v1",
    api_key="YOUR_DARVAREH_API_KEY"
)

این شباهت، ساخت معماری Multi-Model و Hybrid را بسیار ساده‌تر می‌کند.

دریافت خروجی JSON از Ollama

برای خودکارسازی نرم‌افزار، متن آزاد همیشه مناسب نیست. می‌توان از مدل خواست خروجی JSON تولید کند.

نمونه با API اصلی Ollama:

import json
import requests

schema = {
    "type": "object",
    "properties": {
        "language": {
            "type": "string"
        },
        "difficulty": {
            "type": "string",
            "enum": ["beginner", "intermediate", "advanced"]
        },
        "topics": {
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    },
    "required": [
        "language",
        "difficulty",
        "topics"
    ]
}

payload = {
    "model": "YOUR_LOCAL_MODEL",
    "prompt": (
        "متن زیر را تحلیل کن:\n"
        "این دوره درباره ساخت API با Python و FastAPI است."
    ),
    "format": schema,
    "stream": False
}

response = requests.post(
    "http://localhost:11434/api/generate",
    json=payload,
    timeout=120
)

response.raise_for_status()
data = response.json()

structured_data = json.loads(data["response"])

print(json.dumps(
    structured_data,
    ensure_ascii=False,
    indent=2
))

حتی با وجود Schema، خروجی را اعتبارسنجی کنید. قابلیت Structured Output به کیفیت و تبعیت مدل نیز وابسته است.

ساخت Embedding با Ollama

Embedding یک بردار عددی است که معنای متن را نمایش می‌دهد. از آن برای این کاربردها استفاده می‌شود:

• جست‌وجوی معنایی
• RAG
• پیدا‌کردن متن مشابه
• خوشه‌بندی اسناد
• پیشنهاد محتوا
• تشخیص شباهت سوال‌ها
• دسته‌بندی داده

Endpoint مربوط به Embedding:

POST /api/embed

نمونه Python:

import requests

payload = {
    "model": "YOUR_EMBEDDING_MODEL",
    "input": [
        "Ollama ابزار اجرای مدل‌های محلی است.",
        "درواره API یکپارچه مدل‌های هوش مصنوعی است."
    ]
}

response = requests.post(
    "http://localhost:11434/api/embed",
    json=payload,
    timeout=120
)

response.raise_for_status()
data = response.json()

embeddings = data["embeddings"]

print("Number of vectors:", len(embeddings))
print("Vector dimensions:", len(embeddings[0]))

مستندات Ollama یک Endpoint مستقل برای تولید Embedding ارائه می‌کنند. مستندات Embed API

نکته مهم درباره Embedding

بردارهای تولیدشده توسط مدل‌های مختلف قابل جایگزینی مستقیم نیستند. اگر Vector Database را با یک مدل ساخته‌اید، برای Query نیز باید همان مدل یا نسخه سازگار را استفاده کنید.

با تغییر مدل Embedding معمولاً لازم است تمام اسناد دوباره پردازش شوند.

ساخت مدل سفارشی با Modelfile

Modelfile به شما اجازه می‌دهد یک مدل پایه را با تنظیمات و System Prompt دلخواه بسته‌بندی کنید.

نمونه فایل Modelfile:

FROM YOUR_BASE_MODEL

PARAMETER temperature 0.2
PARAMETER num_ctx 8192

SYSTEM """
شما یک دستیار برنامه‌نویسی فارسی هستید.
پاسخ‌ها باید:
- دقیق و عملی باشند.
- کد کامل و قابل اجرا داشته باشند.
- فرضیات را مشخص کنند.
- خطاهای احتمالی را توضیح دهند.
- اصطلاحات فنی را به شکل رایج فارسی و انگلیسی بنویسند.
"""

ساخت مدل:

ollama create darvareh-coder -f Modelfile

اجرای مدل:

ollama run darvareh-coder

بررسی اطلاعات:

ollama show darvareh-coder

این فرایند معمولاً مدل را Fine-tune نمی‌کند. شما بیشتر یک مدل پایه را با Template، پارامترها و System Prompt مشخص بسته‌بندی می‌کنید.

تفاوت Modelfile با Fine-tuning

برای بسیاری از پروژه‌ها ابتدا System Prompt، Structured Output و RAG را آزمایش کنید. Fine-tuning زمانی مناسب است که مسئله با Prompt و Retrieval حل نشود و Dataset مناسبی داشته باشید.

ساخت چت‌بات ساده با FastAPI و Ollama

نصب وابستگی‌ها:

pip install fastapi uvicorn requests pydantic

فایل app.py:

from typing import Literal
import requests
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, Field

app = FastAPI(
    title="Ollama Chat API",
    version="1.0.0"
)

OLLAMA_URL = "http://localhost:11434/api/chat"
LOCAL_MODEL = "YOUR_LOCAL_MODEL"


class Message(BaseModel):
    role: Literal["system", "user", "assistant"]
    content: str = Field(min_length=1, max_length=10000)


class ChatRequest(BaseModel):
    messages: list[Message] = Field(min_length=1, max_length=30)


@app.post("/chat")
def chat(request: ChatRequest):
    payload = {
        "model": LOCAL_MODEL,
        "messages": [
            message.model_dump()
            for message in request.messages
        ],
        "stream": False
    }

    try:
        response = requests.post(
            OLLAMA_URL,
            json=payload,
            timeout=180
        )

        response.raise_for_status()
        data = response.json()

        return {
            "model": LOCAL_MODEL,
            "message": data["message"]["content"]
        }

    except requests.exceptions.Timeout:
        raise HTTPException(
            status_code=504,
            detail="Ollama response timed out"
        )

    except requests.exceptions.ConnectionError:
        raise HTTPException(
            status_code=503,
            detail="Ollama is not available"
        )

    except requests.exceptions.HTTPError as error:
        raise HTTPException(
            status_code=502,
            detail="Ollama request failed: {}".format(error)
        )

    except (KeyError, ValueError):
        raise HTTPException(
            status_code=502,
            detail="Invalid response from Ollama"
        )

اجرا:

uvicorn app:app --reload

آزمایش:

curl http://127.0.0.1:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "یک مثال ساده از Dependency Injection در FastAPI بده."
      }
    ]
  }'

برای Production باید Authentication، Rate Limit، Log، Monitoring، Queue، Streaming و مدیریت هم‌زمانی نیز اضافه شوند.

ساخت معماری ترکیبی Ollama و درواره

مدل محلی برای تمام وظایف مناسب نیست. یک معماری ترکیبی می‌تواند درخواست‌ها را براساس پیچیدگی، حساسیت و منابع موجود مسیریابی کند.

درخواست کاربر
    ↓
بررسی نوع وظیفه
    ↓
آیا محلی و ساده است؟
    ├── بله → Ollama
    └── خیر → API درواره

نمونه تقسیم وظایف:

پیاده‌سازی Router ترکیبی با Python

ابتدا SDK را نصب کنید:

pip install openai

نمونه کد:

from openai import OpenAI

LOCAL_BASE_URL = "http://localhost:11434/v1"
DARVAREH_BASE_URL = "https://api.darvareh.ir/v1"

LOCAL_MODEL = "YOUR_LOCAL_MODEL"
DARVAREH_MODEL = "YOUR_MODEL_ID"

local_client = OpenAI(
    base_url=LOCAL_BASE_URL,
    api_key="ollama"
)

darvareh_client = OpenAI(
    base_url=DARVAREH_BASE_URL,
    api_key="YOUR_DARVAREH_API_KEY"
)


def choose_route(
    task_type: str,
    prompt_length: int,
    needs_vision: bool,
    requires_strong_reasoning: bool
) -> str:
    if needs_vision:
        return "darvareh"

    if requires_strong_reasoning:
        return "darvareh"

    if prompt_length > 8000:
        return "darvareh"

    local_tasks = {
        "classification",
        "short_summary",
        "rewrite",
        "tagging"
    }

    if task_type in local_tasks:
        return "local"

    return "darvareh"


def generate(
    prompt: str,
    task_type: str = "general",
    needs_vision: bool = False,
    requires_strong_reasoning: bool = False
) -> dict:
    route = choose_route(
        task_type=task_type,
        prompt_length=len(prompt),
        needs_vision=needs_vision,
        requires_strong_reasoning=requires_strong_reasoning
    )

    if route == "local":
        client = local_client
        model = LOCAL_MODEL
    else:
        client = darvareh_client
        model = DARVAREH_MODEL

    response = client.chat.completions.create(
        model=model,
        messages=[
            {
                "role": "system",
                "content": (
                    "پاسخ دقیق، کاربردی و مختصر ارائه کن."
                )
            },
            {
                "role": "user",
                "content": prompt
            }
        ],
        temperature=0.2
    )

    return {
        "route": route,
        "model": model,
        "content": response.choices[0].message.content
    }


result = generate(
    prompt="این متن را در یک پاراگراف خلاصه کن.",
    task_type="short_summary"
)

print("Route:", result["route"])
print("Model:", result["model"])
print(result["content"])

این Router ابتدایی و Rule-based است. در یک سیستم واقعی باید معیارهای بیشتری در نظر گرفته شوند:

• زمان پاسخ
• حافظه آزاد GPU
• تعداد درخواست‌های در صف
• طول Context
• هزینه مدل ابری
• کیفیت موردنیاز
• زبان ورودی
• قابلیت Tool Calling
• نیاز به Structured Output
• وضعیت سلامت سرویس محلی

افزودن Fallback از Ollama به درواره

اگر Ollama متوقف شود، حافظه کافی نداشته باشد یا در زمان مشخص پاسخ ندهد، درخواست می‌تواند به مدل درواره منتقل شود.

from openai import OpenAI, APIConnectionError, APITimeoutError

local_client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
    timeout=60
)

darvareh_client = OpenAI(
    base_url="https://api.darvareh.ir/v1",
    api_key="YOUR_DARVAREH_API_KEY",
    timeout=120
)


def chat_with_fallback(prompt: str) -> dict:
    messages = [
        {
            "role": "user",
            "content": prompt
        }
    ]

    try:
        local_response = local_client.chat.completions.create(
            model="YOUR_LOCAL_MODEL",
            messages=messages,
            temperature=0.2
        )

        return {
            "provider": "local",
            "content": local_response.choices[0].message.content
        }

    except (APIConnectionError, APITimeoutError):
        remote_response = darvareh_client.chat.completions.create(
            model="YOUR_MODEL_ID",
            messages=messages,
            temperature=0.2
        )

        return {
            "provider": "darvareh",
            "content": remote_response.choices[0].message.content
        }

در Production بهتر است Fallback فقط برای خطاهای قابل بازیابی انجام شود. برای مثال، خطای ورودی نامعتبر نباید با ارسال همان درخواست اشتباه به مدل دیگر تکرار شود.

انتخاب مدل مناسب برای Ollama

هنگام انتخاب مدل محلی فقط به تعداد پارامترها نگاه نکنید. معیارهای مهم عبارت‌اند از:

• زبان فارسی
• کیفیت برنامه‌نویسی
• توانایی استدلال
• پشتیبانی از Tool Calling
• پشتیبانی از تصویر
• طول Context
• سرعت تولید
• میزان RAM و VRAM
• مجوز مدل
• اندازه فایل
• نوع Quantization
• سازگاری با سیستم شما

مدل کوچک یا بزرگ؟

مدل کوچک:

• سریع‌تر اجرا می‌شود.
• حافظه کمتری مصرف می‌کند.
• برای دسته‌بندی و بازنویسی ساده مناسب است.
• در استدلال پیچیده خطای بیشتری دارد.

مدل بزرگ:

• معمولاً کیفیت بهتری دارد.
• حافظه بیشتری مصرف می‌کند.
• سرعت پایین‌تری روی سخت‌افزار ضعیف دارد.
• برای کارهای پیچیده مناسب‌تر است.
• ممکن است اصلاً روی سیستم شخصی قابل اجرا نباشد.

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

ارزیابی مدل محلی پیش از استفاده

یک Dataset کوچک از وظایف واقعی خود بسازید:

[
  {
    "task": "classification",
    "input": "متن نمونه اول",
    "expected": "technical"
  },
  {
    "task": "summary",
    "input": "متن نمونه دوم",
    "expected_points": [
      "نکته اول",
      "نکته دوم"
    ]
  }
]

سپس مدل‌ها را براساس این معیارها مقایسه کنید:

• دقت
• تبعیت از دستور
• کیفیت فارسی
• صحت کد
• سرعت پاسخ
• مصرف حافظه
• طول پاسخ
• پایداری JSON
• نرخ خطا
• Token در ثانیه

برای انتخاب مسیر Local یا API، ارزیابی واقعی پروژه از Benchmark عمومی مهم‌تر است.

خطاهای رایج Ollama

خطای Connection Refused

علت احتمالی:

• سرویس Ollama اجرا نشده است.
• پورت تغییر کرده است.
• برنامه به Host اشتباه متصل می‌شود.

بررسی:

ollama serve

یا در Linux:

sudo systemctl status ollama

خطای Model Not Found

فهرست مدل‌ها را ببینید:

ollama list

مدل را دریافت کنید:

ollama pull YOUR_LOCAL_MODEL

سرعت بسیار پایین

دلایل احتمالی:

• مدل برای سخت‌افزار بزرگ است.
• اجرا روی CPU انجام می‌شود.
• Context بیش‌ازحد طولانی است.
• حافظه کافی وجود ندارد.
• چند مدل هم‌زمان در حافظه هستند.
• برنامه‌های دیگر GPU را مصرف می‌کنند.

مدل‌های فعال:

ollama ps

کمبود حافظه

راهکارهای احتمالی:

• مدل کوچک‌تر انتخاب کنید.
• Quantization سبک‌تر استفاده کنید.
• Context را کاهش دهید.
• مدل‌های دیگر را متوقف کنید.
• درخواست‌های هم‌زمان را محدود کنید.
• وظیفه سنگین را به API درواره منتقل کنید.

پاسخ ضعیف فارسی

• مدل دیگری را آزمایش کنید.
• System Prompt فارسی دقیق‌تری بنویسید.
• نمونه خروجی مطلوب ارائه دهید.
• Temperature را کاهش دهید.
• مدل را روی Dataset واقعی خود ارزیابی کنید.
• برای وظایف مهم از مدل قدرتمندتر در درواره استفاده کنید.

JSON نامعتبر

• از Schema استفاده کنید.
• Streaming را برای خروجی ساختاریافته غیرفعال کنید.
• Temperature را کاهش دهید.
• پاسخ را اعتبارسنجی کنید.
• در صورت خطا یک Retry کنترل‌شده انجام دهید.

آیا باید پورت Ollama را در اینترنت باز کنیم؟

در حالت محلی، API Ollama به API Key نیاز ندارد. مستندات رسمی نیز بیان می‌کنند که دسترسی محلی به localhost:11434 بدون Authentication انجام می‌شود. مستندات Authentication در Ollama

بنابراین سرویس محلی را بدون لایه محافظ مستقیماً در اینترنت منتشر نکنید.

برای استفاده تیمی بهتر است این معماری را داشته باشید:

کاربر
    ↓
Backend دارای Authentication
    ↓
Rate Limit و Validation
    ↓
Ollama در شبکه داخلی

Backend باید موارد زیر را کنترل کند:

• احراز هویت
• محدودیت درخواست
• طول Prompt
• تعداد Token
• Timeout
• Log
• دسترسی به مدل‌ها
• هم‌زمانی
• Queue
• خطاها

Ollama برای Production مناسب است؟

پاسخ به مقیاس پروژه بستگی دارد.

Ollama برای این موارد مناسب است:

• نمونه اولیه
• محیط توسعه
• ابزار شخصی
• اپلیکیشن تک‌کاربره
• پردازش داخلی محدود
• سرویس تیم کوچک با بار کنترل‌شده
• اجرای مدل‌های کوچک در شبکه داخلی

برای سرویس عمومی پرترافیک باید موارد زیر را ارزیابی کنید:

• مدیریت چند GPU
• Load Balancing
• Queue
• Autoscaling
• Observability
• Throughput
• Batch Processing
• Model Replication
• High Availability
• Rolling Update
• مدیریت حافظه
• Rate Limit
• هزینه نگهداری GPU

در بعضی پروژه‌ها هزینه خرید و نگهداری GPU از استفاده از API بیشتر می‌شود؛ مخصوصاً وقتی مصرف نامنظم باشد یا به مدل‌های بزرگ نیاز داشته باشید.

مقایسه مدل محلی و API درواره

بهترین معماری برای یک استارتاپ

برای بسیاری از تیم‌ها این مسیر عملی است:

مرحله اول: توسعه

• استفاده از Ollama برای تست‌های ساده
• استفاده از داده غیرحساس
• طراحی رابط OpenAI-compatible
• جداسازی Model ID از کد
• ساخت Evals اولیه

مرحله دوم: آزمایش کیفیت

• مقایسه مدل محلی با مدل‌های درواره
• اندازه‌گیری سرعت و دقت
• محاسبه هزینه واقعی GPU
• تعیین وظایف مناسب هر مسیر

مرحله سوم: معماری ترکیبی

• اجرای کارهای ساده به‌صورت محلی
• انتقال کارهای پیچیده به درواره
• افزودن Fallback
• ثبت هزینه و کیفیت هر مسیر

مرحله چهارم: Production

• افزودن Monitoring
• Rate Limit
• Queue
• Timeout
• Retry کنترل‌شده
• Evals خودکار
• محدودیت بودجه
• مدیریت نسخه مدل

چک‌لیست راه‌اندازی Ollama

نصب

• Ollama از منبع رسمی نصب شده است.
• نسخه CLI بررسی شده است.
• سرویس روی localhost:11434 پاسخ می‌دهد.
• GPU و درایور شناسایی شده‌اند.
• فضای ذخیره‌سازی کافی وجود دارد.

انتخاب مدل

• مدل با سخت‌افزار سازگار است.
• کیفیت فارسی آزمایش شده است.
• سرعت تولید اندازه‌گیری شده است.
• Context موردنیاز بررسی شده است.
• مجوز مدل بررسی شده است.
• مدل روی Dataset واقعی ارزیابی شده است.

برنامه‌نویسی

• Timeout تعریف شده است.
• خطاهای اتصال مدیریت می‌شوند.
• Streaming در صورت نیاز پیاده‌سازی شده است.
• خروجی JSON اعتبارسنجی می‌شود.
• نام مدل در تنظیمات قرار دارد.
• Prompt داخل کد پراکنده نشده است.

Production

• پورت Ollama مستقیماً عمومی نیست.
• Backend احراز هویت دارد.
• Rate Limit وجود دارد.
• تعداد درخواست هم‌زمان محدود است.
• مصرف RAM و GPU مانیتور می‌شود.
• Fallback به درواره وجود دارد.
• مدل و Prompt نسخه‌بندی شده‌اند.

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

Ollama چیست؟

Ollama ابزاری برای دانلود، مدیریت و اجرای مدل‌های هوش مصنوعی روی ویندوز، لینوکس و macOS است و یک API محلی نیز ارائه می‌دهد.

آیا Ollama رایگان است؟

خود ابزار Ollama برای اجرای محلی قابل دانلود است، اما باید هزینه سخت‌افزار، برق، فضای ذخیره‌سازی و نگهداری سیستم را در نظر بگیرید. شرایط استفاده و مجوز هر مدل نیز جداگانه است.

آیا Ollama بدون اینترنت کار می‌کند؟

پس از نصب و دانلود کامل مدل محلی، بسیاری از عملیات آن بدون اینترنت انجام می‌شوند. دریافت مدل جدید یا استفاده از سرویس‌های غیرمحلی به اینترنت نیاز دارد.

آیا Ollama روی ویندوز نصب می‌شود؟

بله. Ollama نسخه Native برای Windows دارد و پس از نصب API آن معمولاً روی localhost:11434 در دسترس است.

آیا برای Ollama کارت گرافیک لازم است؟

الزاماً نه، اما GPU سازگار می‌تواند سرعت را به شکل محسوسی افزایش دهد. اجرای مدل بزرگ روی CPU ممکن است بسیار کند باشد.

آیا Ollama از API سازگار با OpenAI پشتیبانی می‌کند؟

بله. Ollama بخشی از OpenAI API را پشتیبانی می‌کند و می‌توان بعضی ابزارها و SDKهای سازگار را به Base URL محلی آن متصل کرد.

Base URL اولاما چیست؟

برای API اصلی:

http://localhost:11434/api

برای OpenAI Compatibility:

http://localhost:11434/v1

آیا می‌توان Ollama را با Python استفاده کرد؟

بله. می‌توانید با requests، OpenAI SDK یا کتابخانه‌های سازگار به API محلی Ollama درخواست ارسال کنید.

آیا Ollama برای RAG مناسب است؟

بله. می‌توان از Ollama برای تولید Embedding و پاسخ نهایی استفاده کرد. کیفیت سیستم به مدل، Chunking، Retrieval و Vector Database نیز بستگی دارد.

آیا Ollama برای برنامه‌نویسی مناسب است؟

بله، به شرط انتخاب مدل مناسب کدنویسی و سخت‌افزار کافی. برای تحلیل‌های پیچیده ممکن است مدل‌های قدرتمندتر API نتیجه بهتری ارائه دهند.

Ollama بهتر است یا API هوش مصنوعی؟

هیچ پاسخ یکسانی برای تمام پروژه‌ها وجود ندارد. Ollama برای اجرای محلی و کنترل بیشتر مناسب است؛ API برای دسترسی سریع به مدل‌های قدرتمند و حذف هزینه نگهداری زیرساخت. معماری ترکیبی اغلب انتخاب مناسبی است.

آیا می‌توان Ollama و درواره را هم‌زمان استفاده کرد؟

بله. چون هر دو امکان اتصال از طریق ساختار سازگار با OpenAI را فراهم می‌کنند، می‌توانید وظایف ساده را به Ollama و وظایف پیچیده را به API درواره ارسال کنید.

آیا می‌توان هنگام قطع Ollama از درواره به‌عنوان Fallback استفاده کرد؟

بله. برنامه می‌تواند خطاهای اتصال و Timeout سرویس محلی را تشخیص دهد و درخواست را به مدل انتخاب‌شده در درواره منتقل کند.

جمع‌بندی

Ollama یکی از ساده‌ترین راه‌ها برای شروع کار با مدل‌های هوش مصنوعی محلی است. این ابزار نصب Runtime، دانلود مدل، اجرای گفتگو و ارائه API محلی را در یک جریان کاری ساده قرار می‌دهد.

با Ollama می‌توانید:

• مدل محلی اجرا کنید.
• چت‌بات بسازید.
• از Python و Node.js درخواست ارسال کنید.
• از OpenAI SDK استفاده کنید.
• Embedding تولید کنید.
• خروجی JSON بگیرید.
• مدل را با Modelfile شخصی‌سازی کنید.
• نمونه اولیه RAG و Agent بسازید.
• بخشی از پردازش‌های ساده را داخل سیستم خود نگه دارید.

اما اجرای محلی محدودیت‌هایی مانند نیاز به RAM، VRAM، فضای ذخیره‌سازی، نگهداری زیرساخت و کیفیت پایین‌تر بعضی مدل‌های کوچک دارد. برای وظایف سنگین، مدل‌های چندوجهی، تولید تصویر و ویدئو، استدلال پیچیده یا بار کاری متغیر، استفاده از API مدیریت‌شده می‌تواند انتخاب مناسب‌تری باشد.

بهترین معماری برای بسیاری از پروژه‌ها، معماری ترکیبی است: Ollama برای پردازش محلی و وظایف ساده، و درواره برای دسترسی به مدل‌های قدرتمند، متنوع و مقیاس‌پذیر.

برای ساخت این معماری و اتصال نرم‌افزار خود به مدل‌های مختلف هوش مصنوعی، در درواره ثبت‌نام کنید. برای مشاهده Model IDها و قیمت‌های به‌روز نیز صفحه مدل‌های درواره را ببینید.

مقالات مرتبط

• Open WebUI چیست؟ آموزش نصب، Docker، Ollama و اتصال به API درواره
• آموزش اتصال OpenCode به API درواره
• آموزش اتصال Cline به API درواره
• OpenAI-Compatible API چیست؟
• API هوش مصنوعی چیست؟
• بهترین مدل هوش مصنوعی برای برنامه‌نویسی
• ابزارهای هوش مصنوعی برنامه‌نویسی؛ بخش اول
• ابزارهای هوش مصنوعی برنامه‌نویسی؛ بخش دوم
• Qwen چیست؟ معرفی خانواده مدل‌های هوش مصنوعی کوئن
• Llama چیست؟ معرفی خانواده مدل‌های هوش مصنوعی متا

برای مطالعه شرایط استفاده و محدودیت‌های مسئولیت، صفحه «سلب مسئولیت» را مشاهده کنید.