Utilisation de Converse « Hello, World! » - Amazon Bedrock

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilisation de Converse « Hello, World! »

Pour utiliser le plugin Converse API, vous appelez les ConverseStream opérations Converse or pour envoyer des messages à un modèle. Pour appelerConverse, vous devez disposer d'une autorisation pour effectuer l'bedrock:InvokeModelopération. Pour appelerConverseStream, vous devez disposer d'une autorisation pour effectuer l'bedrock:InvokeModelWithResponseStreamopération.

Demande

Lorsque vous effectuez une demande Converse avec un point de terminaison Amazon Bedrock, vous pouvez inclure les champs suivants :

  • ModelID — Paramètre obligatoire dans l'en-tête qui vous permet de spécifier la ressource à utiliser pour l'inférence.

  • Les champs suivants vous permettent de personnaliser l'invite :

    • messages — À utiliser pour spécifier le contenu et le rôle des invites.

    • système — À utiliser pour spécifier les instructions du système, qui définissent les instructions ou le contexte du modèle.

    • InferenceConfig — À utiliser pour spécifier les paramètres d'inférence communs à tous les modèles. Les paramètres d'inférence influencent la génération de la réponse.

    • additionalmodelRequestFields— À utiliser pour spécifier des paramètres d'inférence spécifiques au modèle avec lequel vous exécutez l'inférence.

    • PromptVariables — (Si vous utilisez une invite de la gestion des invites) Utilisez ce champ pour définir les variables de l'invite à renseigner et les valeurs avec lesquelles les remplir.

  • Les champs suivants vous permettent de personnaliser le mode de renvoi de la réponse :

    • GuardRailConfig — Utilisez ce champ pour inclure un garde-corps à appliquer à l'ensemble de l'invite.

    • ToolConfig — Utilisez ce champ pour inclure un outil permettant à un modèle de générer des réponses.

    • additionalModelResponseFieldPaths— Utilisez ce champ pour spécifier les champs à renvoyer sous forme d'objet pointeur JSON.

  • RequestMetadata — Utilisez ce champ pour inclure des métadonnées qui peuvent être filtrées lors de l'utilisation des journaux d'invocation.

Note

Les restrictions suivantes s'appliquent lorsque vous utilisez une invite de gestion rapide avec Converse ou ConverseStream :

  • Vous ne pouvez pas inclure les toolConfig champs additionalModelRequestFields inferenceConfigsystem,, ou.

  • Si vous incluez le messages champ, les messages sont ajoutés après les messages définis dans l'invite.

  • Si vous incluez le guardrailConfig champ, le garde-corps est appliqué à l'ensemble de l'invite. Si vous incluez guardContent des blocs dans le ContentBlockchamp, le garde-corps ne sera appliqué qu'à ces blocs.

Développez une section pour en savoir plus sur un champ dans le corps de la Converse demande :

