مفتاح API الخاص بـ Ollama: لماذا لا يوجد واحد وما يجب استخدامه بدلاً منه

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

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

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

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

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

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

الإعداد	القيمة الخاصة بـ Ollama المحلي
عنوان URL الأساسي	http://localhost:11434/v1
مفتاح API	أي سلسلة غير فارغة، على سبيل المثال Ollama
النموذج	وسم قمت بسحبه، على سبيل المثال llama3.2

Python، باستخدام SDK OpenAI الرسمي:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",  # required by the SDK, ignored by Ollama
)

response = client.chat.completions.create(
    model="llama3.2",
    messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)

JavaScript / TypeScript:

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: "Hello" }],
});
console.log(response.choices[0].message.content);

يجب أن يكون النموذج قد تم سحبه بالفعل ("ollama pull llama3.2") أو ستفشل الطلب مع رسالة خطأ model-not-found. إذا لم تكن متأكداً ما الذي يجب تشغيله، راجع اختياراتنا لـ أفضل النماذج المحلية لـ Ollama.

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

نظراً لأن Ollama لا يمكنه التحقق من المفاتيح بنفسه، النمط القياسي هو الحفاظ على Ollama في ربط الحلقة المحلية الافتراضي وضع خادم وكيل عكسي في الأمام. يوقف الوكيل TLS، ويتحقق من الرمز، وينقل الطلبات الصحيحة إلى 127.0.0.1:11434. إعدادات nginx الحد الأدنى التي تتطلب رمز Bearer:

server {
    listen 443 ssl;
    server_name ollama.example.com;
    # ssl_certificate and ssl_certificate_key lines omitted

    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 مقصودة: يمكن أن تعمل الأجيال المُرسلة لدقائق، والمهلات الزمنية الافتراضية للوكيل ستقطعها في منتصف الاستجابة.

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

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

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

ويندوز

أغلق Ollama من صينية النظام. افتح الإعدادات، ابحث عن «متغيرات البيئة،» واختر «تحرير متغيرات البيئة لحسابك.» أضف متغيراً باسم OLLAMA_HOST بالقيمة 0.0.0.0، احفظ، وأعد تشغيل Ollama.

macOS

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

Linux

للخدمة 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 على جهاز له عنوان IP عام يحول GPU الخاص بك إلى أداة مساعدة عامة. جدّر المنفذ 11434 حتى يتمكن فقط المضيفون الذين يحتاجون إليه من الاتصال.

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

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

من خلال واجهة سطر الأوامر المحلية. تشغيل ollama signin للاتصال بحسابك ollama.com، ثم قم بتشغيل النماذج المستضافة في السحابة بواسطة العلامات السحابية الخاصة بهم — في وقت الكتابة، على سبيل المثال، 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) أو الأجهزة المحلية أكثر ملاءمةً لحمل العمل الخاص بك، فإن دليلنا self-hosting vs API break-even calculator يقدّم أرقامًا توضيحية لذلك، وكذلك حاسبة 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 حسب الاتفاقية المتبعة. والسبب في هذه المتطلبات هو بحتٌ من جانب العميل؛ إذ إن 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 تلقائيًّا إلى تلك الآلة، وذكّر نفسك بأن كل جهاز متصل بهذه الشبكة — بما في ذلك هواتف الضيوف — سيكون قادرًا حينها على استخدام نماذجك وإدارتها.