مفتاح واجهة برمجة تطبيقات أولاما: لماذا لا يوجد واحدٌ أصلًا وما الذي يجب استخدامه بدلًا منه

لا يحتوي تثبيت أولاما المحلي على مفتاح واجهة برمجة تطبيقات، ولا توجد طريقة مضمنة لتعيين واحد. فالخادم البروتوكولي (HTTP) الذي يشغِّله يرد على أي طلب يصل إليه. http://localhost:11434 غالبًا ما يبحث الأشخاص عن «مفتاح واجهة برمجة تطبيقات أولاما» لأنهم يحتاجون أحد ثلاثة أمور: شيءً ما لإدخاله في حقل المفتاح الإلزامي في تطبيق العميل، أو وسيلةً لتوفير الأمان لنسخة يمكن للآلات الأخرى الوصول إليها، أو مفتاحًا لخدمة السحابة المُدارة من أولاما — وهي المكان الوحيد الذي يوجد فيه مفتاح حقيقي. ويغطي هذا الدليل هذه الحالات الثلاث جميعها.

لماذا لا يشمل أولاما المحلي ميزة المصادقة افتراضيًّا؟

افتراضيًّا، يرتبط أولاما بعنوان الحلقة المحلية (loopback address) 127.0.0.1 على المنفذ 11434. وبالتالي، لا يمكن لأي عملية إلا تلك التي تعمل على الجهاز نفسه أن تتصل به، ولذلك فإن وجود مفتاح واجهة برمجة تطبيقات سيضيف تعقيدًا دون أن يعزِّز الأمن: فكل برنامج محلي قادر على قراءة ملف المفتاح سيكون قادرًا بنفس السهولة على استدعاء واجهة برمجة التطبيقات مباشرةً. وهذه هي نفس نموذج الثقة الذي تستخدمه معظم خوادم التطوير المحلية.

والنتيجة هي أنه لا يوجد مفتاح واجهة برمجة تطبيقات Ollama متغيرٌ لا يتضمّن علامة مفتاح ولا خيار كلمة مرور في أي مكان ضمن الإعدادات. واعتبارًا من وقت كتابة هذه السطور، لا يحتوي خادم Ollama المحلي على آلية مصادقة مضمنة على الإطلاق — وبالتالي فإن تأمين النسخة القابلة للوصول عبر الشبكة هو مسؤوليتك أنت، وسيتم تناول ذلك أدناه. وإذا كنت ما زلت في مرحلة الإعداد الأولي، فابدأ بقراءة دليلنا الموجّه لـ دليل تثبيت أولاما أو للمجال الأوسع الدليل الشامل لأولاما.

ما الذي يجب إدخاله في حقل مفتاح واجهة برمجة التطبيقات في العملاء المتوافقة مع OpenAI

يقدّم Ollama نقاط نهاية متوافقة مع واجهة برمجة تطبيقات OpenAI تحت عنوان /v1وهذا بالضبط سبب قدرة واجهات الدردشة (UIs) ومساعدات البرمجة وأدوات تطوير البرمجيات الرسمية الخاصة بـ OpenAI على الاتصال به. وتُجبر هذه الأدوات (SDKs) العميلَ على إدخال مفتاح واجهة برمجة تطبيقات غير فارغ عند إنشاء كائن العميل — ويتم هذا التحقق من جانب العميل قبل إرسال أي طلبٍ على الإطلاق. وبعد ذلك، يتجاهل Ollama رأس (header) الـ المصادقة بالكامل، لذا فإن أي سلسلة نصية ستفي بالغرض. والمعتاد هو استخدام أولاما.

بايثون باستخدام حزمة تطوير البرمجيات الرسمية الخاصة بـ OpenAI:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # مطلوب من قِبل حزمة SDK، لكن Ollama يتجاهله تمامًا
)

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "مرحبًا"}],
)
print(response.choices[0].message.content)

جافاسكريبت / تايبسكريبت:

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "http://localhost:11434/v1",
  apiKey: "ollama",
});

const response = await client.chat.completions.create({
  model: "llama3.2",
  messages: [{ role: "user", content: "مرحبًا" }],
});
console.log(response.choices[0].message.content);

يجب أن تكون النموذج قد تم تنزيله مسبقًا (ollama pull llama3.2) وإلا فستفشل العملية برفع خطأ «النموذج غير موجود». وإذا لم تكن متأكدًا من الأمر الذي يجب تنفيذه، فاطّلع على قائمة اختياراتنا لأفضل أفضل النماذج المحلية لأولاما.

