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, thêm SDK vào các phần phụ thuộc của nhà xuất bản và khởi động mô hình.

dart pub add google_generative_ai

flutter pub add google_generative_ai

import 'package:google_generative_ai/google_generative_ai.dart';

// Access your API key as an environment variable (see "Set up your API key" above)
final apiKey = Platform.environment['API_KEY'];
if (apiKey == null) {
  print('No \$API_KEY environment variable');
  exit(1);
}

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

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ề.

Future<Map<String, Object?>> findExchangeRate(
  Map<String, Object?> arguments,
) async =>
    // This hypothetical API returns a JSON such as:
    // {"base":"USD","date":"2024-04-17","rates":{"SEK": 0.091}}
    {
      'date': arguments['currencyDate'],
      'base': arguments['currencyFrom'],
      'rates': <String, Object?>{arguments['currencyTo'] as String: 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.

final exchangeRateTool = FunctionDeclaration(
    'findExchangeRate',
    'Returns the exchange rate between currencies on given date.',
    Schema(SchemaType.object, properties: {
      'currencyDate': Schema(SchemaType.string,
          description: 'A date in YYYY-MM-DD format or '
              'the exact value "latest" if a time period is not specified.'),
      'currencyFrom': Schema(SchemaType.string,
          description: 'The currency code of the currency to convert from, '
              'such as "USD".'),
      'currencyTo': Schema(SchemaType.string,
          description: 'The currency code of the currency to convert to, '
              'such as "USD".')
    }, requiredProperties: [
      '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:

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

  // Specify the function declaration.
  tools: [
    Tool(functionDeclarations: [exchangeRateTool])
  ],
);

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.

final chat = model.startChat();
final prompt = 'How much is 50 US dollars worth in Swedish krona?';

// Send the message to the generative model.
var response = await chat.sendMessage(Content.text(prompt));

final functionCalls = response.functionCalls.toList();
// When the model response with a function call, invoke the function.
if (functionCalls.isNotEmpty) {
  final functionCall = functionCalls.first;
  final result = switch (functionCall.name) {
    // Forward arguments to the hypothetical API.
    'findExchangeRate' => await findExchangeRate(functionCall.args),
    // Throw an exception if the model attempted to call a function that was
    // not declared.
    _ => throw UnimplementedError(
        'Function not implemented: ${functionCall.name}')
  };
  // Send the response to the model so that it can use the result to generate
  // text for the user.
  response = await chat
      .sendMessage(Content.functionResponse(functionCall.name, result));
}
// When the model responds with non-null text content, print it.
if (response.text case final text?) {
  print(text);
}