Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Inferensi menggunakan Converse API
Converse API hanya tersedia di `bedrock-runtime` endpoint.
Anda dapat menggunakan Amazon Bedrock Converse API untuk membuat aplikasi percakapan yang mengirim dan menerima pesan ke dan dari model Amazon Bedrock. Misalnya, Anda dapat membuat bot obrolan yang mempertahankan percakapan dalam banyak putaran dan menggunakan penyesuaian persona atau nada yang unik untuk kebutuhan Anda, seperti asisten dukungan teknis yang membantu.
Untuk menggunakan Converse API, Anda menggunakan operasi [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) atau [ConverseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStream.html)(untuk respons streaming) untuk mengirim pesan ke model. Dimungkinkan untuk menggunakan operasi inferensi dasar yang ada ([InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)atau [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)) untuk aplikasi percakapan. Namun, sebaiknya gunakan Converse API karena menyediakan API yang konsisten, yang berfungsi dengan semua model Amazon Bedrock yang mendukung pesan. Ini berarti Anda dapat menulis kode sekali dan menggunakannya dengan model yang berbeda. Jika model memiliki parameter inferensi yang unik, Converse API juga memungkinkan Anda untuk meneruskan parameter unik tersebut dalam struktur khusus model.
Anda dapat menggunakan Converse API untuk mengimplementasikan [penggunaan alat](tool-use.md) dan [pagar pembatas dalam aplikasi](guardrails-use-converse-api.md) Anda.
**catatan**
Dengan Mistral AI dan Meta model, Converse API menyematkan input Anda dalam template prompt khusus model yang memungkinkan percakapan.
Pembatasan berlaku untuk operasi berikut:`InvokeModel`,`InvokeModelWithResponseStream`,`Converse`, dan`ConverseStream`. Lihat [pembatasan API](inference-api-restrictions.md) untuk detailnya.
Untuk contoh kode, lihat berikut ini:
+ PythonContoh untuk topik ini — [Bercakap Contoh APIContoh API Converse (dipindahkan)](conversation-inference-examples.md)
+ Berbagai bahasa dan model — [Contoh kode untuk Amazon Bedrock Runtime menggunakan AWS SDK](service_code_examples_bedrock-runtime.md)
+ Tutorial [Java - Panduan pengembang Java untuk API baru Converse Bedrock](https://community.aws/content/2hUiEkO83hpoGF5nm3FWrdfYvPt/amazon-bedrock-converse-api-java-developer-guide)
+ JavaScript tutorial — [Panduan pengembang untuk API baru Converse Bedrock](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide)
## Menggunakan Bercakap API
Untuk menggunakan Converse API, Anda memanggil `ConverseStream` operasi `Converse` atau untuk mengirim pesan ke model. Untuk menelepon`Converse`, Anda memerlukan izin untuk `bedrock:InvokeModel` operasi. Untuk menelepon`ConverseStream`, Anda memerlukan izin untuk `bedrock:InvokeModelWithResponseStream` operasi.
### Permintaan
Saat membuat permintaan [Converse](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Converse.html) dengan [titik akhir runtime Amazon Bedrock](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#br-rt), Anda dapat menyertakan bidang berikut:
+ **ModelID** — Parameter yang diperlukan di header yang memungkinkan Anda menentukan sumber daya yang akan digunakan untuk inferensi.
+ Bidang berikut memungkinkan Anda menyesuaikan prompt:
+ **pesan** — Gunakan untuk menentukan konten dan peran petunjuknya.
+ **sistem** — Gunakan untuk menentukan prompt sistem, yang menentukan instruksi atau konteks untuk model.
+ **InferenceConfig** — Gunakan untuk menentukan parameter inferensi yang umum untuk semua model. Parameter inferensi mempengaruhi generasi respons.
+ **tambahan ModelRequestFields** — Gunakan untuk menentukan parameter inferensi yang spesifik untuk model yang Anda jalankan inferensi.
+ **PromptVariables** - (Jika Anda menggunakan prompt dari manajemen Prompt) Gunakan bidang ini untuk menentukan variabel dalam prompt untuk mengisi dan nilai-nilai yang digunakan untuk mengisinya.
+ Bidang berikut memungkinkan Anda menyesuaikan bagaimana respons dikembalikan:
+ **GuardrailConfig** — Gunakan bidang ini untuk menyertakan pagar pembatas untuk diterapkan ke seluruh prompt.
+ **ToolConfig** — Gunakan bidang ini untuk menyertakan alat untuk membantu model menghasilkan respons.
+ **tambahan ModelResponseFieldPaths** - Gunakan bidang ini untuk menentukan bidang untuk kembali sebagai objek penunjuk JSON.
+ **ServiceTier** - Gunakan bidang ini untuk menentukan tingkat layanan untuk permintaan tertentu
+ **RequestMetadata** — Gunakan bidang ini untuk menyertakan metadata yang dapat difilter saat menggunakan log pemanggilan.
**catatan**
Pembatasan berikut berlaku saat Anda menggunakan prompt manajemen Prompt dengan `Converse` atau`ConverseStream`:
Anda tidak dapat menyertakan`additionalModelRequestFields`,`inferenceConfig`,`system`, atau `toolConfig` bidang.
Jika Anda menyertakan `messages` bidang, pesan akan ditambahkan setelah pesan yang ditentukan dalam prompt.
Jika Anda menyertakan `guardrailConfig` bidang, pagar pembatas diterapkan ke seluruh prompt. Jika Anda memasukkan `guardContent` blok di [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)lapangan, pagar pembatas hanya akan diterapkan pada blok tersebut.
Perluas bagian untuk mempelajari lebih lanjut tentang bidang di badan `Converse` permintaan:
#### pesan
`messages`Bidang adalah array objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html), yang masing-masing mendefinisikan pesan antara pengguna dan model. Sebuah `Message` objek berisi bidang-bidang berikut:
+ **peran** — Mendefinisikan apakah pesan berasal dari `user` (prompt yang dikirim ke model) atau `assistant` (respons model).
+ **content** — Mendefinisikan konten dalam prompt.
**catatan**
Amazon Bedrock tidak menyimpan teks, gambar, atau dokumen apa pun yang Anda berikan sebagai konten. Data hanya digunakan untuk menghasilkan respons.
Anda dapat mempertahankan konteks percakapan dengan menyertakan semua pesan dalam percakapan dalam `Converse` permintaan berikutnya dan menggunakan `role` bidang untuk menentukan apakah pesan tersebut berasal dari pengguna atau model.
`content`Bidang memetakan ke array [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)objek. Di dalam masing-masing [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html), Anda dapat menentukan salah satu bidang berikut (untuk melihat model apa yang mendukung blok apa, [lihat model sekilas](model-cards.md)):
------
#### [ text ]
`text`Bidang memetakan ke string yang menentukan prompt. `text`Bidang ditafsirkan bersama bidang lain yang ditentukan dalam hal yang sama [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html).
Berikut ini menunjukkan objek [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang hanya berisi teks [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html):
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
}
]
}
```
------
#### [ image ]
Peta `image` lapangan ke sebuah [ImageBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ImageBlock.html). Lulus byte mentah, dikodekan dalam base64, untuk gambar di lapangan. `bytes` Jika Anda menggunakan AWS SDK, Anda tidak perlu menyandikan byte di base64.
Jika Anda mengecualikan `text` bidang, model menjelaskan gambar.
Berikut ini menunjukkan contoh objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang hanya berisi gambar [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html):
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"bytes": "{{image in bytes}}"
}
}
}
]
}
```
Anda juga dapat menentukan URI Amazon S3 alih-alih meneruskan byte langsung di badan permintaan. Berikut ini menunjukkan `Message` objek sampel dengan larik konten yang berisi sumber yang dilewatkan melalui URI Amazon S3.
```
{
"role": "user",
"content": [
{
"image": {
"format": "png",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myImage",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ document ]
Peta `document` lapangan ke sebuah [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html). Jika Anda menyertakan`DocumentBlock`, periksa apakah permintaan Anda sesuai dengan batasan berikut:
+ Di `content` bidang objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html), Anda juga harus menyertakan `text` bidang dengan prompt yang terkait dengan dokumen.
+ Lulus byte mentah, dikodekan dalam base64, untuk dokumen di lapangan. `bytes` Jika Anda menggunakan AWS SDK, Anda tidak perlu menyandikan byte dokumen di base64.
+ `name`Bidang hanya dapat berisi karakter berikut:
+ Karakter alfanumerik
+ Karakter spasi (tidak lebih dari satu berturut-turut)
+ Tanda hubung
+ Tanda kurung
+ Kurung persegi
**catatan**
`name`Bidang ini rentan terhadap suntikan cepat, karena model mungkin secara tidak sengaja menafsirkannya sebagai instruksi. Oleh karena itu, kami menyarankan Anda menentukan nama netral.
Saat menggunakan dokumen, Anda dapat mengaktifkan `citations` tag, yang akan memberikan kutipan khusus dokumen dalam respons panggilan API. Lihat [DocumentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_DocumentBlock.html)API untuk detail selengkapnya.
Berikut ini menunjukkan contoh objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang hanya berisi dokumen [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)dan teks yang menyertainya diperlukan. [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"bytes": "{{document in bytes}}"
}
}
}
]
}
```
Anda juga dapat menentukan URI Amazon S3 alih-alih meneruskan byte langsung di badan permintaan. Berikut ini menunjukkan `Message` objek sampel dengan larik konten yang berisi sumber yang dilewatkan melalui URI Amazon S3.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "MyDocument",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myDocument",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
------
#### [ video ]
`video`Bidang memetakan ke [VideoBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_VideoBlock.html)objek. Lulus byte mentah di `bytes` lapangan, dikodekan dalam base64. Jika Anda menggunakan AWS SDK, Anda tidak perlu menyandikan byte di base64.
Jika Anda tidak menyertakan `text` bidang, model akan menjelaskan video.
Berikut ini menunjukkan contoh objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang hanya berisi video [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html).
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"bytes": "{{video in bytes}}"
}
}
}
]
}
```
Anda juga dapat menentukan URI Amazon S3 alih-alih meneruskan byte langsung di badan permintaan. Berikut ini menunjukkan `Message` objek sampel dengan larik konten yang berisi sumber yang dilewatkan melalui URI Amazon S3.
```
{
"role": "user",
"content": [
{
"video": {
"format": "mp4",
"source": {
"s3Location": {
"uri": "s3://amzn-s3-demo-bucket/myVideo",
"bucketOwner": "111122223333"
}
}
}
}
]
}
```
**catatan**
Peran yang diasumsikan harus memiliki `s3:GetObject` izin ke URI Amazon S3. `bucketOwner`Kolom ini opsional tetapi harus ditentukan jika akun yang membuat permintaan tidak memiliki keranjang tempat URI Amazon S3 ditemukan. Untuk informasi selengkapnya, lihat [Konfigurasikan akses ke bucket Amazon S3](s3-bucket-access.md).
------
#### [ cachePoint ]
Anda dapat menambahkan pos pemeriksaan cache sebagai blok dalam pesan di samping prompt yang menyertainya dengan menggunakan `cachePoint` bidang untuk menggunakan caching prompt. Prompt caching adalah fitur yang memungkinkan Anda memulai cache konteks percakapan untuk mencapai penghematan biaya dan latensi. Untuk informasi selengkapnya, lihat [Caching cepat untuk inferensi model yang lebih cepat](prompt-caching.md).
Berikut ini menunjukkan contoh objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang berisi dokumen [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)dan teks yang menyertainya yang diperlukan [ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html), serta **CachePoint** yang menambahkan dokumen dan isi teks ke cache.
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"document": {
"format": "pdf",
"name": "string",
"source": {
"bytes": "{{document in bytes}}"
}
}
},
{
"cachePoint": {
"type": "default"
}
}
]
}
```
------
#### [ guardContent ]
`guardContent`Bidang memetakan ke [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)objek. Anda dapat menggunakan bidang ini untuk menargetkan input yang akan dievaluasi oleh pagar pembatas yang ditentukan di bidang. `guardrailConfig` Jika Anda tidak menentukan bidang ini, pagar pembatas akan mengevaluasi semua pesan di badan permintaan. Anda dapat meneruskan jenis konten berikut di`GuardBlock`:
+ **text** - Berikut ini menunjukkan contoh objek [Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang hanya berisi teks [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html):
```
{
"role": "user",
"content": [
{
"text": "Tell me what stocks to buy.",
"qualifiers": [
"guard_content"
]
}
]
}
```
Anda menentukan teks yang akan dievaluasi dan menyertakan kualifikasi apa pun yang akan digunakan untuk landasan [kontekstual](guardrails-contextual-grounding-check.md).
+ **image** — Berikut ini menunjukkan objek [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) dengan `content` array yang hanya berisi gambar [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html):
```
{
"role": "user",
"content": [
{
"format": "png",
"source": {
"bytes": "{{image in bytes}}"
}
}
]
}
```
Anda menentukan format gambar dan menentukan gambar dalam byte.
Untuk informasi selengkapnya tentang penggunaan pagar pembatas, lihat. [Mendeteksi dan memfilter konten berbahaya dengan menggunakan Amazon Bedrock Guardrails](guardrails.md)
------
#### [ reasoningContent ]
`reasoningContent`Bidang memetakan ke a [ReasoningContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ReasoningContentBlock.html). Blok ini berisi konten mengenai alasan yang dilakukan oleh model untuk menghasilkan respons yang menyertainya`ContentBlock`.
Berikut ini menunjukkan `Message` objek dengan `content` array yang hanya berisi `ReasoningContentBlock` dan teks yang menyertainya. `ContentBlock`
```
{
"role": "user",
"content": [
{
"text": "{{string}}"
},
{
"reasoningContent": {
"reasoningText": {
"text": "{{string}}",
"signature": "{{string}}"
}
"redactedContent": "{{base64-encoded binary data object}}"
}
}
]
}
```
`ReasoningContentBlock`Berisi alasan yang digunakan untuk menghasilkan konten yang menyertainya di `reasoningText` lapangan, di samping konten apa pun dalam alasan yang dienkripsi oleh penyedia model untuk alasan kepercayaan dan keamanan di lapangan. `redactedContent`
Di dalam `reasoningText` lapangan, `text` bidang menjelaskan alasannya. `signature`Bidang adalah hash dari semua pesan dalam percakapan dan merupakan perlindungan terhadap gangguan penalaran yang digunakan oleh model. Anda harus menyertakan tanda tangan dan semua pesan sebelumnya dalam `Converse` permintaan berikutnya. Jika ada pesan yang diubah, respons akan menimbulkan kesalahan.
------
#### [ toolUse ]
Berisi informasi tentang alat untuk model yang akan digunakan. Untuk informasi selengkapnya, lihat [Gunakan alat untuk menyelesaikan respons model Amazon Bedrock](tool-use.md).
------
#### [ toolResult ]
Berisi informasi tentang hasil dari model menggunakan alat. Untuk informasi selengkapnya, lihat [Gunakan alat untuk menyelesaikan respons model Amazon Bedrock](tool-use.md).
------
Dalam `messages` contoh berikut, pengguna meminta daftar tiga lagu pop, dan model menghasilkan daftar lagu.
```
[
{
"role": "user",
"content": [
{
"text": "Create a list of 3 pop songs."
}
]
},
{
"role": "assistant",
"content": [
{
"text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"As It Was\" by Harry Styles\n2. \"Easy On Me\" by Adele\n3. \"Unholy\" by Sam Smith and Kim Petras"
}
]
}
]
```
#### sistem
Prompt sistem adalah jenis prompt yang memberikan instruksi atau konteks kepada model tentang tugas yang harus dilakukan, atau persona yang harus diadopsi selama percakapan. Anda dapat menentukan daftar prompt sistem untuk permintaan di bidang `system` ([SystemContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_SystemContentBlock.html)), seperti yang ditunjukkan pada contoh berikut.
```
[
{
"text": "You are an app that creates play lists for a radio station that plays rock and pop music. Only return song names and the artist. "
}
]
```
#### InferensiConfig
ConverseAPI mendukung kumpulan dasar parameter inferensi yang Anda tetapkan di `inferenceConfig` field ([InferenceConfiguration](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InferenceConfiguration.html)). Set dasar parameter inferensi adalah:
+ **MaxTokens** — Jumlah maksimum token untuk memungkinkan respons yang dihasilkan.
+ **StopSequences** — Daftar urutan berhenti. Urutan berhenti adalah urutan karakter yang menyebabkan model berhenti menghasilkan respons.
+ **suhu** — Kemungkinan model memilih opsi probabilitas yang lebih tinggi sambil menghasilkan respons.
+ **TopP** — Persentase kandidat yang paling mungkin yang dipertimbangkan model untuk token berikutnya.
Untuk informasi selengkapnya, lihat [Mempengaruhi generasi respons dengan parameter inferensi](inference-parameters.md).
Contoh berikut JSON menetapkan parameter `temperature` inferensi.
```
{"temperature": 0.5}
```
#### tambahan ModelRequestFields
Jika model yang Anda gunakan memiliki parameter inferensi tambahan, Anda dapat mengatur parameter tersebut dengan menentukannya sebagai JSON di lapangan. `additionalModelRequestFields` Contoh berikut JSON menunjukkan cara menyetel`top_k`, yang tersedia dalam Anthropic Claude model, tetapi bukan merupakan parameter inferensi dasar di API pesan.
```
{"top_k": 200}
```
#### PromptVariables
Jika Anda menentukan [prompt dari manajemen Prompt](prompt-management.md) `modelId` sebagai sumber daya untuk menjalankan inferensi, gunakan bidang ini untuk mengisi variabel prompt dengan nilai aktual. `promptVariables`Bidang memetakan ke objek JSON dengan kunci yang sesuai dengan variabel yang ditentukan dalam prompt dan nilai untuk mengganti variabel dengan.
Misalnya, katakanlah Anda memiliki prompt yang mengatakan**Make me a {{{{genre}}}} playlist consisting of the following number of songs: {{{{number}}}}.**. ID prompt adalah `PROMPT12345` dan versinya adalah`1`. Anda dapat mengirim `Converse` permintaan berikut untuk mengganti variabel:
```
POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1
Content-type: application/json
{
"promptVariables": {
"genre": {
"text": "pop"
},
"number": {
"text": "3"
}
}
}
```
#### GuardrailConfig
Anda dapat menerapkan pagar pembatas yang Anda buat dengan [Amazon Bedrock Guardrails](guardrails.md) dengan menyertakan bidang ini. Untuk menerapkan pagar pembatas ke pesan tertentu dalam percakapan, sertakan pesan dalam file. [GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html) Jika Anda tidak menyertakan `GuardrailConverseContentBlock` s apa pun di badan permintaan, pagar pembatas diterapkan ke semua pesan di `messages` bidang. Sebagai contoh, lihat [Sertakan pagar pembatas dengan Bercakap-cakap API](guardrails-use-converse-api.md).
#### ToolConfig
Bidang ini memungkinkan Anda menentukan alat untuk model yang akan digunakan untuk membantunya menghasilkan respons. Untuk informasi selengkapnya, lihat [Gunakan alat untuk menyelesaikan respons model Amazon Bedrock](tool-use.md).
#### tambahan ModelResponseFieldPaths
Anda dapat menentukan jalur untuk parameter model tambahan di `additionalModelResponseFieldPaths` lapangan, seperti yang ditunjukkan pada contoh berikut.
```
[ "/stop_sequence" ]
```
API mengembalikan bidang tambahan yang Anda minta di `additionalModelResponseFields` bidang tersebut.
#### PermintaMetadata
`requestMetadata`Bidang memetakan ke objek JSON dari tag nilai kunci yang direkam dengan permintaan di log pemanggilan model Anda. Anda dapat menggunakan metadata permintaan untuk memfilter dan mengumpulkan log berdasarkan tim, aplikasi, lingkungan, atau dimensi lain yang bervariasi per panggilan.
Kemampuan yang sama tersedia di [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html)dan [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html)melalui header `X-Amzn-Bedrock-Request-Metadata` HTTP. Untuk detail tentang API yang didukung, batasan, dan cara metadata permintaan muncul di log pemanggilan, lihat. [Per-request penandaan metadata](cost-mgmt-request-metadata.md)
#### ServiceTier
Bidang ini memetakan ke objek JSON. Anda dapat menentukan tingkat layanan untuk permintaan tertentu.
Contoh berikut menunjukkan `serviceTier` struktur:
```
"serviceTier": {
"type": "reserved" | "priority" | "default" | "flex"
}
```
Untuk informasi rinci tentang tingkatan layanan, termasuk karakteristik harga dan kinerja, lihat[Tingkat layanan untuk mengoptimalkan kinerja dan biaya](service-tiers-inference.md).
Anda juga dapat secara opsional menambahkan pos pemeriksaan cache ke `tools` bidang `system` atau untuk menggunakan caching prompt, tergantung pada model yang Anda gunakan. Untuk informasi selengkapnya, lihat [Caching cepat untuk inferensi model yang lebih cepat](prompt-caching.md).
### Respons
Respons yang Anda dapatkan dari Converse API tergantung pada operasi yang Anda panggil, `Converse` atau`ConverseStream`.
#### Tanggapan Converse
Dalam tanggapan dari`Converse`, `output` bidang ([ConverseOutput](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseOutput.html)) berisi pesan ([Pesan](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)) yang dihasilkan model. Konten pesan ada di bidang `content` ([ContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlock.html)) dan peran (`user`atau`assistant`) yang sesuai dengan pesan ada di `role` bidang.
Jika Anda menggunakan [caching prompt](prompt-caching.md), maka di bidang penggunaan, `cacheReadInputTokens` dan `cacheWriteInputTokens` memberi tahu Anda berapa banyak total token yang dibaca dari cache dan ditulis ke cache, masing-masing.
Jika Anda menggunakan [tingkatan layanan](#inference-service-tiers), maka di bidang respons, `service tier` akan memberi tahu Anda tingkat layanan mana yang digunakan untuk permintaan tersebut.
`metrics`Bidang ([ConverseMetrics](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseMetrics.html)) menyertakan metrik untuk panggilan. Untuk menentukan mengapa model berhenti menghasilkan konten, periksa `stopReason` bidangnya. Anda bisa mendapatkan informasi tentang token yang diteruskan ke model dalam permintaan, dan token yang dihasilkan dalam respons, dengan memeriksa `usage` bidang ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html)). Jika Anda menetapkan bidang respons tambahan dalam permintaan, API akan mengembalikannya sebagai JSON di `additionalModelResponseFields` bidang tersebut.
Contoh berikut menunjukkan respons dari `Converse` saat Anda meneruskan prompt yang dibahas di[Permintaan](#conversation-inference-call-request).
```
{
"output": {
"message": {
"role": "assistant",
"content": [
{
"text": "Here is a list of 3 pop songs by artists from the United Kingdom:\n\n1. \"Wannabe\" by Spice Girls\n2. \"Bitter Sweet Symphony\" by The Verve \n3. \"Don't Look Back in Anger\" by Oasis"
}
]
}
},
"stopReason": "end_turn",
"usage": {
"inputTokens": 125,
"outputTokens": 60,
"totalTokens": 185
},
"metrics": {
"latencyMs": 1175
}
}
```
#### ConverseStream respon
Jika Anda memanggil `ConverseStream` untuk mengalirkan respons dari model, aliran dikembalikan di bidang `stream` respons. Aliran memancarkan peristiwa berikut dalam urutan sebagai berikut.
1. `messageStart`([MessageStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStartEvent.html)). Acara awal untuk pesan. Termasuk peran untuk pesan.
1. `contentBlockStart`([ContentBlockStartEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStartEvent.html)). Acara mulai blok Konten. Hanya menggunakan alat.
1. `contentBlockDelta`([ContentBlockDeltaEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockDeltaEvent.html)). Acara delta blok Konten. Termasuk salah satu dari berikut ini:
+ `text`— Teks parsi yang dihasilkan model.
+ `reasoningContent`— Penalaran sebagian yang dilakukan oleh model untuk menghasilkan respons. Anda harus mengirimkan yang dikembalikan`signature`, selain semua pesan sebelumnya dalam `Converse` permintaan berikutnya. Jika ada pesan yang diubah, respons akan menimbulkan kesalahan.
+ `toolUse`— Masukan sebagian objek JSON untuk penggunaan alat.
1. `contentBlockStop`([ContentBlockStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ContentBlockStopEvent.html)). Peristiwa penghentian blok Konten.
1. `messageStop`([MessageStopEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_MessageStopEvent.html)). Acara berhenti untuk pesan. Termasuk alasan mengapa model berhenti menghasilkan output.
1. `metadata`([ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)). Metadata untuk permintaan. Metadata mencakup penggunaan token in `usage` ([TokenUsage](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_TokenUsage.html)) dan metrik untuk panggilan in `metrics` (). [ConverseStreamMetadataEvent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_ConverseStreamMetadataEvent.html)
ConverseStream mengalirkan blok konten lengkap sebagai `ContentBlockStartEvent` acara, satu atau beberapa `ContentBlockDeltaEvent` acara, dan `ContentBlockStopEvent` acara. Gunakan `contentBlockIndex` bidang sebagai indeks untuk mengkorelasikan peristiwa yang membentuk blok konten.
Contoh berikut adalah sebagian respon dari`ConverseStream`.
```
{'messageStart': {'role': 'assistant'}}
{'contentBlockDelta': {'delta': {'text': ''}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ' Title'}, 'contentBlockIndex': 0}}
{'contentBlockDelta': {'delta': {'text': ':'}, 'contentBlockIndex': 0}}
.
.
.
{'contentBlockDelta': {'delta': {'text': ' The'}, 'contentBlockIndex': 0}}
{'messageStop': {'stopReason': 'max_tokens'}}
{'metadata': {'usage': {'inputTokens': 47, 'outputTokens': 20, 'totalTokens': 67}, 'metrics': {'latencyMs': 100.0}}}
```
## Bercakap Contoh API
Contoh berikut menunjukkan cara menggunakan `Converse` dan `ConverseStream` operasi.
------
#### [ Text ]
Contoh ini menunjukkan cara memanggil `Converse` operasi dengan *AnthropicClaude 3 Sonnet*model. Contoh menunjukkan cara mengirim teks input, parameter inferensi, dan parameter tambahan yang unik untuk model. Kode memulai percakapan dengan meminta model untuk membuat daftar lagu. Kemudian melanjutkan percakapan dengan menanyakan bahwa lagu-lagu tersebut dibuat oleh artis dari Britania Raya.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API with Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
system_prompts,
messages):
"""
Sends messages to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
system_prompts (JSON) : The system prompts for the model to use.
messages (JSON) : The messages to send to the model.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters to use.
inference_config = {"temperature": temperature}
# Additional inference parameters to use.
additional_model_fields = {"top_k": top_k}
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
# Log token usage.
token_usage = response['usage']
logger.info("Input tokens: %s", token_usage['inputTokens'])
logger.info("Output tokens: %s", token_usage['outputTokens'])
logger.info("Total tokens: %s", token_usage['totalTokens'])
logger.info("Stop reason: %s", response['stopReason'])
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
# Setup the system prompts and messages to send to the model.
system_prompts = [{"text": "You are an app that creates playlists for a radio station that plays rock and pop music. Only return song names and the artist."}]
message_1 = {
"role": "user",
"content": [{"text": "Create a list of 3 pop songs."}]
}
message_2 = {
"role": "user",
"content": [{"text": "Make sure the songs are by artists from the United Kingdom."}]
}
messages = []
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
# Start the conversation with the 1st message.
messages.append(message_1)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
# Add the response message to the conversation.
output_message = response['output']['message']
messages.append(output_message)
# Continue the conversation with the 2nd message.
messages.append(message_2)
response = generate_conversation(
bedrock_client, model_id, system_prompts, messages)
output_message = response['output']['message']
messages.append(output_message)
# Show the complete conversation.
for message in messages:
print(f"Role: {message['role']}")
for content in message['content']:
print(f"Text: {content['text']}")
print()
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()
```
------
#### [ Image ]
Contoh ini menunjukkan cara mengirim gambar sebagai bagian dari pesan dan permintaan agar model menggambarkan gambar. Contoh menggunakan `Converse` operasi dan *AnthropicClaude 3 Sonnet*model.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an image with the Converse API with an accompanying text prompt to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_image):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The text prompt accompanying the image.
input_image : The path to the input image.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get image extension and read in image as bytes
image_ext = input_image.split(".")[-1]
with open(input_image, "rb") as f:
image = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"image": {
"format": image_ext,
"source": {
"bytes": image
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this image?"
input_image = "path/to/image"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_image)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
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()
```
------
#### [ Document ]
Contoh ini menunjukkan cara mengirim dokumen sebagai bagian dari pesan dan meminta agar model menggambarkan isi dokumen. Contoh menggunakan `Converse` operasi dan *AnthropicClaude 3 Sonnet*model.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send an document as part of a message to Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_message(bedrock_client,
model_id,
input_text,
input_document_path):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_document_path : The path to the input document.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Get format from path and read the path
input_document_format = input_document_path.split(".")[-1]
with open(input_document_path, 'rb') as input_document_file:
input_document = input_document_file.read()
# Message to send.
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"document": {
"name": "MyDocument",
"format": input_document_format,
"source": {
"bytes": input_document
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Anthropic Claude 3 Sonnet example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
input_text = "What's in this document?"
input_document_path = "path/to/document"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_message(
bedrock_client, model_id, input_text, input_document_path)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
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()
```
------
#### [ Streaming ]
Contoh ini menunjukkan cara memanggil `ConverseStream` operasi dengan *AnthropicClaude 3 Sonnet*model. Contoh menunjukkan cara mengirim teks input, parameter inferensi, dan parameter tambahan yang unik untuk model.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to use the Converse API to stream a response from Anthropic Claude 3 Sonnet (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def stream_conversation(bedrock_client,
model_id,
messages,
system_prompts,
inference_config,
additional_model_fields):
"""
Sends messages 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.
system_prompts (JSON) : The system prompts to send.
inference_config (JSON) : The inference configuration to use.
additional_model_fields (JSON) : Additional model fields to use.
Returns:
Nothing.
"""
logger.info("Streaming messages with model %s", model_id)
response = bedrock_client.converse_stream(
modelId=model_id,
messages=messages,
system=system_prompts,
inferenceConfig=inference_config,
additionalModelRequestFields=additional_model_fields
)
stream = response.get('stream')
if stream:
for event in stream:
if 'messageStart' in event:
print(f"\nRole: {event['messageStart']['role']}")
if 'contentBlockDelta' in event:
print(event['contentBlockDelta']['delta']['text'], end="")
if 'messageStop' in event:
print(f"\nStop reason: {event['messageStop']['stopReason']}")
if 'metadata' in event:
metadata = event['metadata']
if 'usage' in metadata:
print("\nToken usage")
print(f"Input tokens: {metadata['usage']['inputTokens']}")
print(
f":Output tokens: {metadata['usage']['outputTokens']}")
print(f":Total tokens: {metadata['usage']['totalTokens']}")
if 'metrics' in event['metadata']:
print(
f"Latency: {metadata['metrics']['latencyMs']} milliseconds")
def main():
"""
Entrypoint for streaming message API response example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "anthropic.claude-3-sonnet-20240229-v1:0"
system_prompt = """You are an app that creates playlists for a radio station
that plays rock and pop music. Only return song names and the artist."""
# Message to send to the model.
input_text = "Create a list of 3 pop songs."
message = {
"role": "user",
"content": [{"text": input_text}]
}
messages = [message]
# System prompts.
system_prompts = [{"text" : system_prompt}]
# inference parameters to use.
temperature = 0.5
top_k = 200
# Base inference parameters.
inference_config = {
"temperature": temperature
}
# Additional model inference parameters.
additional_model_fields = {"top_k": top_k}
try:
bedrock_client = boto3.client(service_name='bedrock-runtime')
stream_conversation(bedrock_client, model_id, messages,
system_prompts, inference_config, additional_model_fields)
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"Finished streaming messages with model {model_id}.")
if __name__ == "__main__":
main()
```
------
#### [ Video ]
Contoh ini menunjukkan cara mengirim video sebagai bagian dari pesan dan permintaan agar model menjelaskan video tersebut. Contoh menggunakan `Converse` operasi dan Amazon Nova Pro model.
```
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
# SPDX-License-Identifier: Apache-2.0
"""
Shows how to send a video with the Converse API to Amazon Nova Pro (on demand).
"""
import logging
import boto3
from botocore.exceptions import ClientError
logger = logging.getLogger(__name__)
logging.basicConfig(level=logging.INFO)
def generate_conversation(bedrock_client,
model_id,
input_text,
input_video):
"""
Sends a message to a model.
Args:
bedrock_client: The Boto3 Bedrock runtime client.
model_id (str): The model ID to use.
input text : The input message.
input_video : The input video.
Returns:
response (JSON): The conversation that the model generated.
"""
logger.info("Generating message with model %s", model_id)
# Message to send.
with open(input_video, "rb") as f:
video = f.read()
message = {
"role": "user",
"content": [
{
"text": input_text
},
{
"video": {
"format": 'mp4',
"source": {
"bytes": video
}
}
}
]
}
messages = [message]
# Send the message.
response = bedrock_client.converse(
modelId=model_id,
messages=messages
)
return response
def main():
"""
Entrypoint for Amazon Nova Pro example.
"""
logging.basicConfig(level=logging.INFO,
format="%(levelname)s: %(message)s")
model_id = "amazon.nova-pro-v1:0"
input_text = "What's in this video?"
input_video = "path/to/video"
try:
bedrock_client = boto3.client(service_name="bedrock-runtime")
response = generate_conversation(
bedrock_client, model_id, input_text, input_video)
output_message = response['output']['message']
print(f"Role: {output_message['role']}")
for content in output_message['content']:
print(f"Text: {content['text']}")
token_usage = response['usage']
print(f"Input tokens: {token_usage['inputTokens']}")
print(f"Output tokens: {token_usage['outputTokens']}")
print(f"Total tokens: {token_usage['totalTokens']}")
print(f"Stop reason: {response['stopReason']}")
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()
```
------