บทแนะนำการเรียกใช้ฟังก์ชัน

การเรียกฟังก์ชันช่วยให้คุณได้รับเอาต์พุตของ Structured Data ได้ง่ายขึ้น โมเดล Generative จากนั้นคุณสามารถใช้เอาต์พุตเหล่านี้เพื่อเรียกใช้ API อื่นๆ และแสดงผล ข้อมูลการตอบสนองที่เกี่ยวข้องกับโมเดล กล่าวคือ การเรียกใช้ฟังก์ชันจะช่วยคุณเชื่อมต่อโมเดล Generative กับระบบภายนอกเพื่อให้เนื้อหาที่สร้างขึ้นมีข้อมูลล่าสุดและถูกต้อง

คุณสามารถจัดเตรียมคำอธิบายฟังก์ชันต่างๆ ให้กับโมเดล Gemini ได้ ฟังก์ชันเหล่านี้คือฟังก์ชันที่คุณเขียนในภาษาของแอป (ไม่ใช่ฟังก์ชัน Google Cloud) โมเดลอาจขอให้คุณเรียกใช้ฟังก์ชันและส่งผลลัพธ์กลับเพื่อช่วยโมเดลจัดการการค้นหาของคุณ

หากยังไม่ได้ดู โปรดไปที่ ข้อมูลเบื้องต้นเกี่ยวกับการเรียกใช้ฟังก์ชันเพื่อเรียนรู้ อีกมากมาย

ตัวอย่าง API สำหรับการควบคุมแสง

ลองนึกภาพว่าคุณมีระบบควบคุมแสงพื้นฐานที่มีการเขียนโปรแกรมแอปพลิเคชัน อินเทอร์เฟซ (API) และคุณต้องการให้ผู้ใช้ควบคุมแสงไฟผ่าน คำขอแชท คุณสามารถใช้ฟีเจอร์การเรียกฟังก์ชันเพื่อตีความคําขอเปลี่ยนแปลงแสงจากผู้ใช้และแปลเป็นคําเรียก API เพื่อตั้งค่าแสงได้ ระบบควบคุมแสงสมมตินี้ช่วยให้คุณควบคุมความสว่างของแสงและอุณหภูมิสีของแสงได้ ซึ่งกำหนดเป็น 2 พารามิเตอร์แยกกัน ดังนี้

พารามิเตอร์ ประเภท ต้องระบุ คำอธิบาย
brightness ตัวเลข ใช่ ระดับแสงตั้งแต่ 0 ถึง 100 0 คือปิดและ 100 คือความสว่างเต็มที่
colorTemperature สตริง ใช่ อุณหภูมิสีของโคมไฟอาจเป็น daylight, cool หรือ warm

เพื่อความง่าย ระบบการจัดแสงในจินตนาการนี้จึงมีไฟเพียงดวงเดียว ดังนั้นผู้ใช้ โดยไม่ต้องระบุห้องหรือสถานที่ ต่อไปนี้คือตัวอย่างคําขอ JSON ที่คุณสามารถส่งไปยัง API การควบคุมแสงเพื่อเปลี่ยนระดับแสงเป็น 50% โดยใช้อุณหภูมิสีของแสงแดด

{
  "brightness": "50",
  "colorTemperature": "daylight"
}

บทแนะนำนี้จะแสดงวิธีตั้งค่าการเรียกฟังก์ชันสําหรับ Gemini API เพื่อตีความคําขอแสงของผู้ใช้และจับคู่กับการตั้งค่า API เพื่อควบคุมค่าความสว่างและอุณหภูมิสีของแสง

ก่อนเริ่มต้น: ตั้งค่าโปรเจ็กต์และคีย์ API

คุณต้องตั้งค่าโปรเจ็กต์และกำหนดค่าคีย์ API ก่อนเรียกใช้ Gemini API

กำหนดฟังก์ชัน API

สร้างฟังก์ชันที่สร้างคำขอ API ฟังก์ชันนี้ควรกำหนดภายในโค้ดของแอปพลิเคชัน แต่สามารถเรียกบริการหรือ API ที่อยู่นอกแอปพลิเคชันได้ Gemini API ไม่เรียกใช้ฟังก์ชันนี้โดยตรง คุณจึงควบคุมวิธีและเวลาเรียกใช้ฟังก์ชันนี้ผ่านโค้ดแอปพลิเคชันได้ สำหรับการสาธิตนี้ บทแนะนำนี้จะให้คำจำกัดความของฟังก์ชัน API จำลองที่ จะแสดงค่าแสงที่ขอ:

Future<Map<String, Object?>> setLightValues(
  Map<String, Object?> arguments,
) async =>
    // This mock API returns the requested lighting values
    {
      'brightness': arguments['brightness'],
      'colorTemperature': arguments['colorTemp'],
    };

สร้างการประกาศฟังก์ชัน

สร้างการประกาศฟังก์ชันที่จะส่งไปยังโมเดล Generative เมื่อประกาศฟังก์ชันให้โมเดลใช้ คุณควรระบุรายละเอียดให้มากที่สุดในคำอธิบายฟังก์ชันและพารามิเตอร์ โมเดล Generative ใช้ข้อมูลนี้เพื่อพิจารณาว่าควรเลือกฟังก์ชันใดและวิธีระบุค่าสำหรับพารามิเตอร์ในการเรียกใช้ฟังก์ชัน โค้ดต่อไปนี้แสดงวิธีประกาศฟังก์ชันการควบคุมแสง

final lightControlTool = FunctionDeclaration(
    'setLightValues',
    'Set the brightness and color temperature of a room light.',
    Schema(SchemaType.object, properties: {
      'brightness': Schema(SchemaType.number,
          description: 'Light level from 0 to 100. '
              'Zero is off and 100 is full brightness.'),
      'colorTemperature': Schema(SchemaType.string,
          description: 'Color temperature of the light fixture, '
              'which can be `daylight`, `cool` or `warm`.'),
    }, requiredProperties: [
      'brightness',
      'colorTemperature'
    ]));

ประกาศฟังก์ชันระหว่างการเริ่มต้นโมเดล

เมื่อต้องการใช้การเรียกฟังก์ชันกับโมเดล คุณต้องให้ การประกาศฟังก์ชันเมื่อคุณเริ่มต้นออบเจ็กต์โมเดล คุณประกาศฟังก์ชันได้โดยการตั้งค่าพารามิเตอร์ tools ของโมเดล นอกจากนี้ Dart SDK ยังรองรับการประกาศฟังก์ชันเป็นอาร์กิวเมนต์ของ generateContent หรือ generateContentStream API ด้วย

final model = GenerativeModel(
  model: 'gemini-1.5-flash',
  apiKey: apiKey,

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

สร้างการเรียกใช้ฟังก์ชัน

เมื่อเริ่มต้นโมเดลด้วยการประกาศฟังก์ชันแล้ว คุณจะแสดงพรอมต์ โมเดลที่มีฟังก์ชันที่กำหนด คุณควรใช้การเรียกใช้ฟังก์ชันโดยใช้พรอมต์แชท (sendMessage()) เนื่องจากโดยทั่วไปการเรียกใช้ฟังก์ชันจะมีประโยชน์จากบริบทของพรอมต์และการตอบกลับก่อนหน้า

final chat = model.startChat(); final prompt =
  'Dim the lights so the room feels cozy and warm.';

// 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.
    'setLightValues' => await setLightValues(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);
}