تعرف على كيفية استخدام Ollama -Apis كيفية إنشاء ودردشة واستخدام المزيد مع Curl و JQ مع أمثلة مفيدة

Ollama هو برنامج مفتوح المصدر يمكن تنفيذه بسلاسة على جهاز الكمبيوتر الخاص بك (أو حتى على السحابة). Ollama المكتوبة في Go Lang هو مستخدمي وسهل البدء. في هذا المنشور ، الجزء 3 من سلسلة نشر مدونة Ollama ، سوف تتعلم كيفية استخدام واجهات برمجة تطبيقات Ollama لتوليد الإجابات (استنتاج LLM) وأكثر من ذلك بكثير. لنبدأ!

جدول المحتويات #

مراجعة سريعة لسلسلة Ollama # #

منشور المدونة هذا هو الجزء 3 من سلسلة Ollama. في الجزء الأول ، اكتشفت ماهية Ollama ، بما في ذلك وظائفه وكيف يمكنك توجيه Ollama مع عدد قليل من الطرز على جهازك المحلي.

في الجزء الثاني ، قمت بفحص بعض أوامر Ollama المفيدة ، مثل Ollama لبدء Ollama وتشغيل النماذج المتاحة ، وأداء Ollama Run لسحب (التنزيل) ونموذج.

في هذا الجزء سوف تتعلم شيئًا عن Ollama -Apis. بالإضافة إلى نقاط نهاية الاستدلال -api /api/generate و /api/chatسوف تكتشف أيضًا نقاط نهاية واجهة برمجة التطبيقات الأخرى المفيدة. أوامر Ollama تسمي واجهات برمجة التطبيقات هذه وراء الكواليس لتوفير المخارج.

لهذا الدليل ، استخدم Curl للوصول إلى واجهات برمجة التطبيقات مع JQ. لتثبيت JQ ، اتبع مؤشرات ترابط التنزيل الرسمية ، على سبيل المثال على جهاز Mac. يمكنك الجري brew install jqيمكنك أيضًا التشغيل على جهاز كمبيوتر Ubuntu sudo apt-get install jq يمكنك استخدام الشوكولاتة على جهاز Windows. أو يمكنك الحصول على الملف الثنائي وجعله قابل للتنفيذ.

يمكنك استخدام لغات البرمجة الأخرى مثل Python و JavaScript مع المكتبات الرسمية لـ Python و JavaScript وأطر مثل Litellm أو Langchain لتسمية Ollama APIs.

Ollama API Endpoints #

هناك أكثر من 10 نقاط نهاية Allama API. يركز هذا البرنامج التعليمي على بعض من أهمه. لاستخدام واجهات برمجة التطبيقات ، تحتاج إلى Ollama الذي يمكنك تشغيله ollama serve أو كخدمة. تحتاج أيضًا إلى نموذج واحد على الأقل لمكالمات API.

لهذا الدليل ، استخدم SMOLLM2: 135 م ، أحد LLMs الأصغر في 221 ميغابايت. يمكنك استخدام أي نموذج أكبر إذا تم تنفيذه على الموارد المتاحة. سبب الاختيار smollm2:135m هو لأن معظم الآلات ، أيضا مع 512 ميغابايت أو الذاكرة ، يمكن أن تفعل ذلك.

للبدء ollama serve, في علامة تبويب CLI أخرى وتشغيلها ollama pull smollm2:135m. عندما تسحب smollm2:135m التنزيل سريع للغاية من الأجزاء السابقة من سلسلة البرنامج التعليمي هذه لأن الملفات متوفرة بالفعل.

توليد نقطة النهاية #

كما يؤكد الاسم ، تتوفر نقطة نهاية API هذه /api/generate يمكنك نشر البيانات لإنشاء إجابة من النموذج المحدد لطلب الإدخال المطلوب. بشكل افتراضي ، يتفاعل كدفق ؛ يمكنك تكوينه بطريقة يتم إرجاع جميع الإجابات مرة واحدة وليس كدفق. لديها أربعة معلمات:

