ما هو Gemini 3.1 Pro Customtools؟ افهم طريقة استخدام نموذج الأدوات المخصصة أولاً في 5 دقائق

يشعر الكثير من المطورين بالحيرة عند رؤية اسم النموذج gemini-3.1-pro-preview-customtools: ماذا يعني customtools؟ وكيف يختلف عن النسخة القياسية gemini-3.1-pro-preview؟ سيساعدك هذا المقال في توضيح الأمر تماماً خلال 5 دقائق.

القيمة الجوهرية: بعد قراءة هذا المقال، ستعرف متى تستخدم النسخة القياسية ومتى تستخدم نسخة customtools، وكيفية الاختيار الصحيح عند تطوير الوكلاء (Agents).

ما هو Gemini 3.1 Pro Customtools

شرح في جملة واحدة

gemini-3.1-pro-preview-customtools هو إصدار مخصص (Variant) أطلقته جوجل في 19 فبراير 2026 بالتزامن مع النسخة القياسية من Gemini 3.1 Pro. الفرق الجوهري الوحيد بينه وبين النسخة القياسية هو: إعطاء الأولوية لاستخدام الأدوات المخصصة التي قمت بتسجيلها، بدلاً من تشغيل أوامر bash الافتراضية.

النص الأصلي من سجل التغييرات الرسمي لجوجل (Changelog) يقول:

"تم إطلاق نقطة نهاية منفصلة gemini-3.1-pro-preview-customtools تبرع في إعطاء الأولوية للأدوات المخصصة، وهي موجهة للمستخدمين الذين يبنون أنظمة تجمع بين bash والأدوات."

لماذا نحتاج إلى هذا الإصدار؟

في تطوير الوكلاء (Agents)، عادةً ما يمنح المطورون النموذج نوعين من القدرات:

1. تنفيذ Bash/الكود: السماح للنموذج بتشغيل أوامر shell مباشرة.
2. الأدوات المخصصة (Custom Tools): وظائف منظمة يحددها المطور، مثل view_file و search_code و create_pr وما إلى ذلك.

أين تكمن المشكلة؟ النسخة القياسية من Gemini 3.1 Pro قد "تتكاسل" أحياناً، فتتجاوز الأدوات المخصصة التي صممتها بعناية، وتستخدم أوامر bash مباشرة لإنجاز المهمة. على سبيل المثال، قد تقوم بتسجيل أداة view_file لقراءة الملفات، لكن النموذج قد ينفذ ببساطة cat filename.py متجاوزاً أداتك.

وهذا يمثل مشكلة في سيناريوهات معينة:

• قد تحتوي الأدوات المخصصة على تحكم في الصلاحيات و تسجيل للعمليات (Logging).
• تنسيق المخرجات من الأدوات المخصصة يكون منظماً (Structured)، مما يسهل معالجته لاحقاً.
• قد تكون الأدوات المخصصة مرتبطة بـ أنظمة خارجية (قواعد بيانات، واجهات برمجة تطبيقات، إلخ).

إصدار customtools جاء ليحل هذه المشكلة تحديداً: جعل النموذج يفضل اختيار الأدوات التي قمت بتسجيلها.

الفروق الجوهرية بين Gemini 3.1 Pro الإصدار القياسي وإصدار Customtools

🎯 فهم جوهري: "مستوى الذكاء" في كلا النموذجين متطابق تماماً. الفرق الوحيد يكمن في أنه عند مواجهة خيار "هل أستخدم bash أم الأداة التي قمت بتسجيلها؟"، سيميل إصدار customtools بشكل أكبر لاختيار أدواتك المخصصة.

متى تحتاج إلى استخدام Gemini 3.1 Pro Customtools

السيناريوهات التي تتطلب customtools

السيناريوهات التي لا تتطلب customtools

نصيحة جوجل الرسمية

ذكرت جوجل بوضوح في الأسئلة الشائعة لدليل مطوري Gemini 3:

If you are using gemini-3.1-pro-preview and the model ignores your custom tools in favor of bash commands, try the gemini-3.1-pro-preview-customtools model instead.

