أساسيات واجهة Ollama API

Ollama يوفر واجهة REST API تجعل دمج نماذج اللغة الكبيرة المحلية في أي تطبيق سهلاً. لنستكشف نقاط النهاية الأساسية.

نظرة عامة على API

┌─────────────────────────────────────────────────────────────────┐
│                    واجهة Ollama REST API                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  عنوان URL الأساسي: http://localhost:11434                      │
│                                                                 │
│  نقاط النهاية:                                                  │
│  ──────────                                                     │
│  POST /api/generate     - توليد نص (إكمال)                      │
│  POST /api/chat         - محادثة دردشة                          │
│  POST /api/embed        - توليد تضمينات                         │
│  GET  /api/tags         - عرض النماذج                           │
│  POST /api/pull         - سحب نموذج                             │
│  DELETE /api/delete     - حذف نموذج                             │
│  POST /api/show         - معلومات النموذج                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

نقطة نهاية Generate

نقطة النهاية /api/generate لإكمال النص:

# توليد أساسي
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "The capital of France is",
  "stream": false
}'

# الرد:
{
  "model": "llama3.2",
  "response": " Paris.",
  "done": true,
  "context": [1, 2, 3, ...],
  "total_duration": 1234567890,
  "load_duration": 123456789,
  "prompt_eval_count": 7,
  "eval_count": 3
}

التوليد مع المعاملات

curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Write a short poem about coding",
  "stream": false,
  "options": {
    "temperature": 0.7,
    "top_p": 0.9,
    "num_ctx": 4096,
    "stop": ["\n\n"]
  }
}'

نقطة نهاية Chat

نقطة النهاية /api/chat تتعامل مع المحادثات متعددة الأدوار:

curl http://localhost:11434/api/chat -d '{
  "model": "llama3.2",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is Python?"},
    {"role": "assistant", "content": "Python is a programming language."},
    {"role": "user", "content": "What is it used for?"}
  ],
  "stream": false
}'

# الرد:
{
  "model": "llama3.2",
  "message": {
    "role": "assistant",
    "content": "Python is used for web development, data science..."
  },
  "done": true
}

تدفق الردود

للمخرجات في الوقت الفعلي، استخدم التدفق:

# التدفق يولد كائن JSON واحد لكل رمز
curl http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Tell me a story",
  "stream": true
}'

# المخرجات (أسطر JSON متعددة):
{"model":"llama3.2","response":"Once","done":false}
{"model":"llama3.2","response":" upon","done":false}
{"model":"llama3.2","response":" a","done":false}
{"model":"llama3.2","response":" time","done":false}
...
{"model":"llama3.2","response":"","done":true}

معالجة التدفقات في Shell

# طباعة المخرجات المتدفقة بشكل جميل
curl -s http://localhost:11434/api/generate -d '{
  "model": "llama3.2",
  "prompt": "Explain AI in one sentence",
  "stream": true
}' | while read line; do
  echo "$line" | jq -r '.response' | tr -d '\n'
done
echo

نقطة نهاية التضمينات

توليد تضمينات المتجهات لـ RAG والبحث الدلالي:

curl http://localhost:11434/api/embed -d '{
  "model": "llama3.2",
  "input": "Ollama is a great tool for local LLMs"
}'

# الرد:
{
  "model": "llama3.2",
  "embeddings": [[0.123, -0.456, 0.789, ...]]
}

# مدخلات متعددة
curl http://localhost:11434/api/embed -d '{
  "model": "llama3.2",
  "input": ["First text", "Second text", "Third text"]
}'

نقاط نهاية إدارة النماذج

عرض النماذج

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

# الرد:
{
  "models": [
    {
      "name": "llama3.2:latest",
      "modified_at": "2024-12-15T10:30:00Z",
      "size": 4700000000,
      "digest": "sha256:abc123..."
    }
  ]
}

معلومات النموذج

curl http://localhost:11434/api/show -d '{
  "model": "llama3.2"
}'

# الرد يتضمن modelfile، المعاملات، القالب

سحب نموذج

# سحب مع التقدم (تدفق)
curl http://localhost:11434/api/pull -d '{
  "name": "mistral",
  "stream": true
}'

معالجة الأخطاء

# نموذج غير موجود
curl http://localhost:11434/api/generate -d '{
  "model": "nonexistent-model",
  "prompt": "Hello"
}'

# الرد:
{
  "error": "model 'nonexistent-model' not found"
}

رموز حالة HTTP الشائعة:

• 200: نجاح
• 400: طلب سيء (معاملات غير صالحة)
• 404: نموذج غير موجود
• 500: خطأ في الخادم

مرجع API السريع

نقطة النهاية	الطريقة	الغرض
/api/generate	POST	إكمال النص
/api/chat	POST	محادثة دردشة
/api/embed	POST	توليد تضمينات
/api/tags	GET	عرض النماذج
/api/show	POST	تفاصيل النموذج
/api/pull	POST	تحميل نموذج
/api/delete	DELETE	إزالة نموذج
/api/copy	POST	نسخ نموذج

واجهة REST API توفر كل ما تحتاجه لدمج Ollama في أي تطبيق. في الدرس التالي، سنستخدم Python لتجربة مطور أكثر راحة. :::