Le messages champ est un tableau d'objets Message, dont chacun définit un message entre l'utilisateur et le modèle. Un Message objet contient les champs suivants :

  • rôle — Définit si le message provient de user (l'invite envoyée au modèle) ou assistant (la réponse du modèle).

  • contenu — Définit le contenu de l'invite.

    Note

    Amazon Bedrock ne stocke aucun texte, image ou document que vous fournissez sous forme de contenu. Les données ne sont utilisées que pour générer la réponse.

Vous pouvez conserver le contexte de la conversation en incluant tous les messages de la conversation dans les Converse demandes suivantes et en utilisant le role champ pour spécifier si le message provient de l'utilisateur ou du modèle.

Le content champ correspond à un ensemble d'ContentBlockobjets. Dans chacun d'eux ContentBlock, vous pouvez spécifier l'un des champs suivants (pour savoir quels modèles prennent en charge quelles modalités, voirModèles pris en charge et caractéristiques des modèles) :

text

Le text champ correspond à une chaîne spécifiant l'invite. Le text champ est interprété parallèlement aux autres champs qui y sont spécifiés ContentBlock.

(Facultatif) Pour certains modèles, vous pouvez ajouter des points de contrôle du cache à l'aide de cachePoint champs pour utiliser la mise en cache rapide. La mise en cache rapide est une fonctionnalité qui vous permet de commencer à mettre en cache le contexte des conversations afin de réaliser des économies de coûts et de latence. Pour de plus amples informations, veuillez consulter Mise en cache rapide pour une inférence de modèle plus rapide.

Note

La mise en cache rapide d'Amazon Bedrock n'est actuellement disponible que pour un certain nombre de clients. Pour en savoir plus sur la participation à la version préliminaire, consultez Amazon Bedrock prompt caching.

L'image suivante montre un objet Message avec un content tableau contenant uniquement du texte ContentBlock:

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

L'image suivante montre un objet Message avec un content tableau contenant un texte ContentBlocket un cachePoint champ facultatif. Le contenu du texte ContentBlockest ainsi ajouté au cache.

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

Le image champ correspond à un ImageBlock. Passez les octets bruts, codés en base64, pour une image dans le bytes champ. Si vous utilisez un AWS SDK, vous n'avez pas besoin de coder les octets en base64.

Si vous excluez le text champ, le modèle décrit l'image.

(Facultatif) Pour certains modèles, vous pouvez ajouter des points de contrôle du cache à l'aide de cachePoint champs pour utiliser la mise en cache rapide. La mise en cache rapide est une fonctionnalité qui vous permet de commencer à mettre en cache le contexte des conversations afin de réaliser des économies de coûts et de latence. Pour de plus amples informations, veuillez consulter Mise en cache rapide pour une inférence de modèle plus rapide.

Note

La mise en cache rapide d'Amazon Bedrock n'est actuellement disponible que pour un certain nombre de clients. Pour en savoir plus sur la participation à la version préliminaire, consultez Amazon Bedrock prompt caching.

L'image suivante montre un objet Message avec un content tableau contenant uniquement une image ContentBlock:

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

L'image suivante montre un objet Message avec un content tableau contenant une image ContentBlocket un cachePoint champ facultatif. Le contenu de l'image est ainsi ajouté au cache.

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

Le document champ correspond à un DocumentBlock. Si vous incluez unDocumentBlock, vérifiez que votre demande est conforme aux restrictions suivantes :

  • Dans le content champ de l'objet Message, vous devez également inclure un text champ contenant une invite liée au document.

  • Transmettez les octets bruts, codés en base64, pour le document dans le bytes champ. Si vous utilisez un AWS SDK, vous n'avez pas besoin de coder les octets du document en base64.

  • Le name champ ne peut contenir que les caractères suivants :

    • Caractères alphanumériques

    • Caractères d'espacement (pas plus d'un par ligne)

    • Tirets

    • Parenthèses

    • Crochets

    Note

    Le name champ est vulnérable aux injections rapides, car le modèle risque de l'interpréter par inadvertance comme des instructions. Par conséquent, nous vous recommandons de spécifier un nom neutre.

(Facultatif) Pour certains modèles, vous pouvez ajouter des points de contrôle du cache à l'aide de cachePoint champs pour utiliser la mise en cache rapide. La mise en cache rapide est une fonctionnalité qui vous permet de commencer à mettre en cache le contexte des conversations afin de réaliser des économies de coûts et de latence. Pour de plus amples informations, veuillez consulter Mise en cache rapide pour une inférence de modèle plus rapide.

Note

La mise en cache rapide d'Amazon Bedrock n'est actuellement disponible que pour un certain nombre de clients. Pour en savoir plus sur la participation à la version préliminaire, consultez Amazon Bedrock prompt caching.

L'image suivante montre un objet Message avec un content tableau contenant uniquement un document ContentBlocket le texte d'accompagnement obligatoire ContentBlock.

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

L'image suivante montre un objet Message avec un content tableau contenant un document ContentBlocket le texte d'accompagnement requis ContentBlock, ainsi qu'un CachePoint qui ajoute le contenu du document et du texte au 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

