DEV Community

Cover image for كيفية استخدام نماذج لغوية محلية كواجهات برمجة تطبيقات؟
Yusuf Khalidd
Yusuf Khalidd

Posted on • Originally published at apidog.com

كيفية استخدام نماذج لغوية محلية كواجهات برمجة تطبيقات؟

يمكنك تشغيل نموذج LLM محليًا خلف نفس واجهة OpenAI التي تستخدمها في الإنتاج. غيّر base_url فقط، وسيستمر كود العميل نفسه في العمل. هذا يتيح لك التطوير دون اتصال، تقليل تكلفة الرموز أثناء الاختبار، وحماية البيانات الحساسة قبل إرسال أي شيء إلى نموذج مستضاف. في هذا الدليل ستشغّل Ollama أو vLLM أو llama.cpp، تكشف نقطة نهاية متوافقة مع OpenAI، تختبرها من الكود، ثم تدير نفس السيناريوهات عبر Apidog قبل ترحيلها إلى الإنتاج.

جرّب Apidog اليوم

خلاصة القول (TL;DR)

يمكنك تشغيل LLM API محليًا باستخدام Ollama أو vLLM أو llama.cpp. كل خيار منها يوفّر نقطة نهاية REST متوافقة مع OpenAI.

بدلًا من استدعاء:

https://api.openai.com/v1
Enter fullscreen mode Exit fullscreen mode

استخدم محليًا:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

ثم اترك باقي كود OpenAI SDK كما هو. استخدم Apidog لإدارة بيئتين:

  • Local تشير إلى النموذج المحلي.
  • Production تشير إلى نموذج مستضاف.

بهذا تستطيع تشغيل نفس اختبارات API على البيئتين دون تغيير الكود.

مقدمة

أصبحت حزمة LLM API المحلية جزءًا عمليًا من سير عمل مطوري APIs. السبب الأهم ليس فقط أن النماذج أصبحت أسرع، بل أن معظم بيئات التشغيل أصبحت تتحدث نفس شكل OpenAI:

/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

هذا يعني أنك لم تعد بحاجة إلى عميلين مختلفين أو طبقة تكامل منفصلة. نفس OpenAI SDK يمكنه الاتصال بـ localhost أو بـ api.openai.com بناءً على متغير بيئة واحد.

إذا كنت تستخدم Apidog لاختبار طلباتك، يمكنك نقل الطلب من:

https://api.openai.com/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

إلى:

{{BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode

ثم تغيير BASE_URL حسب البيئة. وإذا كنت تتابع بالفعل تكلفة API لكل ميزة، يمكنك مقارنة نموذج محلي مع نموذج مستضاف بنفس السيناريوهات.

يغطي هذا الدليل:

  • اختيار بيئة التشغيل المناسبة.
  • تشغيل نقطة نهاية OpenAI-compatible محليًا.
  • ربطها بـ Python وJavaScript.
  • اختبارها في Apidog.
  • التعامل مع التكميم، الذاكرة، والبث.
  • مقارنة التكلفة وزمن الوصول.

للاطلاع على خيارات أوسع للنماذج، راجع أفضل النماذج اللغوية الكبيرة المحلية لعام 2026.

لماذا تشغيل LLM محليًا مفيد لمطوري APIs؟

تشغيل LLM محليًا مفيد عندما تحتاج إلى:

  • التطوير دون اتصال.
  • اختبار أوامر تحتوي بيانات حساسة.
  • تقليل تكلفة الرموز أثناء التطوير.
  • تثبيت نسخة نموذج لا تتغير من خلفك.
  • تشغيل اختبارات CI ضد نقطة نهاية تتحكم بها.

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

هناك أيضًا عامل التكلفة. إذا كان فريقك يرسل ملايين الرموز يوميًا أثناء التطوير، فالتشغيل المحلي قد يخفض تكلفة التجارب بشكل كبير. يمكنك قراءة تفصيل مشابه في كيفية استخدام GPT-5.5 Instant وتطبيق الحسابات على حملك الفعلي.

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

ثلاث بيئات تشغيل توفر نقاط نهاية متوافقة مع OpenAI

اختر بيئة التشغيل حسب الحالة، وليس حسب الشعبية:

البيئة الأنسب لـ المنفذ الافتراضي ملاحظات
Ollama التطوير المحلي السريع 11434 أسهل خيار للبدء
vLLM الإنتاج أو خوادم التطوير المشتركة 8000 إنتاجية عالية مع batching
llama.cpp التحكم الدقيق والتشغيل على أجهزة محدودة قابل للتكوين ممتاز مع GGUF والتكميم

1. تشغيل Ollama محليًا

Ollama هو أبسط خيار لتشغيل نموذج محلي خلف OpenAI-compatible API. يقوم بتنزيل النموذج، إدارة التكميم، وتشغيل خادم HTTP محلي.

Ollama UI screenshot

التثبيت على macOS 

brew install ollama
ollama serve &
ollama pull llama3.3:70b-instruct-q4_K_M
ollama run llama3.3:70b-instruct-q4_K_M
Enter fullscreen mode Exit fullscreen mode

بعد تشغيل ollama serve، تصبح نقطة النهاية:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

يمكنك اختبارها عبر OpenAI Python SDK:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama",
)

resp = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_K_M",
    messages=[
        {"role": "user", "content": "Reply with the word OK only."}
    ],
)

