واجهة برمجة تطبيقات Ollama في Python، ثم نقطة نهاية مستضافة

إعداد عميل Python

ثبّت Ollama أولاً، ثم شغّله واسحب النموذج من طرفية الأوامر: ollama pull llama3. يستمع الخادم على http://localhost:11434. بعد ذلك، ثبّت حزمة Python في بيئة افتراضية:

Copypython -m venv .venv
source .venv/bin/activate
pip install ollama openai

تتحدث الحزمة ollama مع نقاط النهاية الأصلية لـ Ollama تحت المسار /api. الحزمة openai مخصصة للنصف الثاني من هذا الدليل، حيث يكون الهدف نقطة نهاية مستضافة. إذا كنت تفضل أداة بصرية قبل البرمجة، انظر الملاحظات حول استخدام Ollama مع واجهة المستخدم الرسومية.

تحقّق من التثبيت بتشغيل ollama list في الطرفية. إذا ظهر نموذجك هناك، فستجده Python. إذا حصلت على خطأ في الاتصال لاحقاً، فمن المرجح أن الخادم لا يعمل.

أول مكالمة دردشة لك

هذا هو أساس واجهة برمجة التطبيقات لـ ollama في Python في مقتطف واحد: رسالة نظام، ورسالة مستخدم، وخياران.

Copyimport ollama

resp = ollama.chat(
    model="llama3",
    messages=[
        {"role": "system", "content": "Answer in one short paragraph."},
        {"role": "user", "content": "What is a context window?"},
    ],
    options={"temperature": 0.4, "num_ctx": 8192},
)
print(resp["message"]["content"])

الرد عبارة عن كائن يشبه القاموس؛ يتواجد النص في message.content. في options يمكنك ضبط معلمات التوليد. يتحكم temperature في العشوائية ويحدد num_ctx طول نافذة السياق لذلك الطلب. Ollama تستخدم افتراضياً نافذة سياق صغيرة نسبياً ما لم ترفعها، مما يفاجئ من يلصق مستندات طويلة ويحصل على إجابات تتجاهل البداية.

للدردشة متعددة الأدوار، احتفظ بقائمة من الرسائل وأضف كل رد بنفسك. Ollama، مثل معظم واجهات برمجة تطبيقات الدردشة، عديم الحالة بين المكالمات.

استجابات البث المتدفق

بدون البث المتدفق، تنتظر الإجابة الكاملة. مع stream=True، تُرجع الدالة مولّداً (generator) وتطبع الأجزاء مع وصولها:

Copyimport ollama

for part in ollama.chat(
    model="llama3",
    messages=[{"role": "user", "content": "Explain recursion with a cooking analogy."}],
    stream=True,
):
    print(part["message"]["content"], end="", flush=True)

يحمل كل جزء message.content صغيراً. الجزء الأخير يحتوي على done مضبوطاً على true ويحتوي على التوقيت وعدد الرموز. لتطبيقات الويب، قم بتوجيه هذه الأجزاء إلى المتصفح عبر أحداث الإرسال من الخادم أو عبر WebSockets.

الأخطاء التي ستراها فعلياً

يغطي فشلان معظم مشاكل المبتدئين.

Copyimport ollama

try:
    ollama.chat(model="llama3", messages=[{"role": "user", "content": "hi"}])
except ollama.ResponseError as exc:
    if exc.status_code == 404:
        print("Model missing. Run: ollama pull llama3")
    else:
        raise
except ConnectionError:
    print("Cannot reach Ollama. Is the server running on port 11434?")

خطأ 404 من ResponseError يعني أن اسم النموذج لا يتطابق مع ما قمت بسحبه. تتضمن الأسماء علامات، لذا llama3 و llama3:70b هما نموذجان مختلفان. خطأ الاتصال يعني أن الخادم لا يعمل، أو أنك داخل حاوية حيث يشير localhost إلى الحاوية وليس المضيف. في هذه الحالة، مرر عميلاً مع المضيف الصحيح: ollama.Client(host="http://host.docker.internal:11434").

يتم جمع أنماط أكثر في أخطاء واجهة برمجة التطبيقات الشائعة لـ Ollama.

نفس البرنامج، نقطة نهاية مستضافة

النماذج المحلية محدودة بذاكرة جهازك وسرعته. عندما يجب أن يعمل نص برمجي على خادم، أو يعالج العديد من المهام المتزامنة، أو يستخدم نافذة سياق أكبر، تكون نقطة النهاية المستضافة أسهل. الحيلة هي كتابة البرنامج باستخدام OpenAI SDK ومعاملة URL الأساسي والمفتاح والنموذج كإعدادات:

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.ollamansfw.com/v1"),
    api_key=os.environ["LLM_API_KEY"],
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

