ข้อมูลเบื้องต้นเกี่ยวกับการเรียกฟังก์ชันด้วย Gemini API

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

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

ดูตัวอย่างการเรียกใช้ฟังก์ชันได้ที่โน้ตบุ๊ก"light bot"

วิธีการทำงานของการเรียกฟังก์ชัน

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

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

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

เมื่อใช้การเรียกฟังก์ชันในพรอมต์ คุณกำลังสร้างออบเจ็กต์ tools ซึ่งมี function declarations อย่างน้อย 1 รายการ คุณกําหนดฟังก์ชันโดยใช้ JSON โดยเฉพาะกับชุดย่อยที่เลือกของรูปแบบสคีมา OpenAPI การประกาศฟังก์ชันเดียวอาจมีพารามิเตอร์ต่อไปนี้

  • name (สตริง): ตัวระบุที่ไม่ซ้ำกันสำหรับฟังก์ชันภายในการเรียก API
  • description (สตริง): คำอธิบายที่ครอบคลุมเกี่ยวกับวัตถุประสงค์และความสามารถของฟังก์ชัน
  • parameters (ออบเจ็กต์): กําหนดข้อมูลอินพุตที่จําเป็นสําหรับฟังก์ชัน
    • type (สตริง): ระบุประเภทข้อมูลโดยรวม เช่น object
    • properties (ออบเจ็กต์): แสดงรายการพารามิเตอร์แต่ละรายการ โดยแต่ละรายการจะมีข้อมูลต่อไปนี้
      • type (สตริง): ประเภทข้อมูลของพารามิเตอร์ เช่น string, integer, boolean
      • description (สตริง): คําอธิบายที่ชัดเจนเกี่ยวกับวัตถุประสงค์และรูปแบบที่คาดไว้ของพารามิเตอร์
    • required (อาร์เรย์): อาร์เรย์สตริงที่แสดงรายการชื่อพารามิเตอร์ที่จําเป็นต่อการทำงานของฟังก์ชัน

ดูตัวอย่างโค้ดของการประกาศฟังก์ชันโดยใช้คําสั่ง cURL ได้ที่ตัวอย่างการเรียกใช้ฟังก์ชัน ดูตัวอย่างการสร้างประกาศฟังก์ชันโดยใช้ Gemini API SDK ได้ที่บทแนะนำการเรียกใช้ฟังก์ชัน

แนวทางปฏิบัติแนะนำสำหรับการประกาศฟังก์ชัน

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

  • name: ใช้ชื่อที่สื่อความหมายชัดเจนโดยไม่มีเว้นวรรค จุด (.) หรือเครื่องหมายขีดกลาง (-) แต่ให้ใช้อักขระขีดล่าง (_) หรือตัวพิมพ์ใหญ่ขึ้นต้น

  • description: ระบุคำอธิบายฟังก์ชันที่ละเอียด ชัดเจน และเฉพาะเจาะจง พร้อมตัวอย่างหากจำเป็น เช่น ใช้ find theaters based on location and optionally movie title that is currently playing in theaters. แทน find theaters หลีกเลี่ยงคำอธิบายที่กว้างเกินไปหรือคลุมเครือ

  • properties > type: ใช้พารามิเตอร์ที่มีการกําหนดประเภทอย่างเข้มงวดเพื่อลดความสับสนของโมเดล เช่น หากค่าพารามิเตอร์มาจากชุดที่จำกัด ให้ใช้ช่อง enum แทนการระบุค่าในคำอธิบาย (เช่น "type": "enum", "values": ["now_playing", "upcoming"]) หากค่าพารามิเตอร์เป็นจํานวนเต็มเสมอ ให้ตั้งค่าประเภทเป็น integer แทน number

  • properties > description: ระบุตัวอย่างและข้อจำกัดที่ชัดเจน เช่น ใช้ The city and state, e.g. San Francisco, CA or a zip code e.g. 95616 แทน the location to search

ดูแนวทางปฏิบัติแนะนำเพิ่มเติมเมื่อใช้การเรียกฟังก์ชันได้ที่ส่วนแนวทางปฏิบัติแนะนำ

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

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

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

ระบบรองรับการใช้โหมด ANY ("การเรียกใช้ฟังก์ชันแบบบังคับ") สำหรับรุ่น Gemini 1.5 Pro และ Gemini 1.5 Flash เท่านั้น

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

ข้อมูลโค้ดต่อไปนี้จากคําขอตัวอย่างแสดงวิธีตั้งค่า mode เป็น ANY และระบุรายการฟังก์ชันที่อนุญาต

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

การเรียกใช้ฟังก์ชันแบบคอมโพสิชัน