الترجمة: إذا وجدت أن الإصدار القياسي يتجاهل أدواتك المخصصة ويستخدم bash مباشرة، فجرب التبديل إلى إصدار gemini-3.1-pro-preview-customtools.

طريقة استدعاء API لـ Gemini 3.1 Pro Customtools

استدعاء أساسي: تماماً مثل الإصدار القياسي

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # الواجهة الموحدة لـ APIYI
)

# تحتاج فقط إلى تغيير اسم النموذج (model)، وستبقى بقية الأكواد كما هي تماماً
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "ساعدني في عرض محتوى ملف main.py في المشروع"}
    ]
)
print(response.choices[0].message.content)

استدعاء Agent مع أدوات مخصصة

تكمن القوة الحقيقية لإصدار customtools في دمجه مع ميزة استدعاء الوظائف (function calling):

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # الواجهة الموحدة لـ APIYI
)

# تعريف الأدوات المخصصة
tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "عرض محتوى ملف محدد",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {
                        "type": "string",
                        "description": "مسار الملف"
                    }
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "البحث عن كلمات مفتاحية في قاعدة الكود",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "كلمة البحث المفتاحية"
                    },
                    "file_pattern": {
                        "type": "string",
                        "description": "نمط مطابقة الملفات، مثل *.py"
                    }
                },
                "required": ["query"]
            }
        }
    }
]

# سيعطي إصدار customtools الأولوية لاستخدام الأدوات المحددة أعلاه
response = client.chat.completions.create(
    model="gemini-3.1-pro-preview-customtools",
    messages=[
        {"role": "user", "content": "ساعدني في العثور على جميع ملفات Python التي تحتوي على TODO في المشروع"}
    ],
    tools=tools
)

# سيقوم النموذج باستدعاء أداة search_code بدلاً من استخدام grep مباشرة
tool_call = response.choices[0].message.tool_calls[0]
print(f"الأداة: {tool_call.function.name}")
print(f"المعاملات: {tool_call.function.arguments}")

import openai
import json

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "view_file",
            "description": "عرض محتوى ملف محدد",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "مسار الملف"}
                },
                "required": ["file_path"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_code",
            "description": "البحث عن كلمات مفتاحية في قاعدة الكود",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "كلمة البحث المفتاحية"},
                    "file_pattern": {"type": "string", "description": "نمط مطابقة الملفات"}
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "edit_file",
            "description": "تحرير محتوى محدد في الملف",
            "parameters": {
                "type": "object",
                "properties": {
                    "file_path": {"type": "string", "description": "مسار الملف"},
                    "old_content": {"type": "string", "description": "المحتوى القديم المراد استبداله"},
                    "new_content": {"type": "string", "description": "المحتوى الجديد"}
                },
                "required": ["file_path", "old_content", "new_content"]
            }
        }
    }
]

# محاكاة تنفيذ الأداة
def execute_tool(name, args):
    """في المشروع الفعلي، استبدل هذا بتنفيذ حقيقي للأدوات"""
    if name == "view_file":
        return f"محتوى الملف: {args['file_path']} (محاكاة)"
    elif name == "search_code":
        return f"نتائج البحث عن '{args['query']}': تم العثور على 3 مطابقات (محاكاة)"
    elif name == "edit_file":
        return f"تم استبدال المحتوى في {args['file_path']} (محاكاة)"
    return "أداة غير معروفة"

# الحلقة الرئيسية للـ Agent
messages = [{"role": "user", "content": "ابحث عن جميع تعليقات TODO في المشروع وقم بإصلاحها"}]
max_turns = 5

for turn in range(max_turns):
    response = client.chat.completions.create(
        model="gemini-3.1-pro-preview-customtools",
        messages=messages,
        tools=tools
    )

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

    if msg.tool_calls:
        for tc in msg.tool_calls:
            args = json.loads(tc.function.arguments)
            result = execute_tool(tc.function.name, args)
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })
            print(f"[الجولة {turn+1}] استدعاء: {tc.function.name}({args})")
    else:
        print(f"[اكتمل] {msg.content[:200]}")
        break