• النموذج: اسم النموذج ، على سبيل المثال ، smollm2:135mهي المعلمة المطلوبة.
• طلب الإدخال: هل موجه الأوامر الذي تريد إرساله إلى النموذج المحدد ، مثل Why is the sky blue?
• لاحقة: يمكن استخدامها إذا كنت تريد إرفاق نص بعد الإجابة
• الصور: قائمة بالصور المصنوعة من BASE64 إذا كنت ترغب في استخدامها مع نماذج متعددة الوسائط مثل LLAVA أو SMOLVLM.

هناك أيضًا معلمات موسعة أخرى مثل stream, التي يمكنك قراءتها في المستندات الرسمية. في الوقت الحالي ، يمكنك القيام بأمر Curl التالي للحصول على إجابة smollm2:!35m نموذج:

curl  -d '{
"model": "smollm2:135m",
"prompt": "Why is the sky blue? Give the shortest answer possible in under 20 words",
"stream": false
}' | jq .

في ما سبق curl الأمر الذي تستخدمه /api/generate نقطة نهاية API والأسئلة حول smollm2:135m نموذج. Why is the sky blue? Give the shortest answer possible in under 20 wordsواطلب من أولاما عدم دفق الطبعة. لذا أعط الجواب الكامل في وقت واحد. ثم يتم توجيه النتيجة إلى الخطوط jq. هذا يوفر الطبعة التالية:

{
"model": "smollm2:135m",
"created_at": "2025-02-08T11:02:55.115275Z",
"response": "The sky's clear and deep color due to tiny oxygen molecules (O2) scattering the sun's light allowing us to perceive it as blue.",
"done": true,
"done_reason": "stop",
"context": [
],
"total_duration": 302810709,
"load_duration": 13315375,
"prompt_eval_count": 47,
"prompt_eval_duration": 132000000,
"eval_count": 30,
"eval_duration": 156000000
}

إذا كنت تتصل API هذا من برنامج نصي أو نظام برمجي آخر ، فستكون أكثر قلقًا بشأن response ينقسم. إذا كنت تريد فقط رؤية الإجابة من النموذج ، فيمكنك استخدامها jq لأن هذا:

curl  -d '{
"model": "smollm2:135m",
"prompt": "Why is the sky blue? Give the shortest answer possible in under 20 words",
"stream": false
}' | jq '.["response"]'

يسألون jq أظهر لهم فقط response ميزة من استجابة JSON وليس من الإجابة بأكملها. سيبدو على النحو التالي:

يمكنك توفير العديد من أنواع الاستفسارات حول نقطة نهاية API التي تم إنشاؤها. مفيد هو الإصدار المهيكل الذي يمكنك من خلاله تحديد بنية الإخراج ككائن JSON. مع خيار البذور ، يمكنك الحصول على مخرجات قابلة للتكرار. إذا قمت بتقديم موجه أوامر فارغ ، يتم تحميل النموذج في الذاكرة. سيكون من المستحسن قراءة المستندات الرسمية حول القراءة generate نهاية نقطة.

نقطة نهاية الدردشة #

نقطة نهاية الدردشة المتاحة /api/chatما يعمل أيضًا مع البريد مشابه generate API. يولد الرسالة التالية في الدردشة مع طراز محدد. إنها نقطة نهاية دفق لها عدد من الإجابات. يمكنك تبديل التدفق مع الإغلاق ”stream::false المعلمات ، كما هو موضح أدناه:

curl  -d '{
"model": "smollm2:135m",
"stream":false,
"messages": [
{
"role": "user",
"content": "Why is the sky blue? Give the shortest answer possible in under 20 words"
}
]
}' | jq .

يشبه إخراج حليقة أعلاه على النحو التالي:

