كيفية استخدام استدعاء الدوال مع DeepSeek V4 Pro API

أخرجت DeepSeek الإصدار V4 Pro من مرحلة المعاينة في 12 أغسطس 2026، وتتصدر تغطية الإطلاق سير العمل التفاعلي (agentic workflows): البرمجة، استخدام الأدوات، والمهام طويلة المدى التي تربط عشرات الخطوات دون فقدان السياق. لذلك، فإن استدعاء الدوال (function calling) هو الميزة الأساسية لبناء وكلاء عمليين، وليس مجرد إكمال دردشة.

جرّب Apidog اليوم

في هذا الدليل ستعرّف مخطط أداة، وتجري أول استدعاء باستخدام حزمة openai القياسية في بايثون، ثم تبني حلقة وكيل كاملة وتختبرها في Apidog. إن لم يكن لديك مفتاح DeepSeek API، أعدّه أولًا عبر دليل كيفية استخدام DeepSeek V4 API.

TL;DR

• يدعم deepseek-v4-pro، إصدار GA ‏DeepSeek-V4-Pro-0813، استدعاء الدوال بأسلوب OpenAI: أرسل tools، واستقبل tool_calls، ثم أعد النتائج برسائل tool.
• يمكنك بناء حلقة وكيل كاملة في نحو 30 سطرًا من بايثون: استدعِ النموذج، نفّذ الأدوات، أضف النتائج، وكرّر حتى ينتج إجابة نهائية.
• يدعم النموذج الاستدعاءات المتوازية والمخرجات المنظمة. ويضيف وضع التفكير الحقل reasoning_content.
• يحدد التخزين المؤقت التلقائي للمقدمة سعر إدخال cache-hit عند 0.003625 دولار لكل مليون توكن، مقابل 0.435 دولار لإدخال cache-miss.
• اختبر النموذج باستخدام مخططات أدواتك الفعلية وسيناريوهاتك الحقيقية، لا بالمعايير العامة فقط.

لماذا يُعد استدعاء الأدوات حالة الاستخدام الرئيسية لـ V4 Pro؟

صممت DeepSeek الإصدار V4 Pro للوكلاء، وتوضح مواصفاته سبب ملاءمته لحلقات الأدوات الطويلة:

المواصفات	DeepSeek V4 Pro
البنية	Sparse MoE: 1.6 تريليون معلمة إجمالية، و49 مليار معلمة نشطة لكل توكن
نافذة السياق	1 مليون توكن
الحد الأقصى للمخرجات	384 ألف توكن
سعر الإدخال	0.435 دولار/مليون توكن بدون ذاكرة مؤقتة، و0.003625 دولار/مليون مع الذاكرة المؤقتة
سعر المخرجات	0.87 دولار/مليون توكن
استدعاء الدوال	مصفوفة tools متوافقة مع OpenAI واستجابات tool_calls
واجهات أخرى	تنسيق رسائل Anthropic وواجهة Responses API من DeepSeek

تساعد نافذة السياق الكبيرة في الاحتفاظ بسجل استدعاءات الأدوات ونتائجها. كما تجعل تكلفة cache-hit المنخفضة تكرار حلقات الوكيل أقل تكلفة. النموذج متاح أيضًا على OpenRouter باسم deepseek-v4-pro-0813 للمقارنة بين الموفرين.

لكن لا تفترض أن الأداء ثابت في كل البيئات. في مناقشة إطلاق Hacker News، أفاد مطورون بأن جودة استدعاء الأدوات تتأثر بالإطار المستخدم، وهيكل التعليمات، وصياغة مخطط JSON. اختبر أدواتك ومخططاتك الفعلية قبل الإنتاج.

كيف يعمل استدعاء الدوال في DeepSeek؟

استدعاء الدالة لا يعني أن النموذج ينفذ الدالة بنفسه. بل يعيد طلبًا منظمًا، مثل:

{
  "name": "get_order",
  "arguments": "{\"order_id\":\"ORD-10442\"}"
}

تتولى أنت تنفيذ الدالة، ثم تعيد النتيجة للنموذج. الدورة كالتالي:

1. أرسل messages ومصفوفة tools التي تصف دوالك بمخطط JSON.
2. يقرر النموذج أنه يحتاج أداة ويرد بـ tool_calls.
3. حلّل الوسائط ونفّذ الدالة الفعلية في بيئتك.
4. أضف النتيجة برسالة ذات role: "tool" ومعرف الاستدعاء الصحيح.
5. استدعِ النموذج مجددًا حتى يطلب أداة أخرى أو ينتج إجابة نهائية.

إذا استخدمت استدعاء الدوال في OpenAI، فالتنسيق نفسه تقريبًا. غالبًا ستحتاج فقط إلى تغيير base_url واسم النموذج. راجع أيضًا وثائق DeepSeek الرسمية.

الخطوة 1: إعداد العميل

ثبّت حزمة SDK واضبط مفتاح API:

pip install openai
export DEEPSEEK_API_KEY="sk-..."

ثم أنشئ العميل:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

تستخدم الأمثلة التالية النموذج deepseek-v4-pro، الذي يشير إلى إصدار GA ‏DeepSeek-V4-Pro-0813.

الخطوة 2: تحديد مخطط أداة

سننشئ وكيل دعم لمتجر إلكتروني. الأداة الأولى تسترجع تفاصيل طلب من خلال معرّفه.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order",
            "description": (
                "Look up a customer order by its ID. Returns the order status, "
                "carrier, tracking number, and estimated delivery date. Use this "
                "whenever the user asks where an order is or what state it's in."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "The order ID, formatted like 'ORD-10442'.",
                    }
                },
                "required": ["order_id"],
            },
        },
    }
]

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

لأغراض التجربة، استخدم تنفيذًا محليًا بديلًا لخدمة الطلبات:

def get_order(order_id: str) -> dict:
    """Stub for your real order service."""
    fake_db = {
        "ORD-10442": {
            "status": "shipped",
            "carrier": "DHL",
            "tracking_number": "4281337005",
            "estimated_delivery": "2026-08-15",
        },
        "ORD-10587": {
            "status": "processing",
            "estimated_ship_date": "2026-08-14",
        },
    }

    return fake_db.get(
        order_id,
        {"error": f"Unknown order ID: {order_id}"}
    )

الخطوة 3: إجراء أول استدعاء لأداة

أرسل سؤالًا يحتاج إلى بيانات حقيقية:

messages = [
    {
        "role": "system",
        "content": "You are a support agent for an online store.",
    },
    {
        "role": "user",
        "content": "Where is my order ORD-10442?",
    },
]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
)

message = response.choices[0].message

print(message.tool_calls[0].function.name)
# get_order

print(message.tool_calls[0].function.arguments)
# {"order_id": "ORD-10442"}

بدلًا من الإجابة النصية، يطلب النموذج منك تنفيذ get_order. قد تبدو الاستجابة الخام بهذا الشكل:

{
  "id": "chatcmpl-8f3a1c",
  "object": "chat.completion",
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_0_f1c29a44",
            "type": "function",
            "function": {
              "name": "get_order",
              "arguments": "{\"order_id\": \"ORD-10442\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 24,
    "total_tokens": 336,
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 312
  }
}

انتبه إلى ثلاث نقاط:

• عندما تكون finish_reason هي "tool_calls"، يجب أن تنفذ الأدوات قبل متابعة المحادثة.
• يحمل كل استدعاء id فريدًا، ويجب إرجاعه في tool_call_id.
• القيمة arguments سلسلة JSON نصية، لذلك يجب تحليلها والتحقق منها قبل التنفيذ.

الخطوة 4: تنفيذ الدالة وإرجاع النتيجة

نفّذ الدالة ثم أضف رسالة المساعد التي تحتوي الاستدعاء، متبوعة برسالة الأداة التي تحتوي النتيجة:

import json

tool_call = message.tool_calls[0]
args = json.loads(tool_call.function.arguments)

result = get_order(**args)

messages.append(message)

messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(result),
})

final = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)

مثال للإجابة النهائية:

Your order ORD-10442 shipped with DHL and is estimated to arrive
by August 15, 2026. Tracking number: 4281337005.

