Giới thiệu về chức năng Gọi bằng Gemini API

Bạn có thể xác định và cung cấp các hàm tuỳ chỉnh cho các mô hình Gemini bằng cách sử dụng Hàm Tính năng gọi điện. Các mô hình không trực tiếp gọi ra những hàm này, mà thay vào đó tạo đầu ra dữ liệu có cấu trúc trong đó chỉ định tên hàm và gợi ý đối số. Kết quả này cho phép bạn viết các ứng dụng có phần tử đầu ra và gọi API bên ngoài, kết quả đầu ra API sau đó có thể là được tích hợp vào một câu lệnh mô hình khác, giúp truy vấn toàn diện hơn phản hồi. Tính năng gọi hàm cho phép người dùng tương tác theo thời gian thực thông tin và nhiều dịch vụ khác nhau, chẳng hạn như cơ sở dữ liệu, quan hệ khách hàng hệ thống quản lý và kho lưu trữ tài liệu, nâng cao khả năng đưa ra câu trả lời phù hợp và theo bối cảnh.

Cách hoạt động của lệnh gọi hàm

Bạn sử dụng tính năng Gọi hàm bằng cách thêm dữ liệu truy vấn có cấu trúc mô tả các giao diện lập trình, được gọi là khai báo hàm, thành dấu nhắc mô hình. Chiến lược phát hành đĩa đơn Phần khai báo hàm cho biết tên của hàm API, giải thích mục đích của hàm đó bất kỳ tham số nào mà lớp đó hỗ trợ cũng như nội dung mô tả về các tham số đó. Sau khi bạn vượt qua danh sách nội dung khai báo hàm trong một truy vấn đến mô hình, công cụ này sẽ phân tích hàm và phần còn lại của truy vấn để xác định cách sử dụng các API để phản hồi yêu cầu.

Sau đó, mô hình này sẽ trả về một đối tượng trong một Giản đồ tương thích với OpenAPI chỉ định cách gọi một hoặc nhiều hàm được khai báo để phản hồi câu hỏi của người dùng. Sau đó, bạn có thể thực hiện lệnh gọi hàm được đề xuất tham số, gọi API thực tế, nhận phản hồi và cung cấp phản hồi đó cho người dùng hoặc thực hiện hành động khác. Lưu ý rằng mô hình này không thực sự gọi phương thức các hàm đã khai báo. Thay vào đó, bạn sẽ sử dụng các tham số của đối tượng giản đồ được trả về để gọi hàm đó. Gemini API cũng hỗ trợ chức năng gọi song song, trong đó mô hình này đề xuất nhiều lệnh gọi hàm API dựa trên một yêu cầu duy nhất.

Mô hình được hỗ trợ

Các kiểu máy sau hỗ trợ tính năng Gọi hàm:

  • gemini-1.0-pro
  • gemini-1.0-pro-001
  • gemini-1.5-flash-latest
  • gemini-1.5-pro-latest

Khai báo hàm

Khi triển khai lệnh gọi hàm trong một câu lệnh, bạn sẽ tạo một đối tượng tools, chứa một hoặc nhiều function declarations. Bạn xác định các hàm bằng JSON, đặc biệt là với chọn tập hợp con của Giản đồ OpenAPI . Phần khai báo một hàm có thể bao gồm các tham số sau:

  • name (chuỗi): Giá trị nhận dạng duy nhất của hàm trong API .
  • description (chuỗi): Giải thích toàn diện về hàm mục đích và khả năng.
  • parameters (đối tượng): Xác định dữ liệu đầu vào mà hàm yêu cầu.
    • type (chuỗi): Chỉ định kiểu dữ liệu tổng thể, chẳng hạn như object.
    • properties (đối tượng): Liệt kê từng tham số, mỗi tham số có:
      • type (chuỗi): Loại dữ liệu của tham số, chẳng hạn như string, integer, boolean.
      • description (chuỗi): Giải thích rõ ràng về giá trị của tham số mục đích và định dạng dự kiến.
    • required (mảng): Một mảng chuỗi liệt kê tên thông số bắt buộc để hàm hoạt động.

Để xem ví dụ về mã của phần khai báo hàm bằng lệnh cURL, hãy xem Ví dụ về cách gọi hàm. Ví dụ: và thông tin về cách tạo nội dung khai báo hàm cho các nền tảng khác, hãy xem Hướng dẫn về các nền tảng gọi hàm.

Các phương pháp hay nhất để khai báo hàm