Gemini 2.0 รองรับความสามารถในการเรียกใช้ฟังก์ชันใหม่ ซึ่งก็คือการเรียกใช้ฟังก์ชันแบบคอมโพสิชัน การเรียกฟังก์ชันแบบคอมโพสิชันช่วยให้ Gemini API สามารถเรียกใช้ฟังก์ชันที่ผู้ใช้กำหนดไว้หลายรายการโดยอัตโนมัติในกระบวนการสร้างคำตอบ ตัวอย่างเช่น หากต้องการตอบกลับพรอมต์ "Get the temperature in my current location" ทาง Gemini API อาจเรียกใช้ทั้งฟังก์ชัน get_current_location() และฟังก์ชัน get_weather() ที่ใช้ตำแหน่งเป็นพารามิเตอร์

การเรียกใช้ฟังก์ชันการคอมโพสิชันที่มีการดำเนินการโค้ดต้องใช้การสตรีมแบบ 2 ทิศทางและ Multimodal Live API ใหม่เท่านั้นที่รองรับ ต่อไปนี้เป็นตัวอย่างที่แสดงวิธีใช้การเรียกฟังก์ชันการคอมโพสิชัน การดำเนินการโค้ด และ Multimodal Live API ร่วมกัน

turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

นักพัฒนาซอฟต์แวร์ Python สามารถลองใช้ฟีเจอร์นี้ได้ในโน้ตบุ๊กการใช้เครื่องมือ API แบบเรียลไทม์

การใช้งานแบบหลายเครื่องมือ

เท่านั้นที่รองรับการใช้เครื่องมือหลายอย่าง

เมื่อใช้ Gemini 2.0 คุณจะเปิดใช้เครื่องมือหลายรายการพร้อมกันได้ และโมเดลจะเป็นผู้ตัดสินใจว่าจะเรียกใช้เครื่องมือใดเมื่อใด ต่อไปนี้คือตัวอย่างที่เปิดใช้เครื่องมือ 2 อย่าง ได้แก่ การกําหนดค่าโดยใช้ Google Search และการดำเนินการโค้ดในคําขอโดยใช้ Multimodal Live API

prompt = """
  Hey, I need you to do three things for me.

  1. Turn on the lights.
  2. Then compute the largest prime palindrome under 100000.
  3. Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
  """

tools = [
    {'google_search': {}},
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

นักพัฒนาซอฟต์แวร์ Python สามารถลองใช้เครื่องมือนี้ในโน้ตบุ๊กการใช้เครื่องมือ API แบบเรียลไทม์

ตัวอย่างการเรียกใช้ฟังก์ชัน

ส่วนนี้จะแสดงตัวอย่างพรอมต์สำหรับการเรียกใช้ฟังก์ชันโดยใช้คำสั่ง cURL ตัวอย่างมีตั้งแต่สถานการณ์เลี้ยวเดียวไปจนถึงเลี้ยวหลายครั้ง และการเปิดใช้โหมดการเรียกฟังก์ชันที่แตกต่างกัน

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

ตัวอย่างการเลี้ยวครั้งเดียว

รูปแบบการพูดครั้งเดียวคือเมื่อคุณเรียกใช้โมเดลภาษาเพียงครั้งเดียว เมื่อใช้การเรียกฟังก์ชัน Use Case แบบเทิร์นเดียวอาจเป็นกรณีที่คุณระบุการค้นหาที่เป็นภาษาธรรมชาติและรายการฟังก์ชันให้กับโมเดล ในกรณีนี้ โมเดลจะใช้การประกาศฟังก์ชัน ซึ่งประกอบด้วยชื่อฟังก์ชัน พารามิเตอร์ และคําอธิบาย เพื่อคาดคะเนว่าควรเรียกใช้ฟังก์ชันใดและควรใช้อาร์กิวเมนต์ใดในการเรียกใช้

ตัวอย่าง curl ต่อไปนี้เป็นตัวอย่างการส่งคำอธิบายของฟังก์ชันที่แสดงผลข้อมูลเกี่ยวกับสถานที่ที่ภาพยนตร์เล่น คำขอมีประกาศฟังก์ชันหลายรายการ เช่น find_movies และ find_theaters

คำขอตัวอย่างการเรียกฟังก์ชันแบบเทิร์นเดียว

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"
            ]
          }
        }
      ]
    }
  ]
}'
    

การตอบกลับสําหรับตัวอย่าง curl นี้อาจคล้ายกับตัวอย่างต่อไปนี้

การตอบกลับตัวอย่างการเรียกฟังก์ชันการเรียกใช้ 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
  }
}]
    

ตัวอย่างการเลี้ยวเดียวโดยใช้โหมดใดก็ได้

ตัวอย่างการใช้ curl ต่อไปนี้คล้ายกับตัวอย่างการเลี้ยวครั้งเดียว แต่ตั้งค่าmode เป็น ANY

"tool_config": {
  "function_calling_config": {
    "mode": "ANY"
  },
}

การเรียกฟังก์ชันแบบเทิร์นเดียวโดยใช้โหมดใดก็ได้ (คำขอ)

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"
    },
  }
}'
    

การตอบกลับอาจมีลักษณะคล้ายกับข้อความต่อไปนี้

การเรียกฟังก์ชันแบบเทิร์นเดียวโดยใช้โหมด ANY (การตอบกลับ)

