ฟีเจอร์ "ค้นหาข้อมูลเกี่ยวกับสถานที่ตั้งปัจจุบัน" พร้อมให้บริการแล้วใน Google Search ดูข้อมูลเพิ่มเติม

หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

หากยังไม่ได้ดู โปรดไปที่ ข้อมูลเบื้องต้นเกี่ยวกับการเรียกใช้ฟังก์ชันเพื่อเรียนรู้ อีกมากมาย คุณยังสามารถ ลองใช้ฟีเจอร์นี้ใน Google Colab หรือดูโค้ดตัวอย่างใน ที่เก็บ Gemini API Cookbook

ตัวอย่าง 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 หากคุณยังไม่มี สร้างคีย์ใน Google AI Studio

รับคีย์ API

เราขอแนะนำอย่างยิ่งให้คุณไม่ตรวจสอบคีย์ API ในระบบควบคุมเวอร์ชัน

คุณควรจัดเก็บคีย์ API ในที่เก็บข้อมูลลับ เช่น Secret Manager ของ Google Cloud

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

ติดตั้งแพ็กเกจ SDK และกำหนดค่าคีย์ API

Python SDK สําหรับ Gemini API จะอยู่ในแพ็กเกจ google-generativeai

ติดตั้งการอ้างอิงโดยใช้ pip
```
pip install -U google-generativeai
```
นำเข้าแพ็กเกจและกำหนดค่าบริการด้วยคีย์ API ดังนี้
```
import os
import google.generativeai as genai

genai.configure(api_key=os.environ['API_KEY'])
```

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

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

def set_light_values(brightness, color_temp):
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {
        "brightness": brightness,
        "colorTemperature": color_temp
    }

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

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

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

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                              tools=[set_light_values])

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

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

chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text

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

# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)

การเรียกใช้ฟังก์ชันพร้อมกัน

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

กำหนดเครื่องมือ

def power_disco_ball(power: bool) -> bool:
    """Powers the spinning disco ball."""
    print(f"Disco ball is {'spinning!' if power else 'stopped.'}")
    return True


def start_music(energetic: bool, loud: bool, bpm: int) -> str:
    """Play some music matching the specified parameters.

    Args:
      energetic: Whether the music is energetic or not.
      loud: Whether the music is loud or not.
      bpm: The beats per minute of the music.

    Returns: The name of the song being played.
    """
    print(f"Starting music! {energetic=} {loud=}, {bpm=}")
    return "Never gonna give you up."


def dim_lights(brightness: float) -> bool:
    """Dim the lights.

    Args:
      brightness: The brightness of the lights, 0.0 is off, 1.0 is full.
    """
    print(f"Lights are now set to {brightness:.0%}")
    return True

ตอนนี้ให้เรียกใช้โมเดลพร้อมคําสั่งที่ใช้เครื่องมือที่ระบุทั้งหมดได้

# Set the model up with tools.
house_fns = [power_disco_ball, start_music, dim_lights]

model = genai.GenerativeModel(model_name="gemini-1.5-flash", tools=house_fns)

# Call the API.
chat = model.start_chat()
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call.
for part in response.parts:
    if fn := part.function_call:
        args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
        print(f"{fn.name}({args})")

power_disco_ball(power=True)
start_music(energetic=True, loud=True, bpm=120.0)
dim_lights(brightness=0.3)

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

# Simulate the responses from the specified tools.
responses = {
    "power_disco_ball": True,
    "start_music": "Never gonna give you up.",
    "dim_lights": True,
}

# Build the response parts.
response_parts = [
    genai.protos.Part(function_response=genai.protos.FunctionResponse(name=fn, response={"result": val}))
    for fn, val in responses.items()
]

response = chat.send_message(response_parts)
print(response.text)

Let's get this party started! I've turned on the disco ball, started playing some upbeat music, and dimmed the lights. 🎶✨  Get ready to dance! 🕺💃

การแมปประเภทข้อมูลการเรียกใช้ฟังก์ชัน

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

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

คลังไลบรารีไคลเอ็นต์ google.ai.generativelanguage ให้สิทธิ์เข้าถึงประเภทระดับต่ำซึ่งช่วยให้คุณควบคุมได้อย่างเต็มที่

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

def multiply(a:float, b:float):
    """returns a * b."""
    return a*b

model = genai.GenerativeModel(model_name='gemini-1.5-flash',
                             tools=[multiply])

model._tools.to_proto()

[function_declarations {
   name: "multiply"
   description: "returns a * b."
   parameters {
     type_: OBJECT
     properties {
       key: "b"
       value {
         type_: NUMBER
       }
     }
     properties {
       key: "a"
       value {
         type_: NUMBER
       }
     }
     required: "a"
     required: "b"
   }
 }]

การดำเนินการนี้จะแสดงรายการออบเจ็กต์ genai.protos.Tool ที่จะส่งไปยัง API หากไม่คุ้นเคยรูปแบบที่พิมพ์ นั่นเป็นเพราะรูปแบบเหล่านี้คือ Google Protobuf genai.protos.Tool แต่ละรายการ (ในกรณีนี้ 1 รายการ) มีรายการของ genai.protos.FunctionDeclarations ซึ่งอธิบายฟังก์ชันและ อาร์กิวเมนต์

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

calculator = genai.protos.Tool(
    function_declarations=[
      genai.protos.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=genai.protos.Schema(
            type=genai.protos.Type.OBJECT,
            properties={
                'a':genai.protos.Schema(type=genai.protos.Type.NUMBER),
                'b':genai.protos.Schema(type=genai.protos.Type.NUMBER)
            },
            required=['a','b']
        )
      )
    ])

คุณสามารถอธิบายออบเจ็กต์นี้เป็นออบเจ็กต์ที่เข้ากันได้กับ JSON ดังนี้

calculator = {'function_declarations': [
      {'name': 'multiply',
       'description': 'Returns the product of two numbers.',
       'parameters': {'type_': 'OBJECT',
       'properties': {
         'a': {'type_': 'NUMBER'},
         'b': {'type_': 'NUMBER'} },
       'required': ['a', 'b']} }]}

genai.protos.Tool(calculator)

function_declarations {
  name: "multiply"
  description: "Returns the product of two numbers."
  parameters {
    type_: OBJECT
    properties {
      key: "b"
      value {
        type_: NUMBER
      }
    }
    properties {
      key: "a"
      value {
        type_: NUMBER
      }
    }
    required: "a"
    required: "b"
  }
}

ไม่ว่าคุณจะใช้วิธีใด คุณก็ส่งผ่านการรับรอง genai.protos.Tool หรือรายการเครื่องมือเพื่อ

model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()

response = chat.send_message(
    f"What's 234551 X 325552 ?",
)

เช่นเดียวกับก่อนที่โมเดลจะส่งคืน genai.protos.FunctionCall ที่เรียกใช้ฟังก์ชัน multiply ของเครื่องคิดเลข ดังนี้

response.candidates

[index: 0
content {
  parts {
    function_call {
      name: "multiply"
      args {
        fields {
          key: "b"
          value {
            number_value: 325552
          }
        }
        fields {
          key: "a"
          value {
            number_value: 234551
          }
        }
      }
    }
  }
  role: "model"
}
finish_reason: STOP
]

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

fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'

result = fc.args['a'] * fc.args['b']
result

76358547152.0

ส่งผลลัพธ์ไปยังโมเดลเพื่อสนทนาต่อ

response = chat.send_message(
    genai.protos.Content(
    parts=[genai.protos.Part(
        function_response = genai.protos.FunctionResponse(
          name='multiply',
          response={'result': result}))]))