1. Descripción general
¿Qué son las llamadas a funciones en Gemini?
La API de Vertex AI Gemini es una familia de modelos de IA generativa que desarrolló Google DeepMind y que están diseñados para casos de uso multimodales. Las llamadas a funciones son una característica de los modelos de Gemini que facilita a los desarrolladores obtener resultados de datos estructurados de los modelos generativos.
Luego, los desarrolladores pueden usar estos resultados para llamar a otras APIs y devolver los datos de respuesta pertinentes al modelo. En otras palabras, la llamada a función te ayuda a conectar tus modelos generativos a sistemas externos para que el contenido generado incluya la información más actualizada y precisa.
Cómo funciona la llamada a función
Las funciones se describen con declaraciones de funciones, lo que ayuda al modelo generativo a comprender el propósito y los parámetros dentro de una función. Después de pasar declaraciones de funciones en una consulta a un modelo generativo, el modelo devuelve un objeto estructurado que incluye los nombres de las funciones pertinentes y sus argumentos según la consulta del usuario. Ten en cuenta que, con la llamada a función, el modelo no llama a la función en realidad. En su lugar, puedes usar la función y los parámetros devueltos para llamar a la función en cualquier lenguaje, biblioteca o framework que desees.
Qué compilarás
En este codelab, crearás una canalización de IA generativa con la API de Vertex AI Gemini y Python. Con tu app, los usuarios pueden preguntar sobre los tipos de cambio, y el sistema recuperará los datos más recientes de una API externa y le responderá al usuario con la respuesta.
Qué aprenderás
- Cómo interactuar con el modelo de Gemini usando la biblioteca cliente de Python
- Cómo definir una declaración de función y registrarla como herramienta
- Cómo llamar a Gemini y obtener una respuesta de llamada a función
- Cómo devolver la respuesta de la función a Gemini y responder al usuario
Requisitos
- Un proyecto de Google Cloud
- Un navegador, como Chrome
- Un entorno de desarrollo de Python, como Colab o Colab Enterprise
2. Configuración y requisitos
Antes de comenzar a usar las llamadas a funciones en Gemini, debes habilitar la API de Vertex AI y, luego, instalar la versión más reciente de la biblioteca cliente de Vertex AI para Python.
Habilitar la API de Vertex AI
Para habilitar la API de Vertex AI, sigue estos pasos:
- En tu navegador, ve a la página de detalles del servicio de la API de Vertex AI.
- Haz clic en el botón Habilitar para habilitar la API de Vertex AI en tu proyecto de Google Cloud.
Instala la biblioteca cliente de Python para Vertex AI
Para instalar las bibliotecas cliente de Python para Vertex AI, sigue estos pasos:
- Abre una terminal en tu entorno de desarrollo.
- Verifica que tengas un entorno de desarrollo de Python válido y consulta estos lineamientos si es necesario.
- Ejecuta el siguiente comando para instalar la biblioteca cliente de Python para Vertex AI:
pip install --upgrade google-cloud-aiplatform - Si ejecutas el código en un entorno de notebook, es posible que debas reiniciar el kernel o el entorno de ejecución para usar los paquetes recién instalados.
Ya puedes usar la API de Vertex AI.
3. Comprende el problema
¿Alguna vez interactuaste con un modelo de lenguaje grande o un modelo de IA generativa y le preguntaste sobre información actual o en tiempo real, solo para obtener una respuesta con información desactualizada o imprecisa?
¡Probémoslo! Primero, importaremos los paquetes de Python pertinentes y, luego, inicializaremos el modelo de Gemini. Puedes ejecutar el siguiente código en un entorno de desarrollo de Python, como Colab o Colab Enterprise, y, para ello, instala la versión más reciente del SDK de Vertex AI para Python:
import vertexai
from vertexai.generative_models import GenerativeModel
model = GenerativeModel("gemini-1.5-pro-001")
Ahora, hagamos una pregunta sobre el tipo de cambio de diferentes monedas hoy:
response = model.generate_content(
"What's the exchange rate for euros to dollars today?"
)
print(response.text)
El modelo debería generar una respuesta limitada o desactualizada similar a la siguiente:
As an AI language model, I don't have access to real-time currency exchange rates. However, as of my last update in September 2021, the approximate exchange rate between euros (EUR) and US dollars (USD) was: 1 EUR ≈ 1.18 USD Please note that currency exchange rates constantly fluctuate and can vary depending on various factors such as economic conditions, supply and demand, political events, and more. To obtain the most up-to-date and accurate exchange rate, I recommend using a reliable currency converter or financial website that provides live rates. [...]
Si un usuario final recibiera este tipo de respuesta, debería cambiar de contexto para buscar las monedas que le interesan, recuperar el tipo de cambio más reciente y realizar las conversiones por su cuenta.
Idealmente, una canalización de modelos generativos podría controlar algunas o todas estas tareas para el usuario. En la siguiente sección, probarás algunas soluciones alternativas comunes para obtener respuestas estructuradas de los modelos generativos, de modo que puedas llamar a sistemas externos.
4. Prueba soluciones alternativas comunes
Cuando trabajas con modelos generativos en situaciones en las que necesitas información o datos actualizados de fuentes externas, puedes llamar a una API externa y, luego, ingresar los resultados en el modelo generativo para que los use en su respuesta.
Antes de llamar a un sistema externo, debes determinar la función correcta que se debe usar, extraer los parámetros pertinentes del usuario y colocar los parámetros en un objeto de datos estructurados. Por lo general, esto implica una ingeniería de instrucciones exhaustiva para obligar al modelo generativo a producir datos estructurados válidos.
Volvamos a la pregunta que hicimos en la sección anterior y agreguemos algunas instrucciones adicionales para el modelo. Intenta enviar la siguiente solicitud al modelo de Gemini:
user_prompt = "What's the exchange rate from euros to US dollars today?"
response = model.generate_content("""
Your task is to extract parameters from the user's input and return it as a
structured JSON payload. The user will ask about the exchange rate and which
currency they are converting from and converting to.
User input: {user_prompt}
Please extract the currencies as parameters and put them in a JSON object.
""".format(user_prompt=user_prompt))
print(response.text)
El resultado es la siguiente respuesta de texto, que no es un JSON válido y con la que nos resultará difícil trabajar:
```json
{
"currency_from": "euros",
"currency_to": "US dollars"
}
```
En particular, la primera y la última línea de la respuesta de texto incluyen comillas inversas para delimitar el bloque de código, la primera línea incluye un especificador de lenguaje y los valores del objeto JSON no son las abreviaturas estándar de tres letras de las monedas que una API de intercambio de divisas esperaría como parámetros de entrada.
Podríamos intentar usar Python para posprocesar este texto en un diccionario y un JSON válidos, agregar más instrucciones a la instrucción, proporcionar uno o más ejemplos del resultado deseado, ajustar el modelo o realizar otra llamada al modelo generativo para pedirle que limpie el JSON.
Pero hay una forma más determinística. Aprendamos a usar las llamadas a funciones en Gemini para consultar información en servicios externos y devolver respuestas pertinentes a los usuarios finales.
5. Cómo funciona la llamada a función
Antes de comenzar con la extracción de parámetros y la llamada a función, veamos los pasos de la llamada a función y los componentes que se usan en el tiempo de ejecución.
Entrada del usuario a la API de Gemini
La instrucción del usuario se envía a la API de Gemini, y, en esa llamada a la API del modelo de Gemini, el desarrollador definió una o más declaraciones de funciones dentro de una herramienta para que el modelo de Gemini sepa qué funciones puede llamar y cómo llamarlas.
La API de Gemini devuelve una llamada a función
Según el contenido de la entrada y la instrucción del usuario, Gemini devolverá una respuesta de llamada a función con datos estructurados que incluyen el nombre de la función a la que se debe llamar y los parámetros correspondientes que se deben usar.
Realiza una solicitud a la API
Luego, usarás el nombre y los parámetros de la función para realizar una solicitud a la API y recuperar información de un sistema o una API externos. El desarrollador implementa esta solicitud y respuesta de la API en el código de la aplicación, y se produce fuera del alcance de la API y el SDK de Gemini. Por ejemplo, puedes usar la biblioteca requests en Python para llamar a una API de REST y recibir una respuesta JSON. También puedes llamar a la función con tu enfoque y biblioteca cliente preferidos.
Devuelve la respuesta de la API a Gemini
Por último, pasarás la respuesta de la API al modelo de Gemini para que pueda generar una respuesta a la instrucción inicial del usuario final o invocar otra respuesta de llamada a función si el modelo de Gemini determina que necesita información adicional.
6. Elige tu API
Ahora que comprendes el flujo general y los pasos específicos de las llamadas a funciones, compilarás una canalización de IA generativa para recuperar los tipos de cambio más recientes. Primero, deberemos seleccionar la API que queremos usar como fuente de información.
En el caso de nuestra app de cambio de divisas, usaremos la API de REST en https://www.frankfurter.app/ para recuperar la información más reciente sobre los tipos de cambio globales.
Para interactuar con esta API de REST, podríamos hacer una llamada a la API de REST con requests en Python de la siguiente manera:
import requests
url = "https://api.frankfurter.app/latest"
response = requests.get(url)
response.text
o una solicitud cURL como la siguiente:
curl https://api.frankfurter.app/latest
que devuelve una respuesta similar a la siguiente:
{
"amount": 1,
"base": "EUR",
"date": "2023-12-20",
"rates": {
"AUD": 1.6186, "BGN": 1.9558, "BRL": 5.3287,
"CAD": 1.4609, "CHF": 0.946, "CNY": 7.8121,
"CZK": 24.538, "DKK": 7.4565, "GBP": 0.86555,
"HKD": 8.5439, "HUF": 385.23, "IDR": 16994,
"ILS": 3.9983, "INR": 91.06, "ISK": 150.3,
"JPY": 157.12, "KRW": 1425.62, "MXN": 18.6867,
"MYR": 5.0977, "NOK": 11.2895, "NZD": 1.7421,
"PHP": 60.991, "PLN": 4.3413, "RON": 4.9699,
"SEK": 11.129, "SGD": 1.4562, "THB": 38.252,
"TRY": 31.883, "USD": 1.0944, "ZAR": 20.111
}
}
Dado que la llamada a función en Gemini no realiza la llamada a la API externa por ti, no existen restricciones sobre el tipo de API que usas. Podrías usar un servicio de Cloud Run, una Cloud Function, una solicitud a una API de un servicio de Google Cloud o cualquier API de REST externa.
7. Define una función y una herramienta
Ahora que seleccionaste una API de REST para usar, podemos definir una especificación de API y registrar la función en una herramienta.
Asegúrate de haber instalado la versión más reciente del SDK de Vertex AI para Python.
Luego, importa los módulos necesarios del SDK de Python y, luego, inicializa el modelo de Gemini:
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
Si volvemos a la API de REST en https://api.frankfurter.app/, podemos ver que acepta los siguientes parámetros de entrada:
Parámetro | Tipo | Descripción |
| String | Moneda desde la que se realizará la conversión |
| String | Moneda a la que se convertirá |
| String | Fecha para la que se recuperará el tipo de cambio |
Con estos parámetros, una especificación parcial de OpenAPI para esta API de REST en formato YAML se ve de la siguiente manera:
openapi: 3.0.0
info:
title: Frankfurter Exchange Rate API
description: This API provides current and historical exchange rates
version: 1.0.0
servers:
- url: https://api.frankfurter.app
paths:
/{date}:
get:
summary: Get the latest currency exchange rates.
parameters:
- name: date
in: path
description: Get currency rates for a specific date or 'latest' if a date is not specified
required: true
schema:
type: string
- name: from
in: query
description: The currency to convert from.
required: true
schema:
type: string
- name: to
in: query
description: The currency to convert to.
schema:
type: string
Ahora, registremos esto como un FunctionDeclaration con el SDK de Python para Gemini:
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
Asegúrate de usar la mayor cantidad de detalles posible en las descripciones de las funciones y los parámetros, ya que el modelo generativo usará esta información para determinar qué función seleccionar y cómo completar los parámetros en la llamada a función.
Por último, definirás un Tool que incluya la declaración de la función:
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
Aquí, usas una declaración de función dentro de una herramienta, pero ten en cuenta que puedes registrar una o más declaraciones de función en una herramienta, y el modelo seleccionará la función adecuada para usar en el tiempo de ejecución. Consulta la documentación sobre la Llamada a función en la API de Gemini para obtener más detalles sobre FunctionDeclaration, Tool y las clases relacionadas en el SDK de Gemini para Python.
Completaste la configuración de las definiciones de funciones y herramientas. En la siguiente sección, llamaremos al modelo generativo con esta herramienta y obtendremos una llamada a función que podremos usar para llamar a la API de REST.
8. Genera una llamada a función
Ahora puedes solicitarle al modelo generativo que incluya el tool que definiste:
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
Echemos un vistazo al objeto de respuesta:
print(response.candidates[0].content)
role: "model"
parts {
function_call {
name: "get_exchange_rate"
args {
fields {
key: "currency_to"
value {
string_value: "SEK"
}
}
fields {
key: "currency_from"
value {
string_value: "AUD"
}
}
fields {
key: "currency_date"
value {
string_value: "latest"
}
}
}
}
}
Parece que el modelo seleccionó la única función disponible y devolvió una llamada a la función get_exchange_rate junto con los parámetros. Además, los parámetros están en el formato correcto que queríamos. ¡Hurra por obtener respuestas estructuradas de los modelos generativos!
En la siguiente sección, usarás la información de la respuesta para realizar una solicitud a la API.
9. Realiza una solicitud a la API
Recuerda que las llamadas a funciones en Gemini no realizan la llamada a la API externa por ti. En cambio, puedes usar cualquier lenguaje, biblioteca o framework que desees.
Aquí usarás la biblioteca requests en Python para llamar a la API de REST de tipos de cambio.
Desempaquemos la respuesta en un diccionario de Python:
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
Ahora podemos llamar a requests o a cualquier otro método:
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
Lo que genera una respuesta similar a la siguiente:
'{"amount":1.0,"base":"AUD","date":"2024-01-16","rates":{"SEK":6.8682}}'
Y tenemos nuestra respuesta de la API de REST, con la información más reciente del tipo de cambio de hoy. En la siguiente sección, le pasaremos esta información al modelo para que pueda generar una respuesta pertinente para el usuario.
10. Genera una respuesta
Por último, generemos una respuesta para el usuario devolviendo la respuesta de la función al modelo en el siguiente turno de conversación:
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
Una vez que devolvemos la respuesta de la función al modelo, este responderá a la instrucción del usuario junto con la información pertinente de la respuesta de la API.
The exchange rate from Australian dollars to Swedish krona on January 16, 2024, is 1 Australian dollar is equal to 6.8663 Swedish krona. So, 500 Australian dollars would be worth 500 * 6.8663 = 3,433.15 Swedish krona.
11. Consulta el ejemplo de código completo
En este punto, podrías colocar tu código de Python en una API de backend con un servicio de Cloud Run, una Cloud Function o algún otro servicio de Cloud, y, luego, implementar una app de frontend que use esta API de backend para realizar consultas de modelos y llamadas a la API.
Este es el ejemplo de código completo de nuestra solución final:
import requests
from vertexai.generative_models import (
Content,
FunctionDeclaration,
GenerativeModel,
Part,
Tool,
)
model = GenerativeModel("gemini-1.5-pro-001")
get_exchange_rate_func = FunctionDeclaration(
name="get_exchange_rate",
description="Get the exchange rate for currencies between countries",
parameters={
"type": "object",
"properties": {
"currency_date": {
"type": "string",
"description": "A date that must always be in YYYY-MM-DD format or the value 'latest' if a time period is not specified"
},
"currency_from": {
"type": "string",
"description": "The currency to convert from in ISO 4217 format"
},
"currency_to": {
"type": "string",
"description": "The currency to convert to in ISO 4217 format"
}
},
"required": [
"currency_from",
"currency_date",
]
},
)
exchange_rate_tool = Tool(
function_declarations=[get_exchange_rate_func],
)
prompt = """What is the exchange rate from Australian dollars to Swedish krona?
How much is 500 Australian dollars worth in Swedish krona?"""
response = model.generate_content(
prompt,
tools=[exchange_rate_tool],
)
response.candidates[0].content
params = {}
for key, value in response.candidates[0].content.parts[0].function_call.args.items():
params[key[9:]] = value
params
import requests
url = f"https://api.frankfurter.app/{params['date']}"
api_response = requests.get(url, params=params)
api_response.text
response = model.generate_content(
[
Content(role="user", parts=[
Part.from_text(prompt + """Give your answer in steps with lots of detail
and context, including the exchange rate and date."""),
]),
Content(role="function", parts=[
Part.from_dict({
"function_call": {
"name": "get_exchange_rate",
}
})
]),
Content(role="function", parts=[
Part.from_function_response(
name="get_exchange_rate",
response={
"content": api_response.text,
}
)
]),
],
tools=[exchange_rate_tool],
)
response.candidates[0].content.parts[0].text
En esta implementación, usamos dos solicitudes al modelo generativo: una para generar una llamada a función y otra para devolver la respuesta de la función. Ten en cuenta que este es solo un método para controlar las llamadas a funciones y las respuestas de funciones con Gemini. También puedes realizar llamadas a funciones adicionales para obtener más información sobre tu búsqueda o usar la llamada a función con métodos asíncronos y de chat.
Para obtener muestras de código adicionales, consulta el notebook de ejemplo para las llamadas a funciones en Gemini.
12. Felicitaciones
Con la llamada a funciones en Gemini, creaste correctamente una canalización de IA generativa que usa la API de Gemini de Vertex AI y Python. Los usuarios pueden preguntar sobre los tipos de cambio, y el sistema recuperará los datos más recientes de una API externa y responderá con una respuesta.
Dada una instrucción de un usuario final, la llamada a función en Gemini se encarga de seleccionar la función adecuada, extraer parámetros de la instrucción y devolver un objeto de datos estructurados para que realices una llamada a la API externa.
El diseño de la llamada a función en Gemini tiene como objetivo brindarte lo mejor de ambos mundos para extraer parámetros de forma determinística, a la vez que deja la creación de resúmenes y contenido al modelo generativo. No dudes en probar otras APIs y otras instrucciones en tu canal, y explora las otras funciones disponibles relacionadas con la API de Vertex AI Gemini.
Limpieza
Puedes realizar la siguiente limpieza para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en este codelab:
- A fin de evitar cargos innecesarios de Google Cloud, usa la consola de Google Cloud para borrar tu proyecto si no lo necesitas.
- Si quieres inhabilitar las APIs de Vertex AI, navega a la página Detalles del servicio de la API de Vertex AI, haz clic en Inhabilitar API y confirma la acción.
Más información
Continúa con el aprendizaje sobre la IA conversacional y la IA generativa con las siguientes guías y recursos:
- Descripción general de los modelos de Gemini
- Documentación sobre la llamada a funciones en Gemini
- Notebook de ejemplo para la llamada a funciones en Gemini
- Notebooks de ejemplo para Gemini
- La IA generativa en Google Cloud
Licencia
Este trabajo cuenta con una licencia Atribución 2.0 Genérica de Creative Commons.