Bạn cần xác định chính xác các chức năng khi tích hợp các chức năng đó vào yêu cầu. Mỗi hàm dựa vào các tham số cụ thể hướng dẫn hành vi của hàm và tương tác với mô hình. Trang thông tin sau đây cung cấp hướng dẫn về xác định các tham số của một hàm riêng lẻ trong functions_declarations .

  • name: Dùng tên rõ ràng, mang tính mô tả mà không có dấu cách, dấu chấm (.) hoặc dấu gạch ngang (-). Thay vào đó, hãy sử dụng các ký tự dấu gạch dưới (_) hoặc kiểu viết lạc đà.

  • description: Cung cấp chức năng chi tiết, rõ ràng và cụ thể nội dung mô tả, cung cấp ví dụ nếu cần. Ví dụ: thay vì find theaters, sử dụng find theaters based on location and optionally movie title that is currently playing in theaters. Tránh sử dụng từ quá rộng hoặc mơ hồ nội dung mô tả.

  • properties type: Dùng các tham số được nhập mạnh để giảm ảo tưởng mô hình. Ví dụ: nếu giá trị tham số là từ một giá trị hữu hạn đã đặt, hãy sử dụng trường enum thay vì liệt kê các giá trị trong nội dung mô tả (ví dụ: "type": "enum", "values": ["now_playing", "upcoming"]). Nếu giá trị tham số luôn là một số nguyên, hãy đặt loại thành integer thay vì number.

  • properties description: Cung cấp các ví dụ và hạn chế cụ thể. Ví dụ: sử dụng The city and state, e.g. San Francisco, CA or a zip code e.g. 95616 thay vì the location to search.

Để biết thêm các phương pháp hay nhất khi sử dụng Lệnh gọi hàm, hãy xem Phần Các phương pháp hay nhất.

Chế độ gọi hàm

Bạn có thể sử dụng tham số Gọi hàm mode để sửa đổi quá trình thực thi hoạt động của tính năng. Có 3 chế độ:

  • AUTO: Hành vi mặc định của mô hình. Mô hình đó sẽ quyết định dự đoán lệnh gọi hàm hoặc phản hồi bằng ngôn ngữ tự nhiên.
  • ANY: Mô hình bị ràng buộc phải luôn dự đoán lệnh gọi hàm. Nếu allowed_function_names không được cung cấp, mô hình này chọn từ tất cả các khai báo hàm có sẵn. Nếu allowed_function_names được được cung cấp, mô hình sẽ chọn từ tập hợp các hàm được phép.
  • NONE: Mô hình sẽ không dự đoán lệnh gọi hàm. Trong trường hợp này, mô hình sẽ giống như khi bạn không truyền bất kỳ nội dung khai báo hàm nào.

Việc sử dụng chế độ ANY ("gọi hàm bắt buộc") là chỉ được hỗ trợ cho các kiểu máy Gemini 1.5 Pro.

Bạn cũng có thể truyền một tập hợp allowed_function_names mà khi được cung cấp, các giới hạn các hàm mà mô hình sẽ gọi. Bạn chỉ nên thêm allowed_function_names khi chế độ là ANY. Tên hàm phải khớp tên khai báo hàm. Với chế độ được đặt thành ANY và allowed_function_names, mô hình sẽ dự đoán lệnh gọi hàm từ tập hợp tên hàm đã cung cấp.

Đoạn mã sau đây từ một ví dụ về yêu cầu cho biết cách đặt mode thành ANY rồi chỉ định danh sách các hàm được phép:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Ví dụ về cách gọi hàm

Phần này đưa ra các câu lệnh mẫu để gọi hàm bằng lệnh cURL. Các ví dụ bao gồm trường hợp rẽ một chặng và nhiều chặng, đồng thời bật các chế độ gọi hàm khác nhau.

Khi sử dụng các lệnh cURL với tính năng này, hàm và tham số thông tin được bao gồm trong phần tử tools. Mỗi khai báo hàm trong Phần tử tools chứa tên hàm và bạn sẽ chỉ định tham số bằng cách sử dụng giản đồ tương thích với OpenAPI, và phần mô tả hàm.

Ví dụ về một chặng

Một lượt quay là khi bạn gọi mô hình ngôn ngữ một lần. Với chức năng gọi hàm, trường hợp sử dụng một lượt có thể là khi bạn cung cấp cho mô hình ngôn ngữ tự nhiên truy vấn và danh sách hàm. Trong trường hợp này, mô hình sẽ sử dụng hàm trong đó bao gồm tên hàm, tham số và mô tả hàm để dự đoán hàm nào cần gọi và các đối số cần gọi hàm đó.

Mẫu curl sau đây là ví dụ về việc truyền phần mô tả về một trả về thông tin về nơi một bộ phim đang chiếu. Nhiều nội dung khai báo hàm được đưa vào yêu cầu, chẳng hạn như find_movies và find_theaters.