Le video champ correspond à un VideoBlockobjet. Passez les octets bruts dans le bytes champ, codés en base64. Si vous utilisez le AWS SDK, vous n'avez pas besoin de coder les octets en base64.

Si vous n'incluez pas le text champ, le modèle décrira la vidéo.

L'image suivante montre un objet Message avec un content tableau contenant uniquement une vidéo ContentBlock.

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

Notez que pour les fichiers dotés d'une .3gp extension, le format doit être spécifié sous la formethree_gp.

Vous pouvez également transmettre une vidéo via un URI Amazon S3 au lieu de transmettre les octets directement dans le corps de la demande. Ce qui suit montre un Message objet avec un tableau de contenu contenant uniquement une vidéo ContentBlock dont la source vidéo est transmise via un URI Amazon S3.

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

Le s3Location paramètre n'est pris en charge que dans la région de l'est des États-Unis (Virginie du Nord).

Note

Le rôle assumé doit avoir l's3:GetObjectautorisation d'accéder à l'URI Amazon S3. Le bucketOwner champ est facultatif mais doit être spécifié si le compte à l'origine de la demande ne possède pas le compartiment dans lequel se trouve l'URI Amazon S3.

guardContent

Le guardContent champ correspond à un GuardrailConverseContentBlockobjet. Vous pouvez utiliser ce champ pour cibler une entrée à évaluer par le garde-corps défini dans le guardrailConfig champ. Si vous ne spécifiez pas ce champ, le garde-corps évalue tous les messages contenus dans le corps de la demande. Vous pouvez transmettre les types de contenu suivants dans un GuardBlock :

  • text — Ce qui suit montre un objet Message avec un content tableau contenant uniquement du texte GuardrailConverseContentBlock:

    { "role": "user", "content": [ { "text": "string", "qualifiers": [ "grounding_source | query | guard_content", ... ] } ] }

    Vous définissez le texte à évaluer et incluez tous les qualificatifs à utiliser pour étayer le contexte.

  • image — Ce qui suit montre un objet Message avec un content tableau contenant uniquement une image GuardrailConverseContentBlock:

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

    Vous spécifiez le format de l'image et définissez l'image en octets.

Pour plus d'informations sur l'utilisation des glissières de sécurité, consultez. Bloquez les contenus dangereux dans les modèles utilisant Amazon Bedrock Guardrails

reasoningContent

Le reasoningContent champ correspond à un ReasoningContentBlock. Ce bloc contient du contenu concernant le raisonnement qui a été appliqué par le modèle pour générer la réponse dans l'accompagnementContentBlock.

Ce qui suit montre un Message objet avec un content tableau contenant uniquement un ReasoningContentBlock et un texte d'accompagnementContentBlock.

{ "role": "user", "content": [ { "text": "string" }, { "reasoningContent": { "reasoningText": { "text": "string", "signature": "string" } "redactedContent": "base64-encoded binary data object" } } ] }

ReasoningContentBlockIl contient le raisonnement utilisé pour générer le contenu d'accompagnement reasoningText sur le terrain, en plus de tout contenu du raisonnement crypté par le fournisseur du modèle pour des raisons de confiance et de sécurité redactedContent sur le terrain.

Dans le reasoningText champ, les text champs décrivent le raisonnement. Le signature champ est un hachage de tous les messages de la conversation et constitue une protection contre toute modification du raisonnement utilisé par le modèle. Vous devez inclure la signature et tous les messages précédents dans les Converse demandes suivantes. Si l'un des messages est modifié, la réponse génère une erreur.

toolUse

Contient des informations sur un outil destiné au modèle à utiliser. Pour de plus amples informations, veuillez consulter Utiliser un outil pour compléter une réponse du modèle Amazon Bedrock.

toolResult

Contient des informations sur le résultat obtenu par le modèle à l'aide d'un outil. Pour de plus amples informations, veuillez consulter Utiliser un outil pour compléter une réponse du modèle Amazon Bedrock.

Note