إضافة مصادقة فعلية باستخدام وسيط عكسي (Reverse Proxy)

وبما أن Ollama لا يمكنه التحقق من صحة المفاتيح بنفسه، فإن الطريقة القياسية هي ترك Ollama يعمل على ربطه الافتراضي (loopback) ووضع وكيل عكسي (reverse proxy) أمامه. ويقوم هذا الوكيل بإنهاء اتصال TLS، والتحقق من صحة الرمز المميز (token)، ثم إعادة توجيه الطلبات الصالحة إلى 127.0.0.1:11434. فيما يلي مثالٌ بسيط على إعداد nginx يفرض وجود رمز مميز من نوع Bearer:

server {
    listen 443 ssl;
    server_name ollama.example.com;
    # تم حذف سطري ssl_certificate وssl_certificate_key

    location / {
        if ($http_authorization != "Bearer YOUR-LONG-RANDOM-TOKEN") {
            return 401;
        }
        proxy_pass http://127.0.0.1:11434;
        proxy_set_header Host $host;
        proxy_read_timeout 600s;
    }
}

يجب الانتباه إلى تفصيلين مهمين: أولًا، قم بتوليد الرمز المميز باستخدام أمر مثل openssl rand -hex 32 بدلًا من اختراعه يدويًّا. ثانيًا، فإن قيمة المعلمة الطويلة proxy_read_timeout ليست عبثية؛ بل مقصودةٌ عمداً: فالإجابات التي تُولَّد تدريجيًّا (streamed generations) قد تستغرق دقائق، وقيم المهلة الافتراضية في الوكلاء العكسية ستقطعها في منتصف الاستجابة.

والجميل في هذه الطريقة هو أن أدوات تطوير البرمجيات (SDKs) الخاصة بـ OpenAI ترسل المفتاح تلقائيًّا على هيئة رأس Authorization: Bearer . لذا كل ما عليك فعله هو توجيه العميل نحو https://ollama.example.com/v1، وتعيين مفتاح واجهة برمجة التطبيقات (API key) ليكون الرمز المميز الحقيقي، وبذلك يتحول حقل المفتاح الذي كان يُهمَل سابقًا إلى آلية مصادقة فعلية دون الحاجة لتغيير أي شيء من جانب العميل. كما يمكن لخدمتي Caddy وTraefik تطبيق نفس التحقق من رأس المصادقة أو حتى المصادقة الأساسية عبر HTTP (HTTP basic auth) عبر بضعة أسطر فقط من إعداداتها الخاصة؛ لذا إن كنت تستخدم إحدى هاتين الخدمتين بالفعل، فاستخدمها بدلًا من تثبيت nginx من جديد.

تغيير عنوان الاستماع الذي يستمع إليه أولاما: ويندوز، وماك أو إس، ولينكس

لا تتطلب إضافة وكيل عكسي على نفس الجهاز أي تعديلات على إعدادات Ollama. لكن إذا كانت أجهزة أخرى بحاجة إلى الوصول المباشر إلى Ollama — مثل وكيل عكسي على جهاز مختلف، أو حاويات Docker، أو عملاء على شبكة LAN — فيجب تعيين OLLAMA_HOST=0.0.0.0 ليستمع إلى جميع واجهات الشبكة. وطريقة تعيين هذه القيمة تختلف باختلاف نظام التشغيل.

ويندوز

أغلق Ollama من شريط المهام (system tray). ثم افتح «الإعدادات»، وابحث عن «المتغيرات البيئية» (environment variables)، واختر «تحرير المتغيرات البيئية لحسابك». وأضف متغيرًا باسم OLLAMA_HOST ذو القيمة 0.0.0.0، ثم احفظ التغييرات وأعد تشغيل Ollama.

ماك أو إس

تشمل أحدث إصدارات Ollama لسطح المكتب خيارًا في إعدادات التطبيق لجعله قابلاً للوصول عبر الشبكة — لذا تحقّق أولًا من إعدادات التطبيق. أما في الإصدارات الأقدم، فقم بتشغيل الأمر launchctl setenv OLLAMA_HOST "0.0.0.0" وأعد تشغيل تطبيق Ollama.

لينكس

أما بالنسبة لخدمة systemd المثبتة عبر النص البرمجي الرسمي، فقم بتشغيل الأمر sudo systemctl edit ollama.service وأضف ما يلي:

[Service]
Environment="OLLAMA_HOST=0.0.0.0"

ثم نفّذ الأمر sudo systemctl daemon-reload && sudo systemctl restart ollama.