Yêu cầu ví dụ về gọi hàm một lượt

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "Which theaters in Mountain View show Barbie movie?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ]
}'

Phản hồi cho ví dụ về curl này có thể tương tự như sau.

Phản hồi mẫu curl cho hàm một lượt gọi

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "movie": "Barbie",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "totalTokenCount": 9
  }
}]

Ví dụ về một lượt quay bằng chế độ BẤT KỲ

Ví dụ về curl sau đây tương tự với ví dụ về một lượt quay, nhưng sẽ đặt chế độ thành ANY:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

Gọi hàm một lượt bằng chế độ BẤT KỲ (yêu cầu) nào

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY"
    },
  }
}'

Phản hồi này có thể tương tự như sau:

Gọi hàm một lượt bằng chế độ BẤT KỲ (phản hồi)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "",
                "location": "North Seattle, WA"
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Ví dụ về một lượt quay bằng cách sử dụng chế độ BẤT KỲ và các hàm được phép

Ví dụ về curl sau đây tương tự với ví dụ về một lượt quay, nhưng sẽ đặt mode vào ANY và bao gồm danh sách các chế độ được phép hàm:

"tool_config": {
  "function_calling_config": {
    "mode": "ANY",
    "allowed_function_names": ["find_theaters", "get_showtimes"]
  },
}

Gọi hàm một lượt bằng cách sử dụng chế độ BẤT KỲ và các hàm được phép (yêu cầu)

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": {
      "role": "user",
      "parts": {
        "text": "What movies are showing in North Seattle tonight?"
    }
  },
  "tools": [
    {
      "function_declarations": [
        {
          "name": "find_movies",
          "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "description": {
                "type": "string",
                "description": "Any kind of description including category or genre, title words, attributes, etc."
              }
            },
            "required": [
              "description"
            ]
          }
        },
        {
          "name": "find_theaters",
          "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              }
            },
            "required": [
              "location"
            ]
          }
        },
        {
          "name": "get_showtimes",
          "description": "Find the start times for movies playing in a specific theater",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
              },
              "movie": {
                "type": "string",
                "description": "Any movie title"
              },
              "theater": {
                "type": "string",
                "description": "Name of the theater"
              },
              "date": {
                "type": "string",
                "description": "Date for requested showtime"
              }
            },
            "required": [
              "location",
              "movie",
              "theater",
              "date"
            ]
          }
        }
      ]
    }
  ],
  "tool_config": {
    "function_calling_config": {
      "mode": "ANY",
      "allowed_function_names": ["find_theaters", "get_showtimes"]
    },
  }
}'

Mô hình này không thể dự đoán hàm find_movies vì hàm này không có trong danh sách hàm được phép, nên công cụ này sẽ dự đoán một hàm khác. Phản hồi có thể tương tự như sau:

Gọi hàm một lượt bằng cách sử dụng chế độ BẤT KỲ và các hàm được phép (phản hồi)

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_theaters",
              "args": {
                "location": "North Seattle, WA",
                "movie": null
              }
            }
          }
        ],
        "role": "model"
      },
      "finishReason": "STOP",
      "index": 0,
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "promptFeedback": {
    "safetyRatings": [
      {
        "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HATE_SPEECH",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_HARASSMENT",
        "probability": "NEGLIGIBLE"
      },
      {
        "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
        "probability": "NEGLIGIBLE"
      }
    ]
  }
}

Ví dụ về nhiều chặng

Bạn có thể triển khai tình huống gọi hàm nhiều lượt bằng cách làm như sau:

  1. Nhận phản hồi cho lệnh gọi hàm bằng cách gọi mô hình ngôn ngữ. Đây là sự kiện đầu tiên bật/tắt.
  2. Gọi mô hình ngôn ngữ bằng cách sử dụng phản hồi lệnh gọi hàm từ lượt đầu tiên và phản hồi hàm mà bạn nhận được khi gọi hàm đó. Đây là lượt thứ hai.

Phản hồi ở lượt thứ hai sẽ tóm tắt kết quả để trả lời truy vấn ở lượt đầu tiên hoặc chứa lệnh gọi hàm thứ hai mà bạn có thể sử dụng để lấy thêm thông tin cho truy vấn của bạn.

Chủ đề này bao gồm hai ví dụ về cuộn tròn nhiều lượt:

Sử dụng câu trả lời từ ngã rẽ trước

Mẫu curl sau đây gọi hàm và các đối số được trả về bởi ví dụ về lượt đơn trước đó để nhận phản hồi. Phương thức và thông số mà ví dụ về một lượt trả về đều có trong JSON này.

"functionCall": {
  "name": "find_theaters",
  "args": {
    "movie": "Barbie",
    "location": "Mountain View, CA"
  }
}

