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

Khi sử dụng tính năng gọi hàm API Gemini, bạn có thể cung cấp định nghĩa hàm tuỳ chỉnh cho mô hình. Mô hình không trực tiếp gọi các hàm này mà tạo ra kết quả có cấu trúc chỉ định tên hàm và đối số được đề xuất. Sau đó, bạn có thể sử dụng tên hàm và đối số để gọi một API bên ngoài, đồng thời có thể kết hợp kết quả đầu ra của API vào một truy vấn khác cho mô hình, cho phép mô hình cung cấp phản hồi toàn diện hơn và thực hiện thêm các hành động.

Lệnh gọi hàm giúp người dùng tương tác với thông tin và các dịch vụ theo thời gian thực như cơ sở dữ liệu, hệ thống quản lý quan hệ khách hàng và kho lưu trữ tài liệu. Tính năng này cũng giúp nâng cao khả năng của mô hình trong việc cung cấp câu trả lời phù hợp và theo ngữ cảnh. Lệnh gọi hàm là cách tốt nhất để tương tác với các hệ thống bên ngoài. Nếu trường hợp sử dụng của bạn yêu cầu mô hình thực hiện tính toán nhưng không liên quan đến các hệ thống hoặc API bên ngoài, bạn nên cân nhắc sử dụng tính năng thực thi mã.

Để xem ví dụ về cách gọi hàm, hãy xem sổ ghi chú"light bot".

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ả giao diện lập trình, được gọi là khai báo hàm, vào lời nhắc của mô hình. Nội dung khai báo hàm cung cấp tên của hàm API, giải thích mục đích của hàm, mọi tham số mà hàm hỗ trợ và nội dung mô tả các tham số đó. Sau khi bạn truyền danh sách khai báo hàm trong một truy vấn đến mô hình, mô hình sẽ phân tích các khai báo hàm và phần còn lại của truy vấn để xác định cách sử dụng API đã khai báo nhằm phản hồi yêu cầu.

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

Khai báo hàm

Khi triển khai lệnh gọi hàm trong lời nhắc, 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 cách sử dụng JSON, cụ thể là bằng một nhóm con chọn lọc của định dạng giản đồ OpenAPI. Một phần khai báo hàm có thể bao gồm các tham số sau:

  • name (chuỗi): Giá trị nhận dạng duy nhất cho hàm trong lệnh gọi API.
  • description (chuỗi): Nội dung giải thích toàn diện về mục đích và chức năng của hàm.
  • parameters (đối tượng): Xác định dữ liệu đầu vào mà hàm cần.
    • type (chuỗi): Chỉ định loại dữ liệu tổng thể, chẳng hạn như object.
    • properties (đối tượng): Liệt kê các tham số riêng lẻ, 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): Nội dung giải thích rõ ràng về mục đích và định dạng dự kiến của tham số.
    • required (mảng): Một mảng các chuỗi liệt kê tên tham số bắt buộc để hàm hoạt động.

Để biết ví dụ về mã khai báo hàm bằng lệnh cURL, hãy xem Ví dụ về lệnh gọi hàm. Để xem ví dụ về cách tạo nội dung khai báo hàm bằng SDK API Gemini, hãy xem Hướng dẫn 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 hàm khi tích hợp các hàm đó vào yêu cầu. Mỗi hàm đều dựa vào các tham số cụ thể để hướng dẫn hành vi và tương tác với mô hình. Danh sách sau đây cung cấp hướng dẫn về cách định nghĩa các tham số của một hàm riêng lẻ trong mảng functions_declarations.

  • name: Sử dụng tên rõ ràng, 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 ký tự dấu gạch dưới (_) hoặc viết hoa kiểu camel.

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

  • properties > type: Sử dụng các tham số được xác định kiểu để giảm thiểu hiện tượng ảo giác mô hình. Ví dụ: nếu các giá trị thông số là từ một tập hợp có giới hạn, 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à số nguyên, hãy đặt loại thành integer thay vì number.

  • properties > description: Cung cấp các ví dụ và quy tắc ràng buộc cụ thể. Ví dụ: thay vì the location to search, hãy sử dụng The city and state, e.g. San Francisco, CA or a zip code e.g. 95616.

