Gemini API: การเรียกฟังก์ชันด้วย Python

ดูใน ai.google.dev

เรียกใช้ใน Google Colab

ดูซอร์สบน GitHub

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

ตั้งค่า

ติดตั้ง Python SDK

Python SDK สำหรับ Gemini API อยู่ในแพ็กเกจ google-generativeai ติดตั้งทรัพยากร Dependency โดยใช้ PIP:

pip install -U -q google-generativeai

นำเข้าแพ็กเกจ

นำเข้าแพ็กเกจที่จำเป็น

import pathlib
import textwrap
import time

import google.generativeai as genai


from IPython import display
from IPython.display import Markdown

def to_markdown(text):
  text = text.replace('•', '  *')
  return Markdown(textwrap.indent(text, '> ', predicate=lambda _: True))

ตั้งค่าคีย์ API

คุณต้องขอรับคีย์ API ก่อน จึงจะใช้ Gemini API ได้ หากยังไม่มี ให้สร้างคีย์ด้วยคลิกเดียวใน Google AI Studio

รับคีย์ API

ใน Colab ให้เพิ่มคีย์ลงในตัวจัดการข้อมูลลับใต้ "🔑" ในแผงด้านซ้าย ตั้งชื่อว่า API_KEY

เมื่อมีคีย์ API แล้ว ให้ส่งคีย์ดังกล่าวไปยัง SDK โดยสามารถทำได้สองวิธี:

• ใส่คีย์ในตัวแปรสภาพแวดล้อม GOOGLE_API_KEY (SDK จะดึงคีย์จากที่นั่นโดยอัตโนมัติ)
• ส่งกุญแจไปยัง genai.configure(api_key=...)

try:
    # Used to securely store your API key
    from google.colab import userdata

    # Or use `os.getenv('API_KEY')` to fetch an environment variable.
    GOOGLE_API_KEY=userdata.get('GOOGLE_API_KEY')
except ImportError:
    import os
    GOOGLE_API_KEY = os.environ['GOOGLE_API_KEY']

genai.configure(api_key=GOOGLE_API_KEY)

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

คุณสามารถส่งรายการฟังก์ชันไปยังอาร์กิวเมนต์ tools เมื่อสร้าง genai.GenerativeModel

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

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

model

genai.GenerativeModel(
    model_name='models/gemini-1.0-pro',
    generation_config={},
    safety_settings={},
    tools=<google.generativeai.types.content_types.FunctionLibrary object at 0x10e73fe90>,
)

ขอแนะนำให้ใช้การเรียกใช้ฟังก์ชันผ่านอินเทอร์เฟซการแชท เหตุผลหลักก็คือ FunctionCalls เหมาะสมกับโครงสร้างแบบหมุนหลายทางของแชทพอดี

chat = model.start_chat(enable_automatic_function_calling=True)

เมื่อเปิดใช้การเรียกใช้ฟังก์ชันอัตโนมัติ chat.send_message จะเรียกใช้ฟังก์ชันของคุณโดยอัตโนมัติหากโมเดลขอให้ดำเนินการ

ดูเหมือนว่าจะส่งข้อความตอบกลับที่มีคำตอบที่ถูกต้อง:

response = chat.send_message('I have 57 cats, each owns 44 mittens, how many mittens is that in total?')
response.text

'The total number of mittens is 2508.'

57*44

2508

หากดูใน ChatSession.history คุณจะเห็นลําดับเหตุการณ์ดังนี้

1. คุณส่งคำถามแล้ว
2. โมเดลตอบกลับด้วย glm.FunctionCall
3. genai.ChatSession ได้เรียกใช้ฟังก์ชันในเครื่องและส่งโมเดล glm.FunctionResponse กลับคืนมา
4. โมเดลนี้ใช้เอาต์พุตของฟังก์ชันในคำตอบ

for content in chat.history:
    part = content.parts[0]
    print(content.role, "->", type(part).to_dict(part))
    print('-'*80)

user -> {'text': 'I have 57 cats, each owns 44 mittens, how many mittens is that in total?'}
--------------------------------------------------------------------------------
model -> {'function_call': {'name': 'multiply', 'args': {'a': 57.0, 'b': 44.0} } }
--------------------------------------------------------------------------------
user -> {'function_response': {'name': 'multiply', 'response': {'result': 2508.0} } }
--------------------------------------------------------------------------------
model -> {'text': 'The total number of mittens is 2508.'}
--------------------------------------------------------------------------------

โดยทั่วไปแผนภาพสถานะจะเป็นดังนี้

โมเดลจะตอบสนองด้วยการเรียกฟังก์ชันหลายรายการก่อนส่งคืนข้อความตอบกลับ และการเรียกใช้ฟังก์ชันจะมาก่อนข้อความตอบกลับ

แม้ว่าทั้งหมดนี้จะได้รับการจัดการโดยอัตโนมัติ แต่หากต้องการการควบคุมที่มากขึ้น คุณก็สามารถทำดังนี้

• ปล่อยค่าเริ่มต้น enable_automatic_function_calling=False ไว้และประมวลผลคำตอบ glm.FunctionCall ด้วยตนเอง
• หรือใช้ GenerativeModel.generate_content ซึ่งคุณต้องจัดการประวัติการแชทด้วย

[ไม่บังคับ] สิทธิ์เข้าถึงระดับต่ำ

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

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

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

import google.ai.generativelanguage as glm

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

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

model = genai.GenerativeModel(model_name='gemini-1.0-pro',
                             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"
   }
 }]

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

ต่อไปนี้เป็นการประกาศสำหรับฟังก์ชันการคูณเดียวกันที่เขียนโดยใช้คลาส glm

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

calculator = glm.Tool(
    function_declarations=[
      glm.FunctionDeclaration(
        name='multiply',
        description="Returns the product of two numbers.",
        parameters=glm.Schema(
            type=glm.Type.OBJECT,
            properties={
                'a':glm.Schema(type=glm.Type.NUMBER),
                'b':glm.Schema(type=glm.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']} }]}

glm.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"
  }
}

แต่ไม่ว่าจะเลือกแบบไหน คุณจะส่งผ่านตัวแทนกลุ่ม glm.Tool หรือรายชื่อเครื่องมือเพื่อ

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

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

เช่นเดียวกับก่อนที่โมเดลจะแสดงผล glm.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(
    glm.Content(
    parts=[glm.Part(
        function_response = glm.FunctionResponse(
          name='multiply',
          response={'result': result}))]))

สรุป

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