亚马逊AWS官方博客

HAQM Bedrock Runtime API 集成指南——从 Invoke Model API 迁移到 Converse API，简化生成式 AI 应用开发

摘要

HAQM Bedrock 是一项亚马逊云科技在海外区域提供的完全托管服务，通过单个 API 提供来自包括 HAQM 在内的领先人工智能公司的高性能基础模型（FM），并提供通过安全性、隐私性和负责任的人工智能构建生成式人工智能应用程序所需的一系列广泛功能。使用 HAQM Bedrock，您可以轻松试验和评估适合您的使用案例的热门 FM，通过微调和检索增强生成（RAG）等技术利用您的数据对其进行私人定制，并构建使用您的企业系统和数据来源执行任务的代理。由于 HAQM Bedrock 是无服务器的，因此您无需管理任何基础设施，并且可以使用已经熟悉的亚马逊云科技服务将生成式 AI 功能安全地集成和部署到您的应用程序中。

随着基础模型（FM）的高速发展， HAQM Bedrock 通过模型生命周期管理来不断调整其提供的基础模型。在 2025 年下半年，HAQM Bedrock 将会停止支持一部分版本比较旧的基础模型（FM）。本博客旨在帮助客户评估和/或将 HAQM Bedrock runtime API 从 Invoke Model API 迁移到 Converse API，从而更高效地构建对话式应用。

HAQM Bedrock runtime API 及其支持的推理参数格式

目前，HAQM Bedrock runtime API 主要分为两组：Invoke Model API 和 Converse API（较新）。两组都有 RESTful API 和 streaming API （流式 API），并且同一组内支持的推理参数格式是相同的。

2024 年 5 月，HAQM Bedrock 宣布了新的 Converse API，为开发者提供了一种统一的调用 HAQM Bedrock 模型的方式，消除了因模型特定差异（如推理参数）而带来的复杂度。Converse API 还通过允许开发者以结构化方式在 API 请求中提供对话历史，简化了多轮对话管理。

对于 Invoke Model API，每个基础模型（FM）的推理参数遵循模型提供商的定义，因此参数可能会根据您使用的 FM 而有所不同，提高了业务代码维护的难度。
对于 Converse API，HAQM Bedrock 将所有支持的 FM 推理参数抽象为统一的推理参数。Converse API 支持的 FM 详情请参考文档。

请注意：截止至本博客写作时 （2025 年 5 月），Converse API 暂时不支持 embedding 模型（如 Titan Embeddings G1 – Text）、图像生成模型（如 Stability AI 的 Stable Diffusion）、视频生成模型、或语音模型（如 HAQM Nova Sonic）。

HAQM Bedrock Invoke Model API 接口名称：

  • RESTful：InvokeModel
  • 流式形式：InvokeModelWithResponseStream

HAQM Bedrock Converse API 接口名称：

  • RESTful：Converse
  • 流式形式：ConverseStream

下表列出了 HAQM Bedrock runtime API 的详细信息及其支持的一些参数格式。

请在此处查找 HAQM Bedrock runtime API 支持的模型和模型功能的信息。

模型 API 参数格式

支持 Invoke Model /

Invoke ModelWithResponseStream

 支持 Converse / ConverseStream
Anthropic Claude Text Completions API 格式 是 是（需少量修改）
Anthropic Claude Messages API 格式 是 是（需少量修改）
Meta Llama API 格式 是 是（提示词格式修改）
AI21Labs Jamba API 格式 是 是（提示词格式修改）
Stability AI model API 是 否
HAQM Titan Embeddings Text API 是（不支持流式） 否
Cohere Embed model API 是（不支持流式） 否

HAQM Bedrock Runtime API 权限管理

HAQM IAM 角色或 IAM 用户访问 HAQM Bedrock runtime API 所需的最小权限：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
            "HAQM Bedrock:InvokeModel",
            "HAQM Bedrock:InvokeModelWithResponseStream"
            ],
        "Resource": "*",
        "Effect": "Allow",
        "Sid": "HAQM BedrockRuntimeAPIAccess"
        }
    ]
}

使用 HAQM Bedrock Invoke Model API

推理参数格式

系统提示词 （System Prompts）：

Invoke Model API 的系统提示词格式是一个字符串，例如：

"system": "[your system prompts]"

提示词（prompts）格式：

