برنامج تعليمي: استدعاء الوظائف باستخدام واجهة برمجة تطبيقات Gemini

Python Node.js الانتقال Dart (Flutter) Android Swift الويب

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

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

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

إعداد مشروعك

قبل طلب البيانات من Gemini API، عليك إعداد مشروعك، ويتضمّن ذلك إعداد مفتاح واجهة برمجة التطبيقات، وتثبيت حزمة SDK، وإعداد النموذج.

go get github.com/google/generative-ai-go

import "github.com/google/generative-ai-go/genai"
import "google.golang.org/api/option"

ctx := context.Background()
// Access your API key as an environment variable (see "Set up your API key" above)
client, err := genai.NewClient(ctx, option.WithAPIKey(os.Getenv("API_KEY")))
if err != nil {
  log.Fatal(err)
}
defer client.Close()

// Use a model that supports function calling, like Gemini 1.0 Pro.
// See "Supported models" in the "Introduction to function calling" page.
model := client.GenerativeModel("MODEL_NAME")

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

في هذا البرنامج التعليمي، ستجعل النموذج يتفاعل مع واجهة برمجة تطبيقات تبادل العملات الافتراضية التي تدعم المعلمات التالية:

مثال على طلب بيانات من واجهة برمجة التطبيقات

{
  "currencyDate": "2024-04-17",
  "currencyFrom": "USD",
  "currencyTo": "SEK"
}

مثال على ردّ من واجهة برمجة التطبيقات

{
  "base": "USD",
  "date": "2024-04-17",
  "rates": {"SEK": 0.091}
}

الخطوة 1: إنشاء الدالة التي تنشئ طلب البيانات من واجهة برمجة التطبيقات

إذا لم تكن قد فعلت ذلك بالفعل، فابدأ بإنشاء الدالة التي تنشئ طلب واجهة برمجة تطبيقات.

لأغراض التوضيح في هذا البرنامج التعليمي، بدلاً من إرسال طلب فعلي من واجهة برمجة التطبيقات، ستعرض قيمًا ذات ترميز ثابت بالتنسيق نفسه الذي تعرضه واجهة برمجة التطبيقات الفعلية.

func exchangeRate(currencyDate string,
    currencyFrom string, currencyTo string) map[string]any {
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","date":"2024-04-17","rates":{"SEK": 0.091}}
    return map[string]any{
        "base":  currencyFrom,
        "date":  currencyDate,
        "rates": map[string]any{currencyTo: 0.091}}
}

الخطوة 2: إنشاء تعريف دالة

أنشئ تعريف الدالة الذي ستنتقل إلى النموذج التوليدي (الخطوة التالية في هذا البرنامج التعليمي).

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

currencyExchangeTool := &genai.Tool{
    FunctionDeclarations: []*genai.FunctionDeclaration{{
        Name:        "exchangeRate",
        Description: "Lookup currency exchange rates by date",
        Parameters: &genai.Schema{
            Type: genai.TypeObject,
            Properties: map[string]*genai.Schema{
                "currencyDate": {
                    Type:        genai.TypeString,
                    Description: "A date that must always be in YYYY-MM-DD format" +
                        " or the value 'latest' if a time period is not specified",
                },
                "currencyFrom": {
                    Type:        genai.TypeString,
                    Description: "Currency to convert from",
                },
                "currencyTo": {
                    Type:        genai.TypeString,
                    Description: "Currency to convert to",
                },
            },
            Required: []string{"currencyDate", "currencyFrom"},
        },
    }},
}

الخطوة 3: تحديد تعريف الدالة أثناء إعداد النموذج

حدد تعريف الدالة عند إعداد النموذج التوليدي من خلال تمريره إلى معلمة Tools للنموذج:

// ...

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

// Use a model that supports function calling, like Gemini 1.0 Pro.
// See "Supported models" in the "Introduction to function calling" page.
model := client.GenerativeModel("gemini-1.0-pro")

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

الخطوة 4: إنشاء استدعاء دالة

يمكنك الآن المطالبة بالنموذج باستخدام الدالة المحددة.

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

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

prompt := "How much is 50 US dollars worth in Swedish krona?"

// 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, currencyExchangeTool.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{
    "base":  "USD",
    "date":  "2024-04-17",
    "rates": map[string]any{"SEK": 0.091}}

// 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:     currencyExchangeTool.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)
}