Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.
Puoi utilizzare l'API Amazon Bedrock per consentire a un modello di accedere a strumenti che possono aiutarlo a generare risposte ai messaggi che invii al modello. Ad esempio, potresti avere un'applicazione di chat che consente agli utenti di scoprire la canzone più popolare riprodotta su una stazione radio. Per rispondere a una richiesta per la canzone più popolare, un modello necessita di uno strumento in grado di interrogare e restituire le informazioni sul brano.
L'uso dello strumento con i modelli è noto anche come chiamata di funzione.
In Amazon Bedrock, il modello non chiama direttamente lo strumento. Piuttosto, quando invii un messaggio a un modello, fornisci anche una definizione per uno o più strumenti che potrebbero potenzialmente aiutare il modello a generare una risposta. In questo esempio, si dovrebbe fornire una definizione per uno strumento che restituisce la canzone più popolare per una stazione radio specificata. Se il modello determina che necessita dello strumento per generare una risposta al messaggio, risponde con una richiesta di chiamata allo strumento. Include anche i parametri di input (la stazione radio richiesta) da passare allo strumento.
Nel codice, si chiama lo strumento per conto del modello. In questo scenario, supponiamo che l'implementazione dello strumento sia un'API. Lo strumento potrebbe essere altrettanto facilmente un database, una funzione Lambda o qualche altro software. Sei tu a decidere come implementare lo strumento. Quindi continuate la conversazione con il modello fornendo un messaggio con il risultato dello strumento. Infine, il modello genera una risposta al messaggio originale che include i risultati dell'utensile che avete inviato al modello.
Per utilizzare gli strumenti con un modello puoi utilizzare l'API Converse (Converse o). ConverseStream Il codice di esempio riportato in questo argomento utilizza l'API Converse per mostrare come utilizzare uno strumento che rileva la canzone più popolare di una stazione radio. Per informazioni generali sulla chiamata all'API Converse, consulta. Usa l'API Converse
È possibile utilizzare strumenti con le operazioni di inferenza di base (InvokeModelo InvokeModelWithResponseStream). Per trovare i parametri di inferenza che passate nel corpo della richiesta, consultate i parametri di inferenza per il modello che desiderate utilizzare. Ti consigliamo di utilizzare l'API Converse in quanto fornisce un'API coerente, che funziona con tutti i modelli Amazon Bedrock che supportano l'uso degli strumenti.
Amazon Bedrock supporta la chiamata di strumenti con i seguenti modelli.
Per ulteriori informazioni, consulta Modelli e caratteristiche del modello supportati.
I passaggi seguenti mostrano come utilizzare uno strumento con l'API Converse.
Per inviare il messaggio e la definizione dello strumento, utilizzate le operazioni Converse o ConverseStream(per le risposte in streaming).
La definizione dello strumento è uno schema JSON che si passa il parametro di richiesta toolConfig (ToolConfiguration) all'Converseoperazione. Per informazioni sullo schema, vedete Schema JSON. Di seguito è riportato uno schema di esempio per uno strumento che consente di riprodurre la canzone più popolare su una stazione 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"
]
}
}
}
}
]
}
Nella stessa richiesta, si passa anche un messaggio utente nel parametro di richiesta messages (Message).
[
{
"role": "user",
"content": [
{
"text": "What is the most popular song on WZPZ?"
}
]
}
]
Se utilizzate un modello Anthropic Claude 3D, potete forzare l'uso di uno strumento specificando il campo toolChoice (ToolChoice) nel parametro di toolConfig richiesta. Forzare l'uso di uno strumento è utile per testare lo strumento durante lo sviluppo. L'esempio seguente mostra come forzare l'uso di uno strumento chiamato top_song.
{"tool" : {"name" : "top_song"}}
Per informazioni sugli altri parametri che potete passare, consultate. Usa l'API Converse
Quando richiamate l'Converseoperazione con il messaggio e la definizione dell'utensile, il modello utilizza la definizione dell'utensile per determinare se l'utensile è necessario per rispondere al messaggio. Ad esempio, se l'utente dell'app di chat invia il messaggio Qual è la canzone più popolare su WZPZ? , il modello abbina il messaggio allo schema nella definizione dello strumento top_song e determina che lo strumento può contribuire a generare una risposta.
Quando il modello decide di aver bisogno di uno strumento per generare una risposta, imposta il campo di stopReason risposta su. tool_use La risposta identifica anche lo strumento (top_song) che il modello vuole che tu esegua e la stazione radio (WZPZ) che desidera che tu interroghi con lo strumento. Le informazioni sullo strumento richiesto si trovano nel messaggio che il modello restituisce nel campo (). output ConverseOutput In particolare, il campo toolUse (ToolUseBlock). Il toolUseId campo viene utilizzato per identificare la richiesta dello strumento nelle chiamate successive.
L'esempio seguente mostra la risposta ottenuta Converse quando si passa il messaggio discusso inFase 1: Inviare il messaggio e la definizione dello strumento.
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"toolUse": {
"toolUseId": "tooluse_hbTgdi0CSLq_hM4P8csZJA",
"name": "top_song",
"input": {
"sign": "WZPZ"
}
}
}
]
}
},
"stopReason": "tool_use"
}
Dal toolUse campo della risposta del modello, utilizzate il name campo per identificare il nome dello strumento. Quindi richiamate l'implementazione dello strumento e passate i parametri di input dal input campo.
Quindi, costruisci un messaggio utente che includa un blocco di contenuto toolResult (ToolResultBlock). Nel blocco di contenuto, includi la risposta dello strumento e l'ID per la richiesta dello strumento che hai ricevuto nel passaggio precedente.
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"content": [
{
"json": {
"song": "Elemental Hotel",
"artist": "8 Storey Hike"
}
}
]
}
}
]
}
Se si verifica un errore nello strumento, ad esempio una richiesta di una stazione radio inesistente, puoi inviare informazioni sull'errore al modello presente sul toolResult campo. Per indicare un errore, specificare error nel status campo. L'errore di esempio seguente si riferisce al caso in cui lo strumento non riesce a trovare la stazione radio.
{
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": "tooluse_kZJMlvQmRJ6eAyJE5GIl7Q",
"content": [
{
"text": "Station WZPA not found."
}
],
"status": "error"
}
}
]
}
Continua la conversazione con la modella includendo il messaggio utente creato nel passaggio precedente in una chiamata aConverse. Il modello genera quindi una risposta che risponde al messaggio originale (Qual è la canzone più popolare su WZPZ? ) con le informazioni che hai fornito nel toolResult campo del messaggio.
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "The most popular song on WZPZ is Elemental Hotel by 8 Storey Hike."
}
]
}
},
"stopReason": "end_turn"
Gli esempi seguenti mostrano come utilizzare uno strumento con l'API Converse. Lo strumento restituisce la canzone più popolare di una stazione radio immaginaria.
- Converse
-
Questo esempio mostra come utilizzare uno strumento con l'Converseoperazione con il Command Rmodello.
# 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
-
Questo esempio mostra come utilizzare uno strumento con l'operazione di ConverseStream streaming e il AnthropicClaude 3 Haikumodello.
# 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()
