> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# استدعاء نموذج اللغة من الكود عبر API متوافقة مع OpenAI
- URL: https://arabroot.io/articles/استدعاء-نموذج-اللغة-من-الكود-عبر-api-متوافقة-مع-openai/
- Published: 2026-11-18T21:39:41.000Z
- Updated: 2026-11-18T22:50:29.000Z
- Description: كيف تستدعي نموذجاً على سيرفرك من الكود بنفس واجهة OpenAI، وتتعامل مع البث والمخرج المنظم والأدوات والأخطاء وتحسب تكلفة كل طلب.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الذكاء الاصطناعي والبيانات, الاستضافة الذاتية

بعد أن تشغل نموذج لغة على سيرفرك وتجربه في واجهة محادثة، يأتي السؤال الذي يهم المطور فعلاً: كيف أستدعيه من الكود Code؟ فالمطلوب في العمل ليس أن يكتب الموظف سؤاله في نافذة محادثة، وإنما أن يلخص برنامجك تذكرة الدعم الفني لحظة وصولها، أو يستخرج رقم الطلب من رسالة العميل ويضعه في قاعدة البيانات، أو يرد على سؤال داخل تطبيق الموظفين. وكل هذا يمر عبر واجهة برمجية API واحدة تقريباً أصبحت هي المعيار الفعلي في هذا المجال: الواجهة المتوافقة مع OpenAI، التي تقبلها Ollama وllama.cpp وvLLM على سيرفرك، وتقبلها أيضاً أغلب الخدمات السحابية.

والفائدة العملية من هذا المعيار كبيرة، فالكود الذي تكتبه اليوم لنموذج على سيرفرك هو نفسه الكود الذي يعمل غداً مع خدمة سحابية أو مع سيرفر vLLM لفريق كامل، والفرق عنوان السيرفر Server واسم النموذج Model ومفتاح الدخول. ولكن بين «أرسلت سؤالاً ووصلت إجابة» وبين كود يعمل في الإنتاج Production تفاصيل كثيرة: لماذا تختلف الإجابة في كل مرة، ولماذا تنقطع في منتصفها، وكيف تعرض الكلمات أثناء كتابتها، وكيف تحصل على JSON صحيح في كل مرة، وماذا يحدث عندما يكون النص أطول من ذاكرة النموذج، وكم يكلف الطلب الواحد إذا انتقلت إلى خدمة مدفوعة. لذلك سوف نمر على كل ذلك بطلبات حقيقية على سيرفر محلي، ونقرأ الردود الخام سطراً سطراً.

