Lệnh gọi hàm giúp bạn dễ dàng nhận kết quả đầu ra 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 những dữ liệu đầ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, lệnh gọi hàm giúp bạn kết nối các mô hình tạo sinh với các hệ thống bên ngoài để nội dung được tạo có chứa thông tin mới nhất và chính xác nhất.
Bạn có thể cung cấp cho các mô hình Gemini phần mô tả các chức năng. Đây là các hàm mà bạn viết bằng ngôn ngữ của ứng dụng (nghĩa là không phải là Google Cloud Functions). Mô hình đó 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.
Hãy xem phần Giới thiệu về cách gọi hàm để tìm hiểu thêm (nếu bạn chưa xem).
API mẫu để điều khiển ánh sáng
Hãy tưởng tượng bạn có một hệ thống điều khiển ánh sáng cơ bản với giao diện lập trình ứng dụng (API) và bạn muốn cho phép người dùng điều khiển đèn thông qua các yêu cầu văn bản đơn giản. Bạn có thể sử dụng tính năng Gọi hàm để diễn giải các yêu cầu thay đổi ánh sáng từ người dùng và chuyển các yêu cầu đó thành lệnh gọi API để đặt giá trị ánh sáng. Hệ thống điều khiển ánh sáng giả định này cho phép bạn kiểm soát độ sáng của ánh sáng và nhiệt độ màu, được xác định bằng 2 thông số riêng biệt:
| Thông số | Loại | Bắt buộc | Nội dung mô tả |
|---|---|---|---|
brightness |
number | có | Mức độ sáng từ 0 đến 100. Mức 0 đang tắt và mức 100 có độ sáng tối đa. |
colorTemperature |
string | có | Nhiệt độ màu của thiết bị chiếu sáng có thể là daylight, cool hoặc warm. |
Để đơn giản, hệ thống chiếu sáng ảo này chỉ có một đèn, vì vậy, người dùng không phải chỉ định một phòng hoặc vị trí. Dưới đây là ví dụ về yêu cầu JSON mà bạn có thể gửi đến API điều khiển ánh sáng để thay đổi mức ánh sáng thành 50% theo nhiệt độ màu ban ngày:
{
"brightness": "50",
"colorTemperature": "daylight"
}
Hướng dẫn này cho bạn biết cách thiết lập Lệnh gọi hàm cho Gemini API để diễn giải các yêu cầu về ánh sáng của người dùng và ánh xạ các yêu cầu đó đến chế độ cài đặt API để điều khiển độ sáng và giá trị nhiệt độ màu của đèn.
Trước khi bắt đầu: Thiết lập dự án và khoá API của bạn
Trước khi gọi Gemini API, bạn cần thiết lập dự án và định cấu hình khoá API của mình.
Xác định hàm API
Tạo một hàm gửi yêu cầu API. Bạn nên xác định hàm này trong mã của ứng dụng, nhưng có thể gọi các dịch vụ hoặc API bên ngoài ứng dụng đó. Gemini API không gọi trực tiếp hàm này, vì vậy, bạn có thể kiểm soát cách thức và thời điểm thực thi hàm này thông qua mã xử lý ứng dụng. Để minh hoạ, hướng dẫn này xác định một hàm API mô phỏng chỉ trả về các giá trị ánh sáng được yêu cầu:
async function setLightValues(brightness, colorTemp) {
// This mock API returns the requested lighting values
return {
brightness: brightness,
colorTemperature: colorTemp
};
}
Tạo phần khai báo hàm
Tạo phần khai báo hàm mà bạn sẽ truyền đến mô hình tạo sinh. Khi khai báo một hàm để mô hình sử dụng, bạn nên đưa càng nhiều thông tin chi tiết càng tốt vào 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. Đoạn mã sau đây cho biết cách khai báo chức năng điều khiển ánh sáng:
// Function declaration, to pass to the model.
const controlLightFunctionDeclaration = {
name: "controlLight",
parameters: {
type: "OBJECT",
description: "Set the brightness and color temperature of a room light.",
properties: {
brightness: {
type: "NUMBER",
description: "Light level from 0 to 100. Zero is off and 100 is full brightness.",
},
colorTemperature: {
type: "STRING",
description: "Color temperature of the light fixture which can be `daylight`, `cool` or `warm`.",
},
},
required: ["brightness", "colorTemperature"],
},
};
// Executable function code. Put it in a map keyed by the function name
// so that you can call it once you get the name string from the model.
const functions = {
controlLight: ({ brightness, colorTemp }) => {
return setLightValues( brightness, colorTemp)
}
};
Khai báo hàm trong quá trình khởi tạo mô hình
Nếu muốn sử dụng lệnh gọi hàm bằng một mô hình, bạn phải khai báo hàm khi khởi tạo đối tượng mô hình. Bạn sẽ khai báo các hàm bằng cách đặt tham số tools của mô hình:
<html>
<body>
<!-- ... Your HTML and CSS -->
<script type="importmap">
{
"imports": {
"@google/generative-ai": "https://esm.run/@google/generative-ai"
}
}
</script>
<script type="module">
import { GoogleGenerativeAI } from "@google/generative-ai";
// Fetch your API_KEY
const API_KEY = "...";
// Access your API key (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(API_KEY);
// ...
const generativeModel = genAI.getGenerativeModel({
// Use a model that supports function calling, like a Gemini 1.5 model
model: "gemini-1.5-flash",
// Specify the function declaration.
tools: {
functionDeclarations: [controlLightFunctionDeclaration],
},
});
</script>
</body>
</html>
Tạo lệnh gọi hàm
Sau khi khởi tạo mô hình bằng nội dung khai báo hàm, bạn có thể nhắc
mô hình bằng hàm đã xác định. Bạn nên sử dụng phương thức gọi hàm bằng cách dùng tính năng nhắc trò chuyện (sendMessage()), vì lệnh gọi hàm thường có lợi ích từ việc có ngữ cảnh của các lời nhắc và câu trả lời trước đó.
const chat = generativeModel.startChat();
const prompt = "Dim the lights so the room feels cozy and warm.";
// Send the message to the model.
const result = await chat.sendMessage(prompt);
// For simplicity, this uses the first function call found.
const call = result.response.functionCalls()[0];
if (call) {
// Call the executable function named in the function call
// with the arguments specified in the function call and
// let it call the hypothetical API.
const apiResponse = await functions[call.name](call.args);
// Send the API response back to the model so it can generate
// a text response that can be displayed to the user.
const result = await chat.sendMessage([{functionResponse: {
name: 'controlLight',
response: apiResponse
}}]);
// Log the text response.
console.log(result.response.text());
}