{
"model": "smollm2:135m",
"created_at": "2025-02-08T11:22:15.229839Z",
"message": {
"role": "assistant",
"content": "The sky appears blue because when sunlight passes through Earth's atmosphere, it contains tiny molecules like water vapor and oxygen. These molecules scatter shorter wavelengths of light (such as blue and violet) more than the longer wavelengths (like red and orange), making the sky appear blue to our eyes. Thank you for pointing this out!"
},
"done_reason": "stop",
"done": true,
"total_duration": 407998750,
"load_duration": 6202542,
"prompt_eval_count": 47,
"prompt_eval_duration": 36000000,
"eval_count": 65,
"eval_duration": 363000000
}

كما يتضح في الإجابة أعلاه ، فإن هيكل الإجابة يختلف إلى حد ما عن ذلك generate نقطة نهاية API. هذا لديه message اعز ما هو الكائن و content ميزة في ذلك. إذا كنت ترغب في استخراج المحتوى باستخدام JQ من الإجابة ، يمكنك تنفيذ الأمر التالي:

curl  -d '{
"model": "smollm2:135m",
"stream":false,
"messages": [
{
"role": "user",
"content": "Why is the sky blue? Give the shortest answer possible in under 20 words"
}
]
}' | jq '.["message"]["content"]'

المحتوى المستخرج من رد فعل /api/chat سوف تبدو على النحو التالي:

يمكنك تشغيل المخرجات المنظمة مع نقطة نهاية الدردشة. كنقطة نهاية الدردشة ، يمكنك إرسال تاريخ المحادثة إلى نقطة النهاية. يمكنك إرسالها لجميع أنواع المترسمة الأخرى /api/chat نقطة النهاية ، سيكون من الأفضل أن نمر من خلال وثائق Ollama الرسمية حول هذا الموضوع.

قائمة النماذج #

لسرد النماذج المحلية المتاحة ، يمكنك الاتصال بها /api/tags نقطة النهاية التي تعمل مع طلب الحصول على. في نقطة النهاية هذه ، يسرد النماذج المتوفرة في الموقع ، والتي يمكنك إنشاء الدردشة وإرسالها كمعلمة اسم النموذج. في ما يلي ستجد مثالًا على استدعاء واجهة برمجة التطبيقات هذه:

curl  | jq .

سيكون JSON مشابهًا أدناه:

{
"models": [
{
"name": "smollm2:135m",
"model": "smollm2:135m",
"modified_at": "2025-02-08T15:33:44.760304367+11:00",
"size": 270898672,
"digest": "9077fe9d2ae1a4a41a868836b56b8163731a8fe16621397028c2c76f838c6907",
"details": {
"parent_model": "",
"format": "gguf",
"family": "llama",
"families": [
"llama"
],
"parameter_size": "134.52M",
"quantization_level": "F16"
}
},    
{
"name": "qwen2.5:0.5b",
"model": "qwen2.5:0.5b",
"modified_at": "2025-02-06T15:59:09.320362549+11:00",
"size": 397821319,
"digest": "a8b0c51577010a279d933d14c2a8ab4b268079d44c5c8830c0a93900f1827c67",
"details": {
"parent_model": "",
"format": "gguf",
"family": "qwen2",
"families": [
"qwen2"
],
"parameter_size": "494.03M",
"quantization_level": "Q4_K_M"
}
},
{
"name": "deepseek-r1:8b",
"model": "deepseek-r1:8b",
"modified_at": "2025-02-02T13:33:29.069046707+11:00",
"size": 4920738407,
"digest": "28f8fd6cdc677661426adab9338ce3c013d7e69a5bea9e704b364171a5d61a10",
"details": {
"parent_model": "",
"format": "gguf",
"family": "llama",
"families": [
"llama"
],
"parameter_size": "8.0B",
"quantization_level": "Q4_K_M"
}
}
]
}

لدي هذه النماذج الثلاثة المتاحة على الجهاز الخاص بي. قد يكون رد فعلك بسيطًا ، لكن بنية البداية تظل كما هي.

اسحب نموذجًا #