Les restrictions suivantes s'appliquent à ce content champ :

  • Vous pouvez inclure jusqu'à 20 images. La taille, la hauteur et la largeur de chaque image ne doivent pas dépasser 3,75 Mo, 8 000 pixels et 8 000 pixels, respectivement.

  • Vous pouvez inclure jusqu'à cinq documents. La taille de chaque document ne doit pas dépasser 4,5 Mo.

  • Vous ne pouvez inclure des images et des documents que si role c'est le casuser.

Dans l'messagesexemple suivant, l'utilisateur demande une liste de trois chansons pop, et le modèle génère une liste de chansons.

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

Une invite système est un type d'invite qui fournit des instructions ou un contexte au modèle concernant la tâche qu'il doit effectuer ou le personnage qu'il doit adopter au cours de la conversation. Vous pouvez spécifier une liste d'invites système pour la demande dans le champ system (SystemContentBlock), comme illustré dans l'exemple suivant.

[ { "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. " } ]

Le Converse L'API prend en charge un ensemble de base de paramètres d'inférence que vous définissez dans le inferenceConfig champ (InferenceConfiguration). L'ensemble de base des paramètres d'inférence est le suivant :

  • MaxTokens — Le nombre maximum de jetons à autoriser dans la réponse générée.

  • StopSequences — Liste de séquences d'arrêt. Une séquence d'arrêt est une séquence de caractères qui empêche le modèle de générer la réponse.

  • température — Probabilité que le modèle sélectionne des options à probabilité plus élevée lors de la génération d'une réponse.

  • TopP — Le pourcentage de candidats les plus probables que le modèle prend en compte pour le jeton suivant.

Pour de plus amples informations, veuillez consulter Influencez la génération de réponses à l'aide de paramètres d'inférence.

L'exemple JSON suivant définit le paramètre temperature d'inférence.

{"temperature": 0.5}

Si le modèle que vous utilisez possède des paramètres d'inférence supplémentaires, vous pouvez définir ces paramètres en les spécifiant au format JSON dans le additionalModelRequestFields champ. L'exemple JSON suivant montre comment définirtop_k, qui est disponible dans Anthropic Claude modèles, mais il ne s'agit pas d'un paramètre d'inférence de base dans l'API des messages.

{"top_k": 200}

Si vous spécifiez une invite dans Prompt Management modelId comme ressource sur laquelle exécuter l'inférence, utilisez ce champ pour renseigner les variables d'invite avec des valeurs réelles. Le promptVariables champ correspond à un objet JSON dont les clés correspondent aux variables définies dans les instructions et aux valeurs par lesquelles les variables doivent être remplacées.

Supposons, par exemple, que vous ayez un message indiquantMake me a {{genre}} playlist consisting of the following number of songs: {{number}}.. L'ID de l'invite est PROMPT12345 et sa version est1. Vous pouvez envoyer la Converse demande suivante pour remplacer les variables :

POST /model/arn:aws:bedrock:us-east-1:111122223333:prompt/PROMPT12345:1/converse HTTP/1.1 Content-type: application/json { "promptVariables": { "genre" : "pop", "number": 3 } }

Vous pouvez appliquer un garde-corps que vous avez créé avec Amazon Bedrock Guardrails en incluant ce champ. Pour appliquer le garde-corps à un message spécifique de la conversation, incluez le message dans un. GuardrailConverseContentBlock Si vous n'incluez aucun GuardrailConverseContentBlock s dans le corps de la demande, le garde-fou est appliqué à tous les messages du champ. messages Pour obtenir un exemple, consultez Incluez un garde-corps avec Converse « Hello, World! » .

Ce champ vous permet de définir un outil que le modèle doit utiliser pour l'aider à générer une réponse. Pour de plus amples informations, veuillez consulter Utiliser un outil pour compléter une réponse du modèle Amazon Bedrock.

Vous pouvez spécifier les chemins pour les paramètres de modèle supplémentaires dans le additionalModelResponseFieldPaths champ, comme illustré dans l'exemple suivant.

[ "/stop_sequence" ]