print(resp.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

إذا ظهرت:

OK
Enter fullscreen mode Exit fullscreen mode

فالنموذج والخادم والعميل يعملون بشكل صحيح.

استخدم Ollama عندما تحتاج إلى:

  • تجربة محلية سريعة.
  • بيئة تطوير لمستخدم واحد.
  • تشغيل smoke tests محلية.
  • عروض توضيحية دون إعداد بنية تحتية.

2. تشغيل vLLM لخادم مشترك أو إنتاجي

vLLM مناسب عندما تحتاج إلى throughput أعلى، خصوصًا مع طلبات متزامنة. يستخدم PagedAttention وcontinuous batching لزيادة الإنتاجية مقارنة بالتنفيذ التقليدي.

vLLM architecture diagram

تشغيل vLLM 

pip install vllm

vllm serve meta-llama/Llama-3.3-70B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192
Enter fullscreen mode Exit fullscreen mode

تصبح نقطة النهاية:

http://localhost:8000/v1
Enter fullscreen mode Exit fullscreen mode

مثال اتصال:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="local-key",
)

response = client.chat.completions.create(
    model="meta-llama/Llama-3.3-70B-Instruct",
    messages=[
        {"role": "user", "content": "Give me a short API testing checklist."}
    ],
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

استخدم vLLM عندما تحتاج إلى:

  • GPU server مشترك.
  • طلبات متزامنة.
  • throughput أعلى.
  • بيئة staging داخل شبكة خاصة.

ملاحظة: vLLM يتطلب عادة GPU يدعم CUDA أو ROCm، ولا يناسب Apple Silicon بنفس سهولة Ollama.

3. تشغيل llama.cpp

llama.cpp هو خيار مرن جدًا، خصوصًا مع نماذج GGUF والتكميم. يعمل على أجهزة كثيرة، من أجهزة ضعيفة إلى خوادم GPU قوية.

llama.cpp terminal screenshot

البناء والتشغيل 

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp && make -j LLAMA_METAL=1

./llama-server -m models/llama-3.3-70b-q4_k_m.gguf \
  --port 8080 \
  --host 0.0.0.0 \
  -c 8192 \
  -ngl 99
Enter fullscreen mode Exit fullscreen mode

نقطة النهاية:

http://localhost:8080/v1/chat/completions
Enter fullscreen mode Exit fullscreen mode

الخيار -ngl 99 يحاول تحميل أكبر عدد ممكن من الطبقات على GPU. إذا لم تكفِ الذاكرة، قلل الرقم.

استخدم llama.cpp عندما تحتاج إلى:

  • تحكم أكبر في التكميم.
  • تشغيل نموذج على ذاكرة محدودة.
  • اختبار أجهزة غير تقليدية.
  • استخدام ملفات GGUF مباشرة.

أدوات مثل LM Studio وJan تغلف llama.cpp بواجهة رسومية وتوفر أيضًا OpenAI-compatible endpoint، وهي مفيدة لأعضاء الفريق غير المرتاحين للطرفية.

اختبار النموذج المحلي باستخدام curl

قبل ربط النموذج بالكود أو Apidog، اختبر نقطة النهاية مباشرة.

Ollama 

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{
    "model": "llama3.3:70b-instruct-q4_K_M",
    "messages": [
      { "role": "user", "content": "Return OK only." }
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

الاستجابة يجب أن تحتوي شكلًا قريبًا من:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "OK"
      }
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

إذا كان هذا الشكل صحيحًا، فغالبًا سيعمل OpenAI SDK وApidog دون تغييرات كبيرة.

اختبر نموذجك المحلي باستخدام Apidog

Apidog UI showing environment variables and request details

الفكرة العملية: لا تكتب طلبين منفصلين للمحلي والمستضاف. اكتب طلبًا واحدًا باستخدام متغيرات بيئة.

1. أنشئ بيئة Local

في مشروع Apidog:

  • أنشئ بيئة باسم Local.
  • أضف المتغيرات التالية: 
BASE_URL = http://localhost:11434/v1
API_KEY = ollama
MODEL = llama3.3:70b-instruct-q4_K_M
Enter fullscreen mode Exit fullscreen mode

2. أنشئ بيئة Production

استنسخ البيئة أو أنشئ واحدة جديدة:

BASE_URL = https://api.openai.com/v1
API_KEY = <your-hosted-provider-key>
MODEL = <your-production-model>
Enter fullscreen mode Exit fullscreen mode

3. اجعل الطلب يستخدم المتغيرات

استخدم هذا المسار:

{{BASE_URL}}/chat/completions
Enter fullscreen mode Exit fullscreen mode

وأضف الرؤوس:

Content-Type: application/json
Authorization: Bearer {{API_KEY}}
Enter fullscreen mode Exit fullscreen mode

وجسم الطلب:

{
  "model": "{{MODEL}}",
  "messages": [
    {
      "role": "system",
      "content": "You are a concise API assistant."
    },
    {
      "role": "user",
      "content": "Return a JSON object with status ok."
    }
  ],
  "response_format": {
    "type": "json_object"
  }
}
Enter fullscreen mode Exit fullscreen mode

4. أضف assertions

في سيناريو Apidog، تحقق من:

choices[0].message.role == "assistant"
choices[0].message.content is not empty
usage.total_tokens > 0
Enter fullscreen mode Exit fullscreen mode

إذا لم تكن بعض runtimes ترجع usage بنفس الشكل، اجعل هذا الفحص اختياريًا أو افحصه فقط في البيئة التي تدعمه.

5. شغّل نفس السيناريو على البيئتين

نفّذ السيناريو ضد:

  1. Local
  2. Production

إذا نجح السيناريو في البيئتين، فقد عزلت الاختلاف في الإعدادات بدلًا من الكود.

يمكنك استخدام نفس النمط في اختبار وكلاء الذكاء الاصطناعي الذين يستدعون واجهات برمجة تطبيقات متعددة الخطوات.

تبديل OpenAI SDK بين المحلي والمستضاف

Python 

import os
from openai import OpenAI

def get_client() -> OpenAI:
    if os.getenv("ENV") == "local":
        return OpenAI(
            base_url=os.getenv("LOCAL_BASE_URL", "http://localhost:11434/v1"),
            api_key=os.getenv("LOCAL_API_KEY", "ollama"),
        )

    return OpenAI(
        base_url=os.getenv("OPENAI_BASE_URL", "https://api.openai.com/v1"),
        api_key=os.environ["OPENAI_API_KEY"],
    )

client = get_client()

response = client.chat.completions.create(
    model=os.getenv("MODEL", "llama3.3:70b-instruct-q4_K_M"),
    messages=[
        {"role": "system", "content": "You are a JSON-only assistant."},
        {"role": "user", "content": "Return {\"status\": \"ok\"}."},
    ],
    response_format={"type": "json_object"},
)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

تشغيل محلي:

ENV=local python app.py
Enter fullscreen mode Exit fullscreen mode

تشغيل مستضاف:

ENV=production OPENAI_API_KEY=sk-... MODEL=gpt-... python app.py
Enter fullscreen mode Exit fullscreen mode

JavaScript 

import OpenAI from "openai";

const isLocal = process.env.ENV === "local";

const client = new OpenAI({
  baseURL: isLocal
    ? process.env.LOCAL_BASE_URL || "http://localhost:11434/v1"
    : process.env.OPENAI_BASE_URL || "https://api.openai.com/v1",
  apiKey: isLocal
    ? process.env.LOCAL_API_KEY || "ollama"
    : process.env.OPENAI_API_KEY,
});

const resp = await client.chat.completions.create({
  model: process.env.MODEL || "llama3.3:70b-instruct-q4_K_M",
  messages: [
    { role: "user", content: "Say hi." }
  ],
});

console.log(resp.choices[0].message.content);
Enter fullscreen mode Exit fullscreen mode

تشغيل محلي:

ENV=local node app.js
Enter fullscreen mode Exit fullscreen mode

تشغيل مستضاف:

ENV=production OPENAI_API_KEY=sk-... MODEL=gpt-... node app.js
Enter fullscreen mode Exit fullscreen mode

دمج الاختبارات في CI

بعد أن يصبح طلب Apidog معتمدًا على المتغيرات، يمكنك استخدامه كـ smoke test في CI.

الفكرة:

  1. شغّل runtime محليًا داخل job أو على runner داخلي.
  2. انتظر حتى تصبح نقطة النهاية جاهزة.
  3. شغّل سيناريو Apidog.
  4. أفشل build إذا فشل assertion.

مثال مبسط لفكرة GitHub Actions:

name: local-llm-api-test

on:
  pull_request:

jobs:
  test-local-llm:
    runs-on: self-hosted

    steps:
      - uses: actions/checkout@v4

      - name: Start Ollama
        run: |
          ollama serve &
          sleep 5
          ollama pull llama3.3:70b-instruct-q4_K_M

      - name: Run API scenario
        run: |
          apidog run ./apidog-project.json --env Local
Enter fullscreen mode Exit fullscreen mode

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

تقنيات مهمة عند تشغيل LLM محليًا

1. اختر التكميم المناسب

التكميم يحدد هل سيتسع النموذج في الذاكرة أم لا.

قاعدة عملية:

التكميم متى تستخدمه؟
Q8 جودة أعلى، ذاكرة أكبر
Q5_K_M توازن جيد إذا لديك RAM كافية
Q4_K_M الخيار العملي لمعظم الاستخدامات
Q2_K عندما تكون الذاكرة ضيقة جدًا، مع تنازل واضح في الجودة

لنموذج 70B، غالبًا ستبدأ بـ Q4_K_M لأنه يقلل الحجم كثيرًا مع جودة مقبولة للدردشة والاختبار.

2. راقب GPU offload

في llama.cpp، الخيار المهم هو:

-ngl 99
Enter fullscreen mode Exit fullscreen mode

وفي Ollama يمكن التحكم في إعدادات مشابهة عبر خيارات النموذج.

كلما زادت الطبقات المحملة على GPU، زادت السرعة. إذا لم تكفِ VRAM، سيعود جزء من النموذج إلى CPU وتنخفض الإنتاجية.

3. استخدم streaming

البث يقلل زمن الانتظار المدرك لأن العميل يبدأ باستقبال الرموز قبل اكتمال الإجابة.

Python:

stream = client.chat.completions.create(
    model="llama3.3:70b-instruct-q4_K_M",
    messages=[{"role": "user", "content": "Explain API rate limiting briefly."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="")
Enter fullscreen mode Exit fullscreen mode

4. ثبّت system prompt داخل Modelfile في Ollama

بدل تكرار system prompt في كل طلب، يمكنك إنشاء نموذج مخصص:

FROM llama3.3:70b-instruct-q4_K_M

SYSTEM """
You are a concise API testing assistant.
Return practical, implementation-focused answers.
"""

PARAMETER temperature 0.2
Enter fullscreen mode Exit fullscreen mode

ثم:

ollama create api-assistant -f Modelfile
Enter fullscreen mode Exit fullscreen mode

واستخدمه في الطلب:

{
  "model": "api-assistant",
  "messages": [
    {
      "role": "user",
      "content": "Create a smoke test checklist for a REST API."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

أخطاء شائعة

تجنب هذه الأخطاء عند نقل كودك بين المحلي والمستضاف:

  • لا تضع http://localhost:11434 مباشرة داخل كود الإنتاج. استخدم متغير بيئة.
  • لا تفترض أن كل runtime يرجع usage بنفس الشكل.
  • لا تنسَ Authorization header. قد يتجاهله Ollama، لكن vLLM قد يرفض الطلب بدونه عند تفعيل --api-key.
  • لا تشغّل خادمين على نفس المنفذ.
  • لا تتوقع من نموذج Q4 أن يطابق جودة نموذج مستضاف كبير في كل المهام.
  • لا تترك max_tokens مفتوحًا في الاختبارات؛ عيّن حدًا واضحًا.
  • لا تعتمد على مخرجات نصية غير مستقرة في assertions. افحص الشكل والبنية أولًا.

مقارنة المحلي مقابل المستضاف: التكلفة وزمن الوصول

تفترض الأرقام أدناه جهاز M3 Max بذاكرة موحدة 128 جيجابايت للتشغيل المحلي، وأسعارًا عامة لنقاط نهاية مستضافة. زمن الوصول للرمز الأول TTFT مقاس على prompt مكون من 1024 رمزًا بدون batching.

النموذج TTFT المحلي الإنتاجية المحلية المكافئ المستضاف سعر المستضاف TTFT المستضاف
Llama 3.3 70B Q4_K_M 1.2 ثانية 12 رمز/ثانية GPT-5.5 Instant 5 دولارات / 30 دولارًا لكل مليون 200 مللي ثانية
DeepSeek V4 67B Q4_K_M 1.4 ثانية 10 رموز/ثانية DeepSeek-Chat مستضاف 0.55 دولار / 2.20 دولار لكل مليون 280 مللي ثانية
Qwen 3.6 32B Q5_K_M 0.7 ثانية 28 رمز/ثانية Qwen-Max مستضاف 1.60 دولار / 6.40 دولار لكل مليون 240 مللي ثانية
Gemma 4 27B Q4_K_M 0.5 ثانية 35 رمز/ثانية Gemini 3 Flash 0.35 دولار / 1.05 دولار لكل مليون 180 مللي ثانية

الخلاصة العملية:

  • استخدم المحلي أثناء التطوير الداخلي.
  • استخدم المستضاف عندما تحتاج إلى زمن وصول منخفض لمستخدمين نهائيين.
  • استخدم المحلي عندما تمنعك متطلبات الخصوصية من إرسال البيانات للخارج.
  • شغّل نفس اختبارات Apidog على الاثنين لتقليل اختلافات التكامل.

للمزيد حول نماذج محددة، راجع كيفية تشغيل DeepSeek V4 محليًا ودليل DeepSeek V4.

حالات استخدام واقعية

1. فريق امتثال مالي

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

اختبار Apidog يتحقق من أن التنقيح يعمل قبل أي استدعاء خارجي.

2. استوديو ألعاب

استوديو ألعاب يستخدم Qwen محليًا لتدريب فريق التصميم على prompt engineering. لا توجد تكلفة رموز أثناء التدريب، ولا خطر تسريب تفاصيل القصة. في الإنتاج، يستخدمون Gemini 3 Flash بتغيير BASE_URL وMODEL.

يمكن إعادة استخدام نمط التكامل من دليل Gemini 3 Flash API.

3. شركة رعاية صحية

شركة رعاية صحية تشغّل vLLM داخل شبكة مستشفى العميل. لا توجد نقطة نهاية عامة، وتعمل اختبارات التكامل من Jenkins داخل نفس الشبكة. نفس OpenAI SDK، لكن بثلاث بيئات:

  • local
  • staging داخلي
  • production

الخاتمة

تشغيل LLM API محليًا أصبح عمليًا لأن سطح API استقر حول شكل OpenAI. لبدء تطبيق ذلك في مشروعك:

  1. استخدم Ollama للتطوير المحلي السريع، vLLM للخوادم المشتركة، وllama.cpp عندما تحتاج تحكمًا أعمق في الذاكرة والتكميم.
  2. اكشف نقطة نهاية متوافقة مع OpenAI.
  3. اختبرها بـ curl قبل ربطها بالكود.
  4. انقل base_url وapi_key إلى متغيرات بيئة.
  5. أنشئ طلبًا واحدًا في Apidog يعمل ضد Local وProduction.
  6. أضف assertions تركز على شكل الاستجابة بدل النص الحرفي.
  7. شغّل السيناريوهات في CI لاكتشاف أي اختلاف مبكرًا.

ابدأ ببيئة واحدة تشير إلى:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

ثم شغّل نفس السيناريو ضد النموذج المستضاف. إذا لم تكن قد اخترت النموذج بعد، راجع أفضل النماذج اللغوية الكبيرة المحلية لعام 2026. وإذا كنت تختبر تدفقات agentic متعددة الخطوات، اقرأ كيفية اختبار واجهة برمجة تطبيقات وكلاء الذكاء الاصطناعي.

Top comments (0)