🚀 بداية سريعة: من خلال منصة APIYI (apiyi.com)، يستخدم الإصدار القياسي وإصدار customtools نفس مفتاح API Key. ما عليك سوى تعديل معلمة النموذج (model) للتبديل بينهما، وهو أمر مثالي لاختبار A/B لتحديد أي إصدار يناسب الـ Agent الخاص بك بشكل أفضل.

العلاقة بين Gemini 3.1 Pro Customtools وإطارات عمل الـ Agent

توافق إطارات عمل الـ Agent الشائعة

يعد إصدار customtools ذا قيمة خاصة لسيناريوهات تطوير الـ Agent التالية:

Gemini 3.1 Pro Customtools 与标准版的行为对比

为了更直观地理解区别,看一个具体的例子:

同一个请求,两个模型的不同反应

用户请求: 「帮我查看 src/main.py 文件的内容」

已注册工具: view_file(file_path: string)

两种方式都能获取文件内容,但通过自定义工具调用有以下优势:

1. 权限控制: 你的 view_file 工具可以检查路径是否在白名单内
2. 格式化输出: 工具可以返回结构化的 JSON 而非原始文本
3. 日志审计: 工具调用会被框架自动记录
4. 错误处理: 工具可以提供友好的错误信息而非 bash 报错

谷歌 Gemini 工具调用模型的演进

customtools 是谷歌首次为工具调用提供专用模型变体。以下是谷歌 Gemini 工具相关模型的完整图谱:

这表明谷歌正在将模型按使用场景细分,而不是用一个通用模型覆盖所有场景。未来可能会出现更多专用变体。

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

ملخص: دليل Gemini 3.1 Pro Customtools السريع

الخلاصة في جملة واحدة: gemini-3.1-pro-preview-customtools هو "وضع العميل الذكي المخصص" لنموذج Gemini 3.1 Pro — فهو يجعل النموذج أكثر طاعة في استخدام الأدوات التي سجلتها بدلاً من تشغيل أوامر bash مباشرة. السعر لم يتغير، والذكاء لم يتغير، فقط استراتيجية اختيار الأدوات أصبحت أكثر ملاءمة لتطوير العملاء الأذكياء (Agents).

نوصي بالوصول إلى كلا الإصدارين عبر منصة APIYI (apiyi.com) في وقت واحد، واختيار الأنسب بعد إجراء اختبار A/B في مشروعك الفعلي. بالنسبة لمطوري الـ Agents، فإن نسخة customtools هي الخيار الأفضل دائماً تقريباً.

المراجع

1. وثائق Google AI: صفحة نموذج Gemini 3.1 Pro Preview

   • الرابط: ai.google.dev/gemini-api/docs/models/gemini-3.1-pro-preview
   • الوصف: تتضمن توضيحاً للمقارنة بين الإصدار القياسي وإصدار customtools.

2. سجل تغييرات Gemini API: تحديث 19 فبراير 2026

   • الرابط: ai.google.dev/gemini-api/docs/changelog
   • الوصف: سجل الإصدار الأول لمتغير customtools.

3. دليل مطوري Gemini 3: توصيات اختيار الأدوات في الأسئلة الشائعة (FAQ)

   • الرابط: ai.google.dev/gemini-api/docs/gemini-3
   • الوصف: متى يجب الانتقال من الإصدار القياسي إلى إصدار customtools.

4. وثائق Google AI: دليل استدعاء الدوال (Function Calling)

   • الرابط: ai.google.dev/gemini-api/docs/function-calling
   • الوصف: شرح مفصل لـ API استدعاء الدوال في نماذج Gemini.

📝 المؤلف: فريق APIYI | للتواصل التقني يرجى زيارة APIYI عبر apiyi.com
📅 تاريخ التحديث: 20 فبراير 2026
🏷️ الكلمات المفتاحية: gemini-3.1-pro-preview-customtools، أدوات مخصصة، تطوير الوكلاء (Agents)، استدعاء الدوال (function calling)، استدعاء الأدوات، استدعاء API.