Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Menggunakan Converse API

Untuk menggunakan Converse API, Anda memanggil Converse atau ConverseStream operasi untuk mengirim pesan ke model. Untuk meneleponConverse, Anda memerlukan izin untuk bedrock:InvokeModel operasi. Untuk meneleponConverseStream, Anda memerlukan izin untuk bedrock:InvokeModelWithResponseStream operasi.

Permintaan

Anda menentukan model yang ingin Anda gunakan dengan mengatur modelId bidang. Untuk daftar model IDs yang didukung Amazon Bedrock, lihatModel pondasi yang didukung di Amazon Bedrock.

Percakapan adalah serangkaian pesan antara pengguna dan model. Anda memulai percakapan dengan mengirim pesan sebagai pengguna (peran pengguna) ke model. Model, bertindak sebagai asisten (peran asisten), kemudian menghasilkan respons yang dikembalikan dalam pesan. Jika diinginkan, Anda dapat melanjutkan percakapan dengan mengirimkan pesan peran pengguna lebih lanjut ke model. Untuk mempertahankan konteks percakapan, pastikan untuk menyertakan pesan peran asisten yang Anda terima dari model dalam permintaan berikutnya.

Anda memberikan pesan yang ingin diteruskan ke model di messages bidang, yang memetakan ke array objek Pesan. Setiap Pesan berisi konten untuk pesan dan peran yang dimainkan pesan dalam percakapan.

Anda menambahkan konten untuk pesan di content bidang, yang memetakan ke array ContentBlockobjek. Dalam masing-masing ContentBlock, Anda dapat menentukan salah satu bidang berikut (untuk melihat model apa yang mendukung modalitas apa, lihatModel dan fitur model yang didukung):

text

textBidang memetakan ke string yang menentukan prompt. textBidang ditafsirkan bersama bidang lain yang ditentukan dalam hal yang sama ContentBlock.

(Opsional) Untuk model tertentu, Anda dapat menambahkan pos pemeriksaan cache menggunakan cachePoint bidang untuk memanfaatkan caching prompt. Prompt caching adalah fitur yang memungkinkan Anda untuk mulai caching konteks percakapan untuk mencapai penghematan biaya dan latensi. Untuk informasi selengkapnya, lihat Caching cepat untuk inferensi model yang lebih cepat.

catatan

Amazon Bedrock prompt caching saat ini hanya tersedia untuk sejumlah pelanggan tertentu. Untuk mempelajari lebih lanjut tentang berpartisipasi dalam pratinjau, lihat caching prompt Amazon Bedrock.

Berikut ini menunjukkan objek Message dengan content array yang hanya berisi teks ContentBlock:

{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        }
    ]
}

Berikut ini menunjukkan objek Pesan dengan content array yang berisi teks ContentBlockdan cachePoint bidang opsional. Konten dalam teks ContentBlockditambahkan ke cache sebagai hasilnya.

{
    "role": "user | assistant",
    "content": [
        {
            "text": "string"
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

image

Peta image lapangan ke sebuah ImageBlock. 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.

(Opsional) Untuk model tertentu, Anda dapat menambahkan pos pemeriksaan cache menggunakan cachePoint bidang untuk memanfaatkan caching prompt. Prompt caching adalah fitur yang memungkinkan Anda untuk mulai caching konteks percakapan untuk mencapai penghematan biaya dan latensi. Untuk informasi selengkapnya, lihat Caching cepat untuk inferensi model yang lebih cepat.

catatan

Amazon Bedrock prompt caching saat ini hanya tersedia untuk sejumlah pelanggan tertentu. Untuk mempelajari lebih lanjut tentang berpartisipasi dalam pratinjau, lihat caching prompt Amazon Bedrock.

Berikut ini menunjukkan objek Message dengan content array yang hanya berisi gambar ContentBlock:

{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        }
    ]
}

Berikut ini menunjukkan objek Pesan dengan content array yang berisi gambar ContentBlockdan cachePoint bidang opsional. Konten gambar ditambahkan ke cache sebagai hasilnya.

{
    "role": "user",
    "content": [
        {
            "image": {
                "format": "png | jpeg | gif | webp",
                "source": {
                    "bytes": "image in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

document

Peta document lapangan ke sebuah DocumentBlock. Jika Anda menyertakanDocumentBlock, periksa apakah permintaan Anda sesuai dengan batasan berikut:

• Di content bidang objek Pesan, 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.

• nameBidang hanya dapat berisi karakter berikut:

  • Karakter alfanumerik

  • Karakter spasi (tidak lebih dari satu berturut-turut)

  • Tanda hubung

  • Tanda kurung

  • Kurung persegi

  catatan

  nameBidang ini rentan terhadap suntikan cepat, karena model mungkin secara tidak sengaja menafsirkannya sebagai instruksi. Oleh karena itu, kami menyarankan Anda menentukan nama netral.

(Opsional) Untuk model tertentu, Anda dapat menambahkan pos pemeriksaan cache menggunakan cachePoint bidang untuk memanfaatkan caching prompt. Prompt caching adalah fitur yang memungkinkan Anda untuk mulai caching konteks percakapan untuk mencapai penghematan biaya dan latensi. Untuk informasi selengkapnya, lihat Caching cepat untuk inferensi model yang lebih cepat.

catatan

Amazon Bedrock prompt caching saat ini hanya tersedia untuk sejumlah pelanggan tertentu. Untuk mempelajari lebih lanjut tentang berpartisipasi dalam pratinjau, lihat caching prompt Amazon Bedrock.

Berikut ini menunjukkan objek Message dengan content array yang hanya berisi dokumen ContentBlockdan teks yang menyertainya diperlukan. ContentBlock

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        }
    ]
}

Berikut ini menunjukkan objek Pesan dengan content array yang berisi dokumen ContentBlockdan teks yang menyertainya yang diperlukan ContentBlock, serta cachePointyang menambahkan dokumen dan isi teks ke cache.

{
    "role": "user",
    "content": [
        {
            "text": "string"
        },
        {
            "document": {
                "format": "pdf | csv | doc | docx | xls | xlsx | html | txt | md",
                "name": "string",
                "source": {
                    "bytes": "document in bytes"
                }
            }
        },
        {
            "cachePoint": {
                "type": "default"
            }
        }
    ]
}

video

Peta video lapangan ke aVideoBlock. 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 objek Message dengan content array yang hanya berisi video ContentBlock.

{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "bytes": "video in bytes"
                }
            }
        }
    ]
}

