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

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

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

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

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

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

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

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

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

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

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

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

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

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

async function setLightValues(brightness, colorTemp) {
  // This mock API returns the requested lighting values
  return {
    brightness: brightness,
    colorTemperature: colorTemp
  };
}

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

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

// 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)
  }
};

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

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

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

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

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

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());
}