{
  "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"
      }
    ]
  }
}
    

ตัวอย่างการเลี้ยวเดียวโดยใช้โหมด "ใดก็ได้" และฟังก์ชันที่อนุญาต

ตัวอย่างการใช้ curl ต่อไปนี้คล้ายกับตัวอย่างแบบเทิร์นเดียว แต่ตั้งค่า mode เป็น ANY และมีรายการฟังก์ชันที่อนุญาต

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

การเรียกฟังก์ชันแบบเทิร์นเดียวโดยใช้โหมด "ใดก็ได้" และฟังก์ชันที่อนุญาต (คำขอ)

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"]
    },
  }
}'
    

โมเดลไม่สามารถคาดการณ์ฟังก์ชัน find_movies เนื่องจากไม่ได้อยู่ในรายการฟังก์ชันที่อนุญาต จึงคาดการณ์ฟังก์ชันอื่นแทน การตอบกลับอาจมีลักษณะคล้ายกับตัวอย่างต่อไปนี้

การเรียกฟังก์ชันแบบเทิร์นเดียวโดยใช้โหมด "ใดก็ได้" และฟังก์ชันที่อนุญาต (การตอบกลับ)

{
  "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"
      }
    ]
  }
}
    

ตัวอย่างการสนทนาแบบหลายรอบ

คุณสามารถใช้สถานการณ์การเรียกฟังก์ชันแบบหลายรอบได้โดยทําดังนี้

  1. รับการตอบกลับการเรียกฟังก์ชันโดยเรียกใช้โมเดลภาษา นี่คือทางเลี้ยวแรก
  2. เรียกใช้โมเดลภาษาโดยใช้การตอบสนองการเรียกฟังก์ชันจากรอบแรก และการตอบสนองของฟังก์ชันที่คุณได้รับจากการเรียกใช้ฟังก์ชันนั้น นี่เป็นการหมุนครั้งที่ 2

การตอบกลับจากรอบที่ 2 จะสรุปผลลัพธ์เพื่อตอบคำถามของคุณในรอบที่ 1 หรือมีการเรียกใช้ฟังก์ชันที่ 2 ที่คุณสามารถใช้เพื่อรับข้อมูลเพิ่มเติมสำหรับคำค้นหา

หัวข้อนี้มีตัวอย่างการใช้ Curl แบบหลายรอบ 2 ตัวอย่างดังนี้

ใช้คำตอบจากรอบก่อนหน้า

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

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

คำขอตัวอย่างการเรียกฟังก์ชันหลายรอบของ curl

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"]
      }
    }]
  }]
}'
    

การตอบกลับของตัวอย่าง curl นี้จะมีผลลัพธ์ของการเรียกใช้เมธอด find_theaters การตอบกลับอาจมีลักษณะคล้ายกับข้อความต่อไปนี้

ตัวอย่างการตอบกลับการเรียกฟังก์ชันหลายรอบของ curl

{
  "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
  }
}
    

เรียกใช้โมเดลหลายครั้ง

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

คำขอตัวอย่างการเรียกฟังก์ชันหลายรอบของ curl

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"]
      }
    }]
  }]
}'
    

ตัวอย่างการตอบกลับการเรียกฟังก์ชันหลายรอบของ curl

[{
  "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
  }
}
]
    

แนวทางปฏิบัติแนะนำ

ทําตามแนวทางปฏิบัติแนะนําเหล่านี้เพื่อปรับปรุงความแม่นยำและความน่าเชื่อถือของคําเรียกฟังก์ชัน

พรอมต์ของผู้ใช้

ใส่รายละเอียดต่อไปนี้ไว้ข้างหน้าข้อความค้นหาของผู้ใช้เพื่อให้ได้ผลลัพธ์ที่ดีที่สุด

  • บริบทเพิ่มเติมสำหรับโมเดล ตัวอย่างเช่น You are a movie API assistant to help users find movies and showtimes based on their preferences.
  • รายละเอียดหรือวิธีการเกี่ยวกับวิธีและกรณีที่ควรใช้ฟังก์ชัน เช่น Don't make assumptions on showtimes. Always use a future date for showtimes.
  • วิธีการถามคำถามเพื่อชี้แจงหากคำค้นหาของผู้ใช้ไม่ชัดเจน เช่น Ask clarifying questions if not enough information is available to complete the request.

พารามิเตอร์การสุ่มตัวอย่าง

สําหรับพารามิเตอร์อุณหภูมิ ให้ใช้ 0 หรือค่าต่ำอื่นๆ ซึ่งจะบอกให้โมเดลสร้างผลลัพธ์ที่มั่นใจมากขึ้นและลดภาพหลอน

การเรียก API

หากโมเดลเสนอการเรียกใช้ฟังก์ชันที่จะส่งคำสั่งซื้อ อัปเดตฐานข้อมูล หรือมีผลที่ตามมาอย่างมีนัยสำคัญ ให้ตรวจสอบการเรียกใช้ฟังก์ชันกับผู้ใช้ก่อนดำเนินการ