Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Puede usar la API de Amazon Bedrock para dar a un modelo acceso a herramientas que pueden ayudarlo a generar respuestas para los mensajes que envíe al modelo. Por ejemplo, puede tener una aplicación de chat que permita a los usuarios encontrar la canción más popular que se reproduce en una emisora de radio. Para responder a una solicitud de la canción más popular, una modelo necesita una herramienta que pueda consultar y devolver la información de la canción.
El uso de herramientas con los modelos también se conoce como llamada a funciones.
En Amazon Bedrock, el modelo no llama directamente a la herramienta. Por el contrario, cuando envía un mensaje a un modelo, también proporciona una definición de una o más herramientas que podrían ayudar al modelo a generar una respuesta. En este ejemplo, proporcionaría una definición para una herramienta que devuelva la canción más popular de una emisora de radio específica. Si el modelo determina que necesita la herramienta para generar una respuesta para el mensaje, responde con una solicitud para que llame a la herramienta. También incluye los parámetros de entrada (la emisora de radio requerida) para pasarlos a la herramienta.
En el código, se llama a la herramienta en nombre del modelo. En este escenario, suponga que la implementación de la herramienta es una API. La herramienta podría ser fácilmente una base de datos, una función Lambda o algún otro software. Usted decide cómo quiere implementar la herramienta. A continuación, continúe la conversación con la modelo proporcionando un mensaje con el resultado de la herramienta. Por último, el modelo genera una respuesta para el mensaje original que incluye los resultados de la herramienta que envió al modelo.
Para usar herramientas con un modelo, puede usar la API de Converse (Converse o). ConverseStream El código de ejemplo de este tema usa la API de Converse para mostrar cómo usar una herramienta que obtiene la canción más popular de una emisora de radio. Para obtener información general sobre cómo llamar a la API de Converse, consulte. Usa la API de Converse
Es posible utilizar herramientas con las operaciones de inferencia básicas (InvokeModelo InvokeModelWithResponseStream). Para encontrar los parámetros de inferencia que se transfieren en el cuerpo de la solicitud, consulte los parámetros de inferencia del modelo que se desee utilizar. Recomendamos usar la API de Converse, ya que proporciona una API coherente que funciona con todos los modelos de Amazon Bedrock que admiten el uso de herramientas.
Amazon Bedrock admite las llamadas a herramientas con los siguientes modelos.
Para obtener más información, consulte Modelos y características de los modelos compatibles.
Los siguientes pasos muestran cómo usar una herramienta con la API de Converse.
Para enviar el mensaje y la definición de la herramienta, utilice las operaciones Converse o ConverseStream(para transmitir las respuestas).
La definición de la herramienta es un esquema JSON que se transfiere a la Converse operación con el parámetro de solicitud toolConfig (ToolConfiguration). Para obtener información sobre el esquema, consulta el esquema JSON. El siguiente es un ejemplo de esquema de una herramienta que permite reproducir la canción más popular en una emisora de radio.
{
"tools": [
{
"toolSpec": {
"name": "top_song",
"description": "Get the most popular song played on a radio station.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
}
},
"required": [
"sign"
]
}
}
}
}
]
}
En la misma solicitud, también se pasa un mensaje de usuario en el parámetro de solicitud messages (Mensaje).
[
{
"role": "user",
"content": [
{
"text": "What is the most popular song on WZPZ?"
}
]
}
]
Si utiliza un modelo Anthropic Claude 3, puede forzar el uso de una herramienta especificando el campo toolChoice (ToolChoice) en el parámetro de toolConfig solicitud. Forzar el uso de una herramienta es útil para probarla durante el desarrollo. El siguiente ejemplo muestra cómo forzar el uso de una herramienta llamada top_song.
{"tool" : {"name" : "top_song"}}
Para obtener información sobre otros parámetros que puede pasar, consulte. Usa la API de Converse
Al invocar la Converse operación con el mensaje y la definición de la herramienta, el modelo utiliza la definición de la herramienta para determinar si la herramienta es necesaria para responder al mensaje. Por ejemplo, si el usuario de la aplicación de chat envía el mensaje ¿Cuál es la canción más popular de WZPZ? , el modelo hace coincidir el mensaje con el esquema de la definición de la herramienta top_song y determina que la herramienta puede ayudar a generar una respuesta.
Cuando el modelo decide que necesita una herramienta para generar una respuesta, establece el campo de stopReason respuesta en. tool_use La respuesta también identifica la herramienta (top_song) que el modelo quiere que ejecute y la emisora de radio (WZPZ) que quiere que consulte con la herramienta. La información sobre la herramienta solicitada se encuentra en el mensaje que devuelve el modelo en el output campo (). ConverseOutput Concretamente, el campo toolUse (ToolUseBloquear). El toolUseId campo se utiliza para identificar la solicitud de herramienta en llamadas posteriores.
En el siguiente ejemplo, se muestra la respuesta Converse al pasar el mensaje descrito enPaso 1: Enviar el mensaje y la definición de la herramienta.
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"toolUse": {
"toolUseId": "tooluse_hbTgdi0CSLq_hM4P8csZJA",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
]
}
},
"stopReason": "tool_use"
}
En el toolUse campo de la respuesta del modelo, utilice el name campo para identificar el nombre de la herramienta. A continuación, llame a su implementación de la herramienta y pase los parámetros de entrada desde el input campo.
A continuación, cree un mensaje de usuario que incluya un ToolResultbloque de contenido toolResult (Bloque). En el bloque de contenido, incluye la respuesta de la herramienta y el ID de la solicitud de herramienta que recibiste en el paso anterior.
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"content": [
{
"json": {
"song": "Elemental Hotel",
"artist": "8 Storey Hike"
}
}
]
}
}
]
}
Si se produce un error en la herramienta, como la solicitud de una emisora de radio inexistente, puedes enviar la información del error al modelo en el toolResult campo. Para indicar un error, especifíquelo error en el status campo. El siguiente ejemplo de error se debe a que la herramienta no encuentra la emisora de radio.
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"content": [
{
"text": "Station WZPA not found."
}
],
"status": "error"
}
}
]
}
Continúa la conversación con la modelo incluyendo el mensaje de usuario que creaste en el paso anterior en una llamada aConverse. Luego, la modelo genera una respuesta que responde al mensaje original (¿Cuál es la canción más popular en WZPZ? ) con la información que proporcionó en el toolResult campo del mensaje.
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
}
]
}
},
"stopReason": "end_turn"
En los siguientes ejemplos, se muestra cómo utilizar una herramienta con la API de Converse. La herramienta devuelve la canción más popular de una emisora de radio ficticia.
- Converse
-
En este ejemplo se muestra cómo utilizar una herramienta con la Converse operación con el Command Rmodelo.
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use tools with the Converse API and the Cohere Command R model.
"""
import logging
import json
import boto3
from botocore.exceptions import ClientError
class StationNotFoundError(Exception):
"""Raised when a radio station isn't found."""
pass
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def get_top_song(call_sign):
"""Returns the most popular song for the requested station.
Args:
call_sign (str): The call sign for the station for which you want
the most popular song.
Returns:
response (json): The most popular song and artist.
"""
song = ""
artist = ""
if call_sign == 'WZPZ':
song = "Elemental Hotel"
artist = "8 Storey Hike"
else:
raise StationNotFoundError(f"Station {call_sign} not found.")
return song, artist
def generate_text(bedrock_client, model_id, tool_config, input_text):
"""Generates text using the supplied Amazon Bedrock model. If necessary,
the function handles tool use requests and sends the result to the model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The Amazon Bedrock model ID.
tool_config (dict): The tool configuration.
input_text (str): The input text.
Returns:
Nothing.
"""
logger.info("Generating text with model %s", model_id)
# Create the initial message from the user input.
messages = [{
"role": "user",
"content": [{"text": input_text}]
}]
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
toolConfig=tool_config
)
output_message = response['output']['message']
messages.append(output_message)
stop_reason = response['stopReason']
if stop_reason == 'tool_use':
# Tool use requested. Call the tool and send the result to the model.
tool_requests = response['output']['message']['content']
for tool_request in tool_requests:
if 'toolUse' in tool_request:
tool = tool_request['toolUse']
logger.info("Requesting tool %s. Request: %s",
tool['name'], tool['toolUseId'])
if tool['name'] == 'top_song':
tool_result = {}
try:
song, artist = get_top_song(tool['input']['sign'])
tool_result = {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}]
}
except StationNotFoundError as err:
tool_result = {
"toolUseId": tool['toolUseId'],
"content": [{"text": err.args[0]}],
"status": 'error'
}
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": tool_result
}
]
}
messages.append(tool_result_message)
# Send the tool result to the model.
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
toolConfig=tool_config
)
output_message = response['output']['message']
# print the final response from the model.
for content in output_message['content']:
print(json.dumps(content, indent=4))
def main():
"""
Entrypoint for tool use example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "cohere.command-r-v1:0"
input_text = "What is the most popular song on WZPZ?"
tool_config = {
"tools": [
{
"toolSpec": {
"name": "top_song",
"description": "Get the most popular song played on a radio station.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ, and WKRP."
}
},
"required": [
"sign"
]
}
}
}
}
]
}
bedrock_client = boto3.client(service_name='bedrock-runtime')
try:
print(f"Question: {input_text}")
generate_text(bedrock_client, model_id, tool_config, input_text)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print(f"A client error occured: {message}")
else:
print(
f"Finished generating text with model {model_id}.")
if __name__ == "__main__":
main()
- ConverseStream
-
En este ejemplo se muestra cómo utilizar una herramienta con la operación de ConverseStream transmisión y el AnthropicClaude 3 Haikumodelo.
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use a tool with a streaming conversation.
"""
import logging
import json
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
class StationNotFoundError(Exception):
"""Raised when a radio station isn't found."""
pass
def get_top_song(call_sign):
"""Returns the most popular song for the requested station.
Args:
call_sign (str): The call sign for the station for which you want
the most popular song.
Returns:
response (json): The most popular song and artist.
"""
song = ""
artist = ""
if call_sign == 'WZPZ':
song = "Elemental Hotel"
artist = "8 Storey Hike"
else:
raise StationNotFoundError(f"Station {call_sign} not found.")
return song, artist
def stream_messages(bedrock_client,
model_id,
messages,
tool_config):
"""
Sends a message to a model and streams the response.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
messages (JSON) : The messages to send to the model.
tool_config : Tool Information to send to the model.
Returns:
stop_reason (str): The reason why the model stopped generating text.
message (JSON): The message that the model generated.
"""
logger.info("Streaming messages with model %s", model_id)
response = bedrock_client.converse_stream(
modelId=model_id,
messages=messages,
toolConfig=tool_config
)
stop_reason = ""
message = {}
content = []
message['content'] = content
text = ''
tool_use = {}
#stream the response into a message.
for chunk in response['stream']:
if 'messageStart' in chunk:
message['role'] = chunk['messageStart']['role']
elif 'contentBlockStart' in chunk:
tool = chunk['contentBlockStart']['start']['toolUse']
tool_use['toolUseId'] = tool['toolUseId']
tool_use['name'] = tool['name']
elif 'contentBlockDelta' in chunk:
delta = chunk['contentBlockDelta']['delta']
if 'toolUse' in delta:
if 'input' not in tool_use:
tool_use['input'] = ''
tool_use['input'] += delta['toolUse']['input']
elif 'text' in delta:
text += delta['text']
print(delta['text'], end='')
elif 'contentBlockStop' in chunk:
if 'input' in tool_use:
tool_use['input'] = json.loads(tool_use['input'])
content.append({'toolUse': tool_use})
tool_use = {}
else:
content.append({'text': text})
text = ''
elif 'messageStop' in chunk:
stop_reason = chunk['messageStop']['stopReason']
return stop_reason, message
def main():
"""
Entrypoint for streaming tool use example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-haiku-20240307-v1:0"
input_text = "What is the most popular song on WZPZ?"
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
# Create the initial message from the user input.
messages = [{
"role": "user",
"content": [{"text": input_text}]
}]
# Define the tool to send to the model.
tool_config = {
"tools": [
{
"toolSpec": {
"name": "top_song",
"description": "Get the most popular song played on a radio station.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"sign": {
"type": "string",
"description": "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP."
}
},
"required": ["sign"]
}
}
}
}
]
}
# Send the message and get the tool use request from response.
stop_reason, message = stream_messages(
bedrock_client, model_id, messages, tool_config)
messages.append(message)
if stop_reason == "tool_use":
for content in message['content']:
if 'toolUse' in content:
tool = content['toolUse']
if tool['name'] == 'top_song':
tool_result = {}
try:
song, artist = get_top_song(tool['input']['sign'])
tool_result = {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"song": song, "artist": artist}}]
}
except StationNotFoundError as err:
tool_result = {
"toolUseId": tool['toolUseId'],
"content": [{"text": err.args[0]}],
"status": 'error'
}
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": tool_result
}
]
}
# Add the result info to message.
messages.append(tool_result_message)
#Send the messages, including the tool result, to the model.
stop_reason, message = stream_messages(
bedrock_client, model_id, messages, tool_config)
except ClientError as err:
message = err.response['Error']['Message']
logger.error("A client error occurred: %s", message)
print("A client error occured: " +
format(message))
else:
print(
f"\nFinished streaming messages with model {model_id}.")
if __name__ == "__main__":
main()