تحذيرٌ واحدٌ قبل تفعيل هذا الخيار: 0.0.0.0 تفعيل Ollama على جهاز يملك عنوان IP عام يجعل وحدة معالجة الرسومات (GPU) الخاصة بك متاحة للعموم. لذا تأكد من تقييد المنفذ 11434 عبر جدار الحماية بحيث يسمح فقط بالاتصالات القادمة من الأجهزة التي تحتاج إليه حقًّا.

أولاما كلاود: المكان الوحيد الذي ينطبق عليه مفتاح واجهة برمجة تطبيقات حقيقي

توفر خدمة Ollama Cloud تشغيل النماذج الكبيرة جدًّا التي لا تستوعبها معظم الأجهزة المحلية، وذلك على وحدات معالجة الرسومات (GPUs) الموجودة في مراكز بيانات Ollama نفسها، وهي الجزء الوحيد في النظام البيئي الذي يوفّر مفاتيح واجهة برمجة تطبيقات فعلية. وهناك طريقتان للوصول إليها:

عبر واجهة سطر الأوامر المحلية (CLI). تشغيل ollama signin لربط حسابك على ollama.com، ثم شغّل النماذج المستضافة سحابيًّا باستخدام علاماتها السحابية (cloud tags) — فعلى سبيل المثال، وفي وقت كتابة هذه السطور، يمكنك تنفيذ الأمر ollama run gpt-oss:120b-cloud. وترتبط الطلبات تلقائيًّا بحسابك، دون الحاجة لإدارة المفاتيح يدويًّا.

مباشرةً عبر HTTPS. أنشئ مفتاح واجهة برمجة تطبيقات في قسم «مفاتيح واجهة برمجة التطبيقات» ضمن إعدادات حسابك على ollama.com، وأرسله كرمز مميز من نوع Bearer. وتُحاكي واجهة برمجة التطبيقات المستضافة الواجهة المحلية تمامًا، باستثناء أن عنوان URL الأساسي يكون https://ollama.com بدلًا من localhost:11434:

curl https://ollama.com/api/chat 
  -H "Authorization: Bearer $OLLAMA_API_KEY" 
  -d '{
    "model": "gpt-oss:120b",
    "messages": [{"role": "user", "content": "مرحبًا"}],
    "stream": false
  }'

وتتغيّر قائمة النماذج السحابية ونقاط النهاية (endpoints) وحدود الخطط مع مرور الوقت، لذا اعتبر وثائق Ollama السحابية الرسمية المرجع الأوثق فيما يخص أسماء النماذج الحالية وسقف الاستخدامات المسموح بها. وعند اتخاذ قرارٍ بشأن ما إذا كانت الاستنتاجات المستضافة (hosted inference) أو الأجهزة المحلية أكثر ملاءمةً لحمل العمل الخاص بك، فإن دليلنا آلة حساب نقطة التعادل بين الاستضافة المحلية وواجهات برمجة التطبيقات (API) يقدّم أرقامًا توضيحية لذلك، وكذلك حاسبة ذاكرة VRAM يُخبرك ما إذا كان النموذج المحدد يتوافق مع وحدة معالجة الرسومات (GPU) الخاصة بك أصلًا.

الخطر الفعلي الحقيقي: تشغيل نسخة غير مصرَّح لها من أولاما على الإنترنت

القصة الحقيقية المتعلقة بالأمان حول مفتاح واجهة برمجة التطبيقات (API) الخاص بـ Ollama ليست السلسلة الافتراضية الموجودة في نص برمجي بايثون — بل هي الآلاف من خوادم Ollama التي تكتشفها عمليات الفحص الشاملة على الإنترنت عادةً وهي تستمع على المنفذ 11434 دون أي آلية مصادقة. ويمكن لأي شخص يعثر على خادمك أن يقوم بتشغيل استنتاجات (inference) على وحدة معالجة الرسومات الخاصة بك مجانًا، أو سرد النماذج المتوفرة لديك عبر /api/tags، أو تنزيل النماذج حتى تمتلئ مساحة التخزين على قرصك الصلب، أو حذفها. كما أن أي ثغرة أمنية مستقبلية في الخادم تصبح قابلة للاستغلال دون الحاجة إلى بيانات اعتماد: فمثلًا، الثغرة الأمنية CVE-2024-37032، وهي ثغرة تسمح بتنفيذ تعليمات برمجية عن بُعد (RCE)، قد تم إصلاحها في عام 2024، وتُعتبر سابقة في هذا السياق.

