Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Menggunakan alat (panggilan fungsi)
Alat memperluas kemampuan Amazon Nova dengan menghubungkan model ke fungsionalitas eksternal seperti APIs, database dan lingkungan eksekusi kode. Penggunaan alat memungkinkan Amazon Nova mengakses informasi real-time, melakukan perhitungan, dan berinteraksi dengan sistem eksternal.
## Memahami alur kerja penggunaan alat
Penggunaan alat dengan Amazon Nova melibatkan tiga fase utama:
Kueri Pengguna dan Definisi Alat
Tentukan alat dengan menyediakan skema JSON yang menjelaskan fungsionalitas masing-masing alat dan persyaratan input. Konfigurasi alat harus menyertakan detail eksplisit tentang kapan dan bagaimana menggunakan setiap alat.
Pemilihan Alat
Ketika pengguna mengirim pesan, Amazon Nova menganalisisnya untuk menentukan apakah alat diperlukan. Pilihan alat otomatis ini memeriksa konteks dan memutuskan alat mana (jika ada) untuk dipanggil. Jika Amazon Nova mengidentifikasi alat yang sesuai, ia mengembalikan nama alat dan parameter yang diperlukan.
Anda bertanggung jawab untuk mengeksekusi alat berdasarkan permintaan model. Ini berarti menulis kode yang memanggil fungsionalitas alat dan memproses parameter input yang disediakan oleh model.
Hasil Pengembalian
Setelah menjalankan alat, kirim hasilnya kembali ke Amazon Nova dalam format terstruktur menggunakan JSON atau kombinasi teks dan gambar. Amazon Nova menggabungkan output alat ke dalam respons akhir. Jika kesalahan terjadi selama eksekusi, nyatakan ini dalam respons alat untuk memungkinkan Amazon Nova menyesuaikannya.
## Buat alat
Tentukan alat menggunakan konfigurasi alat yang mencakup berbagai alat dan secara opsional parameter pilihan alat. Setiap spesifikasi alat harus mencakup:
+ **Nama:** Hapus pengenal untuk alat
+ **Deskripsi:** Penjelasan singkat tentang fungsionalitas alat
+ **Skema Input: Skema** JSON yang mendefinisikan parameter yang diperlukan dan opsional
**Example Contoh konfigurasi alat**
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "calculator",
"description": "A calculator tool that can execute a math equation",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"equation": {
"type": "string",
"description": "The full equation to evaluate"
}
},
"required": ["equation"]
}
}
}
}
]
}
```
### Praktik terbaik untuk definisi alat
+ Pastikan nama dan deskripsi secara eksplisit menyampaikan fungsionalitas alat yang tepat; hindari alat yang terlalu mirip secara semantik
+ Sertakan pembeda utama dalam deskripsi untuk membantu model membedakan antara alat serupa
+ Batasi skema JSON menjadi dua lapisan bersarang untuk kinerja terbaik
+ Membatasi input menggunakan jenis skema (misalnya, enum, int, float) daripada menggambarkan struktur dalam teks biasa
+ Nyatakan parameter yang diperlukan vs. opsional menggunakan notasi skema JSON (misalnya, “wajib”: ["param1", “param2"])
+ Validasi skema JSON Anda menggunakan validator standar sebelum mengirimkan
+ Tempatkan argumen string panjang terakhir dalam skema dan hindari menyarangkannya
### Output terstruktur dengan decoding terbatas
Model Amazon Nova memanfaatkan decoding terbatas untuk memastikan keandalan tinggi dalam output yang dihasilkan. Teknik ini menggunakan tata bahasa untuk membatasi kemungkinan token pada setiap langkah pembuatan, mencegah kunci yang tidak valid dan menerapkan tipe data yang benar berdasarkan skema yang Anda tentukan.
**Example Contoh keluaran terstruktur**
```
tool_config = {
"tools": [
{
"toolSpec": {
"name": "ProductAnalysis",
"description": "Analyze product information from text.",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Product name"
},
"rating": {
"maximum": 5,
"description": "Customer rating 1-5",
"type": ["number", "null"],
"minimum": 1
},
"features": {
"description": "Key product features",
"type": "array",
"items": {"type": "string"}
},
"category": {
"type": "string",
"description": "Product category"
},
"price": {
"type": "number",
"description": "Price in USD"
}
},
"required": ["name", "category", "price", "features"]
}
}
}
}
],
"toolChoice": {
"tool": {"name": "ProductAnalysis"}
}
}
```
### Opsi pilihan alat
Amazon Nova mendukung tiga parameter pilihan alat:
Alat
Alat yang ditentukan akan dipanggil sekali, ideal untuk kasus penggunaan keluaran terstruktur
Setiap
Salah satu alat yang disediakan akan dipanggil setidaknya sekali, berguna untuk skenario pemilihan API
Otomatis
Model memutuskan apakah akan memanggil alat dan berapa banyak alat yang akan dipanggil (perilaku default)
## Panggil alat
Ketika Amazon Nova memutuskan untuk memanggil alat, ia mengembalikan blok penggunaan alat sebagai bagian dari pesan asisten dengan StopReason disetel ke “tool\$1use”. Blok alat berisi nama alat dan inputnya.
**catatan**
Jalankan bagian kode berikut secara berurutan (Memanggil alat → Panggilan alat pemrosesan → Mengembalikan hasil alat) dalam satu sesi Python. Untuk menjalankan contoh lagi, restart sesi Python Anda.
**Example Memanggil alat**
```
import boto3
import json
# Create Bedrock client
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
# Complex calculation that benefits from precise computation
messages = [{
"role": "user",
"content": [{
"text": "Calculate the compound interest on $10,000 invested at 4.75% annual rate for 7 years, compounded quarterly. Use the formula A = P(1 + r/n)^(nt) where P=10000, r=0.0475, n=4, t=7"
}]
}]
# Define tool configuration with calculator
tool_config = {
"tools": [{
"toolSpec": {
"name": "calculator",
"description": "Perform mathematical calculations",
"inputSchema": {
"json": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Mathematical expression to evaluate"
}
},
"required": ["expression"]
}
}
}
}]
}
# Invoke Model
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=messages,
toolConfig=tool_config
)
# Extract tool use from response
tool = next(
block["toolUse"]
for block in response["output"]["message"]["content"]
if "toolUse" in block
)
print(f"Tool: {tool['name']}")
print(f"Expression: {tool['input']['expression']}")
```
### Panggilan alat pemrosesan
Ekstrak nama alat dan argumen dari pesan, lalu panggil alat:
```
def calculate(expression):
"""Evaluate mathematical expression"""
print(f"Calculating: {expression}")
P = 10000
r = 0.0475
n = 4
t = 7
result = P * (1 + r/n) ** (n*t)
return result
stop_reason = response["stopReason"]
if stop_reason == "tool_use":
if tool["name"] == "calculator":
result = calculate(tool["input"]["expression"])
```
### Mengembalikan hasil alat
Kembalikan hasil alat menggunakan ToolResultBlock skema:
```
messages.append(response["output"]["message"])
# Add the tool result
messages.append({
"role": "user",
"content": [{
"toolResult": {
"toolUseId": tool['toolUseId'],
"content": [{"json": {"result": result}}],
"status": "success"
}
}]
})
# Send the tool result to the model
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=messages,
toolConfig=tool_config
)
# Extract and display final response
final_text = next(
block["text"]
for block in response["output"]["message"]["content"]
if "text" in block
)
print(f"\nFinal Response:\n{final_text}")
```
### Penanganan kesalahan
Laporkan kesalahan kembali ke Amazon Nova untuk mengizinkan modifikasi permintaan dan coba lagi:
```
tool_result_message = {
"role": "user",
"content": [
{
"toolResult": {
"toolUseId": tool["toolUseId"],
"content": [{"text": "A validation exception occurred on field: sample.field"}],
"status": "error"
}
}
]
}
```
### Pertimbangan keamanan
+ Validasi bahwa alat ada sebelum memanggilnya
+ Pastikan input diformat dengan benar
+ Verifikasi izin yang sesuai ada sebelum eksekusi alat
+ Andalkan detail sesi daripada mengizinkan Amazon Nova menyuntikkan informasi pengguna ke dalam panggilan alat
+ Ingat bahwa LLMs dapat berhalusinasi panggilan alat; selalu memvalidasi sebelum eksekusi
## Alat sistem bawaan
Model Amazon Nova 2.0 menyertakan alat bawaan yang dikelola sepenuhnya yang tidak memerlukan implementasi khusus. Aktifkan alat ini dengan sakelar sederhana di Converse API.
### Penerjemah Kode
Code Interpreter memungkinkan Nova untuk menjalankan kode Python dengan aman di lingkungan kotak pasir yang terisolasi. Alat ini dirancang untuk perhitungan matematika, operasi logis, dan algoritma iteratif.
**catatan**
Code Interpreter tersedia di Wilayah IAD, PDX, dan NRT. AWS Untuk memastikan permintaan Anda dialihkan ke Wilayah yang didukung, gunakan Global CRIS. Saat menggunakan kunci API Bedrock, Anda harus menambahkan `InvokeTool` izin secara manual ke definisi kebijakan. Peran Bedrock default tidak mengizinkan `InvokeTool` tindakan.
Aktifkan Code Interpreter dengan menentukan parameter SystemTool:
```
import boto3
import json
bedrock = boto3.client('bedrock-runtime', region_name='us-east-1')
tool_config = {
"tools": [{
"systemTool": {
"name": "nova_code_interpreter"
}
}]
}
response = bedrock.converse(
modelId="us.amazon.nova-2-lite-v1:0",
messages=[{
"role": "user",
"content": [{
"text": "What is the average of 10, 24, 2, 3, 43, 52, 13, 68, 6, 7, 902, 82"
}]
}],
toolConfig=tool_config,
inferenceConfig={"maxTokens": 10000, "temperature": 0}
)
# Pretty print the response
for block in response["output"]["message"]["content"]:
if "toolUse" in block:
print("=== Tool Use ===")
print(f"Tool: {block['toolUse']['name']}")
print(f"Code:\n{block['toolUse']['input']['snippet']}\n")
elif "toolResult" in block:
print("=== Tool Result ===")
result = block['toolResult']['content'][0]['json']
print(f"Output: {result['stdOut']}")
if result['stdErr']:
print(f"Error: {result['stdErr']}")
print(f"Exit Code: {result['exitCode']}\n")
elif "text" in block:
print("=== Final Answer ===")
print(block["text"])
```
Penerjemah menjalankan kode di kotak pasir dan mengembalikan hasil dalam skema standar:
```
{
"stdOut": "String",
"stdErr": "String",
"exitCode": "int",
"isError": "boolean"
}
```
### Pembumian Web
Web grounding memungkinkan Amazon Nova untuk mengakses informasi real-time dari internet, memberikan up-to-date tanggapan dan mengurangi halusinasi. Aktifkan dengan menentukan alat sistem nova\$1grounding:
```
tool_config = {
"tools": [{
"systemTool": {"name": "nova_grounding"}
}]
}
```
Untuk informasi rinci tentang Web Grounding, lihat[Pembumian Web](web-grounding.md).
### Protokol Konteks Model (MCP)
Model Context Protocol (MCP) adalah standar terbuka yang memungkinkan koneksi dua arah yang aman antara sumber data dan alat yang didukung AI. Alih-alih menulis adaptor khusus untuk setiap API atau layanan, jalankan server MCP dan biarkan Amazon Nova menemukan alatnya secara otomatis melalui jembatan klien.
Setelah terhubung, Amazon Nova memperlakukan alat MCP seperti integrasi eksternal lainnya: ia memutuskan kapan harus memanggil mereka, mengirim parameter yang diperlukan dan memasukkan hasil ke dalam tanggapan. Menggunakan Amazon Nova dengan Strands membuatnya lebih mudah dengan built-in MCPClient yang mengelola penemuan, koneksi, dan pemetaan hasil secara otomatis.