لتنزيل نموذج جديد من تسجيل نموذج Ollama ، يمكنك استخدامه /api/pull نقطة نهاية API التي تعمل مع مكالمة بريدية. مثل بلدان DOC الرسمية ، سيتم استئناف القطارات التي تم إلغاؤها ، وفي حالة العديد من مكالمات السحب ، فإنها تشترك في نفس تقدم التنزيل.

مطلوب اسم طراز لسحب نموذج ويمكنك دفق الإجابة أو عدم دفقها. ستجد أدناه مثالًا على الاتصال بـ /api/pull نقطة نهاية دون تدفق لسحب/تنزيل snowflake-arctic-embed:22mيا له من نموذج تضمين مع 46 ميغابايت هو:

curl  -d '{
"model": "snowflake-arctic-embed:22m"
}' | jq .

هناك نسخة طويلة جدًا مع جميع المعلومات حول السحب (التنزيل) وتنتهي بـ:

{
"status": "pulling 2977e9705f4b",
"digest": "sha256:2977e9705f4b122813b1aeb50fc0c6563113da0b626f540c3daa8149827e30d3",
"total": 333,
"completed": 333
}
{
"status": "verifying sha256 digest"
}
{
"status": "writing manifest"
}
{
"status": "success"
}

في ضوء حقيقة أن النموذج تم تنزيله ، فإن أسهل طريقة هي التحقق من ذلك من خلال تنفيذ هذا ollama list القيادة وستراهم snowflake-arctic-embed:22m طراز 45 ملم في القائمة. مع هذا النموذج يمكنك استخدامه /api/embed نقطة النهاية لإنشاء التضمين.

إظهار معلومات النموذج #

إذا قمت باستدعاء نقطة النهاية “/API/show” باستخدام مكالمة بريدية ، فيمكنك عرض معلومات النموذج بما في ذلك التفاصيل وملف النموذج والقالب والمعلمات والترخيص وطلب النظام. اسم النموذج هو معلمة مطلوبة. تسليم verbose تقوم المعلمة الاختيارية بإرجاع البيانات الكاملة بحقول مفصلة في الإجابة.

في ما يلي ستجد عينة من النقطة النهائية لنقطة نهاية معلومات النموذج دون العلامة التفصيلية ل smollm2:135m النموذج ، تم قطع بعض الحقول للإيجاز:

{
"license": "\nApache License\n Version 2.0, January 2004...the full apache license here",
"modelfile": "# Modelfile generated by \"ollama show\"\n# To build a new Modelfile based on this, replace FROM with:\n# FROM smollm2:135m\n\nFROM /path/to/.ollama/models/blobs/sha256-f535f83ec568d040f88ddc04a199fa6da90923bbb41d4dcaed02caa924d6ef57\nTEMPLATE \"\"\"template and parameter info here\nLICENSE \"\"\"\nApache License\n    Version 2.0, January 2004...the full apache license here",
"parameters": "stop\"<|im_start|>\"\nstop\"<|im_end|>\"",
"template": "template info here",
"system": "You are a helpful AI assistant named SmolLM, trained by Hugging Face",
"details": {
"parent_model": "/path/to/.ollama/models/blobs/sha256-f535f83ec568d040f88ddc04a199fa6da90923bbb41d4dcaed02caa924d6ef57",
"format": "gguf",
"family": "llama",
"families": [
"llama"
],
"parameter_size": "134.52M",
"quantization_level": "F16"
},
"model_info": {
"general.architecture": "llama",
"general.basename": "smollm2",
"general.file_type": 1,
"general.finetune": "8k-lc100k-mix1-ep2",
"general.languages": [
"en"
],
"general.license": "apache-2.0",
"general.organization": "HuggingFaceTB",
"general.parameter_count": 134515008,
"general.quantization_version": 2,
"general.size_label": "135M",
"general.type": "model",
"llama.attention.head_count": 9,
"llama.attention.head_count_kv": 3,
"llama.attention.layer_norm_rms_epsilon": 0.00001,
"llama.block_count": 30,
"llama.context_length": 8192,
"llama.embedding_length": 576,
"llama.feed_forward_length": 1536,
"llama.rope.dimension_count": 64,
"llama.rope.freq_base": 100000,
"llama.vocab_size": 49152,
"tokenizer.ggml.add_bos_token": false,
"tokenizer.ggml.add_space_prefix": false,
"tokenizer.ggml.bos_token_id": 1,
"tokenizer.ggml.eos_token_id": 2,
"tokenizer.ggml.merges": null,
"tokenizer.ggml.model": "gpt2",
"tokenizer.ggml.padding_token_id": 2,
"tokenizer.ggml.pre": "smollm",
"tokenizer.ggml.token_type": null,
"tokenizer.ggml.tokens": null,
"tokenizer.ggml.unknown_token_id": 0
},
"modified_at": "2025-02-08T15:33:44.760304367+11:00"
}

