 Посмотреть на ai.google.dev |  Запустить в Google Colab |  Посмотреть исходный код на GitHub |
Вы можете предоставить модели Gemini описания функций. Модель может попросить вас вызвать функцию и отправить результат обратно, чтобы помочь модели обработать ваш запрос.
Настраивать
Установите SDK Python
Python SDK для Gemini API содержится в пакете google-generativeai . Установите зависимость с помощью 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.
В 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.'l10n
57*44
2508
Если вы посмотрите ChatSession.history вы увидите последовательность событий:
- Вы отправили вопрос.
- Модель ответила
glm.FunctionCall. -
genai.ChatSessionвыполнил функцию локально и отправил модели обратноglm.FunctionResponse. - Модель использовала выходные данные функции в своем ответе.
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. Если печатный формат вам не знаком, то это потому, что это классы Google protobuf. Каждый 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. Помните, что управляться в режиме чата проще из-за естественной структуры обмена сообщениями. Вы отвечаете за вызов функций и отправку результатов обратно в модель, чтобы она могла выдать текстовый ответ.