Lệnh gọi hàm giúp bạn dễ dàng nhận được đầu ra dữ liệu có cấu trúc từ các mô hình tạo sinh. Sau đó, bạn có thể sử dụng những dữ liệu đầu ra này để gọi các API khác và trả về dữ liệu phản hồi phù hợp cho mô hình. Nói cách khác, lệnh gọi hàm giúp bạn kết nối các mô hình tạo sinh với các hệ thống bên ngoài để nội dung được tạo có thông tin mới nhất và chính xác nhất.
Bạn có thể cung cấp cho mô hình Gemini nội dung mô tả về các hàm. Đây là các hàm mà bạn viết bằng ngôn ngữ của ứng dụng (tức là không phải là Hàm trên Google Cloud). Mô hình có thể yêu cầu bạn gọi một hàm và gửi lại kết quả để giúp mô hình xử lý truy vấn của bạn.
Nếu bạn chưa xem, hãy xem Giới thiệu về cách gọi hàm để tìm hiểu khác. Bạn cũng có thể hãy dùng thử tính năng này trong Google Colab hoặc xem mã ví dụ trong Kho lưu trữ Cẩm nang về Gemini API.
API mẫu để điều khiển ánh sáng
Giả sử bạn có một hệ thống điều khiển ánh sáng cơ bản bằng một chương trình lập trình ứng dụng giao diện (API) và bạn muốn cho phép người dùng điều khiển đèn thông qua yêu cầu tin nhắn văn bản. Bạn có thể sử dụng tính năng Gọi hàm để diễn giải các yêu cầu thay đổi ánh sáng của người dùng và dịch các yêu cầu đó thành lệnh gọi API để đặt các giá trị ánh sáng. Hệ thống điều khiển ánh sáng giả định này cho phép bạn kiểm soát độ sáng của ánh sáng và nhiệt độ màu của ánh sáng, được xác định là hai tham số riêng biệt:
| Thông số | Loại | Bắt buộc | Mô tả |
|---|---|---|---|
brightness |
số | có | Mức độ sáng từ 0 đến 100. Mức 0 đang tắt và mức 100 có độ sáng tối đa. |
colorTemperature |
string | có | Nhiệt độ màu của thiết bị chiếu sáng có thể là daylight, cool hoặc warm. |
Để đơn giản, hệ thống chiếu sáng tưởng tượng này chỉ có một đèn, vì vậy, người dùng không cần chỉ định phòng hoặc vị trí. Dưới đây là một yêu cầu JSON mẫu mà bạn có thể gửi đến API điều khiển ánh sáng để thay đổi độ sáng thành 50% bằng cách sử dụng nhiệt độ màu ban ngày:
{
"brightness": "50",
"colorTemperature": "daylight"
}
Hướng dẫn này chỉ cho bạn cách thiết lập Lệnh gọi hàm cho Gemini API để diễn giải các yêu cầu về chiếu sáng của người dùng và ánh xạ chúng tới chế độ cài đặt API để điều khiển các giá trị độ sáng và nhiệt độ màu của đèn.
Trước khi bắt đầu: Thiết lập dự án và khoá API
Trước khi gọi API Gemini, bạn cần thiết lập dự án và định cấu hình khoá API.
Xác định hàm API
Tạo một hàm tạo yêu cầu API. Bạn nên xác định hàm này trong mã của ứng dụng, nhưng có thể gọi các dịch vụ hoặc API bên ngoài ứng dụng. Gemini API không gọi trực tiếp chức năng này, vì vậy, bạn có thể kiểm soát cách thức và thời điểm thực thi hàm này thông qua ứng dụng của bạn . Để minh hoạ, hướng dẫn này xác định một hàm API mô phỏng chỉ trả về các giá trị ánh sáng được yêu cầu:
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
}
Khi bạn tạo một hàm để mô hình sử dụng trong lệnh gọi hàm, bạn phải bao gồm càng nhiều chi tiết càng tốt trong hàm và tham số nội dung mô tả. Mô hình tạo sinh sử dụng thông tin này để xác định hàm để chọn và cách cung cấp giá trị cho các tham số trong hàm .
Khai báo hàm trong quá trình khởi chạy mô hình
Khi muốn sử dụng lệnh gọi hàm với một mô hình, bạn phải khai báo hàm khi khởi tạo đối tượng mô hình. Bạn khai báo các hàm bằng cách đặt tham số tools của mô hình:
model = genai.GenerativeModel(model_name='gemini-1.5-flash',
tools=[set_light_values])
Tạo lệnh gọi hàm
Sau khi khởi tạo mô hình cùng với nội dung khai báo hàm, bạn có thể nhắc
mô hình có hàm được xác định. Bạn nên sử dụng lệnh gọi hàm bằng lời nhắc trò chuyện (sendMessage()), vì lệnh gọi hàm thường có lợi khi có ngữ cảnh của các lời nhắc và phản hồi trước đó.
chat = model.start_chat()
response = chat.send_message('Dim the lights so the room feels cozy and warm.')
response.text
SDK Python
ChatSession
đối tượng giúp đơn giản hoá việc quản lý các phiên trò chuyện bằng cách xử lý nhật ký trò chuyện
cho bạn. Bạn có thể sử dụng enable_automatic_function_calling để có SDK
tự động gọi hàm.
# Create a chat session that automatically makes suggested function calls
chat = model.start_chat(enable_automatic_function_calling=True)
Gọi hàm song song
Ngoài lệnh gọi hàm cơ bản được mô tả ở trên, bạn cũng có thể gọi nhiều hàm trong một lượt. Phần này trình bày một ví dụ về cách bạn có thể sử dụng lệnh gọi hàm song song.
Xác định công cụ.
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
Bây giờ, hãy gọi mô hình bằng một hướng dẫn có thể sử dụng tất cả các công cụ đã chỉ định.
# 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)
Mỗi kết quả in phản ánh một lệnh gọi hàm mà mô hình đã yêu cầu. Để gửi lại kết quả, hãy đưa các phản hồi theo thứ tự đã yêu cầu.
# 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! 🕺💃
Liên kết loại dữ liệu lệnh gọi của hàm
Tính năng tự động trích xuất giản đồ từ các hàm Python không hoạt động trong mọi trường hợp. Ví dụ: hàm này không xử lý các trường hợp bạn mô tả các trường của đối tượng từ điển lồng nhau, nhưng API lại hỗ trợ việc này. API này có thể mô tả bất kỳ loại nào sau đây:
AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])
Thư viện ứng dụng google.ai.generativelanguage cung cấp quyền truy cập vào các loại cấp thấp để bạn có toàn quyền kiểm soát.
Trước tiên, hãy xem bên trong thuộc tính _tools của mô hình, bạn có thể thấy cách thuộc tính này mô tả (các) hàm mà bạn đã truyền vào mô hình:
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"
}
}]
Thao tác này sẽ trả về danh sách các đối tượng genai.protos.Tool sẽ được gửi đến API. Nếu định dạng in không quen thuộc, thì đó là do đây là các lớp protobuf của Google. Mỗi genai.protos.Tool (1 trong trường hợp này) chứa một danh sách genai.protos.FunctionDeclarations mô tả một hàm và các đối số của hàm đó.
Dưới đây là nội dung khai báo cho cùng một hàm nhân được viết bằng các lớp genai.protos. Lưu ý rằng các lớp này chỉ mô tả hàm cho
API, chúng không bao gồm việc triển khai API. Vì vậy, việc sử dụng tính năng này không hiệu quả
bằng cách gọi hàm tự động, nhưng các hàm không phải lúc nào cũng cần
trong quá trình triển khai.
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']
)
)
])
Tương tự, bạn có thể mô tả đối tượng này là một đối tượng tương thích với 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"
}
}
Dù bằng cách nào, bạn cũng truyền nội dung đại diện cho genai.protos.Tool hoặc danh sách công cụ đến
model = genai.GenerativeModel('gemini-1.5-flash', tools=calculator)
chat = model.start_chat()
response = chat.send_message(
f"What's 234551 X 325552 ?",
)
Giống như trước, mô hình trả về một genai.protos.FunctionCall gọi hàm multiply của máy tính:
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
]
Tự thực thi hàm:
fc = response.candidates[0].content.parts[0].function_call
assert fc.name == 'multiply'
result = fc.args['a'] * fc.args['b']
result
76358547152.0
Gửi kết quả đến mô hình để tiếp tục cuộc trò chuyện:
response = chat.send_message(
genai.protos.Content(
parts=[genai.protos.Part(
function_response = genai.protos.FunctionResponse(
name='multiply',
response={'result': result}))]))