Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
Gunakan alat untuk menyelesaikan respons model Amazon Bedrock
Anda dapat menggunakan Amazon Bedrock API untuk memberikan akses model ke alat yang dapat membantunya menghasilkan respons untuk pesan yang Anda kirim ke model. Misalnya, Anda mungkin memiliki aplikasi obrolan yang memungkinkan pengguna mengetahui lagu paling populer yang diputar di stasiun radio. Untuk menjawab permintaan lagu paling populer, model membutuhkan alat yang dapat menanyakan dan mengembalikan informasi lagu.
Di Amazon Bedrock, model tidak secara langsung memanggil alat. Sebaliknya, ketika Anda mengirim pesan ke model, Anda juga memberikan definisi untuk satu atau beberapa alat yang berpotensi membantu model menghasilkan respons. Dalam contoh ini, Anda akan memberikan definisi untuk alat yang mengembalikan lagu paling populer untuk stasiun radio tertentu. Jika model menentukan bahwa ia memerlukan alat untuk menghasilkan respons untuk pesan, model, tergantung pada API yang digunakan untuk memanggil model, dapat melakukan panggilan sisi klien atau meminta Bedrock untuk memanggil alat menggunakan pemanggilan alat sisi server. Mari kita bahas dua opsi ini secara lebih rinci.
Panggilan alat sisi klien
Jika Anda menggunakan Responses API, Chat Completions API, Converse API, atau InvokeModel API untuk mengirim permintaan, maka model tersebut menggunakan pemanggilan alat sisi klien. Ini berarti bahwa dalam kode Anda, Anda memanggil alat atas nama model. Dalam skenario ini, asumsikan implementasi alat adalah API. Alat ini bisa dengan mudah menjadi database, fungsi Lambda, atau perangkat lunak lainnya. Anda memutuskan bagaimana Anda ingin menerapkan alat ini. Anda kemudian melanjutkan percakapan dengan model dengan memberikan pesan dengan hasil dari alat. Terakhir, model menghasilkan respons untuk pesan asli yang menyertakan hasil alat yang Anda kirim ke model.
Mari kita mendefinisikan alat yang akan kita gunakan untuk penggunaan alat. Contoh Python berikut menunjukkan cara menggunakan alat yang mengembalikan lagu paling populer di stasiun radio fiksi.
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")
Menggunakan Responses API untuk perkakas sisi klien
Anda dapat menggunakan fitur pemanggilan Fungsi
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)
Menggunakan Chat Completions API untuk perkakas sisi klien
Anda juga dapat menggunakan Chat Completions API. Berikut adalah kode Python untuk menggunakan 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)
Untuk detail selengkapnya tentang penggunaan Function Calling on Responses API dan Chat Completions API, lihat Function Calling
Menggunakan Converse API untuk perkakas sisi klien
Anda dapat menggunakan Converse API untuk membiarkan model menggunakan alat dalam percakapan. Contoh Python berikut menunjukkan cara menggunakan alat yang mengembalikan lagu paling populer di stasiun radio fiksi.
# 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()
Menggunakan Invoke APIs untuk penggunaan alat sisi klien
Dimungkinkan untuk menggunakan alat dengan operasi inferensi dasar (InvokeModelatau InvokeModelWithResponseStream). Untuk menemukan parameter inferensi yang Anda lewatkan di badan permintaan, lihat parameter inferensi untuk model yang ingin Anda gunakan.
Panggilan alat sisi server
Jika Anda menggunakan Responses API untuk memanggil model, maka itu dapat menggunakan pemanggilan alat sisi server, selain pemanggilan alat sisi klien yang telah kita bahas sebelumnya. Panggilan alat sisi server adalah mekanisme di mana alat (APIs, fungsi, alur kerja) dijalankan di lingkungan backend tepercaya, bukan pada klien. Ini meningkatkan keamanan, keandalan, dan postur tata kelola aplikasi. Sebelum Amazon Bedrock menjalankan fungsi Lambda yang mengimplementasikan penggunaan alat, ini memastikan bahwa fungsi Lambda memiliki kebijakan IAM yang sama dengan aplikasi yang memanggilnya. Karena Amazon Bedrock mendorong eksekusi alat, klien dapat fokus pada penerapan logika bisnis mereka, daripada menambahkan fungsionalitas alat. Amazon Bedrock juga mendukung standar tata kelola tertinggi seperti ISO, SOC, dan HIPAA yang memenuhi syarat. Pelanggan dapat mengirimkan fungsi Lambda kustom mereka sendiri untuk menjalankan alat atau menggunakan alat yang telah ditentukan sebelumnya, seperti catatan dan tugas. Alat sisi server yang menggunakan Responses API tersedia dimulai dengan model GPT OSS 20B/120B OpenAI, dengan dukungan untuk model lain segera hadir. Anda dapat menggunakan Models API untuk menemukan model yang tersedia yang dapat Anda gunakan dengan API Responses. Untuk detail selengkapnya tentang API Responses, lihat Menghasilkan respons menggunakan OpenAI APIs.
Ada dua jenis alat yang dapat Anda gunakan dengan Amazon Bedrock: Alat khusus menggunakan Lambda, atau alat yang telah ditentukan sebelumnya yang didukung oleh Bedrock. Pada bagian ini kita akan meninjau cara membuat alat Lambda khusus dengan API Responses. Mari kita bahas keduanya secara detail.
Alat kustom menggunakan Lambda di Responses API
Dengan menggunakan fungsi Lambda sebagai alat khusus di Bedrock, Anda dapat memperluas kemampuan agen dengan mengintegrasikan fungsi AWS Lambda khusus sebagai alat. Ini memungkinkan Anda membuat alat tanpa server dan dapat diskalakan yang dapat dipanggil oleh asisten AI dan aplikasi lain melalui Model Context Protocol (MCP). Berikut adalah kelebihan dari fitur ini:
Perluas Fungsionalitas: Tambahkan logika bisnis khusus, integrasi API, atau kemampuan pemrosesan data.
Jalankan alat dengan aman: Lambda memungkinkan alat untuk mengakses sumber daya di dalam VPC tanpa harus memberikan akses VPC penuh.
Arsitektur Tanpa Server: Tidak ada manajemen infrastruktur, Lambda menangani penskalaan secara otomatis.
Hemat Biaya: Bayar hanya untuk waktu eksekusi, bukan sumber daya idle.
Integrasi Mudah: Fungsi Lambda muncul bersama alat bawaan dengan mulus.
Agar model di Amazon Bedrock menggunakan alat untuk menyelesaikan respons pesan, Anda mengirim pesan dan definisi untuk satu atau beberapa alat ke model. Berdasarkan prompt aplikasi Anda, jika model menentukan bahwa salah satu alat dapat membantu menghasilkan respons, ia mengembalikan permintaan untuk Bedrock untuk menggunakan alat dan mengirim hasil alat kembali ke model. Model kemudian menggunakan hasil untuk menghasilkan respons terhadap pesan asli.
Langkah-langkah berikut menunjukkan cara menggunakan alat dengan Responses API.
Cara kerjanya
Fungsi Lambda: Buat fungsi Lambda Anda yang mengimplementasikan protokol MCP
Penemuan Alat: Bedrock memanggil fungsi Lambda Anda untuk menemukan alat yang tersedia
Pendaftaran Alat: Alat Anda terdaftar di Bedrock
Eksekusi Alat: Saat agen meminta alat Anda, Bedrock memanggil fungsi Lambda Anda
Response Handling: Hasil dikembalikan ke agen melalui antarmuka standar
Langkah 1: Tentukan fungsi Lambda untuk mendapatkan lagu paling populer
Buat fungsi Lambda yang mengimplementasikan protokol MCP. Berikut adalah contoh Python sederhana:
import json def lambda_handler(event, context): # Parse JSON-RPC request method = event.get('method') params = event.get('params', {}) request_id = event.get('id') if method == 'tools/list': return { "jsonrpc": "2.0", "id": request_id, "result": { "tools": [ { "name": "my_custom_tool", "description": "My custom business logic tool", "inputSchema": { "type": "object", "properties": { "input": { "type": "string", "description": "Input text to process" } }, "required": ["input"] } } ] } } elif method == 'tools/call': tool_name = params.get('name') arguments = params.get('arguments', {}) if tool_name == 'my_custom_tool': # Your custom logic here result = f"Processed: {arguments.get('input', '')}" return { "jsonrpc": "2.0", "id": request_id, "result": { "content": [ { "type": "text", "text": result } ] } } # Error response for unsupported methods return { "jsonrpc": "2.0", "id": request_id, "error": { "code": -32601, "message": "Method not found" } }
Langkah 2: Menyebarkan fungsi Lambda
Selanjutnya, gunakan peran IAM Anda untuk menerapkan fungsi Lambda ini untuk mendapatkan ARN. Anda dapat membaca lebih lanjut tentang penerapan fungsi Lambda di sini.
# Example using AWS CLI aws lambda create-function \ --function-name my-custom-tool \ --runtime python3.14 \ --role arn:aws:iam::YOUR-ACCOUNT:role/lambda-execution-role \ --handler lambda_function.lambda_handler \ --zip-file fileb://function.zip
Katakanlah ARN Anda adalah: arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool
Langkah 3: Tentukan definisi pesan dan alat dalam permintaan inferensi Anda
Untuk mengirim pesan dan definisi alat, Anda menggunakan operasi Responses API. Amazon Bedrock menggunakan konektor dan fungsionalitas server MCP jarak jauhconnector_id bidang di API konektor Responses, Anda dapat meneruskan ARN Lambda yang telah Anda buat di langkah sebelumnya. Anda tidak perlu memberikan kredensi otorisasi karena Bedrock menggunakan peran dan kebijakan IAM yang sama yang digunakan untuk aplikasi Anda yang memanggil model. Berikut ini adalah contoh skema untuk alat yang mendapatkan lagu paling populer diputar di stasiun radio.
from openai import OpenAI client = OpenAI() resp = client.responses.create( model="oss-gpt-120b", tools=[ { "type": "mcp", "server_label": "xamzn_arn", "connector_id": "arn:aws:lambda:us-west-2:123456789012:function:my-custom-tool", "require_approval": "never", }, ], input="My custom prompt.", ) print(resp.output_text)
Langkah 4: Bedrock memanggil alat dan meneruskan respons kembali ke model
Kemampuan untuk menggunakan alat konektor tersedia dalam model yang mendukung Responses API
Ketika Anda menentukan fungsi Lambda dalam tools parameter, API akan mencoba untuk mendapatkan daftar alat dari server. Jika berhasil mengambil daftar alat, item mcp_list_tools keluaran baru akan muncul di output respons model. toolsProperti objek ini akan menunjukkan alat yang berhasil diimpor. Setelah model memiliki akses ke definisi alat ini, ia dapat memilih untuk memanggilnya tergantung pada apa yang ada dalam konteks model. Ketika model memutuskan untuk memanggil alat Lambda, API akan membuat permintaan ke fungsi Lambda untuk memanggil alat dan memasukkan outputnya ke dalam konteks model. Anda dapat membaca lebih lanjut tentang alat daftar dan alat panggilan di dokumentasi OpenAI
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32000, "message": "Tool execution failed", "data": "Additional error details" } }
Menggunakan alat yang disediakan AWS di Responses API
Ada dua alat yang disediakan AWS yang tersedia di Bedrock: Fungsi pencatatan (alat catatan) dan Manajemen tugas (alat tugas). Mari kita bahas keduanya secara detail.
Ikhtisar Alat Catatan
notesAlat ini memungkinkan Anda untuk menyimpan dan mengambil pasangan nilai kunci dalam sesi percakapan yang sama. Ini menyediakan mekanisme memori sederhana untuk mempertahankan konteks di berbagai interaksi. Kunci adalah string peka huruf besar/kecil dan tidak ada batasan panjang kunci atau konvensi penamaan. Sistem menimpa nilai sebelumnya untuk kunci yang sama. Nilai disimpan sebagai string (JSON, URLs dll.) dan tidak ada batasan ukuran yang diberlakukan pada tingkat alat. Nilai dipertahankan melalui seluruh sesi percakapan. Memori hanya mencakup percakapan saat ini.
Parameter
| Parameter | Tipe | Diperlukan | Deskripsi |
|---|---|---|---|
operation |
string | Ya | Operasi untuk melakukan: "store" atau "recall" |
key |
string | Ya | Pengidentifikasi kunci untuk item memori |
value |
string | Bersyarat | Nilai untuk menyimpan (diperlukan hanya untuk "store" operasi) |
Operasi yang Valid
store: Simpan pasangan kunci-nilai ke memorirecall: Ambil nilai dengan kuncinya
Anda dapat menggunakan salah satu bahasa alami (misalnya “Ingat bahwa warna favorit saya adalah biru”, “Apa yang saya ceritakan tentang warna favorit saya?” , “Simpan fakta bahwa saya lebih suka rapat pagi”, “Ingat apa yang saya katakan tentang preferensi rapat”) atau Anda dapat menggunakan alat langsung panggilan di prompt Anda (“Gunakan alat catatan untuk menyimpan email saya sebagai john@example.com “, “Periksa catatan untuk alamat email saya”).
Ikhtisar Alat Tugas
tasksAlat ini menyediakan tumpukan Last-In-First-Out (LIFO) untuk mengelola tugas dalam sesi percakapan. Ini memungkinkan Anda untuk mendorong tugas ke tumpukan dan mematikannya dalam urutan terbalik, membuatnya sempurna untuk mengelola alur kerja bersarang, pengingat sementara, atau manajemen tugas hierarkis. Tugas tetap ada di seluruh sesi percakapan. Status tumpukan dipertahankan di beberapa interaksi. Memori hanya mencakup percakapan saat ini.
| Parameter | Tipe | Diperlukan | Deskripsi |
|---|---|---|---|
operation |
string | Ya | Operasi untuk melakukan: "push" atau "pop" |
description |
string | Bersyarat | Deskripsi item tugas (hanya diperlukan untuk "push" operasi) |
summary |
string | Tidak | Ringkasan opsional tentang item tugas (hanya untuk "push" operasi) |
Anda dapat memanggil alat Tugas dengan menggunakan bahasa alami (misalnya “Tambahkan tugas untuk meninjau anggaran”, “Dorong pengingat untuk memanggil klien”, “Apa tugas selanjutnya yang perlu saya lakukan?” , “Pop tugas terbaru”, “Dapatkan tugas terbaru dari tumpukan saya”) atau Anda dapat memanggil alat langsung di prompt Anda (“Gunakan alat tugas untuk mendorong 'menyelesaikan presentasi'”, “Pop tugas dari tumpukan”, “Tambahkan 'jadwalkan pertemuan' ke daftar tugas saya”).