L'API renvoie les champs supplémentaires que vous demandez dans le additionalModelResponseFields champ.

Ce champ correspond à un objet JSON. Vous pouvez spécifier les clés de métadonnées et les valeurs auxquelles elles correspondent dans cet objet. Vous pouvez utiliser les métadonnées des demandes pour filtrer les journaux d'invocation des modèles.

Vous pouvez également éventuellement ajouter des points de contrôle du cache aux tools champs system or pour utiliser la mise en cache rapide, selon le modèle que vous utilisez. Pour de plus amples informations, veuillez consulter Mise en cache rapide pour une inférence de modèle plus rapide.

Note

La mise en cache rapide d'Amazon Bedrock n'est actuellement disponible que pour un certain nombre de clients. Pour en savoir plus sur la participation à la version préliminaire, consultez Amazon Bedrock prompt caching.

Réponse

La réponse que vous obtenez du Converse L'API dépend de l'opération que vous appelez, Converse ouConverseStream.

Réponse inverse

Dans le formulaire de réponseConverse, le output champ (ConverseOutput) contient le message (Message) généré par le modèle. Le contenu du message se trouve dans le champ content (ContentBlock) et le rôle (userouassistant) auquel le message correspond se trouve dans le role champ.

Si vous avez utilisé la mise en cache rapide, alors dans le champ d'utilisation, cacheReadInputTokensCount cacheWriteInputTokensCount indiquez le nombre total de jetons lus dans le cache et écrits dans le cache, respectivement.

Le metrics champ (ConverseMetrics) inclut les métriques de l'appel. Pour déterminer pourquoi le modèle a cessé de générer du contenu, vérifiez le stopReason champ. Vous pouvez obtenir des informations sur les jetons transmis au modèle dans la demande et sur les jetons générés dans la réponse en cochant le usage champ (TokenUsage). Si vous avez spécifié des champs de réponse supplémentaires dans la demande, l'API les renvoie au format JSON dans le additionalModelResponseFields champ.

L'exemple suivant montre la réponse Converse lorsque vous avez répondu à l'invite décrite dansDemande.

{ "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 réponse

Si vous appelez ConverseStream pour diffuser la réponse d'un modèle, le flux est renvoyé dans le champ de stream réponse. Le flux émet les événements suivants dans l'ordre suivant.

  1. messageStart(MessageStartEvent). L'événement de début d'un message. Inclut le rôle du message.

  2. contentBlockStart(ContentBlockStartEvent). Un événement de démarrage d'un bloc de contenu. Utilisation d'outils uniquement.

  3. contentBlockDelta(ContentBlockDeltaEvent). Un événement delta du bloc de contenu. Inclut l'un des éléments suivants :

    • text— Texte partiel généré par le modèle.

    • reasoningContent— Le raisonnement partiel effectué par le modèle pour générer la réponse. Vous devez envoyer le message renvoyésignature, en plus de tous les messages précédents, dans les Converse demandes suivantes. Si l'un des messages est modifié, la réponse génère une erreur.

    • toolUse— L'objet JSON d'entrée partielle destiné à l'utilisation de l'outil.

  4. contentBlockStop(ContentBlockStopEvent). Un événement d'arrêt du blocage du contenu.

  5. messageStop(MessageStopEvent). L'événement d'arrêt du message. Inclut la raison pour laquelle le modèle a cessé de générer une sortie.

  6. metadata(ConverseStreamMetadataEvent). Métadonnées relatives à la demande. Les métadonnées incluent l'utilisation du jeton dans usage (TokenUsage) et les métriques de l'appel dans metrics (ConverseStreamMetadataEvent).

ConverseStream diffuse un bloc de contenu complet sous forme d'ContentBlockStartEventévénement, d'un ou de plusieurs ContentBlockDeltaEvent événements et d'un ContentBlockStopEvent événement. Utilisez le contentBlockIndex champ comme index pour corréler les événements qui constituent un bloc de contenu.

L'exemple suivant est une réponse partielle deConverseStream.

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