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

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

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

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

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

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

المعلمة النوع مطلوب الوصف
brightness الرقم نعم مستوى الإضاءة من 0 إلى 100 القيمة "صفر" غير مفعّلة والقيمة 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)
}