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

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

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

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

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

สมมติว่าคุณมีระบบควบคุมแสงพื้นฐานที่มี Application Programming Interface (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 จําลองเพื่อสาธิต ซึ่งจะแสดงเฉพาะค่าแสงที่ขอ

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

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

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

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, colorTemperature }) => {
    return setLightValues( brightness, colorTemperature)
  }
};

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

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

const { GoogleGenerativeAI } = require("@google/generative-ai");

// Access your API key as an environment variable (see "Set up your API key" above)
const genAI = new GoogleGenerativeAI(process.env.API_KEY);

// ...

const generativeModel = genAI.getGenerativeModel({
  // Use a model that supports function calling, like a Gemini 1.5 model
  model: "gemini-2.0-flash",

  // Specify the function declaration.
  tools: {
    functionDeclarations: [controlLightFunctionDeclaration],
  },
});

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

เมื่อเริ่มต้นโมเดลด้วยการประกาศฟังก์ชันแล้ว คุณสามารถพรอมต์โมเดลด้วยฟังก์ชันที่กําหนดได้ คุณควรใช้การเรียกใช้ฟังก์ชันโดยใช้พรอมต์แชท (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 result2 = await chat.sendMessage([{functionResponse: {
    name: 'controlLight',
    response: apiResponse
  }}]);

  // Log the text response.
  console.log(result2.response.text());
}

ตัวเลือกเพิ่มเติม

โหมดการเรียกใช้ฟังก์ชัน

คุณสามารถใช้พารามิเตอร์การเรียกฟังก์ชัน mode เพื่อแก้ไขลักษณะการทํางานของฟีเจอร์ โดยจะมี 3 โหมดให้เลือกดังนี้

  • AUTO: ลักษณะการทํางานเริ่มต้นของรูปแบบ โมเดลจะตัดสินใจว่าจะคาดการณ์การเรียกใช้ฟังก์ชันหรือการตอบกลับด้วยภาษาธรรมชาติ
  • ANY: โมเดลถูกจํากัดให้คาดการณ์การเรียกฟังก์ชันเสมอ หากไม่ได้ระบุ allowed_function_names โมเดลจะเลือกจากประกาศฟังก์ชันทั้งหมดที่ใช้ได้ หากระบุ allowed_function_names ไว้ โมเดลจะเลือกจากชุดฟังก์ชันที่อนุญาต
  • NONE: โมเดลจะไม่คาดการณ์การเรียกใช้ฟังก์ชัน ในกรณีนี้ ลักษณะการทํางานของโมเดลจะเหมือนกับในกรณีที่คุณไม่ได้ส่งประกาศฟังก์ชันใดๆ

นอกจากนี้ คุณยังส่งชุด allowed_function_names ซึ่งจะจำกัดฟังก์ชันที่โมเดลจะเรียกใช้ได้อีกด้วย คุณควรใส่ allowed_function_names เฉพาะเมื่อโหมดเป็น ANY ชื่อฟังก์ชันควรตรงกับชื่อประกาศฟังก์ชัน เมื่อตั้งค่าโหมดเป็น ANY และตั้งค่า allowed_function_names แล้ว โมเดลจะคาดคะเนการเรียกใช้ฟังก์ชันจากชุดชื่อฟังก์ชันที่ระบุ

คุณสามารถระบุโหมดการเรียกฟังก์ชันได้โดยการตั้งค่าพารามิเตอร์ toolConfig เมื่อเริ่มต้นโมเดล Generative

const generativeModel2 = genAI.getGenerativeModel({
  // Setting a function calling mode is only available in Gemini 1.5 Pro.
  model: "gemini-1.5-pro-latest",
  tools: {
    functionDeclarations: [getExchangeRateFunctionDeclaration],
  },
  toolConfig: {
    functionCallingConfig: {
      // Possible values are: Mode.AUTO, Mode.ANY, Mode.NONE
      mode: FunctionCallingMode.ANY
    }
  }
});