العلاقة بين tool_call_id ورسالة tool صارمة: يجب أن يحصل كل عنصر في tool_calls على رسالة نتيجة مطابقة قبل استدعاء النموذج مرة أخرى.

الخطوة 5: بناء حلقة الوكيل الكاملة

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

import json

TOOLS_BY_NAME = {
    "get_order": get_order,
}

def run_agent(client, messages, tools, max_rounds=10):
    """Run the model until it returns a final answer or hits the cap."""
    for _ in range(max_rounds):
        response = client.chat.completions.create(
            model="deepseek-v4-pro",
            messages=messages,
            tools=tools,
        )

        message = response.choices[0].message
        messages.append(message)

        if not message.tool_calls:
            return message.content

        for tool_call in message.tool_calls:
            fn = TOOLS_BY_NAME.get(tool_call.function.name)

            try:
                if fn is None:
                    raise ValueError(
                        f"Unknown tool: {tool_call.function.name}"
                    )

                args = json.loads(tool_call.function.arguments)
                result = fn(**args)

            except Exception as exc:
                result = {
                    "error": str(exc)
                }

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result),
            })

    raise RuntimeError(
        f"Agent did not finish within {max_rounds} rounds"
    )

استخدم max_rounds دائمًا. فهو يمنع النموذج من الاستمرار في إعادة استدعاء أداة فاشلة إلى ما لا نهاية، ويحوّل الحلقة العالقة إلى خطأ يمكن رصده ومعالجته.

استدعاءات الأدوات المتوازية

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

Compare the status of ORD-10442 and ORD-10587.

قد يعيد النموذج استدعاءين في الدور نفسه:

"tool_calls": [
  {
    "id": "call_0_a7d1",
    "type": "function",
    "function": {
      "name": "get_order",
      "arguments": "{\"order_id\": \"ORD-10442\"}"
    }
  },
  {
    "id": "call_1_b3e9",
    "type": "function",
    "function": {
      "name": "get_order",
      "arguments": "{\"order_id\": \"ORD-10587\"}"
    }
  }
]

تتعامل حلقة run_agent مع عدة استدعاءات بالفعل. ولتقليل زمن التنفيذ، يمكنك تشغيل الدوال المتعددة بشكل متزامن، لكن عليك إضافة نتيجة tool منفصلة لكل tool_call_id.

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

استخدام وضع التفكير مع الأدوات

يوفر V4 Pro ثلاثة أوضاع للتفكير. يمكن استخدام التفكير للمهام التي تحتاج تخطيطًا، وتجاوزه في عمليات البحث الروتينية. راجع الوثائق الرسمية لأسماء الأوضاع والإعدادات الافتراضية.

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
    extra_body={"thinking": {"type": "enabled"}},
)

message = response.choices[0].message

print(message.reasoning_content)
print(message.tool_calls)

يعيد الحقل reasoning_content تتبع التفكير، إلى جانب استدعاءات الأدوات. استخدمه لتصحيح اختيار الأدوات أو تحسين المخططات، لكن أزله قبل إضافة رسالة المساعد إلى سجل المحادثة. كذلك، احتفظ بوضع التفكير للمهام التي تستحق تكلفته، لأنه يُحتسب ضمن المخرجات بسعر 0.87 دولار/مليون توكن.

معالجة أخطاء استدعاءات الأدوات

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

import json
from jsonschema import ValidationError, validate

schema = tools[0]["function"]["parameters"]

try:
    args = json.loads(tool_call.function.arguments)
    validate(instance=args, schema=schema)
    result = get_order(**args)

except (json.JSONDecodeError, ValidationError) as exc:
    result = {
        "error": f"Invalid arguments: {exc}",
        "hint": (
            "Call get_order again with an order_id string "
            "like 'ORD-10442'."
        ),
    }

التلميح القصير غالبًا يكفي لتصحيح الاستدعاء في الجولة التالية.