def ask(prompt, history=None):
    messages = (history or []) + [{"role": "user", "content": prompt}]
    out = ""
    for chunk in client.chat.completions.create(model=MODEL, messages=messages, stream=True):
        if chunk.choices and chunk.choices[0].delta.content:
            piece = chunk.choices[0].delta.content
            out += piece
            print(piece, end="", flush=True)
    return out

ask("Explain recursion with a cooking analogy.")

لـ Ollama المحلي، اضبط LLM_BASE_URL=http://localhost:11434/v1، LLM_API_KEY=ollama (يُقبل أي سلسلة غير فارغة هناك) و LLM_MODEL=llama3. لواجهة الـ API المستضافة، استخدم الإعدادات الافتراضية أعلاه، ومفتاحك الحقيقي والنموذج uncensored. لا يتغير شيء آخر في الكود.

احصل على مفتاح من صفحة مفتاح API. يمكن للحسابات الجديدة المطالبة برصيد تجريبي بقيمة $0.50 بنقرة واحدة، بدون دفع، صالح لمدة 7 أيام. النموذج هو نموذج مفتوح الأوزان من مزود مستقل، ومضبط للإجابة بدون رفض المحتوى للاستخدام القانوني للبالغين. وهو للنص فقط وليس واجهة برمجة تطبيقات رسمية لأي مختبر كبير.

تشغيل العديد من الموجّهات بشكل متزامن

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

Copyfrom concurrent.futures import ThreadPoolExecutor
from openai import OpenAI

client = OpenAI(base_url="https://api.ollamansfw.com/v1", api_key="YOUR_KEY")

def summarize(text):
    r = client.chat.completions.create(
        model="uncensored",
        messages=[{"role": "user", "content": "Summarize in one line: " + text}],
        max_tokens=60,
    )
    return r.choices[0].message.content

docs = ["first text", "second text", "third text"]
with ThreadPoolExecutor(max_workers=6) as pool:
    results = list(pool.map(summarize, docs))
print(results)

تترك ستة عمال هامشاً آمناً تحت حد 8. إذا حصل عامل على خطأ 429، فإن حزمة OpenAI SDK تعيد المحاولة بضع مرات افتراضياً، ولكن أضف آلية ارتداد خاصة بك للتشغيل الطويل. تذكر أيضاً أن كل طلب بث متدفق يحتفظ بفتحة (slot) حتى ينتهي البث، لذا لا تخلط بين دردشة بث طويلة وحزمة كبيرة على نفس مفتاح التجربة.

الاختلافات التي يجب أخذها في الاعتبار

• لا توجد خيارات محلية فقط. لا معنى لـ num_ctx و keep_alive في الجانب المستضاف. نافذة السياق هي 100,000 رمز، للموجّه والإكمال معاً.
• حدود المعدل. المفتاح الكامل يسمح بـ 8 طلبات متزامنة و300 طلب في الدقيقة؛ ويسمح المفتاح التجريبي بـ 2 و60. بعد ذلك، تحصل على 429 مع rate_limited أو concurrency. أعد المحاولة بعد توقف؛ وفي حالة الحمل الزائد المؤقت، تحمل الاستجابة Retry-After: 5.
• التكلفة. سعر الإدخال $0.15 لكل مليون رمز (token)، وسعر الإخراج $0.50 لكل مليون. سكريبت يرسل 2,000 موجّه (prompt) بحجم 600 رمز للإدخال و400 رمز للإخراج ينفق: 2,000 × (600 × $0.15 + 400 × $0.50) / 1M = 2,000 × $0.00029 = $0.58.
• الفوترة. رصيد مسبق الدفع، من $20 إلى $500، يُدفع بالعملات المشفرة (USDT على TRC20 أو USDC على Base). لا تُفرض رسوم على الطلبات الفاشلة أو المرفوضة.

لمقارنة نقاط النهاية جنباً إلى جنب، اقرأ ملاحظة تسعير واجهة برمجة التطبيقات أو المستندات.

المزيد من الأدلة

• واجهة برمجة تطبيقات Ollama مقابل واجهة برمجة تطبيقات OpenAI: نقاط النهاية والأكواد
• كيفية استخدام Ollama مع واجهة رسومية (وملاذ احتياطي مستضاف)