Để 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 hành vi thực thi của tính năng. Có 3 chế độ:

  • AUTO: Hành vi mặc định của mô hình. Mô hình quyết định dự đoán lệnh gọi hàm hoặc câu trả lời bằng ngôn ngữ tự nhiên.
  • ANY: Mô hình bị ràng buộc để luôn dự đoán lệnh gọi hàm. Nếu bạn không cung cấp allowed_function_names, thì mô hình sẽ chọn trong số tất cả các nội dung khai báo hàm hiện có. Nếu allowed_function_names được cung cấp, mô hình sẽ chọn trong 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, hành vi của mô hình 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 ("buộc gọi hàm") chỉ được hỗ trợ cho các mô hình Gemini 1.5 Pro và Gemini 1.5 Flash.

Bạn cũng có thể truyền một tập hợp allowed_function_names (khi được cung cấp) để giới hạn các hàm mà mô hình sẽ gọi. Bạn chỉ nên đưa allowed_function_names vào khi chế độ là ANY. Tên hàm phải khớp với tên khai báo hàm. Khi chế độ được đặt thành ANY và tập hợp 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 được cung cấp.

Đoạn mã sau đây từ một yêu cầu mẫu cho biết cách đặt mode thành ANY và 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ề lệnh gọi hàm

Phần này cung cấp lời nhắc mẫu để gọi hàm bằng các lệnh cURL. Các ví dụ bao gồm các tình huống rẽ một lần và nhiều lần, cũng như 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, thông tin về hàm và tham số sẽ được đưa vào phần tử tools. Mỗi phần khai báo hàm trong phần tử tools chứa tên hàm và bạn chỉ định các tham số bằng cách sử dụng giản đồ tương thích với OpenAPI và nội dung mô tả hàm.

Ví dụ về một lượt

Một lượt là khi bạn gọi mô hình ngôn ngữ một lần. Với lệnh 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 một truy vấn bằng ngôn ngữ tự nhiên và danh sách hàm. Trong trường hợp này, mô hình sử dụng phần khai báo hàm, bao gồm tên hàm, tham số và nội dung mô tả, để dự đoán hàm nào sẽ được gọi và các đối số để gọi hàm đó.

Mẫu curl sau đây là ví dụ về cách truyền vào nội dung mô tả một hàm trả về thông tin về nơi phát phim. Yêu cầu này bao gồm một số nội dung khai báo hàm, chẳng hạn như find_movies và find_theaters.

Yêu cầu ví dụ về lệnh 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 về lệnh gọi hàm một lượt curl

[{
  "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 rẽ sử dụng chế độ BẤT KỲ

Ví dụ sau về curl tương tự như ví dụ về một lượt, nhưng đặ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)

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 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 rẽ sử dụng chế độ BẤT KỲ và các hàm được phép

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

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

Gọi hàm một lượt bằ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 không thể dự đoán hàm find_movies vì hàm này không có trong danh sách các hàm được phép, do đó, mô hình 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 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 lượt

Bạn có thể triển khai một 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 lệnh gọi hàm bằng cách gọi mô hình ngôn ngữ. Đây là lượt rẽ đầu tiên.
  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 từ lượt thứ hai tóm tắt kết quả để trả lời truy vấn của bạn trong 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 để nhận thêm thông tin cho truy vấn của mình.

Chủ đề này bao gồm hai ví dụ về curl nhiều vòng:

Sử dụng câu trả lời từ một lượt trước

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

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

Yêu cầu ví dụ về lệnh curl gọi hàm nhiều 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?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "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 có thể tương tự như sau:

Phản hồi ví dụ về lệnh gọi hàm nhiều lượt cuộn

{
  "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ụ sau về cURL 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, mô hình có thể sử dụng một hàm khác để trả lời một truy vấn khác của người dùng trong yêu cầu.

Yêu cầu ví dụ về lệnh curl gọi hàm nhiều 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?"
    }]
  }, {
    "role": "model",
    "parts": [{
      "functionCall": {
        "name": "find_theaters",
        "args": {
          "location": "Mountain View, CA",
          "movie": "Barbie"
        }
      }
    }]
  }, {
    "role": "user",
    "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 ví dụ về lệnh gọi hàm nhiều lượt cuộn

[{
  "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 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 sau vào đầu cụm từ tìm kiếm của người dùng:

  • Ngữ 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 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 cụm từ tìm kiếm 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. Điều này hướng dẫn mô hình tạo ra kết quả đáng tin cậy hơn và giảm các ảo giác.

Lệnh gọi API

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