Hàm nhiều lượt gọi yêu cầu ví dụ về curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "function",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

Phản hồi cho ví dụ về curl này bao gồm kết quả của việc gọi phương thức find_theaters. Phản hồi này có thể tương tự như sau:

Phản hồi mẫu cho hàm nhiều lượt gọi curl

{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
          }
        ]
      }
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 9,
    "candidatesTokenCount": 27,
    "totalTokenCount": 36
  }
}

Gọi mô hình nhiều lần

Ví dụ cURL sau đây gọi mô hình AI tạo sinh nhiều lần để gọi một hàm. Mỗi lần mô hình gọi hàm này, mô hình có thể sử dụng một để trả lời một truy vấn người dùng khác trong yêu cầu.

Hàm nhiều lượt gọi yêu cầu ví dụ về curl

curl https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent?key=$API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "contents": [{
      "role": "user",
      "parts": [{
        "text": "Which theaters in Mountain View show Barbie movie?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "function",
    "parts": [{
      "functionResponse": {
        "name": "find_theaters",
        "response": {
          "name": "find_theaters",
          "content": {
            "movie": "Barbie",
            "theaters": [{
              "name": "AMC Mountain View 16",
              "address": "2000 W El Camino Real, Mountain View, CA 94040"
            }, {
              "name": "Regal Edwards 14",
              "address": "245 Castro St, Mountain View, CA 94040"
            }]
          }
        }
      }
    }]
  },
  {
    "role": "model",
    "parts": [{
      "text": " OK. Barbie is showing in two theaters in Mountain View, CA: AMC Mountain View 16 and Regal Edwards 14."
    }]
  },{
    "role": "user",
    "parts": [{
      "text": "Can we recommend some comedy movies on show in Mountain View?"
    }]
  }],
  "tools": [{
    "functionDeclarations": [{
      "name": "find_movies",
      "description": "find movie titles currently playing in theaters based on any description, genre, title words, etc.",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "description": {
            "type": "STRING",
            "description": "Any kind of description including category or genre, title words, attributes, etc."
          }
        },
        "required": ["description"]
      }
    }, {
      "name": "find_theaters",
      "description": "find theaters based on location and optionally movie title which is currently playing in theaters",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          }
        },
        "required": ["location"]
      }
    }, {
      "name": "get_showtimes",
      "description": "Find the start times for movies playing in a specific theater",
      "parameters": {
        "type": "OBJECT",
        "properties": {
          "location": {
            "type": "STRING",
            "description": "The city and state, e.g. San Francisco, CA or a zip code e.g. 95616"
          },
          "movie": {
            "type": "STRING",
            "description": "Any movie title"
          },
          "theater": {
            "type": "STRING",
            "description": "Name of the theater"
          },
          "date": {
            "type": "STRING",
            "description": "Date for requested showtime"
          }
        },
        "required": ["location", "movie", "theater", "date"]
      }
    }]
  }]
}'

Phản hồi mẫu cho hàm nhiều lượt gọi curl

[{
  "candidates": [
    {
      "content": {
        "parts": [
          {
            "functionCall": {
              "name": "find_movies",
              "args": {
                "description": "comedy",
                "location": "Mountain View, CA"
              }
            }
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE"
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE"
        }
      ]
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 48,
    "totalTokenCount": 48
  }
}
]

Các phương pháp hay nhất

Hãy làm theo các phương pháp hay nhất sau đây để cải thiện độ chính xác và độ tin cậy của các lệnh gọi hàm.

Lời nhắc người dùng

Để có kết quả tốt nhất, hãy thêm các thông tin chi tiết sau vào trước truy vấn của người dùng:

  • Bối cảnh bổ sung cho mô hình. Ví dụ: You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • Thông tin chi tiết hoặc hướng dẫn về cách thức và thời điểm sử dụng các hàm. Ví dụ: Don't make assumptions on showtimes. Always use a future date for showtimes.
  • Hướng dẫn đặt câu hỏi làm rõ nếu truy vấn của người dùng không rõ ràng. Để ví dụ: Ask clarifying questions if not enough information is available to complete the request.

Tham số lấy mẫu

Đối với tham số nhiệt độ, hãy sử dụng 0 hoặc một giá trị thấp khác. Thao tác này sẽ hướng dẫn mô hình này để tạo ra các kết quả đáng tin cậy hơn và giảm tình trạng ảo tưởng.

Lệnh gọi API

Nếu mô hình đề xuất lệnh gọi một hàm sẽ gửi một đơn đặt hàng, cập nhật cơ sở dữ liệu hoặc gây ra hậu quả đáng kể, xác thực lệnh gọi hàm với người dùng trước khi thực thi lệnh gọi hàm đó.