Perhatikan bahwa untuk file dengan .3gp ekstensi, format harus ditentukan sebagaithree_gp.

Anda juga dapat meneruskan video melalui Amazon S3 URI alih-alih meneruskan byte langsung di badan permintaan. Berikut ini menunjukkan Message objek dengan array konten yang hanya berisi video ContentBlock dengan sumber video melewati Amazon S3URI.

{
    "role": "user",
    "content": [
        {
            "video": {
                "format": "mov | mkv | mp4 | webm | flv | mpeg | mpg | wmv | three_gp",
                "source": {
                    "s3Location": {
                        "uri": "s3 uri",
                        "bucketOwner": "s3 uri bucket owner"
                    }
                }
            }
        }
    ]
}

s3LocationParameter ini hanya didukung di wilayah AS Timur (Virginia N.).

catatan

Peran yang diasumsikan harus memiliki s3:GetObject izin ke Amazon S3URI. bucketOwnerBidang ini opsional tetapi harus ditentukan jika akun yang membuat permintaan tidak memiliki ember tempat Amazon S3 URI ditemukan.

Bidang lainnya ContentBlock adalah untuk penggunaan alat.

Anda menentukan peran di role lapangan. Perannya bisa menjadi salah satu dari yang berikut:

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"
            }
        ]
    }
]

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), 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. "
    }
]

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.

Parameter inferensi

Bagian Converse APImendukung kumpulan dasar parameter inferensi yang Anda tetapkan di inferenceConfig bidang (InferenceConfiguration). Set dasar parameter inferensi adalah:

Untuk informasi selengkapnya, lihat Mempengaruhi generasi respons dengan parameter inferensi.

Contoh berikut JSON menetapkan parameter temperature inferensi.

{"temperature": 0.5}

Jika model yang Anda gunakan memiliki parameter inferensi tambahan, Anda dapat mengatur parameter tersebut dengan menentukannya seperti JSON di additionalModelRequestFields bidang. Contoh berikut JSON menunjukkan cara mengaturtop_k, yang tersedia di Anthropic Claude model, tetapi bukan parameter inferensi dasar dalam pesanAPI.

{"top_k": 200}

Anda dapat menentukan jalur untuk parameter model tambahan di additionalModelResponseFieldPaths lapangan, seperti yang ditunjukkan pada contoh berikut.

[ "/stop_sequence" ]

APIMengembalikan bidang tambahan yang Anda minta di additionalModelResponseFields bidang.

Respons

Tanggapan yang Anda dapatkan dari Converse APItergantung pada operasi yang Anda panggil, Converse atauConverseStream.

Tanggapan Converse

Dalam tanggapan dariConverse, output bidang (ConverseOutput) berisi pesan (Pesan) yang dihasilkan model. Konten pesan ada di bidang content (ContentBlock) dan peran (useratauassistant) yang sesuai dengan pesan ada di role bidang.

Jika Anda menggunakan caching prompt, maka di bidang penggunaan, cacheReadInputTokensCount dan cacheWriteInputTokensCount memberi tahu Anda berapa banyak total token yang dibaca dari cache dan ditulis ke cache, masing-masing.

metricsBidang (ConverseMetrics) 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). Jika Anda menentukan bidang respons tambahan dalam permintaan, API mengembalikannya seperti JSON di additionalModelResponseFields bidang.

Contoh berikut menunjukkan respons dari Converse saat Anda meneruskan prompt yang dibahas diPermintaan.

{
    "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.

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 dariConverseStream.

{'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}}}