استفاده از مدلهای زبانی روی سیستمهای محلی و ابزارهایی مانند Ollama مسیر توسعه را برای برنامهنویسان سادهتر کردهاند. یکی از مولفههای کلیدی در این اکوسیستم، Ollama SDK است؛ مجموعهای از رابطها و کتابخانهها که امکان فراخوانی مدلها، اجرای درخواستها، مدیریت استریم خروجی و ساختن اپلیکیشنهای هوش مصنوعی را با کمترین پیچیدگی فراهم میکند.
گرچه Ollama اصطلاح «SDK» را بهصورت رسمی استفاده نمیکند، اما مجموعهای از ابزارهای API، کتابخانههای Python و JavaScript و رابط خط فرمان (CLI)، عملا نقش یک SDK کامل را ایفا میکنند. در ادامه ساختار و معماری این ابزارها را بررسی میکنیم و با نمونهکدهای کاربردی، نحوهی استفاده از آنها در پروژههای واقعی را نشان خواهیم داد.
Ollama چیست و چرا SDK اهمیت دارد؟
Ollama یک سرویس لوکال برای اجرای مدلهای هوش مصنوعی (مانند Llama 3، Qwen، Mistral یا Gemma) روی کامپیوتر شخصی است. به جای اینکه درخواستها را به سرورهای ابری ارسال کنید، Ollama مدل را روی لپتاپ یا سیستم شخصی اجرا میکند و نتیجه را بدون وابستگی به اینترنت برمیگرداند. نتیجهی این طراحی، تجربهای مشابه APIهای ابری — اما کاملا آفلاین — است. به همین دلیل، در پروژههایی که نیاز به امنیت بالا، پردازش محلی یا هزینه صفر دارند، به سرعت محبوب شده است.
در چنین معماریای، وجود یک SDK اهمیت ویژهای دارد؛ زیرا بدون آن، توسعهدهندگان باید مستقیما با APIهای خام HTTP کار کنند که مدیریت خطا، استریم، احراز هویت یا ساختار درخواست را پیچیدهتر میکند. Ollama SDK این لایه را انتزاع کرده و تجربه توسعه را سادهتر، خواناتر و سریعتر میکند.
معماری SDK در Ollama
اگرچه Ollama عبارتی مثل «Official SDK» منتشر نکرده، اما معماری داخلی آن عملا شامل سه بخش اصلی است:
۱. REST API
Ollama پس از اجرا، یک API محلی روی پورت 11434 ایجاد میکند. یعنی Ollama پس از نصب، یک سرور داخلی روی آدرس پیشفرض زیر ایجاد میکند:
http://localhost:11434
این API از سه قابلیت اصلی پشتیبانی میکند:
- generate برای تولید متن
- chat برای مکالمه با مدل
- embed برای ساخت embedding
این API پایهی تمام کتابخانهها و SDKهای غیررسمی است.
۲. Client Libraries (Python و JavaScript)
Ollama برای سهولت کار توسعهدهندگان، دو کلاینت رسمی ارائه داده است:
- پکیج Python با نام ollama
- پکیج JavaScript برای Node.js و Web
این کلاینتها مستقیم به API متصل میشوند و نحوهی استفاده از Ollama را بسیار سادهتر میکنند و به شما اجازه میدهند:
- ارسال پیام برای Chat/Completion
- دریافت خروجی بهصورت Streaming
- ساخت یا بارگذاری مدل با فایلهای فرمان (Modelfile)
- اجرای Embedding
- مدیریت Pull / List / Create
- اجرای مدلهای سنگین با GPU یا CPU
۳. CLI
رابط خط فرمان Ollama:
- اجرای مدل
- لیست مدلها
- Pull/Remove
- مدیریت حافظه
- تست سریع مدلها
CLI بخشی از «SDK کاربردی» محسوب میشود، چون مبنای توسعه و دیباگ است.
ساختار SDK به سه لایه تقسیم میشود:
- Transport Layer: ارتباط HTTP با سرور لوکال Ollama، مدیریت اتصال، ارسال درخواست و دریافت استریم.
- Abstraction Layer: تبدیل درخواستها به واسط سادهتر که به شکل توابع Python یا JavaScript قابل دسترس است.
- Application Layer: جایی که توسعهدهنده در آن کار میکند: چتبات، API داخلی، وباپ یا ابزار تحلیل.
Python SDK
Ollama یک کلاینت رسمی پایتون منتشر کرده که مهمترین مزیتش سادگی و پشتیبانی از استریم است.
نصب:
|
1 |
pip install ollama |
مثال پایه (Chat Completion):
|
1 2 3 4 5 6 7 8 9 |
from ollama import Client client = Client() response = client.chat(model=“llama3”, messages=[ {“role”: “user”, “content”: “Explain quantum computing simply.”} ]) print(response[‘message’][‘content’]) |
استریم خروجی:
|
1 2 3 4 5 6 |
stream = client.chat(model=“llama3”, messages=[ {“role”: “user”, “content”: “Write a poem about AI.”} ], stream=True) for chunk in stream: print(chunk[‘message’][‘content’], end=“”) |
Embeddings:
|
1 2 3 4 5 |
from ollama import Client client = Client() emb = client.embeddings(model=“llama3”, prompt=“Artificial intelligence is fascinating.”) print(emb[“embedding”]) |
مزایای Python SDK
- سادگی و مینیمالیستی
- پشتیبانی داخلی از استریم
- عدم نیاز به مدیریت دستی HTTP
- مناسب برای ساخت:
- چتبات داخلی
- ابزارهای NLP
- سرویسهای دستهای
- اپلیکیشنهای علمی یا پژوهشی
Ollama JavaScript / Node.js SDK
برای اپلیکیشنهای وب، Node.js و Front-End، کلاینت جاوااسکریپت بهترین گزینه است.
نصب:
|
1 |
npm install ollama |
مثال چت:
|
1 2 3 4 5 6 7 8 |
import ollama from ‘ollama’; const response = await ollama.chat({ model: ‘llama3’, messages: [{ role: ‘user’, content: ‘Hello! What can you do?’ }] }); console.log(response.message.content); |
استریم:
|
1 2 3 4 5 6 7 8 9 |
const stream = await ollama.chat({ model: ‘llama3’, stream: true, messages: [{ role: ‘user’, content: ‘Write a haiku about programming.’ }] }); for await (const chunk of stream) { process.stdout.write(chunk.message.content); } |
Embeddings:
|
1 2 3 4 5 |
const emb = await ollama.embeddings({ model: ‘llama3’, prompt: ‘Deep learning is amazing.’ }); console.log(emb.embedding); |
موارد استفاده JavaScript SDK
- ساخت چتبات داخل وبسایت
- ادغام مدلها در Next.js، Express یا Electron
- ساخت ابزارهای فرانتاند با React/Node
- ساخت افزونههای مرورگر
REST API (مبنای SDK)
میتوانید مستقیما با REST API کار کنید.
Endpoint: Generate
|
1 2 3 4 5 |
POST /api/generate { “model”: “llama3”, “prompt”: “Hello” } |
Endpoint: Chat
|
1 2 3 4 5 6 7 |
POST /api/chat { “model”: “llama3”, “messages”: [ { “role”: “user”, “content”: “Tell me a joke” } ] } |
Endpoint: Embeddings
|
1 2 3 4 5 |
POST /api/embed { “model”: “mxbai-embed-large”, “input”: “sample text” } |
تمام Client Libraries دقیقاً همین API را فراخوانی میکنند.
مثالهای کاربردی با Ollama SDK
در ادامه چند مثال عملی آورده شده است تا نحوه استفاده از Ollama SDK در سناریوهای واقعی روشن شود.
مثال ۱: ساخت چتبات محلی (Python)
- دریافت ورودی کاربر
- ارسال به Ollama
- نمایش پاسخ بهصورت زنده
مثال ۲: ابزار خلاصهسازی اسناد (Node.js)
- دریافت متن بلند
- ارسال chunkها برای مدل
- اتصال خروجیها و ساخت خلاصه
سناریو: ساخت یک سرویس داخلی برای خلاصهسازی اسناد شرکت روی سیستمهای لوکال.
معماری پیشنهادی:
- Flask / FastAPI برای سرویس
- Ollama برای پردازش متن
- Embeddings + Vector DB (مثل ChromaDB)
- استفاده از Python SDK برای اتصال سریع
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
from flask import Flask, request import ollama app = Flask(__name__) @app.post(“/summarize”) def summarize(): text = request.json[“text”] prompt = f“Summarize the following:\n\n{text}” result = ollama.generate(model=“llama3”, prompt=prompt) return {“summary”: result[“response”]} app.run() |
این ساختار نشان میدهد که SDK عملا نقش یک موتور پردازش LLM قابل ادغام را ایفا میکند.
مثال ۳: موتور جستجوی شخصی (Python + Embeddings)
- ساخت بردار برای هر سند
- ذخیره در پایگاه داده
- محاسبه شباهت برای پرسوجو
مثال ۴: تولید خودکار محتوا برای یک CMS
- اجرای API داخلی که ورودی دریافت میکند
- فراخوانی مدل لوکال
- ساخت خروجی HTML یا Markdown
محدودیتهای Ollama SDK
- حجم رم و GPU محدودیت ایجاد میکند
- مدیریت چند مدل بهصورت همزمان پیچیدهتر میشود
- مصرف RAM و GPU به مدل وابسته است
- سرعت Generate در مدلهای حجیم پایینتر از APIهای ابری است
- Python SDK هنوز برخی امکانات جانبی مانند Tool Calling ندارد
- مدیریت Context محدودیتهایی دارد (مثلاً اندازه 8k یا 16k بسته به مدل)
- API ساده است اما امکاناتی مثل Fine-tuning ارائه نمیدهد
جمعبندی
Ollama یک محیط قدرتمند برای اجرای مدلهای هوش مصنوعی بهصورت محلی است و هرچند اصطلاح «SDK» رسمی برای آن وجود ندارد، اما مجموعه ابزارهای ارائهشده شامل REST API، Python SDK، JavaScript SDK و CLI عملا یک SDK کامل را تشکیل میدهند. این رویکرد، توسعهدهندگان را قادر میسازد که بدون وابستگی به سرویسهای ابری، مدلهای پیشرفته را در برنامههای خود ادغام کنند و کنترل کاملی بر امنیت، هزینه و عملکرد داشته باشند.
منابع
docs.ollama.com | npmjs.com | cohorte.co
سوالات متداول
Ollama SDK مجموعهای از کتابخانهها و ابزارهاست که امکان اتصال برنامهها به موتور مدلهای هوش مصنوعی Ollama را فراهم میکند. این SDK توسعه اپلیکیشنهای هوش مصنوعی لوکال را سادهتر میکند.
بله. Ollama یک سرویس کاملاً لوکال است و SDK آن نیز برای تعامل با سرور محلی که روی سیستم شما اجرا میشود طراحی شده است.
در حال حاضر زبانهای اصلی Python و JavaScript/Node.js دارای کلاینت رسمی هستند. در صورت نیاز، میتوان از REST API نیز در هر زبان دیگری استفاده کرد.
بله. هم در Python SDK و هم در JavaScript SDK امکان دریافت خروجی Stream وجود دارد و برای ساخت چتبات بسیار مناسب است.
هر دو SDK (Python و JS) تابعی برای تولید Embeddings دارند که یک بردار عددی ایجاد میکند. این قابلیت برای موتورهای جستجو، دستهبندی متون و RAG ضروری است.
دیدگاهتان را بنویسید