اعتمادًا على مستوى السلامة المطلوب لمثيل Ollama الخاص بك ، يجب ألا يكون متناول نموذج العرض -API متاحًا خارج التطبيق.

واجهات برمجة التطبيقات الأخرى Ollama #

يمكن لآبار واجهات برمجة تطبيقات Ollama الأخرى سرد النماذج المستمرة ، وحذف نموذج (لا تريد أن يحذف شخص ما نموذجًا مرسومًا) ، وإنشاء نموذج من نموذج آخر ، ونسخ نموذج ، وحتى توليد التضمين. يمكنك جميعًا استكشافها في المستندات الرسمية.

لنفترض أنك استخدمت ساعي البريد ومجموعاته. يمكنك أيضًا استخدام مجموعة Postman هذه التي يتم فيها إدراج معظم مكالمات ALAMA API في اختبار لائق وسهل إلى -. في الجزء التالي (الجزء 4) من سلسلة مدونة Ollama ، تعرف على كيفية توجيه Ollama في Docker مع Docker Compose.

قيود مهمة #

إذا كنت تخطط لاستضافة Ollma على عنوان URL الذي يمكن الوصول إليه للجمهور أو بأي شكل من أشكال المصادقة والترخيص ، فيرجى تذكر الكشف عن الإنتاج (((((((((((((((((((((((((/api/generate) والدردشة (/api/chat) نقاط النهاية. لا تريد أن يتصل المستخدمون أو حتى يحذفوا نقاط نهاية السحب أو حتى النموذج -نقاط نهاية API.

يمكنك القيام بذلك عن طريق وضع وكيل عكسي أمام خادم GIN الخاص بـ Ollama (تم تنفيذه على المنفذ 11434 بشكل افتراضي). يمكنك الاختيار بين الوكيل العكسي Nginx أو Caddy. مع وكيل عكسي ، يمكنك فقط المرور عبر حركة المرور ، ويأتي ذلك /api/generate و /api/chat إلى الأمام إلى أولاما. نظرًا لأن خادم Ollama مكتوب في Go/Gin ، يمكنك حتى تجربة هذا المسار لتأمين واجهات برمجة التطبيقات الخاصة بك إذا كنت تعرف كيفية الكتابة Go و Gin. هناك مشكلة في مستودع Ollama Github الرسمي حول شيء مشابه إذا كنت ترغب في متابعة.

دبلوم #

لقد تعلمت في هذه المقالة بعض نقاط نهاية ALLAMA API التي تركز على أولئك الذين يساعدونك في الحصول على إجابة من نموذج مفتوح. لقد تعلمت شيئًا عن نقاط نهاية Allama API لرسم نموذج ، وسرد النماذج ومعلومات عرض النموذج.

من المهم أن تكون على دراية بتقييد حاسم: يجب ألا تعرض جميع واجهات برمجة تطبيقات Ollama المتاحة للعالم الخارجي. إذا استدعى شخص ما نقطة نهاية نموذج نموذج النموذج ، فلن يعمل ALAMA API الخاص بك. لذا كن حذرا. يتعلم!