• احتفظ بالإعداد الافتراضي 127.0.0.1 للمعلمة 'bind' ما لم تكن هناك حاجة فعلية حقًّا للوصول عن بُعد.
• وبالنسبة للوصول الشخصي عن بُعد، يُفضَّل استخدام نفق SSH (ssh -N -L 11434:127.0.0.1:11434 user@server) أو شبكة افتراضية خاصة (VPN) مثل WireGuard أو Tailscale، بدلًا من فتح المنفذ مباشرةً.
• إذا كان لا بد من جعل الخادم متاحًا للوصول العام، فاستخدم أمامه وكيل عكسي (reverse proxy) مُصادَقًا عليه ومُنهيًا لبروتوكول TLS، كما هو موضح أعلاه.
• احرص على تحديث برنامج Ollama باستمرار لضمان تطبيق التصحيحات الخاصة بالثغرات الأمنية المعروفة.

الأسئلة الشائعة

هل يتطلب Ollama مفتاح واجهة برمجة تطبيقات (API key)؟

لا. فخادم Ollama المحلي لا يتضمّن أي آلية مصادقة، ولا توجد خيارٌ لتمكينها. أما المفاتيح الوحيدة الحقيقية لواجهة برمجة تطبيقات Ollama فهي تلك الخاصة بخدمة Ollama Cloud، والتي تُنشَأ ضمن حسابك على موقع ollama.com.

ماذا يجب أن أكتب في حقل مفتاح واجهة برمجة التطبيقات (API key) المطلوب في العميل؟

أي سلسلة غير فارغة — أولاما حسب الاتفاقية المتبعة. والسبب في هذه المتطلبات هو بحتٌ من جانب العميل؛ إذ إن Ollama يتجاهل رأس (header) المفتاح تمامًا. وإذا كنت قد وضعت وكيل عكسي مُصادَقًا عليه أمام خادم Ollama، فعليك إدخال رمز المصادقة الحقيقي الخاص بهذا الوكيل بدلًا من ذلك، لأن العملاء المتوافقة مع واجهة OpenAI ترسل المفتاح كرمز نوع 'bearer token' يمكن للوكيل العكسي التحقق منه.

هل يمكنني جعل Ollama نفسه يطلب مفتاح واجهة برمجة تطبيقات (API key)؟

لا، ليس في الوقت الحالي. فلا توجد متغيرات بيئة (environment variables) أو علامات (flags) أو خيارات تهيئة تتيح تفعيل المصادقة على الخادم المحلي، رغم طلبات المستخدمين المتكررة لهذه الميزة منذ فترة طويلة. والحل المقبول رسميًّا هو استخدام وكيل عكسي أمام الخادم.

كيف يمكنني الحصول على مفتاح واجهة برمجة تطبيقات (API key) لخدمة Ollama Cloud؟

أنشئ حسابًا على موقع ollama.com ووَلِّد مفتاحًا في قسم 'مفاتيح واجهة برمجة التطبيقات (API keys)' ضمن إعدادات حسابك. ثم أرسله كرأس Authorization: Bearer مع طلباتك الموجَّهة إلى https://ollama.com. أما عند الاستخدام عبر سطر الأوامر (CLI)، فإن الأمر ollama signin يربط جهازك بحسابك تلقائيًّا دون الحاجة للتعامل اليدوي مع المفتاح.

لماذا يُظهر مكتبة SDK الخاصة بـ OpenAI خطأ مصادقة قبل إرسال أي طلب؟

لأن المكتبة تقوم بالتحقق من وجود مفتاح واجهة برمجة التطبيقات (API key) أثناء إنشاء العميل، وبالتالي فإن غياب المفتاح أو تركه فارغًا يؤدي إلى فشل التحقق محليًّا، حتى وإن كان Ollama نفسه لا يهتم بذلك. لذا، عيِّن القيمة api_key="ollama" (أو أي سلسلة أخرى)، وتأكد من أن عنوان URL الأساسي ينتهي بـ /v1.

هل من الآمن عرض خادم Ollama على شبكتي المنزلية؟

في شبكة منزلية موثوقة (LAN) تقع خلف NAT، فإن عرض خادم Ollama باستخدام الإعداد OLLAMA_HOST=0.0.0.0 يُعد إعدادًا شائعًا ومعقولًا. تأكَّد من أن جهاز التوجيه (router) الخاص بك لا يقوم بتوجيه المنفذ 11434 تلقائيًّا إلى تلك الآلة، وذكّر نفسك بأن كل جهاز متصل بهذه الشبكة — بما في ذلك هواتف الضيوف — سيكون قادرًا حينها على استخدام نماذجك وإدارتها.