"messages": [
    "role": "user",
    "content": [
        {
            "type": "text | image", 
            "text": "[Your prompts]"
        } 
]

提示词中的角色名称

一些 Text Completions 格式期望交替出现“\n\nHuman:”和“\n\nAssistant:”，但 Messages API 格式使用“user”和“assistant”角色。您可能会看到文档中提到“human”或“user”。这些指的是同一个角色，今后将使用“user”。

例如：

Text completions API 格式提示词为：

"prompt ": "\n\nHuman: Explain what is an AI agent?\n\nAssistant:"

上述提示词应转换为 Messages API 格式提示词：

"messages": [
    "role": "user",
    "content": [
        {
            "type": "text", 
            "text": "Explain what is an AI agent?"
        } 
]

使用 HAQM Bedrock Converse API

2024 年 5 月，HAQM Bedrock 宣布了新的 Converse API，为开发者提供了一种统一的调用 HAQM Bedrock 模型的方式，消除了因模型特定差异（如推理参数差异）而带来的复杂度。该 API 还通过使开发人员能够以结构化方式在 API 请求中提供对话历史记录，从而简化了多轮对话的管理。

此外，Converse API 支持工具使用（函数调用），对于支持的模型，将使开发人员能够执行各种需要访问外部工具和 API 的任务。

HAQM Bedrock Converse API 的系统提示词（system prompts）格式更新为一个 JSON 对象，例如：

"system": [
    { 
        "text": "[Your system prompts]"
    },
    "guardContent": {
        "text": {
            "text": "[Guard content]"
        }
    }
]

HAQM Bedrock Converse API 的提示词（prompts）格式

示例：

"messages":
[
    "role": "user",
    "content": [
        {
            "text": "[Your prompts]",
            "image":
            {
                "format": "[image format]",
                "source": {
                "bytes": "[image base64 encoded string]"
            }
        }
    ]
]

从 HAQM Bedrock Invoke Model API 迁移到 HAQM Bedrock Converse API

迁移系统提示词（System Prompts）

Invoke Model API 的系统提示词格式是一个字符串，例如：

示例：

"system": "[your system prompts]"

Converse API 的系统提示词格式是一个 JSON 对象，例如：

"system": [
    { 
        "text": "[Your system prompts]"
    }
]

因此，您需要将系统提示词转换为 JSON 对象。

Converse API 系统提示还支持一个名为 guardContent 的字段，用来使用 HAQM Bedrock Guardrails 来保护您的生成式 AI 应用。请在文档中查找详细信息。

迁移提示词（Prompts）

HAQM Bedrock Invoke Model API（本例为 Messages API 格式）的提示词格式：

"message": [
        {
            "role": "user",
            "content": [
               {
                   "type": "text",
                   "text": "Your task is to take the text provided and rewrite it into a clear, grammatically correct version while preserving the original meaning as closely as possible. Here is the text: 'I can haz cheeseburger?'"
               }
            ],
        }
    ]

HAQM Bedrock Converse API 的提示格式与 Invoke Model API 非常相似，但没有内容类型声明语句。例如：

"message": [
        {
            "role": "user",
            "content": [
               {
                   "text": " Your task is to take the text provided and rewrite it into a clear, grammatically correct version while preserving the original meaning as closely as possible. Here is the text: 'I can haz cheeseburger?'"
               }
            ],
        }
    ]

请注意，Converse API 不需要类型声明语句（"type": "text",）。

提示词迁移到 Converse API 前后对比：

API Parameter From: Invoke Model API To: Converse API
System prompts 
"system": "You are an AI copyeditor"
 
"system": {"text": "You are an AI copyeditor"}
Messages 
"messages": [
        {
            "role": "user",
            "content": [
               {
                   "type": "text",
                   "text": " Your task is to take the text provided 
                   and rewrite it into a clear, grammatically correct 
                   version while preserving the original meaning as 
                   closely as possible. Here is the text: 
                   'I can haz cheeseburger?'"
               }
            ],
        }
    ]
 
"messages": [
        {
            "role": "user",
            "content": [
               {
                   "text": " Your task is to take the text provided
                    and rewrite it into a clear, grammatically correct 
                    version while preserving the original meaning as 
                    closely as possible. Here is the text: 
                    'I can haz cheeseburger?'"
               }
            ],
        }
    ]
Multimodal Messages 
"messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {
                        "type": "base64",
                        "media_type": "image/jpeg",
                        "data": "iVBORw..."
                    }
                },
                {
                    "type": "text",
                    "text": "What's in these images?"
                }
            ]
        }
    ]
 
"messages": [
   {
        "role": "user",
        "content": [
            {
                    "image": {
                        "format": "jpeg",
                        "source": {
                            "bytes": " iVBORw..."
                        }
                    }
            },
            {
                "text": " What's in these images?"
            }
        ]
    }
]

结论

HAQM Bedrock 是一项亚马逊云科技在海外区域提供的完全托管服务，通过单个 API 提供来自包括 HAQM 在内的领先人工智能公司的高性能基础模型（FM），并提供通过安全性、隐私性和负责任的人工智能构建生成式人工智能应用程序所需的一系列广泛功能。

HAQM Bedrock Converse API 提供了一种一致的体验，可与 HAQM Bedrock 中提供的模型配合使用，消除了开发者管理特定于某个模型的实现工作，降低复杂度。使用此 API，您只需编写统一的代码，便可以无缝使用 HAQM Bedrock 上的多种基础模型。因此，我们建议您在满足业务要求的情况下迁移到 Converse API。

*前述特定亚马逊云科技生成式人工智能相关的服务仅在亚马逊云科技海外区域可用，亚马逊云科技中国仅为帮助您了解行业前沿技术和发展海外业务选择推介该服务。

本篇作者

马競斌

亚马逊云科技资深解决方案架构师，致力于帮助客户构建具有优良架构的产品和应用，以及帮助国内客户出海和海外用户进入中国。在互联网行业有十多年产品研发经验和多年技术管理经验，在海外工作多年，是 Serverless 和 Infrastructure as Code 的爱好者。2023 年初开始聚焦 Generative AI，已帮助多个国内知名 IT 公司成功落地了多个生成式 AI 项目。

朱珊

亚马逊云科技客户解决方案经理，目前在亚马逊云科技主要支持泛娱乐行业的客户。通过运用云相关解决方案等帮助客户在迁移到亚马逊云和云上运维期间实现自身的业务价值，帮助客户成功。

朱辉

亚马逊云科技资深技术客户经理 (TAM)，具备 20 年 IT 专业服务经验，为客户提供包括架构设计、技术咨询及最佳实践指导等企业级技术服务，在数据库、存储、容灾等领域有丰富经验。曾就职于 IBM、Hitachi、Dell 等公司。