وإذا لم تكن قد اخترت أداة التشغيل بعد فابدأ بمقال [تشغيل نماذج اللغة على جهازك](https://arabroot.io/articles/%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D8%B9%D9%84%D9%89-%D8%AC%D9%87%D8%A7%D8%B2%D9%83-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/) لتعرف ما يتحمله جهازك، وإذا كانت المصطلحات مثل التوكن Token ونافذة السياق Context Window جديدة عليك فقد شرحناها في مقال [مصطلحات الذكاء الاصطناعي](https://arabroot.io/articles/%D9%85%D8%B5%D8%B7%D9%84%D8%AD%D8%A7%D8%AA-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D9%88%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/).

وسوف نناقش في هذا المقال ما يلي:

- ما هي الواجهة المتوافقة مع OpenAI، ولماذا أصبحت معياراً، ومن يدعمها، والفرق بين Chat Completions وResponses.
- شكل الطلب والرد: الرسائل Messages والأدوار Roles، ولماذا ترسل المحادثة كاملة في كل طلب.
- الإعدادات التي تغير الإجابة: درجة الحرارة Temperature والبذرة Seed والحد الأقصى للتوكنات Max Tokens.
- البث Streaming كما يصل فعلاً بصيغة Server-Sent Events، وقياس زمن أول توكن.
- المخرج المنظم Structured Output: JSON Mode والمخطط JSON Schema، واستدعاء الأدوات Tool Calls.
- الأخطاء: نموذج غير موجود، ومهلة Timeout تتضاعف مع إعادة المحاولة Retries، ونص أطول من نافذة السياق يقطع دون رسالة خطأ.
- عد التوكنات وحساب تكلفة الطلب بأسعار المزودين الرسمية، بلغة Python وبالأمر curl.

## ما هي الواجهة المتوافقة مع OpenAI؟

عندما أطلقت OpenAI خدمتها للمطورين عرفت واجهة HTTP بسيطة: ترسل طلب POST إلى المسار `/v1/chat/completions` فيه اسم النموذج وقائمة رسائل بصيغة JSON، فيعود رد JSON فيه الإجابة وعدد التوكنات. ولأن ملايين المطورين Developers كتبوا كودهم على هذا الشكل، ولأن مكتبات OpenAI الرسمية تسمح بتغيير عنوان السيرفر بمعامل واحد اسمه `base_url`، قررت أغلب أدوات التشغيل أن تقلد نفس الواجهة بدلاً من أن تفرض على المطورين واجهة جديدة، وهكذا أصبح لدينا معيار لم تكتبه لجنة، وإنما فرضه الاستخدام.

وفيما يلي أمثلة على من يدعمها اليوم، كل منها من توثيقه الرسمي:

- على سيرفرك: [Ollama](https://docs.ollama.com/api/openai-compatibility?ref=arabroot.io) على المسار `/v1`، والسيرفر llama-server في [llama.cpp](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md?ref=arabroot.io)، و[vLLM](https://docs.vllm.ai/en/latest/serving/openai%5Fcompatible%5Fserver.html?ref=arabroot.io) لخدمة فريق كامل، و[LM Studio](https://lmstudio.ai/docs/developer/openai-compat?ref=arabroot.io) على جهاز المطور.
- خدمات سحابية: OpenAI نفسها، وGoogle Gemini عبر [طبقة التوافق](https://ai.google.dev/gemini-api/docs/openai?ref=arabroot.io)، وAnthropic التي توفر [توافقاً مع مكتبة OpenAI](https://platform.claude.com/docs/en/api/openai-sdk?ref=arabroot.io) للتجربة والمقارنة، مع أن واجهتها الأصلية Messages API هي الأكمل في ميزاتها.

ولكن لاحظ أن «متوافق» لا تعني «مطابق»، فكل سيرفر يدعم جزءاً من الحقول، وصفحة التوافق في Ollama مثلاً تقول صراحة إن الحقول `tool_choice` و`logit_bias` و`n` غير مدعومة، وإن الواجهة لا تسمح بتغيير طول نافذة السياق. وبالتالي فالقاعدة الأولى في هذا المقال: اقرأ صفحة التوافق للسيرفر الذي تستخدمه، ولا تفترض أن كل حقل في توثيق OpenAI سوف يعمل.

### Chat Completions أم Responses؟

في 2025 أضافت OpenAI واجهة ثانية اسمها Responses على المسار `/v1/responses`، وهي التي توصي بها اليوم في [صفحة Chat Completions نفسها](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create?ref=arabroot.io) للاستفادة من أحدث ميزات منصتها، ومن الفروق أنها تستطيع أن تحفظ المحادثة عند المزود فلا ترسلها كاملة كل مرة، وأن فيها أدوات مدمجة مثل البحث في الويب. أما في عالم التشغيل الذاتي فما زالت Chat Completions هي الواجهة المشتركة بين كل الأدوات، وOllama مثلاً تدعم Responses بدون حفظ الحالة Non-stateful فقط بحسب توثيقها. لذلك سوف نستخدم في هذا المقال Chat Completions، وكل ما تتعلمه فيها من رسائل وأدوار وتوكنات ينتقل كما هو إلى Responses.

## شكل الطلب والرد

الطلب الكامل في أبسط صوره ثلاثة أشياء: اسم النموذج، وقائمة الرسائل، والإعدادات الاختيارية. وكل رسالة لها دور Role ومحتوى Content، والأدوار المعروفة هي:

- النظام System: تعليمات ثابتة تحدد سلوك النموذج في كل المحادثة، مثل «أنت مساعد دعم فني، أجب بالعربية في جملتين». وفي نماذج OpenAI الحديثة يسمى المطور Developer، ومعناه واحد.
- المستخدم User: ما كتبه المستخدم أو ما يرسله برنامجك نيابة عنه.
- المساعد Assistant: ردود النموذج السابقة، وترسلها أنت مرة أخرى مع كل طلب جديد كما سوف نشرح.
- الأداة Tool: نتيجة أداة نفذها برنامجك بطلب من النموذج، وسوف نراها في [قسم الأدوات](#tools).

وأهم حقيقة يجب أن تفهمها عن هذه الواجهة أنها بلا حالة Stateless، أي أن السيرفر لا يتذكر الطلب السابق، فإذا أردت محادثة من عدة أدوار فبرنامجك هو الذي يحفظ الرسائل كلها، ويرسلها كاملة مع كل سؤال جديد. وهذا يعني أمرين: كل سؤال في محادثة طويلة يكلف توكنات أكثر من السؤال الذي قبله، لأنه يحمل كل ما قبله، وعندما يتجاوز المجموع نافذة السياق يجب أن يقرر برنامجك ماذا يحذف أو يلخص، وإلا قرر السيرفر عنك كما سوف ترى في [تجربة النص الطويل](#lab-overflow).

![طلب Chat Completions من برنامجك إلى السيرفر فيه النموذج والرسائل والإعدادات، والرد فيه الإجابة وسبب التوقف وعدد التوكنات](https://arabroot.io/content/images/2026/11/llm-api-basics-01-request.webp)

طلب واحد ورد واحد: برنامجك يرسل المحادثة كاملة في كل مرة، والسيرفر لا يحفظ شيئاً

## تجربة حقيقية: سيرفر محلي وطلبات حقيقية

سوف نستخدم Ollama كسيرفر، لأن واجهتها المتوافقة تعمل دون أي إعداد، ومعها نموذج صغير هو qwen2.5:3b بحجم 1.9 GB يعمل على المعالج وحده، وبرخصته Qwen Research بحسب بطاقته في مكتبة Ollama. والهدف هنا ليس جودة الإجابة، فهذا موضوع مقال [تشغيل نماذج اللغة على جهازك](https://arabroot.io/articles/%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D8%B9%D9%84%D9%89-%D8%AC%D9%87%D8%A7%D8%B2%D9%83-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/)، وإنما شكل الطلب والرد وسلوك الواجهة، وكل ما سوف تراه ينطبق على أي نموذج وأي سيرفر متوافق.

### تجهيز السيرفر

```bash
docker network create ad3-net
docker volume create ad3-ollama
docker run -d --name ad3-ollama --network ad3-net -p 127.0.0.1:9576:11434 \
  -v ad3-ollama:/root/.ollama ollama/ollama:0.40.13
docker exec ad3-ollama ollama pull qwen2.5:3b
curl -s http://127.0.0.1:9576/v1/models
```

والمخرج سوف يكون كما يلي:

```json
{"object":"list","data":[{"id":"qwen2.5:3b","object":"model","created":1795021435,"owned_by":"library"}]}
```

لاحظ ثلاثة أمور في الإعداد أعلاه: المنفذ منشور على `127.0.0.1` فقط، والسبب أن واجهة Ollama لا تطلب أي مصادقة Authentication، فمن يصل إلى المنفذ يستخدم النموذج، وإذا أردت أن يستخدمها فريقك فضعها خلف Reverse Proxy بمفتاح، أو استخدم أداة مثل Open WebUI. والمنفذ الأصلي داخل ال Container هو 11434 وقد ربطناه بالمنفذ 9576 على الجهاز. والمسار `/v1/models` هو نفس المسار في OpenAI، ويعيد النماذج المتاحة على السيرفر، وهو أول طلب تجربه عندما تتصل بأي سيرفر جديد.

### الطلب الأول بالأمر curl

نبدأ بالأمر curl دون أي مكتبة، حتى ترى ما يمر على الشبكة فعلاً. احفظ الطلب في first.json:

```json
{
  "model": "qwen2.5:3b",
  "messages": [
    {"role": "system", "content": "أنت مساعد دعم فني. أجب بالعربية في جملتين على الأكثر."},
    {"role": "user", "content": "ما الفرق بين الذاكرة RAM والقرص SSD؟"}
  ],
  "temperature": 0
}
```

```bash
curl -s http://127.0.0.1:9576/v1/chat/completions \
  -H "Content-Type: application/json" -H "Authorization: Bearer anything" \
  -d @first.json | python -m json.tool --no-ensure-ascii
```

والمخرج سوف يكون كما يلي:

```json
{
    "id": "chatcmpl-34",
    "object": "chat.completion",
    "created": 1795021504,
    "model": "qwen2.5:3b",
    "system_fingerprint": "fp_ollama",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "RAM ساهمة مؤقتة للبيانات، بينما SSD هو نوع من القرص الصلب يوفر سرعة أسرع وأقل تأخراً."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 46,
        "prompt_tokens_details": {
            "cached_tokens": 0
        },
        "completion_tokens": 38,
        "total_tokens": 84
    }
}
```

في المخرج أعلاه لاحظ التالي:

- الترويسة `Authorization` أرسلناها بقيمة لا معنى لها، وقبلها السيرفر لأن Ollama تتجاهل المفتاح API Key، أما المزودون Providers السحابيون فيرفضون الطلب برمز 401 إذا كان المفتاح خاطئاً. ونرسلها مع ذلك لأن مكتبات OpenAI تشترط وجود مفتاح قبل أن ترسل الطلب.
- الإجابة في `choices[0].message.content`، والحقل `choices` قائمة لأن الواجهة الأصلية تسمح بطلب عدة إجابات بالمعامل `n`، وهو من الحقول التي لا تدعمها Ollama بحسب صفحة التوافق.
- سبب التوقف `finish_reason` قيمته `stop`، أي أن النموذج أنهى الإجابة بنفسه، وسوف نرى بعد قليل القيمتين `length` و`tool_calls`، وهذا أول حقل يجب أن يفحصه الكود قبل أن يستخدم الإجابة.
- الحقل `usage` فيه عدد التوكنات: 46 في المدخلات Prompt، منها التعليمات والسؤال وعلامات القالب Chat Template التي يضيفها السيرفر حول كل رسالة، و38 في المخرجات Completion. وهذا هو الرقم الذي تحسب منه التكلفة Cost عند المزودين السحابيين كما سوف نفعل في آخر المقال.
- والإجابة نفسها فيها خطأ لغوي واضح «ساهمة مؤقتة»، وهذا من حدود نموذج بثلاثة مليارات معامل Parameters في العربية، وليس من حدود الواجهة، وقد شرحنا في مقال [متى يكون الذكاء الاصطناعي واثقاً ومخطئاً](https://arabroot.io/articles/%D9%85%D8%AA%D9%89-%D9%8A%D9%83%D9%88%D9%86-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D9%88%D8%A7%D8%AB%D9%82%D8%A7-%D9%88%D9%85%D8%AE%D8%B7%D8%A6%D8%A7/) لماذا يكتب النموذج جملة واثقة غير دقيقة.

### نفس الطلب بلغة Python

في الكود الحقيقي لن تكتب JSON بيدك، وإنما تستخدم مكتبة OpenAI الرسمية [openai-python](https://github.com/openai/openai-python?ref=arabroot.io)، وهي تعمل مع أي سيرفر متوافق بتغيير `base_url`. وسوف نشغل البرامج في Container على نفس شبكة Docker، لذلك العنوان هو اسم ال Container `ad3-ollama` وليس localhost. هذا ملف Dockerfile للبرامج:

```dockerfile
FROM python:3.13.18-slim
RUN pip install --no-cache-dir openai==3.55.1 tiktoken==0.14.0
WORKDIR /lab
```

والبرنامج hello.py:

```python
import os, time
from openai import OpenAI

# نفس الكود يعمل مع أي سيرفر متوافق: غير العنوان والمفتاح فقط
client = OpenAI(base_url=os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1"),
                api_key=os.environ.get("API_KEY", "not-needed"))
MODEL = os.environ.get("MODEL", "qwen2.5:3b")

t = time.perf_counter()
resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "أنت مساعد دعم فني. أجب بالعربية في جملتين على الأكثر."},
        {"role": "user", "content": "ما الفرق بين الذاكرة RAM والقرص SSD؟"},
    ],
    temperature=0,
)
print(resp.choices[0].message.content)
print("finish_reason:", resp.choices[0].finish_reason)
print("usage:", resp.usage.prompt_tokens, "in +", resp.usage.completion_tokens, "out")
print(f"time: {time.perf_counter() - t:.1f} s")
```

```bash
docker build -t ad3-api:1 .
docker run --rm --network ad3-net -v "$PWD:/lab" ad3-api:1 python hello.py
```

والمخرج سوف يكون كما يلي:

```text
RAM ساهمة مؤقتة، تؤثر على سرعة تشغيل البرامج، بينما SSD هو نوع من القرص الصلب يوفر سرعة أسرع من القرص الصلب التقليدي.
finish_reason: stop
usage: 46 in + 51 out
time: 66.4 s
```

عدد توكنات المدخلات 46 كما في طلب curl، لأن الطلب نفسه، ولكن الإجابة هذه المرة أطول بجملة، رغم أن درجة الحرارة صفر، وسوف نعود إلى سبب ذلك في [قسم درجة الحرارة](#temperature). ولاحظ أن الكود لا يعرف شيئاً عن Ollama، فلو غيرت المتغيرات الثلاثة `BASE_URL` و`API_KEY` و`MODEL` إلى عنوان مزود سحابي ومفتاحه واسم نموذجه لعمل نفس البرنامج دون تعديل سطر واحد، وهذه هي الفائدة كلها من الواجهة المتوافقة. والقاعدة هنا: لا تكتب العنوان والمفتاح داخل الكود أبداً، وإنما في متغيرات البيئة Environment Variables أو في مدير الأسرار Secrets Manager، والسبب أن المفتاح المكتوب في الكود يصل إلى Git ثم إلى كل من يقرأ المستودع.

## الإعدادات التي تغير الإجابة

### درجة الحرارة Temperature والبذرة Seed

النموذج لا يختار الكلمة التالية مباشرة، وإنما يحسب احتمالاً لكل توكن ممكن، ثم يختار منها، وقد شرحنا ذلك بالتفصيل في مقال [كيف تعمل نماذج اللغة](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%B9%D9%85%D9%84-%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D8%A7%D9%84%D9%83%D8%A8%D9%8A%D8%B1%D8%A9-llm-%D8%AE%D8%B7%D9%88%D8%A9-%D8%A8%D8%AE%D8%B7%D9%88%D8%A9/#temperature). ودرجة الحرارة تتحكم في هذا الاختيار: عند الصفر يختار النموذج الاحتمال الأعلى دائماً تقريباً، وكلما ارتفعت أصبحت الاحتمالات الأقل أقرب إلى الأعلى فتتنوع الإجابات. وفي توثيق OpenAI القيمة بين 0 و2 والقيمة الافتراضية 1، أي أنك إذا لم ترسلها فأنت تطلب إجابات متنوعة. والبرنامج temperature.py يسأل نفس السؤال ثلاث مرات عند كل درجة، ثم مرتين بنفس البذرة Seed:

```python
import os
from openai import OpenAI

client = OpenAI(base_url=os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1"), api_key="not-needed")
msgs = [{"role": "user", "content": "اقترح اسماً واحداً فقط لمقهى صغير، دون شرح."}]
for temp in (0, 1.5):
    for i in range(3):
        r = client.chat.completions.create(model="qwen2.5:3b", messages=msgs, temperature=temp, max_tokens=15)
        print(f"temperature={temp} run {i + 1}: {r.choices[0].message.content.strip()}")
r = [client.chat.completions.create(model="qwen2.5:3b", messages=msgs, temperature=1.5, seed=7, max_tokens=15)
     .choices[0].message.content.strip() for _ in range(2)]
print("temperature=1.5 seed=7 twice:", r)
```

والمخرج سوف يكون كما يلي:

```text
temperature=0 run 1: مكتبة الشاي
temperature=0 run 2: مذاق المدينة
temperature=0 run 3: مذاق المدينة
temperature=1.5 run 1: م caffeine时光
temperature=1.5 run 2: هانغيان
temperature=1.5 run 3: قهوة الصندوقين
temperature=1.5 seed=7 twice: ['"الوحة الصغيرة"', '"الوحة الصغيرة"']
```

في المخرج أعلاه لاحظ التالي:

- عند درجة الصفر جاءت المرة الأولى مختلفة عن الثانية والثالثة، أي أن الصفر لا يضمن نفس الإجابة دائماً، ورأيت نفس الشيء في hello.py الذي أعطى إجابة مختلفة عن طلب curl. والسبب أن الحساب بالأرقام العشرية يتأثر بترتيب العمليات، فإذا كان هناك توكنان احتمالهما متقارب جداً فقد يتبدل الأعلى بينهما عندما يتغير شيء في السيرفر: أعيد استخدام حسابات محفوظة من طلب سابق Prompt Cache، أو تغير عدد خيوط المعالج Threads، وقد غيرنا عدد الخيوط فعلاً بين طلب curl وبرنامج hello.py. لذلك لا تبن اختبارات آلية تفترض أن النص يتطابق حرفاً بحرف.
- عند 1.5 ظهرت إجابة فيها حروف صينية وكلمة إنجليزية «م caffeine时光»، وهذا ما يحدث عندما تقترب الاحتمالات الضعيفة من القوية: يصبح التوكن الغريب ممكناً. فدرجة الحرارة العالية ليست «إبداعاً»، وإنما ضجيج أكثر، ونادراً ما تحتاج أكثر من 1 في تطبيق عمل.
- مع البذرة الثابتة `seed=7` تكررت نفس الإجابة مرتين حتى عند 1.5، لأن الاختيار العشوائي أصبح يبدأ من نفس النقطة. ويصف توثيق OpenAI هذا المعامل بأنه محاولة بأفضل جهد Best Effort، وأن الحتمية Determinism غير مضمونة، فاستخدمه في التجارب والمقارنات، ولا تعتمد عليه في منطق البرنامج.

والقاعدة العملية: درجة 0 أو قريبة منها للاستخراج والتصنيف والإجابة من المستندات، حيث تريد نفس السلوك كل مرة، ودرجة بين 0.7 و1 لكتابة نصوص تريد فيها تنوعاً، مثل اقتراح عناوين. ولا تغير `temperature` و`top_p` معاً، فتوثيق OpenAI ينصح بتغيير أحدهما فقط.

### الحد الأقصى للتوكنات Max Tokens: الإجابة المقطوعة

الحقل `max_tokens` يحدد أكبر عدد من التوكنات يكتبه النموذج، وهو حماية للتكلفة وللوقت، ولكن له أثر جانبي يجب أن يعرفه الكود. احفظ هذا في maxtok.json:

```json
{
  "model": "qwen2.5:3b",
  "messages": [{"role": "user", "content": "اشرح ما هو نظام التشغيل Linux في فقرتين."}],
  "max_tokens": 20,
  "temperature": 0
}
```

```bash
curl -s http://127.0.0.1:9576/v1/chat/completions -H "Content-Type: application/json" -d @maxtok.json
```

والمخرج سوف يكون كما يلي:

```json
{"id":"chatcmpl-483","object":"chat.completion","created":1795021806,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"message":{"role":"assistant","content":"نظام التشغيل Linux هو نظام تشغيل قائم على الكود المفتوح"},"finish_reason":"length"}],"usage":{"prompt_tokens":43,"prompt_tokens_details":{"cached_tokens":25},"completion_tokens":20,"total_tokens":63}}
```

الإجابة انقطعت في منتصف الجملة، وسبب التوقف `length` وليس `stop`، و`completion_tokens` يساوي الحد تماماً. والرد نفسه ناجح برمز HTTP 200، فلا يوجد استثناء Exception يخبر برنامجك بالمشكلة، وإذا لم يفحص الكود `finish_reason` فسوف يحفظ نصف جملة في قاعدة البيانات أو يعرضه للعميل، والأسوأ أن يحاول تحليل JSON مقطوع فيفشل في مكان آخر بعيد عن السبب. ولاحظ أيضاً `cached_tokens: 25`: السيرفر وجد أول 25 توكناً من الطلب محفوظة من طلب سابق، وهي تعليمات القالب المشتركة، فلم يحسبها من جديد.

وفي توثيق OpenAI أصبح الحقل `max_tokens` مهملاً Deprecated لصالح `max_completion_tokens`، والسبب أن النماذج التي تفكر قبل أن تجيب Reasoning Models تكتب توكنات تفكير لا تراها، وتحسب من نفس الحد، فقد تصل إلى الحد قبل أن تكتب أي إجابة. أما Ollama وأغلب السيرفرات المحلية فما زالت تقرأ `max_tokens`، فإذا كتبت كوداً يعمل مع الاثنين فاقرأ صفحة التوافق لكل سيرفر.

## البث Streaming: الإجابة كلمة كلمة

بدون بث ينتظر المستخدم حتى يكتب النموذج آخر توكن، ثم تظهر الإجابة كلها مرة واحدة، وعلى سيرفر بالمعالج وحده قد يكون ذلك عشرات الثواني أمام شاشة فارغة. ومع البث Streaming يرسل السيرفر كل جزء من الإجابة لحظة توليده، فيبدأ المستخدم بالقراءة بعد ثوان، وهذا ما تفعله كل واجهات المحادثة التي تعرفها. والمهم أن تعرف الصيغة التي يصل بها البث، لأنك سوف تحتاجها عندما تمرره من سيرفرك إلى المتصفح أو عندما تبحث عن سبب انقطاعه.

### كيف يصل البث فعلاً: Server-Sent Events

البث في هذه الواجهة يستخدم صيغة [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html?ref=arabroot.io) واختصاراً SSE، وهي اتصال HTTP واحد يبقى مفتوحاً، ويرسل فيه السيرفر أسطراً تبدأ بالكلمة `data:` ثم سطراً فارغاً بعد كل حدث. احفظ هذا في stream.json:

```json
{
  "model": "qwen2.5:3b",
  "messages": [{"role": "user", "content": "اكتب ثلاث كلمات عن القهوة."}],
  "stream": true,
  "stream_options": {"include_usage": true},
  "temperature": 0
}
```

والخيار `-N` في curl يمنع تخزين المخرج في الذاكرة المؤقتة Buffering حتى ترى كل سطر لحظة وصوله:

```bash
curl -sN http://127.0.0.1:9576/v1/chat/completions -H "Content-Type: application/json" -d @stream.json
```

والمخرج سوف يكون كما يلي، بعد حذف بعض الأحداث من المنتصف:

```text
data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{"role":"assistant","content":"ال"},"finish_reason":null}]}

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{"content":"ه"},"finish_reason":null}]}

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{"content":"اد"},"finish_reason":null}]}

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{"content":"ئة"},"finish_reason":null}]}

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{"content":"،"},"finish_reason":null}]}

...

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{"content":"."},"finish_reason":null}]}

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: {"id":"chatcmpl-990","object":"chat.completion.chunk","created":1795021765,"model":"qwen2.5:3b","system_fingerprint":"fp_ollama","choices":[],"usage":{"prompt_tokens":39,"prompt_tokens_details":{"cached_tokens":3},"completion_tokens":15,"total_tokens":54},"timings":{"prompt_n":39,"prompt_ms":14642,...,"predicted_n":15,"predicted_ms":20357,...}}

data: [DONE]
```

في المخرج أعلاه لاحظ التالي:

- كل حدث فيه كائن `chat.completion.chunk`، والنص الجديد في `delta.content` وليس في `message.content`، وبرنامجك هو الذي يجمع القطع. والدور `role` يأتي في القطعة الأولى فقط.
- القطع ليست كلمات ولا حروفاً، وإنما توكنات: كلمة «الهادئة» جاءت في أربع قطع «ال» و«ه» و«اد» و«ئة»، وهذا يعني أن ما تعرضه للمستخدم أثناء البث قد يكون نصف كلمة، فلا تفحص المحتوى أو تترجمه أو تحلله قطعة قطعة، وإنما بعد أن يكتمل.
- سبب التوقف يأتي في قطعة خاصة فيها `delta` فارغ، ثم بسبب الخيار `include_usage` تأتي قطعة أخيرة فيها `choices` فارغة وعدد التوكنات، وهذا موثق في توثيق OpenAI: القطعة الإضافية قبل `[DONE]`، وإذا انقطع البث فقد لا تصلك أبداً، لذلك لا تبن حساب التكلفة على وصولها وحدها.
- Ollama أضافت حقلاً اسمه `timings` ليس في واجهة OpenAI، فيه زمن حساب المدخلات وزمن التوليد بالمللي ثانية، وهذا مثال على أن «المتوافق» قد يضيف حقولاً، والمكتبات تتجاهل الحقول التي لا تعرفها.
- والسطر الأخير `data: [DONE]` ليس JSON، فإذا كتبت قارئ SSE بنفسك فافحص هذه القيمة قبل أن تحلل السطر.

### البث بلغة Python وزمن أول توكن

المكتبة تخفي تفاصيل SSE، وتعطيك القطع واحدة بعد الأخرى في حلقة for. والبرنامج stream.py يطبع النص أثناء وصوله، ويقيس زمن أول توكن Time to First Token واختصاراً TTFT، وهو الرقم الذي يشعر به المستخدم أكثر من أي رقم آخر:

```python
import os, sys, time
from openai import OpenAI

client = OpenAI(base_url=os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1"), api_key="not-needed")
t = time.perf_counter()
first = None
stream = client.chat.completions.create(
    model="qwen2.5:3b",
    messages=[{"role": "user", "content": "اشرح في ثلاث جمل لماذا نحتاج النسخ الاحتياطي."}],
    temperature=0, stream=True, stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        if first is None:
            first = time.perf_counter() - t      # زمن أول توكن Time To First Token
        print(chunk.choices[0].delta.content, end="", flush=True)
    if chunk.usage:                              # آخر قطعة فيها العدد فقط ولا يوجد فيها نص
        usage = chunk.usage
total = time.perf_counter() - t
print(f"\n--- first token after {first:.1f} s | done after {total:.1f} s | "
      f"{usage.completion_tokens} tokens = {usage.completion_tokens / (total - first):.1f} tokens/s")
```

والمخرج سوف يكون كما يلي:

```text
النسخ الاحتياطي ضروري لضمان استمرارية النظام وسهولة التعافي في حالة حدوث أخطاء أو أضرار قد تؤثر على البيانات. فهو يوفر القدرة على استعادة البيانات إلى نقطة زمنية محددة في حالة فقدان البيانات بسبب خلل في النظام أو أخطاء ميكانيكية أو تلف في القرص الصلب. بالإضافة إلى ذلك، النسخ الاحتياطي يساعد في الحفاظ على البيانات الأساسية للشركة أو المستخدم، مما يوفر الأمان والحماية ضد فقدان البيانات.
--- first token after 12.4 s | done after 171.0 s | 121 tokens = 0.8 tokens/s
```

أول توكن ظهر بعد 12.4 ثانية، والإجابة كاملة بعد 171 ثانية، أي أن المستخدم بدأ يقرأ قبل نهاية الإجابة بأكثر من دقيقتين ونصف. وزمن أول توكن يتكون أساساً من حساب المدخلات Prompt Processing، فهو يكبر مع طول التعليمات والمحادثة، أما بقية الوقت فهو سرعة التوليد Generation بالتوكن في الثانية، وهي تعتمد على العتاد وحجم النموذج كما شرحنا في مقال [تشغيل نماذج اللغة على جهازك](https://arabroot.io/articles/%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D8%B9%D9%84%D9%89-%D8%AC%D9%87%D8%A7%D8%B2%D9%83-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/#speed). ولاحظ أن الإجابة هنا 121 توكناً لثلاث جمل، فالطلب «في ثلاث جمل» لا يحدد الطول بالتوكن، وإنما `max_tokens` هو الذي يحدده.

![أحداث SSE على خط زمني: قطع نصية لكل توكن ثم قطعة سبب التوقف ثم قطعة العدد ثم DONE](https://arabroot.io/content/images/2026/11/llm-api-basics-02-sse.webp)

البث كما يصل: قطعة لكل توكن، ثم سبب التوقف، ثم عدد التوكنات، ثم \[DONE\]

⚠️

إذا وضعت Nginx أمام سيرفر النموذج فقد يجمع الردود في ذاكرته المؤقتة Proxy Buffering ثم يرسلها دفعة واحدة، فيبدو البث كأنه لا يعمل، والحل أن تضيف `proxy_buffering off;` في ال location الخاص بالواجهة، وأن ترفع `proxy_read_timeout` لأن الإجابة الطويلة قد تتجاوز المهلة Timeout الافتراضية وهي 60 ثانية.

## المخرج المنظم: JSON Mode والمخطط JSON Schema

أغلب الاستخدامات الحقيقية لا تحتاج نصاً يقرؤه إنسان، وإنما بيانات يقرؤها برنامج: استخرج رقم الطلب ونوع المشكلة من رسالة العميل، ثم افتح تذكرة. وهنا ثلاث طرق، من الأضعف إلى الأقوى، والبرنامج structured.py يجربها على نفس الرسالة:

```python
import os, json
from openai import OpenAI

client = OpenAI(base_url=os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1"), api_key="not-needed")
EMAIL = ("السلام عليكم، طلبت لابتوب Dell رقم الطلب 88213 يوم الأحد ووصلني اليوم والشاشة مكسورة، "
         "أريد استبداله وليس استرجاع المبلغ. محمد، جوال 0500000000")
schema = {
    "type": "object",
    "properties": {
        "order_id": {"type": "string"},
        "product": {"type": "string"},
        "problem": {"type": "string"},
        "wants": {"type": "string", "enum": ["refund", "replacement", "repair", "unknown"]},
        "urgent": {"type": "boolean"},
    },
    "required": ["order_id", "product", "problem", "wants", "urgent"],
    "additionalProperties": False,
}
msgs = [{"role": "system", "content": "استخرج بيانات الشكوى من رسالة العميل."},
        {"role": "user", "content": EMAIL}]

# 1) دون أي قيد على الشكل
r = client.chat.completions.create(model="qwen2.5:3b", messages=msgs, temperature=0)
print("free text:\n" + r.choices[0].message.content)

# 2) JSON mode: يضمن JSON صحيحاً، ولا يضمن الحقول
r = client.chat.completions.create(model="qwen2.5:3b", messages=msgs, temperature=0,
                                   response_format={"type": "json_object"})
print("json_object:", r.choices[0].message.content)

# 3) Structured Output: المخرج مقيد بالمخطط Schema نفسه
r = client.chat.completions.create(model="qwen2.5:3b", messages=msgs, temperature=0,
        response_format={"type": "json_schema", "json_schema": {"name": "complaint", "schema": schema, "strict": True}})
data = json.loads(r.choices[0].message.content)
print("json_schema:", json.dumps(data, ensure_ascii=False))
```

والمخرج سوف يكون كما يلي، بعد حذف أول سطور النص الحر:

```text
free text:
هذه هي بيانات الشكوى المExtracted من الرسالة:

الاسم: محمد  
رقم الطلب: 88213  
تاريخ الطلب: الأحد  
المشكلة: الشاشة مكسورة  
المطلوب: استبدال الجهاز وليس استرجاع المبلغ
json_object: {
  "الاسم": "محمد",
  "المنتج": "لابتوب Dell",
  "رقم الطلب": "88213",
  "التاريخ": "الأحد",
  "المشكلة": "الشاشة مكسورة",
  "الطلب": "استبدال لابتوب وليس استرجاع المبلغ"
}
json_schema: {"order_id": "88213", "product": "Laptop Dell", "problem": "شاشة مكسورة", "wants": "replacement", "urgent": false}
```

في المخرج أعلاه لاحظ التالي:

- النص الحر مفيد للقارئ وعديم الفائدة للبرنامج: عناوين بالعربية وترتيب يختاره النموذج، وقد يتغير في الطلب التالي.
- JSON Mode أعطى JSON صحيحاً يمكن تحليله، ولكن النموذج اختار أسماء الحقول بنفسه وبالعربية: «رقم الطلب» و«الطلب»، وأضاف «الاسم» و«التاريخ»، فالبرنامج الذي ينتظر `order_id` سوف يفشل. ولهذا يصفه توثيق OpenAI بأنه الطريقة الأقدم، ويشترط أن تطلب JSON صراحة في التعليمات.
- مع المخطط JSON Schema جاءت الحقول الخمسة بأسمائها وأنواعها بالضبط، و`wants` قيمة من القائمة المسموحة `replacement`، و`urgent` قيمة منطقية Boolean، والسبب أن السيرفر يقيد التوليد نفسه بالمخطط Constrained Decoding، فلا يسمح للنموذج أن يكتب توكناً يخرج عنه. ولاحظ أيضاً أن الحقل `additionalProperties: false` منع الاسم ورقم الجوال من الظهور، وهذا مفيد إذا كانت هذه البيانات لا يجب أن تحفظ في نظام التذاكر، كما شرحنا في مقال [ما لا ترسله لخدمة خارجية](https://arabroot.io/articles/%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D9%81%D9%8A-%D8%A7%D9%84%D8%B9%D9%85%D9%84-%D9%85%D8%A7-%D9%84%D8%A7-%D8%AA%D8%B1%D8%B3%D9%84%D9%87-%D8%A7%D9%84%D9%89-%D8%AE%D8%AF%D9%85%D8%A9-%D8%AE%D8%A7%D8%B1%D8%AC%D9%8A%D8%A9/).
- ولكن المخطط يضمن الشكل وليس الصحة: «urgent: false» حكم من النموذج قد تختلف معه، فالشاشة المكسورة عند بعض الشركات حالة عاجلة. لذلك تحقق في الكود من القيم المهمة، مثل أن رقم الطلب موجود فعلاً في قاعدة الطلبات، قبل أن تنفذ أي شيء.

![ثلاث نتائج لنفس الرسالة: نص حر، وJSON بحقول عربية اختارها النموذج، وJSON مطابق للمخطط](https://arabroot.io/content/images/2026/11/llm-api-basics-03-structured.webp)

كلما قيدت الشكل أكثر أصبح المخرج أصلح للبرنامج، والقيمة نفسها تحتاج تحققاً

## استدعاء الأدوات Tool Calls

الطريقة الثالثة لربط النموذج ببرنامجك أن تعطيه أدوات: تعرف له دالة باسمها ووصفها ومعاملاتها بمخطط JSON Schema، فإذا احتاجها في الإجابة لم يكتب نصاً، وإنما طلب منك تنفيذها، ثم تعيد له النتيجة فيكمل. وقد شرحنا الحلقة الكاملة لهذه الفكرة مع عدة أدوات في مقال [من RAG إلى Agents](https://arabroot.io/articles/rag-%D8%A7%D9%85-fine-tuning-%D8%A7%D9%85-mcp-%D8%A7%D9%85-agents/)، وسوف نفصل فيها أكثر في مقال الوكيل الذكي، أما هنا فنريد أن نرى شكل الرسائل في الواجهة بالضبط. هذا tools.py:

```python
import os, json
from openai import OpenAI

client = OpenAI(base_url=os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1"), api_key="not-needed")
ORDERS = {"88213": {"status": "shipped", "carrier": "SMSA", "eta": "2026-11-20"}}

def get_order_status(order_id: str) -> str:
    # في الواقع: استعلام لقاعدة الطلبات بصلاحية قراءة فقط
    return json.dumps(ORDERS.get(order_id, {"error": "order not found"}))

tools = [{
    "type": "function",
    "function": {
        "name": "get_order_status",
        "description": "Get the shipping status of a customer order by its numeric id.",
        "parameters": {
            "type": "object",
            "properties": {"order_id": {"type": "string", "description": "order number, digits only"}},
            "required": ["order_id"],
        },
    },
}]
messages = [{"role": "system", "content": "أنت مساعد خدمة العملاء لمتجر إلكتروني. أجب بالعربية."},
            {"role": "user", "content": "متى يصل طلبي رقم 88213؟"}]

r = client.chat.completions.create(model="qwen2.5:3b", messages=messages, tools=tools, temperature=0)
msg = r.choices[0].message
print("1) finish_reason:", r.choices[0].finish_reason)
print("   tool_calls:", json.dumps([c.model_dump() for c in msg.tool_calls or []], ensure_ascii=False))
messages.append(msg.model_dump(exclude_none=True))
for call in msg.tool_calls or []:
    args = json.loads(call.function.arguments)        # النص يأتي كسلسلة JSON ويجب تحليلها
    result = get_order_status(**args)
    print("2) our code ran", call.function.name, args, "->", result)
    messages.append({"role": "tool", "tool_call_id": call.id, "content": result})

r = client.chat.completions.create(model="qwen2.5:3b", messages=messages, tools=tools, temperature=0)
print("3) answer:", r.choices[0].message.content)
print("   usage:", r.usage.prompt_tokens, "in +", r.usage.completion_tokens, "out")
```

والمخرج سوف يكون كما يلي:

```text
1) finish_reason: tool_calls
   tool_calls: [{"id": "call_k9lx92nk", "function": {"arguments": "{\"order_id\":\"88213\"}", "name": "get_order_status"}, "type": "function", "index": 0}]
2) our code ran get_order_status {'order_id': '88213'} -> {"status": "shipped", "carrier": "SMSA", "eta": "2026-11-20"}
3) answer: تم الشحن لطلبك رقم 88213. وسيصل طلبك إلى وجهتك في 20 نوفمبر 2026 بواسطة شركة الشحن SMSA.
   usage: 254 in + 40 out
```

في المخرج أعلاه لاحظ التالي:

- سبب التوقف في الرد الأول `tool_calls`، والمحتوى فارغ، وفي `tool_calls` طلب واحد له رقم `id` واسم الدالة ومعاملاتها.
- المعاملات `arguments` تأتي نصاً فيه JSON وليس كائناً، لذلك حللناها بالدالة `json.loads`، وهذه نقطة تخطئ فيها مكتبات كثيرة كتبت لسيرفرات أخرى، فواجهة Ollama الأصلية مثلاً على المسار `/api/chat` تعيدها كائناً جاهزاً.
- أضفنا رد النموذج نفسه إلى الرسائل قبل نتيجة الأداة، ثم النتيجة برسالة دورها `tool` ومعها نفس `tool_call_id`، وبدون ذلك لا يعرف النموذج لماذا ظهرت هذه النتيجة. وفي [دليل Function Calling](https://developers.openai.com/api/docs/guides/function-calling?ref=arabroot.io) نفس الترتيب.
- الطلب الثاني كلف 254 توكناً في المدخلات مقابل 46 في أول طلب في المقال، والسبب أن تعريف الأداة نفسه يدخل في التعليمات مع كل طلب، ومعه رد النموذج ونتيجة الأداة، فكل أداة تضيفها لها ثمن في كل طلب ولو لم تستخدم.
- النموذج هو الذي قرر، وبرنامجنا هو الذي نفذ، فالتحقق من الصلاحية Authorization مكانه دالة `get_order_status` نفسها: هل هذا الطلب يخص هذا العميل؟ ولا تعتمد أبداً على أن النموذج لن يطلب رقم طلب عميل آخر.

## الأخطاء: ما يفشل وكيف يظهر

الكود الذي يعمل في التجربة يفشل في الإنتاج Production لأسباب لا تراها على جهازك: نموذج حذف من السيرفر، وسيرفر مشغول يتأخر، ونص من مستخدم أطول مما توقعت. ولنر الثلاثة بأعيننا، لأن شكل كل خطأ يحدد كيف تكتب معالجته Error Handling.

### اسم نموذج غير موجود

البرنامج errors.py فيه عدة حالات، والأولى تطلب نموذجاً غير موجود على السيرفر:

```python
import os, sys, time
import openai
from openai import OpenAI

BASE = os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1")
case = sys.argv[1]

if case == "model":            # اسم نموذج غير موجود
    try:
        OpenAI(base_url=BASE, api_key="x").chat.completions.create(
            model="qwen2.5:7b", messages=[{"role": "user", "content": "hi"}])
    except openai.APIStatusError as e:
        print(type(e).__name__, e.status_code, e.response.text)

if case in ("timeout", "timeout-noretry"):   # مهلة قصيرة على إجابة طويلة
    retries = 0 if case == "timeout-noretry" else 2   # 2 هي القيمة الافتراضية في المكتبة
    client = OpenAI(base_url=BASE, api_key="x", timeout=5, max_retries=retries)
    t = time.perf_counter()
    try:
        client.chat.completions.create(model="qwen2.5:3b",
            messages=[{"role": "user", "content": "اكتب مقالاً من 800 كلمة عن تاريخ الحاسوب."}])
    except openai.APITimeoutError as e:
        print(f"{type(e).__name__} after {time.perf_counter() - t:.1f} s (max_retries={retries})")
```

```bash
docker run --rm --network ad3-net -v "$PWD:/lab" ad3-api:1 python errors.py model
```

```text
NotFoundError 404 {"error":{"message":"model 'qwen2.5:7b' not found","type":"not_found_error","param":null,"code":null}}
```

الخطأ وصل برمز HTTP 404 وبنفس شكل أخطاء OpenAI: كائن `error` فيه رسالة ونوع، والمكتبة حولته إلى استثناء `NotFoundError`. وهذا الخطأ لا تعيد المحاولة فيه أبداً، لأن النتيجة لن تتغير، وإنما تسجله وتنبه، وغالباً سببه أن أحداً حدث السيرفر أو حذف النموذج. وهذه قاعدة عامة: رموز 400 و401 و403 و404 أخطاء في الطلب نفسه لا تفيد فيها إعادة المحاولة، أما 429 Too Many Requests و500 و503 فأخطاء مؤقتة تستحقها، كما في [صفحة رموز الأخطاء](https://developers.openai.com/api/docs/guides/error-codes?ref=arabroot.io) عند OpenAI و[صفحة الأخطاء](https://platform.claude.com/docs/en/api/errors?ref=arabroot.io) عند Anthropic.

### المهلة Timeout تتضاعف مع إعادة المحاولة Retries

المكتبة الرسمية تعيد المحاولة تلقائياً مرتين بحسب [ملف README](https://github.com/openai/openai-python?ref=arabroot.io) في مستودعها، عند أخطاء الاتصال وعند الرموز 408 و409 و429 و500 وما فوقها، ومن ضمنها انتهاء المهلة، والمهلة الافتراضية عشر دقائق. ولنر ماذا يعني ذلك عندما نضع مهلة 5 ثوان لطلب يحتاج أكثر منها بكثير:

```bash
docker run --rm --network ad3-net -v "$PWD:/lab" ad3-api:1 python errors.py timeout
docker run --rm --network ad3-net -v "$PWD:/lab" ad3-api:1 python errors.py timeout-noretry
```

```text
APITimeoutError after 17.0 s (max_retries=2)
APITimeoutError after 5.2 s (max_retries=0)
```

كتبنا مهلة 5 ثوان، فانتظر البرنامج 17 ثانية قبل أن يفشل: ثلاث محاولات كل منها 5 ثوان، وبينها فترات انتظار قصيرة تتزايد Exponential Backoff. فإذا كان عندك وعد للمستخدم بأن الصفحة تجيب خلال 10 ثوان، فالمهلة 5 مع المحاولات الافتراضية تكسر هذا الوعد دون أن تنتبه. وأسوأ من ذلك أن كل محاولة جديدة طلب جديد على السيرفر، فإذا كان السيرفر بطيئاً لأنه مشغول، فإعادة المحاولة تزيد الضغط عليه. والقاعدة: احسب الزمن الكلي بنفسك، وهو المهلة مضروبة في عدد المحاولات زائد الانتظار بينها، واجعل المهلة على مستوى الطلب كله في كودك وليس على مستوى المحاولة وحدها، واستخدم البث في الواجهات التفاعلية حتى يصل أول توكن قبل المهلة.

![ثلاث محاولات كل منها 5 ثوان مع انتظار بينها، والخطأ بعد 17 ثانية](https://arabroot.io/content/images/2026/11/llm-api-basics-04-retries.webp)

المهلة لكل محاولة وليست للطلب كله: 5 ثوان أصبحت 17 ثانية

### نص أطول من نافذة السياق: يقطع دون رسالة خطأ

هذا أخطر خطأ في هذا القسم، لأنه لا يظهر كخطأ. لكل نموذج نافذة سياق Context Window، ولكل سيرفر إعداد يحدد كم منها يحجز في الذاكرة. وفي Ollama يعتمد الطول الافتراضي على ذاكرة البطاقة الرسومية بحسب [صفحة طول السياق](https://docs.ollama.com/context-length?ref=arabroot.io): 4,096 توكناً إذا كانت أقل من 24 GiB، والأمر `ollama ps` يبين القيمة الحالية في العمود CONTEXT. والواجهة المتوافقة مع OpenAI لا تسمح بتغييرها، فالطريقة الموثقة أن تنشئ نموذجاً باسم جديد من ملف Modelfile. ولكي نصل إلى الحد بسرعة ننشئ نسخة بنافذة 512 توكناً فقط:

```bash
docker exec ad3-ollama sh -c 'printf "FROM qwen2.5:3b\nPARAMETER num_ctx 512\n" > /tmp/Modelfile.ctx && ollama create qwen2.5:3b-ctx512 -f /tmp/Modelfile.ctx'
```

والبرنامج overflow.py يبني مستنداً أول سطر فيه المعلومة المطلوبة، رمز غرفة السيرفرات 4417، وبعده سطور تشبه سجل عمليات، ثم يسأل عن الرمز:

```python
import os, sys
import openai
from openai import OpenAI

client = OpenAI(base_url=os.environ.get("BASE_URL", "http://ad3-ollama:11434/v1"), api_key="x", max_retries=0)
lines = int(sys.argv[1]) if len(sys.argv) > 1 else 400
# مستند طويل: أول سطر فيه المعلومة المطلوبة، وبعده سطور تشبه سجل عمليات
doc = "ملاحظة مهمة: رمز غرفة السيرفرات هو 4417.\n" + "\n".join(
    f"السطر {i}: تمت مزامنة النسخة الاحتياطية للخادم رقم {i % 7} بنجاح دون أخطاء." for i in range(1, lines + 1))
try:
    r = client.chat.completions.create(model=os.environ.get("MODEL", "qwen2.5:3b"), temperature=0, max_tokens=30,
        messages=[{"role": "user", "content": doc + "\n\nسؤال: ما رمز غرفة السيرفرات المذكور في أول المستند؟"}])
    print(f"lines={lines} chars={len(doc)} prompt_tokens={r.usage.prompt_tokens}")
    print("answer:", r.choices[0].message.content)
except openai.APIStatusError as e:
    print(f"lines={lines} chars={len(doc)}", type(e).__name__, e.status_code, e.response.text[:300])
```

```bash
docker run --rm --network ad3-net -e MODEL=qwen2.5:3b-ctx512 -v "$PWD:/lab" ad3-api:1 python overflow.py 15
docker run --rm --network ad3-net -e MODEL=qwen2.5:3b-ctx512 -v "$PWD:/lab" ad3-api:1 python overflow.py 40
```

والمخرج سوف يكون كما يلي:

```text
lines=15 chars=1066 prompt_tokens=258
answer: لم يتم ذكر رمز غرفة السيرفرات في السطر الأول من المستند. لكي أستطيع الإجابة على هذا
lines=40 chars=2791 prompt_tokens=258
answer: في المستند المقدم، لم يتم ذكر رمز غرفة السيرفرات في السطر الأول. السطر الأول يتحدث عن
```

المستندان مختلفان في الطول أكثر من الضعف، ومع ذلك فعدد توكنات المدخلات في الرد واحد: 258\. والسبب أن السيرفر قطع التعليمات بصمت حتى تدخل في النافذة، وحذف من أولها، فضاع السطر الذي فيه الرمز، فأجاب النموذج بثقة أن الرمز غير مذكور. ولا يوجد في الرد أي استثناء ولا تحذير، والرمز 200 والسبب `length` لم يظهر لأن المشكلة في المدخلات وليس في المخرجات. ولنعرف كم كان الطول الحقيقي، نستخدم سيرفر llama-server من llama.cpp على نفس ملف النموذج، لأن فيه نقطة `/tokenize` تعد التوكنات بنفس المقطع Tokenizer قبل أي توليد:

```bash
docker run -d --name ad3-llama --network ad3-net -p 127.0.0.1:9577:8080 -v ad3-ollama:/root/.ollama:ro \
  ad3-llamacpp:1.0.0 llama-server -m /root/.ollama/models/blobs/sha256-5ee4f07cdb9beadbbb293e85803c569b01bd37ed059d2715faa7bb405f31caa6 \
  -c 4096 -t 2 --jinja --host 0.0.0.0 --port 8080 --alias qwen2.5:3b
docker run --rm --network ad3-net -v "$PWD:/lab" ad3-api:1 python count_tokens.py
```

والملف الطويل في الأمر أعلاه هو ملف النموذج نفسه بصيغة GGUF كما حفظته Ollama في ال Volume، فلم ننزل أي شيء جديد، وال Image ad3-llamacpp بنيناه من الكود المصدري للإصدار 1.0.0\. والبرنامج count\_tokens.py:

```python
# عد التوكنات قبل الإرسال: نقطة /tokenize في llama-server تستخدم نفس مقطع النموذج Tokenizer
import json, sys, urllib.request
def tokens(text):
    req = urllib.request.Request("http://ad3-llama:8080/tokenize", json.dumps({"content": text}).encode(),
                                 {"Content-Type": "application/json"})
    return len(json.load(urllib.request.urlopen(req))["tokens"])
for lines in (15, 40):
    doc = "ملاحظة مهمة: رمز غرفة السيرفرات هو 4417.\n" + "\n".join(
        f"السطر {i}: تمت مزامنة النسخة الاحتياطية للخادم رقم {i % 7} بنجاح دون أخطاء." for i in range(1, lines + 1))
    q = doc + "\n\nسؤال: ما رمز غرفة السيرفرات المذكور في أول المستند؟"
    print(f"lines={lines} chars={len(q)} tokens={tokens(q)}")
for t in ["What is the difference between RAM and an SSD?", "ما الفرق بين الذاكرة العشوائية والقرص الصلب؟"]:
    print(f"qwen2.5 tokens={tokens(t):3}  {t}")
```

```text
lines=15 chars=1119 tokens=572
lines=40 chars=2844 tokens=1472
qwen2.5 tokens= 10  What is the difference between RAM and an SSD?
qwen2.5 tokens= 16  ما الفرق بين الذاكرة العشوائية والقرص الصلب؟
```

المستند الأقصر 572 توكناً وحده، والأطول 1,472، وكلاهما أكبر من النافذة 512، لذلك قطع السيرفر الاثنين إلى نفس الطول. والآن نفس الطلب الأقصر مرتين: مرة على النموذج الأصلي في Ollama بنافذته 4,096، ومرة على llama-server بعد أن أعدنا تشغيله بالخيار `-c 512` بدلاً من 4096، حتى نرى كيف يتصرف سيرفر آخر مع نفس المشكلة:

```bash
docker run --rm --network ad3-net -v "$PWD:/lab" ad3-api:1 python overflow.py 15
docker run --rm --network ad3-net -e BASE_URL=http://ad3-llama:8080/v1 -v "$PWD:/lab" ad3-api:1 python overflow.py 15
```

```text
lines=15 chars=1066 prompt_tokens=601
answer: رمز غرفة السيرفرات المذكور في أول المستند هو 4417.
lines=15 chars=1066 BadRequestError 400 {"error":{"code":400,"message":"request (601 tokens) exceeds the available context size (512 tokens), try increasing it","type":"exceed_context_size_error","n_prompt_tokens":601,"n_ctx":512}}
```

في المخرج أعلاه لاحظ التالي:

- مع النافذة الكافية جاء الرمز الصحيح 4417، أي أن النموذج نفسه قادر على الإجابة، والمشكلة كلها كانت في إعداد السيرفر.
- الطلب الكامل 601 توكناً في الحالتين، مقابل 572 في عد `/tokenize`، والفرق 29 توكناً هي علامات قالب المحادثة Chat Template التي يضيفها السيرفر حول الرسالة، فإذا حسبت الطول بنفسك فأضف هامشاً لها.
- llama-server رفض الطلب برمز 400 ورسالة واضحة فيها طول الطلب وطول النافذة، وهذا ما تريده في الإنتاج: خطأ تعالجه في الكود، بدلاً من إجابة خاطئة بثقة. فنفس المشكلة تظهر بشكلين مختلفين في سيرفرين متوافقين، وهذا مثال آخر على أن «متوافق» لا تعني «مطابق».

والقاعدة من هذه التجربة: احسب طول ما ترسله قبل الإرسال، وقارنه بالنافذة التي يحجزها السيرفر فعلاً وليس بالنافذة التي يدعمها النموذج نظرياً، فـ qwen2.5:3b يدعم 32 ألف توكن بحسب بطاقته، وOllama حجزت له 4,096 فقط. وإذا كان المستند أطول فقطعه بنفسك واختر الأجزاء المهمة كما يفعل [RAG](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D8%AD%D8%AB-%D9%81%D9%8A-%D9%85%D8%B3%D8%AA%D9%86%D8%AF%D8%A7%D8%AA%D9%83-%D9%85%D8%B9-rag-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/)، ولا تترك السيرفر يقرر ما يحذفه.

![مستند طوله 572 توكناً يدخل نافذة 512 فيحذف السيرفر أوله والسطر الذي فيه الرمز، والنموذج يجيب أن الرمز غير مذكور](https://arabroot.io/content/images/2026/11/llm-api-basics-05-overflow.webp)

القطع الصامت: الرد ناجح برمز 200، والإجابة خاطئة لأن المعلومة حذفت قبل أن يراها النموذج

## عد التوكنات Tokens قبل الإرسال

رأيت للتو لماذا تحتاج أن تعرف طول التعليمات قبل أن ترسلها: حتى لا يقطعها السيرفر بصمت، وحتى تعرف تكلفتها. والرقم في `usage` يصل بعد الطلب، أما قبله فعندك ثلاث طرق: نقطة عد التوكنات في السيرفر مثل `/tokenize` في llama-server كما فعلنا، أو مكتبة المقطع Tokenizer الخاصة بالنموذج، أو نقطة العد عند المزود السحابي، مثل [Token Counting](https://platform.claude.com/docs/en/build-with-claude/token-counting?ref=arabroot.io) في واجهة Anthropic. ولاحظ أن كل نموذج له مقطعه، فنفس النص له عدد مختلف عند كل مزود، وهذا ما تبينه مكتبة [tiktoken](https://github.com/openai/tiktoken?ref=arabroot.io) لنماذج OpenAI، في البرنامج tokens.py:

```python
import tiktoken
enc = tiktoken.get_encoding("o200k_base")     # الترميز الذي تستخدمه نماذج OpenAI الحديثة
texts = {
    "en": "What is the difference between RAM and an SSD?",
    "ar": "ما الفرق بين الذاكرة العشوائية والقرص الصلب؟",
    "ar+diacritics": "مَا الفَرْقُ بَيْنَ الذَّاكِرَةِ العَشْوَائِيَّةِ وَالقُرْصِ الصُّلْبِ؟",
}
for k, t in texts.items():
    ids = enc.encode(t)
    print(f"{k:14} chars={len(t):3} tokens={len(ids):3}  first pieces: {[enc.decode([i]) for i in ids[:6]]}")
```

```text
en             chars= 46 tokens= 10  first pieces: ['What', ' is', ' the', ' difference', ' between', ' RAM']
ar             chars= 44 tokens= 15  first pieces: ['ما', ' الفرق', ' بين', ' ال', 'ذا', 'كرة']
ar+diacritics  chars= 71 tokens= 44  first pieces: ['م', 'َا', ' الف', 'َر', 'ْ', 'ق']
```

في المخرج أعلاه لاحظ التالي:

- نفس السؤال بالعربية 15 توكناً في ترميز OpenAI مقابل 10 بالإنجليزية، و16 في مقطع Qwen كما رأيت في مخرج count\_tokens.py، أي أن العربية تكلف أكثر في الحالتين، والفرق يختلف بين النماذج، وقد قسنا هذا الفرق على نماذج أكثر في مقال [كيف تعمل نماذج اللغة](https://arabroot.io/articles/%D9%83%D9%8A%D9%81-%D8%AA%D8%B9%D9%85%D9%84-%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D8%A7%D9%84%D9%83%D8%A8%D9%8A%D8%B1%D8%A9-llm-%D8%AE%D8%B7%D9%88%D8%A9-%D8%A8%D8%AE%D8%B7%D9%88%D8%A9/#tokens).
- كلمة «الذاكرة» أصبحت ثلاثة توكنات «ال» و«ذا» و«كرة»، فالمقطع لم ير هذه الكلمة كثيراً بهذا الشكل في بيانات تدريبه.
- التشكيل ضاعف العدد ثلاث مرات تقريباً: 44 توكناً لنفس السؤال، لأن كل حركة أصبحت توكناً مستقلاً. فإذا كانت مستنداتك مشكولة، مثل النصوص الدينية أو التعليمية، فاحذف التشكيل قبل أن ترسلها إذا لم يكن مهماً للإجابة، فهذا وحده يخفض التكلفة إلى الثلث.

## كم يكلف الطلب الواحد؟

على سيرفرك لا تدفع لكل توكن، وإنما تدفع ثمن العتاد والكهرباء، أما المزودون السحابيون فيضربون عدد التوكنات في سعر لكل مليون توكن، وسعر المخرجات عادة أضعاف سعر المدخلات، والمقروء من الذاكرة المؤقتة Cache أرخص بكثير. وقد شرحنا أنواع الأسعار وطرق التخفيض بالتفصيل في مقال [تكلفة التوكنات](https://arabroot.io/articles/%D8%AA%D9%83%D9%84%D9%81%D8%A9-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%A8%D8%A7%D9%84%D8%AA%D9%88%D9%83%D9%86%D8%A7%D8%AA/)، أما هنا فنحسب طلباً واحداً بالكود. والأسعار التالية قرأناها يوم 18 نوفمبر 2026 من [صفحة أسعار Anthropic](https://platform.claude.com/docs/en/about-claude/pricing?ref=arabroot.io) و[صفحة أسعار OpenAI](https://developers.openai.com/api/docs/pricing?ref=arabroot.io)، بالدولار لكل مليون توكن، للطلبات القصيرة وبالسعر العادي، وهي تتغير، فارجع إلى الصفحتين قبل أي قرار:

| النموذج                             | المدخلات Input | المقروء من الذاكرة المؤقتة Cache Hit | المخرجات Output |
| ----------------------------------- | -------------- | ------------------------------------ | --------------- |
| Claude Haiku 5.5 (حتى 100 ألف توكن) | 0.10           | 0.01                                 | 0.50            |
| Claude Sonnet 5.5                   | 2              | 0.10                                 | 10              |
| Claude Opus 5.5                     | 4              | 0.20                                 | 20              |
| gpt-6-luna                          | 0.10           | 0.01                                 | 0.50            |
| gpt-6.2-sol                         | 2              | 0.10                                 | 10              |
| gpt-6.2-astra                       | 8              | 0.40                                 | 40              |

والبرنامج cost.py يحسب طلب دعم فني نموذجياً: تعليمات نظام 600 توكن، وتاريخ محادثة 900، وسؤال 60، وإجابة 250، ثم يضربه في 50 ألف طلب في الشهر، ثم يعيد الحساب إذا كانت التعليمات الثابتة الـ 600 مقروءة من الذاكرة المؤقتة:

```python
# حساب تكلفة الطلب من عدد التوكنات، بالأسعار المنشورة في صفحات المزودين يوم 18 نوفمبر 2026 (دولار لكل مليون توكن)
PRICES = {   # input, cached input, output
    "claude-haiku-5.5":  (0.10, 0.01, 0.50),
    "claude-sonnet-5.5": (2.00, 0.10, 10.00),
    "claude-opus-5.5":   (4.00, 0.20, 20.00),
    "gpt-6-luna":        (0.10, 0.01, 0.50),
    "gpt-6.2-sol":       (2.00, 0.10, 10.00),
    "gpt-6.2-astra":     (8.00, 0.40, 40.00),
}
def cost(model, prompt_tokens, completion_tokens, cached_tokens=0):
    inp, cached, out = PRICES[model]
    return ((prompt_tokens - cached_tokens) * inp + cached_tokens * cached + completion_tokens * out) / 1_000_000

# طلب دعم فني نموذجي: تعليمات نظام 600 توكن، وتاريخ محادثة 900، وسؤال 60، وإجابة 250
p, c = 600 + 900 + 60, 250
print(f"{'model':18} {'per request':>12} {'x 50,000/month':>15} {'cached 600':>12}")
for m in PRICES:
    one = cost(m, p, c)
    print(f"{m:18} ${one:>11.5f} ${one * 50_000:>13,.2f} ${cost(m, p, c, cached_tokens=600) * 50_000:>10,.2f}")
```

```text
model               per request  x 50,000/month   cached 600
claude-haiku-5.5   $    0.00028 $        14.05 $     11.35
claude-sonnet-5.5  $    0.00562 $       281.00 $    224.00
claude-opus-5.5    $    0.01124 $       562.00 $    448.00
gpt-6-luna         $    0.00028 $        14.05 $     11.35
gpt-6.2-sol        $    0.00562 $       281.00 $    224.00
gpt-6.2-astra      $    0.02248 $     1,124.00 $    896.00
```

![رسم أعمدة لتكلفة 50 ألف طلب في الشهر لستة نماذج من 14 إلى 1124 دولاراً](https://arabroot.io/content/images/2026/11/llm-api-basics-06-cost.webp)

نفس الطلب، والتكلفة الشهرية بحسب النموذج فقط

في المخرج أعلاه لاحظ التالي:

- الفرق بين أرخص نموذج وأغلاه في نفس الطلب 80 ضعفاً تقريباً: 14 دولاراً في الشهر مقابل 1,124 دولاراً، ولذلك فاختيار النموذج لكل ميزة Feature قرار مالي قبل أن يكون تقنياً، ومقال [تكلفة التوكنات](https://arabroot.io/articles/%D8%AA%D9%83%D9%84%D9%81%D8%A9-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%A8%D8%A7%D9%84%D8%AA%D9%88%D9%83%D9%86%D8%A7%D8%AA/#routing) يبين كيف ترسل الطلبات السهلة إلى النموذج الصغير.
- الإجابة 250 توكناً فقط من 1,810، ولكنها في Sonnet 0.25 سنت من 0.56 سنت، أي قرابة نصف تكلفة الطلب، لأن سعر المخرجات خمسة أضعاف المدخلات، فحد `max_tokens` وطلب إجابة مختصرة في التعليمات يخفضان التكلفة مباشرة.
- تاريخ المحادثة 900 توكن هو أكبر بند في المدخلات، وهو يكبر مع كل سؤال لأن الواجهة بلا حالة كما شرحنا، فالمحادثة الطويلة أغلى من عدة محادثات قصيرة.
- الذاكرة المؤقتة للتعليمات الثابتة وفرت 20% في هذا المثال، وتوفر أكثر كلما كبر الجزء الثابت، بشرط أن يكون في أول الطلب ولا يتغير حرف فيه بين الطلبات.
- والأعداد هنا لطلب واحد مفترض، أما على سيرفرك فالعدد الحقيقي في `usage` كما رأيت في كل تجربة، فاحفظه مع كل طلب في السجلات Logs، لأنه الرقم الذي سوف تحتاجه لتقارن بين التشغيل الذاتي والخدمة السحابية.

## قبل أن تضعه في الإنتاج Production

التجارب أعلاه تعمل على جهاز واحد ومستخدم واحد، أما في الإنتاج فهناك أربعة أمور يجب أن تقررها قبل أول مستخدم:

- طبقة واحدة أمام كل النماذج: لا تجعل كل خدمة في شركتك تتصل بالسيرفر أو بالمزود مباشرة، وإنما ضع بينها بوابة Gateway واحدة تحمل المفاتيح وحدود الطلبات Rate Limits وسجل الاستخدام لكل فريق، مثل LiteLLM التي ذكرناها في مقال [تكلفة التوكنات](https://arabroot.io/articles/%D8%AA%D9%83%D9%84%D9%81%D8%A9-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%A8%D8%A7%D9%84%D8%AA%D9%88%D9%83%D9%86%D8%A7%D8%AA/#budgets)، فإذا انتقلت من Ollama إلى vLLM أو إلى مزود سحابي غيرت مكاناً واحداً.
- المصادقة Authentication: Ollama وllama-server لا تطلبان مفتاحاً افتراضياً، فلا تنشر منفذهما على الشبكة، وضع أمامهما Reverse Proxy بمفتاح أو الشبكة الداخلية فقط.
- السجلات Logs: احفظ مع كل طلب اسم النموذج وعدد التوكنات وسبب التوقف والزمن، ولا تحفظ نص الطلب كاملاً إذا كان فيه بيانات شخصية، وقد شرحنا ما لا ترسله وما لا تحفظه في مقال [الذكاء الاصطناعي في العمل](https://arabroot.io/articles/%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D9%81%D9%8A-%D8%A7%D9%84%D8%B9%D9%85%D9%84-%D9%85%D8%A7-%D9%84%D8%A7-%D8%AA%D8%B1%D8%B3%D9%84%D9%87-%D8%A7%D9%84%D9%89-%D8%AE%D8%AF%D9%85%D8%A9-%D8%AE%D8%A7%D8%B1%D8%AC%D9%8A%D8%A9/).
- الاختبار Testing: النص لا يتطابق حرفاً بحرف بين تشغيلين كما رأيت حتى عند درجة الصفر، فاختبر الشكل والحقول وسبب التوقف في الاختبارات الآلية، وقس الجودة نفسها بمجموعة أسئلة ثابتة كما سوف نشرح في مقال التقييم Evals.

## أخطاء شائعة

- استخدام الإجابة دون فحص `finish_reason`: القيمة `length` تعني نصاً مقطوعاً برمز 200، و`tool_calls` تعني أن المحتوى فارغ وأن النموذج ينتظر نتيجة أداة.
- الثقة بأن السيرفر سوف يرفض النص الطويل: Ollama قطعت أول المستند بصمت وأجاب النموذج بثقة أن المعلومة غير موجودة، فاحسب الطول قبل الإرسال.
- ترك المهلة والمحاولات على الإعداد الافتراضي: عشر دقائق ومحاولتان، أي أن طلباً معلقاً قد يحجز عملية في برنامجك نصف ساعة، ومهلة 5 ثوان أصبحت 17 ثانية في التجربة.
- إعادة المحاولة عند كل خطأ: رموز 400 و401 و404 لن تتغير بالتكرار، وإعادة المحاولة عند 429 دون انتظار تزيد المشكلة.
- JSON Mode بدلاً من المخطط JSON Schema: الأول يضمن JSON صحيحاً فقط، والنموذج اختار أسماء حقول عربية لم نطلبها.
- تحليل `arguments` في استدعاء الأداة كأنها كائن: في الواجهة المتوافقة هي نص JSON يجب تحليله، وقد يكون JSON غير صحيح من نموذج صغير، فضع التحليل داخل try.
- كتابة المفتاح داخل الكود: ضعه في متغير بيئة أو مدير أسرار، فالمفتاح الذي يصل إلى Git قد وصل إلى كل من يستطيع قراءة المستودع.
- افتراض أن كل حقول OpenAI مدعومة: `n` و`tool_choice` و`logit_bias` غير مدعومة في Ollama، وكل سيرفر له صفحة توافق.
- حساب التكلفة بعدد الكلمات: العربية والتشكيل يكلفان توكنات أكثر من الإنجليزية لنفس المعنى، وكل نموذج له مقطع مختلف.
- عرض قطع البث على المستخدم وكأنها كلمات كاملة ثم تحليلها: القطعة توكن، وقد تكون نصف كلمة، فحلل النص بعد أن يكتمل.

## قائمة التحقق Checklist

- العنوان والمفتاح واسم النموذج في متغيرات البيئة، والكود لا يعرف أي سيرفر يكلم.
- درجة الحرارة محددة صراحة لكل استخدام، وليست الافتراضية 1.
- `max_tokens` محدد، والكود يفحص `finish_reason` قبل أن يستخدم الإجابة.
- المهلة محسوبة مع المحاولات، والمحاولات للأخطاء المؤقتة فقط.
- البث مفعل في كل واجهة يراها مستخدم، و`proxy_buffering off` في Nginx إذا كان أمام السيرفر.
- المخرج الذي يقرؤه برنامج مقيد بمخطط JSON Schema، والقيم المهمة يتحقق منها الكود.
- طول التعليمات يحسب قبل الإرسال ويقارن بنافذة السيرفر الفعلية.
- عدد التوكنات من `usage` يحفظ مع كل طلب في السجلات، ومعه اسم النموذج والميزة.
- السيرفر المحلي ليس منشوراً على الشبكة دون مصادقة.

## حذف التجربة

```bash
docker rm -f ad3-ollama ad3-llama
docker volume rm ad3-ollama
docker network rm ad3-net
docker rmi ad3-api:1
```

## تدريب عملي

- غير `BASE_URL` في hello.py إلى `http://ad3-llama:8080/v1`، وقارن الرد وحقول `usage` بين Ollama وllama-server لنفس الطلب.
- اكتب دالة `safe_chat` تفحص `finish_reason`، وتعيد المحاولة مرة واحدة فقط عند 429 و503 مع انتظار، وترفض أي طلب أطول من النافذة قبل إرساله.
- أضف إلى structured.py حقلاً `category` بقيم محددة مثل shipping وdamage وbilling، وجرب رسائل عملاء مختلفة، وعد كم مرة كانت القيمة صحيحة.

## الخلاصة

وصلنا لنهاية الموضوع، وأهم ما فيه:

- الواجهة المتوافقة مع OpenAI معيار فرضه الاستخدام: طلب POST إلى `/v1/chat/completions` فيه النموذج والرسائل، وتقبله Ollama وllama.cpp وvLLM والمزودون السحابيون، والكود نفسه ينتقل بينها بتغيير العنوان والمفتاح.
- الواجهة بلا حالة، فبرنامجك يرسل المحادثة كاملة في كل طلب، وكل سؤال أغلى من الذي قبله.
- درجة الصفر تقلل التنوع ولا تضمن التطابق، و`max_tokens` يقطع الإجابة برمز 200 و`finish_reason: length`.
- البث يصل بصيغة SSE قطعة لكل توكن، والقطعة الأخيرة فيها العدد، وزمن أول توكن كان 12.4 ثانية مقابل 171 ثانية للإجابة كاملة في التجربة.
- المخطط JSON Schema يضمن الحقول والأنواع، والتحقق من القيم يبقى في الكود، والأدوات يطلبها النموذج وينفذها برنامجك.
- أخطر خطأ لا يظهر كخطأ: نص أطول من النافذة قطعته Ollama بصمت، بينما رفضه llama-server برمز 400، والمحاولات الافتراضية حولت مهلة 5 ثوان إلى 17 ثانية.
- نفس الطلب يكلف بين 14 و1,124 دولاراً في الشهر بحسب النموذج، والعربية والتشكيل يزيدان عدد التوكنات.

والخطوة التالية في نفس المرحلة أن تعطي النموذج عدة أدوات وتتركه يقرر خطواته، وهذا موضوع مقال الوكيل الذكي AI Agent، وفيه نبني الحلقة بأيدينا على نفس هذه الواجهة.

[![](https://arabroot.io/content/images/2026/11/ai-agents-basics-cover-cover.webp)دليلالوكيل الذكي AI Agent: استدعاء الأدوات Tool Calling والحلقةكيف يعمل الوكيل الذكي من الداخل: حلقة صغيرة تكتبها بيدك بثلاث أدوات، والأعطال الحقيقية التي تقع فيها، والحراسات التي تمنع ضررها في الكود.](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%88-%D8%A7%D9%84%D9%88%D9%83%D9%8A%D9%84-%D8%A7%D9%84%D8%B0%D9%83%D9%8A-ai-agent-%D8%A7%D9%84%D8%A7%D8%AF%D9%88%D8%A7%D8%AA-%D9%88%D8%A7%D9%84%D8%AD%D9%84%D9%82%D8%A9-%D9%88%D8%A7%D9%84%D8%B0%D8%A7%D9%83%D8%B1%D8%A9/)[![](https://arabroot.io/content/images/2026/11/ai-token-costs-cover-cover.webp)دليلتكلفة التوكنات Tokens في تطبيقات AI: كيف تقيسها وتخفضهاكيف تحسب تكلفة كل ميزة تستخدم نموذج لغة LLM، وتخفضها بالذاكرة المؤقتة Prompt Caching والتوجيه بين النماذج دون أن تخسر الجودة.](https://arabroot.io/articles/%D8%AA%D9%83%D9%84%D9%81%D8%A9-%D8%A7%D9%84%D8%B0%D9%83%D8%A7%D8%A1-%D8%A7%D9%84%D8%A7%D8%B5%D8%B7%D9%86%D8%A7%D8%B9%D9%8A-%D8%A8%D8%A7%D9%84%D8%AA%D9%88%D9%83%D9%86%D8%A7%D8%AA/)[![](https://arabroot.io/content/images/2026/10/rag-cover-cover.webp)دليلRAG للمبتدئين: نموذج لغة يجيب من مستنداتك على سيرفرككيف تجعل نموذج اللغة يجيب من مستندات مؤسستك ويذكر مصدره، دون أن يخرج أي مستند من سيرفرك.](https://arabroot.io/articles/%D8%A7%D9%84%D8%A8%D8%AD%D8%AB-%D9%81%D9%8A-%D9%85%D8%B3%D8%AA%D9%86%D8%AF%D8%A7%D8%AA%D9%83-%D9%85%D8%B9-rag-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/)[![](https://arabroot.io/content/images/2026/10/local-llm-hardware-cover-cover.webp)دليلتشغيل نماذج اللغة على جهازك: كم ذاكرة وأي GPU تحتاج؟كيف تحسب الذاكرة التي يحتاجها النموذج، وماذا تتوقع من جهازك الحالي قبل أن تشتري بطاقة رسومية GPU.](https://arabroot.io/articles/%D8%AA%D8%B4%D8%BA%D9%8A%D9%84-%D9%86%D9%85%D8%A7%D8%B0%D8%AC-%D8%A7%D9%84%D9%84%D8%BA%D8%A9-%D8%B9%D9%84%D9%89-%D8%AC%D9%87%D8%A7%D8%B2%D9%83-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/)

## سجل التحديثات

- 18 نوفمبر 2026: كتابة المقال، واختبار التجربة على Docker Engine 29.8.0 (معالج فقط) مع Ollama 0.40.13 والنموذج qwen2.5:3b (Q4\_K\_M)، وllama.cpp 1.0.0 (llama-server)، وPython 3.13.18 مع openai 3.55.1 وtiktoken 0.14.0، والأسعار من صفحات Anthropic وOpenAI يوم 18 نوفمبر 2026.