Client-side uso dello strumento

Se utilizzi l'API Responses, l'API Chat Completions, l'API Converse o l' InvokeModel API per inviare la richiesta, il modello utilizza la chiamata allo strumento lato client. Ciò significa che nel tuo codice, chiami lo strumento per conto del modello. In questo scenario, supponiamo che l’implementazione dello strumento sia un’API. Lo strumento potrebbe essere facilmente un database, una funzione Lambda o un altro tipo di software. È l’utente che decide come implementare lo strumento. Quindi si continua la conversazione con il modello fornendo un messaggio con il risultato ottenuto dallo strumento. Infine, il modello genera una risposta per il messaggio originale che include i risultati dell'utensile che avete inviato al modello.

Definiamo lo strumento che useremo per l'uso dello strumento. I seguenti esempi in Python mostrano come usare uno strumento che restituisce la canzone più popolare su una stazione radio immaginaria.

def get_most_popular_song(station_name: str) -> str:
    stations = {
        "Radio Free Mars": "Starman – David Bowie",
        "Neo Tokyo FM": "Plastic Love – Mariya Takeuchi",
        "Cloud Nine Radio": "Blinding Lights – The Weeknd",
    }
    return stations.get(station_name, "Unknown Station – No chart data available")

Utilizzo dell'API Responses per gli strumenti lato client

È possibile utilizzare la funzione di chiamata delle funzioni fornita da OpenAI per chiamare questo strumento. L'API Responses è l'API preferita di OpenAI. Ecco il codice Python per l'API Responses per gli strumenti lato client:

from openai import OpenAI
import json

client = OpenAI()

response = client.responses.create(
    model="oss-gpt-120b",
    input="What is the most popular song on Radio Free Mars?",
    tools=[
        {
            "type": "function",
            "name": "get_most_popular_song",
            "description": "Returns the most popular song on a radio station",
            "parameters": {
                "type": "object",
                "properties": {
                    "station_name": {
                        "type": "string",
                        "description": "Name of the radio station"
                    }
                },
                "required": ["station_name"]
            }
        }
    ]
)

if response.output and response.output[0].content:
    tool_call = response.output[0].content[0]
    args = json.loads(tool_call["arguments"])
    result = get_most_popular_song(args["station_name"])
    
    final_response = client.responses.create(
        model="oss-gpt-120b",
        input=[
            {
                "role": "tool",
                "tool_call_id": tool_call["id"],
                "content": result
            }
        ]
    )
    
    print(final_response.output_text)

Utilizzo dell'API Chat Completions per gli strumenti lato client

Puoi utilizzare anche l'API Chat Completions. Ecco il codice Python per usare Chat Completions:

    from openai import OpenAI
import json

client = OpenAI()

completion = client.chat.completions.create(
    model="oss-gpt-120b",
    messages=[{"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_most_popular_song",
            "description": "Returns the most popular song on a radio station",
            "parameters": {
                "type": "object",
                "properties": {
                   "station_name": {"type": "string", "description": "Name of the radio station"}
                },
                "required": ["station_name"]
            }
        }
    }]
)

message = completion.choices[0].message

if message.tool_calls:
    tool_call = message.tool_calls[0]
    args = json.loads(tool_call.function.arguments)
    result = get_most_popular_song(args["station_name"])

    followup = client.chat.completions.create(
        model="oss-gpt-120b",
        messages=[
            {"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"},
            message,
            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
        ]
    )

    print(followup.choices[0].message.content)
    

Per maggiori dettagli sull'utilizzo dell'API Function Calling on Responses e dell'API Chat Completions, consulta Function Calling in OpenAI.

Utilizzo dell'API Converse per gli strumenti lato client

Puoi utilizzare l'API Converse per consentire a un modello di utilizzare uno strumento in una conversazione. I seguenti esempi in Python mostrano come usare uno strumento che restituisce la canzone più popolare su una stazione radio immaginaria.

# 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()

Scelta dello strumento richiesto dal modello

Il toolChoice campo opzionale toolConfig controlla se il modello deve richiedere uno strumento. Le impostazioni che è possibile utilizzare dipendono dal singolo modello chiamato, non dal fornitore del modello o dalla famiglia di modelli:

Se un modello non supporta l'impostazione che invii, la richiesta ha esito negativo con a ValidationException anziché ritornare aauto. Il messaggio identifica il campo da rimuovere, ad esempio This model doesn't support the toolConfig.toolChoice.tool field. Remove toolConfig.toolChoice.tool and try again. Some models restituisce invece l'errore riportato dal fornitore del modello, ad esempio The model returned the following errors: tool_choice: type "tool" and "any" are not supported for this model. per i modelli For the Anthropic Claude che non supportano any otool, vedi Uso forzato degli strumenti.

Un modello che non supporta affatto l'uso degli strumenti fallisce This model doesn't support tool use. per ogni toolChoice impostazione, inclusa. auto

Utilizzo dello strumento con streaming di risposta

Il supporto per l'uso degli strumenti e il supporto per lo streaming delle risposte sono funzionalità indipendenti. La maggior parte dei modelli che supportano l'uso degli strumenti accetta anche il toolConfig campo onConverseStream, ma i seguenti modelli accettano gli strumenti solo per l'Converseoperazione non in streaming e li rifiutano con: ConverseStream This model doesn't support tool use in streaming mode.

Lo streaming di risposta stesso funziona con tutti questi modelli. Non è supportata solo la combinazione di streaming e utilizzo degli strumenti. Se hai bisogno di usare uno di questi strumenti, chiama Converse invece.

Informazioni sull'ID di utilizzo dello strumento

Ogni richiesta di strumento in una risposta contiene un messaggio toolUseId che identifica tale richiesta. Riproduci lo stesso valore nel toolResult blocco corrispondente in modo che il modello possa abbinare il risultato alla richiesta. Il modo in cui Amazon Bedrock produce questo valore dipende dal tipo di utensile e dal modello:

Per distinguerli in fase di esecuzione, controlla il prefisso. Ogni identificatore generato da Amazon Bedrock inizia con tooluse_ 22 caratteri. Un identificatore che non inizia con tooluse_ proviene dal fornitore del modello. Questo comportamento può differire tra i modelli della stessa famiglia, quindi testate il modello specifico che chiamate.

Utilizzo delle API Invoke per l'utilizzo degli strumenti sul lato client

È possibile utilizzare strumenti con le operazioni di inferenza di base (o). InvokeModelInvokeModelWithResponseStream Per trovare i parametri di inferenza passati nel corpo della richiesta, consulta i parametri di inferenza per il modello da utilizzare.