Hướng dẫn: Gọi hàm bằng API Gemini

Python Node.js Go Dart (Flutter) Android Swift Web

Tính năng gọi hàm giúp bạn dễ dàng nhận được kết quả dữ liệu có cấu trúc từ các mô hình tạo sinh. Sau đó, bạn có thể sử dụng các kết quả đầu ra này để gọi các API khác và trả về dữ liệu phản hồi liên quan cho mô hình. Nói cách khác, tính năng gọi hàm giúp bạn kết nối các mô hình tạo sinh với hệ thống bên ngoài để nội dung được tạo bao gồm thông tin chính xác và mới nhất.

Bạn có thể cung cấp cho mô hình Gemini nội dung mô tả về các hàm. Đây là các hàm mà bạn viết bằng ngôn ngữ của ứng dụng (tức là các hàm này không phải là Google Cloud Functions). Mô hình này có thể yêu cầu bạn gọi một hàm và gửi lại kết quả để giúp mô hình đó xử lý truy vấn của bạn.

Nếu bạn chưa xem, hãy xem phần Giới thiệu về tính năng gọi hàm để tìm hiểu thêm.

Thiết lập dự án

Trước khi gọi API Gemini, bạn cần thiết lập dự án, bao gồm cả việc thiết lập khoá API, cài đặt gói SDK và khởi chạy mô hình.

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")

Thiết lập lệnh gọi hàm

Trong hướng dẫn này, bạn sẽ yêu cầu mô hình tương tác với một API trao đổi tiền tệ giả định hỗ trợ các tham số sau:

Ví dụ về yêu cầu API

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

Ví dụ về phản hồi của API

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

Bước 1: Tạo hàm thực hiện yêu cầu API

Nếu bạn chưa có, hãy bắt đầu bằng cách tạo hàm đưa ra yêu cầu API.

Để minh hoạ trong hướng dẫn này, thay vì gửi yêu cầu API thực tế, bạn sẽ trả về các giá trị được cố định giá trị trong mã ở cùng một định dạng mà API thực tế sẽ trả về.

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}}
}

Bước 2: Tạo phần khai báo hàm

Tạo phần khai báo hàm mà bạn sẽ truyền sang mô hình tạo sinh (bước tiếp theo của hướng dẫn này).

Cung cấp càng nhiều thông tin chi tiết càng tốt trong phần mô tả hàm và tham số. Mô hình tạo sinh sử dụng thông tin này để xác định hàm cần chọn và cách cung cấp giá trị cho các tham số trong lệnh gọi hàm.

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"},
        },
    }},
}

Bước 3: Chỉ định khai báo hàm trong quá trình khởi tạo mô hình

Chỉ định khai báo hàm khi khởi chạy mô hình tạo sinh bằng cách truyền mô hình đó vào tham số Tools của mô hình:

// ...

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}

Bước 4: Tạo lệnh gọi hàm

Bây giờ, bạn có thể nhắc mô hình bằng hàm đã xác định.

Bạn nên sử dụng tính năng gọi hàm thông qua giao diện trò chuyện, vì các lệnh gọi hàm phù hợp với cấu trúc nhiều lượt của cuộc trò chuyện.

// 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)
}