تعامل أيضًا مع أخطاء الوكلاء كحالات أمنية. إذا أُقنع النموذج باستدعاء دالة حساسة بمعاملات قدمها مهاجم، فإن مستوى الضرر يعتمد على صلاحيات المفتاح أو الخدمة خلف الأداة. طبّق مبدأ أقل امتياز، كما في دليل مفاتيح API بأقل امتياز لوكلاء الذكاء الاصطناعي.

اختبار وتصحيح استدعاءات الأدوات باستخدام Apidog قبل الإطلاق

كل أداة هي طبقة فوق API خلفية، والنموذج مستهلك جديد لهذه الواجهة. إذا كان عقد الـ API غامضًا أو غير مستقر، فستظهر المشكلة مباشرة في سلوك الوكيل.

استخدم Apidog بهذه الطريقة:

1. صمم الـ API أولًا
   
   عرّف GET /orders/{order_id} داخل مصمم Apidog. حافظ على توافق مواصفة الـ API ومخطط JSON الخاص بالأداة لتجنب انجرافهما بمرور الوقت.

2. حاكِ الخدمة قبل اكتمال الواجهة الخلفية
   
   استخدم المحاكاة لإرجاع استجابات واقعية اعتمادًا على المخطط، واختبر حلقة الوكيل بينما تكون خدمة الطلبات الفعلية قيد البناء.

3. افحص الاستجابة الخام للنموذج
   
   أرسل جسم messages وtools نفسه إلى https://api.deepseek.com من Apidog، ثم افحص JSON الناتج. بهذه الطريقة ستكتشف سريعًا أخطاء مثل properties غير الصحيحة أو المعاملات المشفرة مرتين.

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

يمكنك تنزيل Apidog مجانًا للمتابعة؛ يتضمن المستوى المجاني خادم المحاكاة وسيناريوهات الاختبار.

تكلفة حلقات الوكيل ولماذا يهم التخزين المؤقت

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

يقلل التخزين المؤقت التلقائي للمقدمة هذه التكلفة. بما أن كل جولة غالبًا تضيف القليل فقط إلى الجولة السابقة، يمكن احتساب معظم المقدمة بسعر cache-hit البالغ 0.003625 دولار/مليون توكن بدلًا من 0.435 دولار/مليون توكن.

كمثال تقريبي:

• إعادة قراءة 100 ألف توكن بدون ذاكرة مؤقتة: نحو 0.0435 دولار.
• إعادة قراءة 100 ألف توكن مع cache-hit: نحو 0.0004 دولار.

راقب الحقول التالية في الاستجابة لقياس نسبة التخزين المؤقت الفعلية:

{
  "prompt_cache_hit_tokens": 0,
  "prompt_cache_miss_tokens": 312
}

لتحقيق معدل cache-hit مرتفع:

• لا تعدّل الرسائل السابقة بين الجولات.
• اجعل مصفوفة tools ثابتة بايتًا ببايت.
• لا تغيّر ترتيب الأدوات أو أوصافها أثناء تنفيذ الحلقة.

لمزيد من التفاصيل، راجع ما هو التخزين المؤقت للموجه.

قد يبدو deepseek-v4-flash بسعر 0.14 دولار / 0.28 دولار خيارًا جذابًا للتوجيه البسيط إلى أداة واحدة، لكنه قد يتدهور في حلقات تربط أكثر من 10 استدعاءات؛ وقد تستهلك إعادة المحاولات أي وفورات متوقعة. لذلك، يكون Pro الخيار الافتراضي الأكثر أمانًا للوكلاء متعددة الخطوات.

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

هل تكلف تعريفات الأدوات توكنات؟

نعم. تكون مصفوفة tools جزءًا من مدخلات كل طلب. حافظ على ثباتها لكي تصبح جزءًا من المقدمة المخزنة مؤقتًا بعد الجولة الأولى.

هل يمكن دمج استدعاء الدوال مع المخرجات المنظمة؟

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

خلاصة

تنفيذ استدعاء الدوال في DeepSeek V4 Pro مباشر عمدًا: مخططات متوافقة مع OpenAI، وtool_calls، ورسائل tool مرتبطة بمعرف الاستدعاء. حلقة run_agent هي البنية الأساسية التي تحتاجها للبدء.

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