برنامج تعليمي حول استدعاء الدوال

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

يمكنك تزويد نماذج Gemini بأوصاف الدوالّ. هذه هي الدوالّ التي تكتبها بلغة تطبيقك (أي أنّها ليست Google Cloud Functions). قد يطلب منك النموذج استدعاء دالة ثم إرجاعها النتيجة لمساعدة النموذج في التعامل مع استعلامك.

يمكنك الاطّلاع على مقالة مقدّمة حول استدعاء الدوالّ للتعرّف على مزيد من المعلومات، إذا لم يسبق لك ذلك.

مثال على واجهة برمجة تطبيقات للتحكّم في الإضاءة

لنفترض أنّ لديك نظامًا أساسيًا للتحكّم في الإضاءة من خلال واجهة برمجة التطبيقات (API) وتريد السماح للمستخدمين بالتحكّم في الأضواء من خلال طلبات مكتوبة بسيطة. يمكنك استخدام ميزة "استدعاء الدوال" لتفسير طلبات تغيير الإضاءة من المستخدمين وترجمتها إلى طلبات بيانات من واجهة برمجة التطبيقات لضبط قيم الإضاءة . يتيح لك نظام التحكم الافتراضي في الإضاءة هذا سطوع الضوء ودرجة حرارة ألوانه، وهما محددتان المَعلمات:

المعلمة النوع مطلوب الوصف
brightness الرقم نعم مستوى الإضاءة من 0 إلى 100 القيمة 0 تعني إيقاف الإضاءة والقيمة 100 تعني الإضاءة الكاملة.
colorTemperature سلسلة نعم درجة حرارة ألوان تجهيز الإضاءة يمكن أن تكون daylight أو cool أو warm.

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

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

يشرح لك هذا الدليل التعليمي كيفية إعداد طلب وظيفي لواجهة برمجة التطبيقات Gemini API لتفسير طلبات الإضاءة من المستخدمين وربطها بإعدادات واجهة برمجة التطبيقات للتحكّم في قيم سطوع ضوء المصابيح ودرجة حرارة اللون.

قبل البدء: إعداد مشروعك ومفتاح واجهة برمجة التطبيقات

قبل طلب Gemini API، عليك إعداد مشروعك وإعداده. مفتاح واجهة برمجة التطبيقات الخاص بك.

تعريف دالة واجهة برمجة التطبيقات

إنشاء دالة تؤدي إلى طلب واجهة برمجة التطبيقات. يجب تعريف هذه الدالة ضمن رمز تطبيقك، ولكن يمكنها استدعاء خدمات أو واجهات برمجة تطبيقات خارج تطبيقك. لا تستدعي Gemini API هذه الوظيفة مباشرةً، لذلك يمكننا التحكم في كيفية ووقت تنفيذ هذه الدالة من خلال تطبيقك الرمز. لأغراض توضيحية، يحدِّد هذا الدليل التعليمي دالة واجهة برمجة تطبيقات وهمية تعرض فقط قيم الإضاءة المطلوبة:

func setLightValues(brightness int, colorTemp string) map[string]any {
    // This mock API returns the requested lighting values
    return map[string]any{
        "brightness":       brightness,
        "colorTemperature": colorTemp}
}

إنشاء تعريف دالة

أنشِئ تعريف الدالة الذي ستنقله إلى النموذج التوليدي. عند تعريف دالة لاستخدامها في النموذج، يجب تضمين أكبر عدد ممكن من التفاصيل في أوصاف الدالة والمَعلمات. يستخدم النموذج التوليدي هذه المعلومات لتحديد الدالة التي سيتم اختيارها وكيفية تقديم قيم للمَعلمات في طلب استدعاء الدالة. يوضّح الرمز البرمجي التالي كيفية تعريف وظيفة التحكّم في الإضاءة:

lightControlTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "controlLight",
        Description: "Set the brightness and color temperature of a room light.",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "brightness": {
                    Type:        genai.TypeString,
                    Description: "Light level from 0 to 100. Zero is off and"+
                        " 100 is full brightness.",
                },
                "colorTemperature": {
                    Type:        genai.TypeString,
                    Description: "Color temperature of the light fixture which" +
                        " can be `daylight`, `cool` or `warm`.",
                },
            },
            Required: []string{"brightness", "colorTemperature"},
        },
    }},
}

تحديد الدوالّ أثناء بدء تشغيل النموذج

عندما تريد استخدام استدعاء الدالة مع نموذج، يجب عليك تقديم عند تهيئة كائن النموذج. يمكنك تحديد الدوالّ من خلال ضبط المَعلمة Tools للنموذج:

// ...

lightControlTool := &genai.Tool{
    // ...
}

// Use a model that supports function calling, like a Gemini 1.5 model
model := client.GenerativeModel("gemini-1.5-flash")

// Specify the function declaration.
model.Tools = []*genai.Tool{lightControlTool}

إنشاء استدعاء دالة

وبعد إعداد النموذج باستخدام بيانات الدوال، يمكنك طلب النموذج مع الدالة المحددة. يجب عليك استخدام استدعاء الدالة باستخدام مطالبة الدردشة (SendMessage())، نظرًا لأن الاستدعاء الوظيفي يستفيد عمومًا من وجود سياق المطالبات والردود السابقة.

// Start new chat session.
session := model.StartChat()

prompt := "Dim the lights so the room feels cozy and warm."

// Send the message to the generative model.
resp, err := session.SendMessage(ctx, genai.Text(prompt))
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Check that you got the expected function call back.
part := resp.Candidates[0].Content.Parts[0]
funcall, ok := part.(genai.FunctionCall)
if !ok {
    log.Fatalf("Expected type FunctionCall, got %T", part)
}
if g, e := funcall.Name, lightControlTool.FunctionDeclarations[0].Name; g != e {
    log.Fatalf("Expected FunctionCall.Name %q, got %q", e, g)
}
fmt.Printf("Received function call response:\n%q\n\n", part)

apiResult := map[string]any{
    "brightness":  "30",
    "colorTemperature":  "warm" }

// Send the hypothetical API result back to the generative model.
fmt.Printf("Sending API result:\n%q\n\n", apiResult)
resp, err = session.SendMessage(ctx, genai.FunctionResponse{
    Name:     lightControlTool.FunctionDeclarations[0].Name,
    Response: apiResult,
})
if err != nil {
    log.Fatalf("Error sending message: %v\n", err)
}

// Show the model's response, which is expected to be text.
for _, part := range resp.Candidates[0].Content.Parts {
    fmt.Printf("%v\n", part)
}