企业官网建设流程全解析

• 示例工程
• 教程
• 后端

Amazon Bedrock Runtime 是 AWS 提供的一项全托管服务，让你可以通过统一的 API 调用来自第三方提供商和 Amazon 自家的基础模型（Foundation Model）。本文以aws-doc-sdk-examples仓库中 python/example_code/bedrock-runtime 目录下的完整示例为主线，讲解如何使用 AWS SDK for Python（Boto3）通过converse/converse_stream/invoke_model/start_async_invoke等接口完成文本对话、流式输出、文档理解、图像生成与文本转视频等任务，并剖析工具调用（Tool Use）这一跨模型场景的完整实现。读完本文，你将能够直接运行这些示例，并掌握把任意支持的基础模型接入自己 Python 应用的落地方法。

1. 概述：Bedrock Runtime 与示例的适用范围

Amazon Bedrock Runtime 是一个全托管推理服务，无需自行部署模型即可访问来自 Anthropic、Cohere、DeepSeek、Meta、Mistral AI、Stability AI 以及 Amazon 自身的多款基础模型。本仓库中的示例覆盖了当前 Bedrock Runtime 最常用的几类推理能力：

• 对话式推理（Converse API）：统一的消息结构，适用于 Claude、Nova、Cohere、Llama、Mistral 等文本模型；
• 原生推理（InvokeModel）：按各模型原生 JSON 结构构造请求，适用于 Titan、Nova Canvas、Stable Image Core 等；
• 异步推理（StartAsyncInvoke）：适用于 Nova Reel 文本转视频这类长耗时任务；
• 文档理解（多模态）：直接把 PDF 等文档内容作为消息的一部分发送给模型。

所有示例均位于 python/example_code/bedrock-runtime 目录，采用 Boto3 的bedrock-runtime服务客户端，代码中均带有snippet-start/snippet-end标记，方便与 AWS 官方文档中的代码片段对应查阅。

说明：运行这些代码会在你的 AWS 账户中产生费用。使用前请了解 AWS 定价与免费套餐（AWS 官方页面），并遵循最低权限原则——只授予完成当前任务所需的最小权限。此外，并非所有代码都在每个 AWS 区域测试过，跨区域使用前请确认模型在该区域的可用性。

2. 前置条件与环境准备

2.1 Python 环境与依赖

示例的依赖清单见 requirements.txt，其中核心依赖为：

• boto3==1.40.42/botocore==1.40.42：AWS SDK 核心库；
• pytest==9.0.3：运行测试所需；
• Pygments、colorama等：部分示例与控制台输出美化相关。

在虚拟环境中安装依赖：

python -m pip install -r requirements.txt

关于 Python 环境的更多通用要求，可参考 python/README.md 中的 Prerequisites 部分。

2.2 模型访问权限（关键前提）

⚠ 使用模型前，必须先向 Amazon Bedrock 申请该模型的访问权限（Model access）。如果尚未开通就在 API 或控制台中使用模型，会直接收到错误信息。模型访问的详细流程参见 Bedrock 用户指南中的 “Model access” 章节。

不同的模型 ID 对应不同的模型族，示例代码中的默认模型 ID 例如：

• anthropic.claude-3-haiku-20240307-v1:0（Claude 3 Haiku）
• amazon.titan-text-premier-v1:0（Titan Text Premier）
• amazon.nova-canvas-v1:0（Nova Canvas）
• amazon.nova-reel-v1:0（Nova Reel）
• stability.stable-image-core-v1:1（Stable Image Core）

2.3 AWS 凭证

所有示例均通过 Boto3 默认的凭证链（环境变量、AWS CLI 配置、IAM 角色等）获取凭证，并在创建客户端时指定区域，例如boto3.client("bedrock-runtime", region_name="us-east-1")。请注意不同模型族示例中使用的区域可能不同（如 Stable Image Core 示例使用us-west-2），请以实际可用区域为准。

3. 代码示例总览：按模型族组织的目录结构

README 将示例按“场景（Scenarios）”与“模型族”两个维度组织，仓库目录结构与此一一对应：

• 场景（跨模型）：cross-model-scenarios/tool_use_demo/tool_use_demo.py——Converse API 工具调用演示；托管 Prompt 示例位于 bedrock-agent/prompts/scenario_get_started_with_prompts.py。
• Amazon Nova（models/amazon_nova）：文本模型的 converse.py、converse_stream.py、document_understanding.py；Canvas 图像生成的 invoke_model.py；Reel 文本转视频的 text_to_video.py。
• Amazon Titan：图像生成 invoke_model.py、文本 invoke_model.py、文本嵌入 invoke_model.py。
• Anthropic Claude（models/anthropic_claude）：converse.py、converse_stream.py、document_understanding.py，另有converse_async.py、converse_stream_pdf.py及聊天机器人场景。
• Cohere Command：converse.py、converse_stream.py、document_understanding.py。
• DeepSeek：document_understanding.py。
• Meta Llama：converse.py、converse_stream.py、document_understanding.py。
• Mistral AI：converse.py、converse_stream.py、document_understanding.py。
• Stability AI（Stable Image Core）：invoke_model.py。

README 中还保留了早期版本的运行说明：python models/anthropic/claude_3.py演示 Claude 3，python bedrock_runtime_wrapper.py演示 Claude 2、Titan、Stable Diffusion、Jurassic-2、Llama 2 与 Mistral AI 双模型。需要说明的是，随着仓库演进，当前目录已按“模型族/单文件”结构重新组织（见上面的目录树），claude_3.py与bedrock_runtime_wrapper.py已不再存在于该目录。建议以当前目录中的具体模型脚本为准，例如：

# 位于 python/example_code/bedrock-runtime 目录下 python models/anthropic_claude/converse.py python models/amazon_titan_text/invoke_model.py python models/amazon_nova/amazon_nova_canvas/invoke_model.py

4. 文本对话：Converse 与 ConverseStream

4.1 基础对话（Converse）

models/anthropic_claude/converse.py 展示了最简的 Converse API 调用流程。核心步骤为：

import boto3 from botocore.exceptions import ClientError client = boto3.client("bedrock-runtime", region_name="us-east-1") model_id = "anthropic.claude-3-haiku-20240307-v1:0" user_message = "Describe the purpose of a 'hello world' program in one line." conversation = [ { "role": "user", "content": [{"text": user_message}], } ] try: response = client.converse( modelId=model_id, messages=conversation, inferenceConfig={"maxTokens": 512, "temperature": 0.5, "topP": 0.9}, ) response_text = response["output"]["message"]["content"][0]["text"] print(response_text) except (ClientError, Exception) as e: print(f"ERROR: Can't invoke '{model_id}'. Reason: {e}") exit(1)

要点解析：

• 消息结构：messages是一个由{"role": ..., "content": [...]}组成的列表，content中的每个元素可以是{"text": ...}文本块，也可以是文档块（见第 5 节）；
• 推理配置：inferenceConfig中的maxTokens（最大生成 token 数）、temperature（温度，控制随机性）、topP（核采样）是跨模型通用的基础参数；
• 响应提取：模型输出位于response["output"]["message"]["content"][0]["text"]，与请求的消息结构对称；
• 异常处理：通过ClientError捕获 AWS 服务端错误（如模型未开通访问权限、模型 ID 不存在等），统一打印错误原因后退出。

4.2 流式输出（ConverseStream）

models/anthropic_claude/converse_stream.py 与基础版结构完全一致，仅将converse换成converse_stream，并通过迭代响应流实现“边生成边显示”的效果：

streaming_response = client.converse_stream( modelId=model_id, messages=conversation, inferenceConfig={"maxTokens": 512, "temperature": 0.5, "topP": 0.9}, ) for chunk in streaming_response["stream"]: if "contentBlockDelta" in chunk: text = chunk["contentBlockDelta"]["delta"]["text"] print(text, end="")

流式响应的每个chunk可能包含不同的事件类型，示例只关心contentBlockDelta（增量文本块），从中取出delta["text"]实时打印。流式输出在长回答场景下能显著改善用户体验。

4.3 异步对话（ConverseAsync）

在 models/anthropic_claude 目录下还提供了converse_async.py，用于展示基于asyncio的异步调用方式，适合在事件循环驱动的应用中（如 FastAPI 服务）集成。同一目录的converse_stream_pdf.py则演示了如何在流式对话中携带 PDF 文档。

5. 文档理解：把 PDF 直接发送给模型

models/anthropic_claude/document_understanding.py 展示了多模态能力——将本地 PDF 作为document块加入用户消息：

with open("example-data/amazon-nova-service-cards.pdf", "rb") as file: document_bytes = file.read() conversation = [ { "role": "user", "content": [ {"text": "Briefly compare the models described in this document"}, { "document": { # Available formats: html, md, pdf, doc/docx, xls/xlsx, csv, and txt "format": "pdf", "name": "Amazon Nova Service Cards", "source": {"bytes": document_bytes}, } }, ], } ] response = client.converse( modelId=model_id, messages=conversation, inferenceConfig={"maxTokens": 500, "temperature": 0.3}, )

实现要点：

• 支持格式：document块的format字段支持html、md、pdf、doc/docx、xls/xlsx、csv、txt；
• 文档来源：既可以通过source: {"bytes": ...}直接传入二进制字节，也可以使用{"s3Location": {...}}指向 S3 对象；
• 示例数据：测试文档 example-data/amazon-nova-service-cards.pdf 位于bedrock-runtime目录下，运行时需保证当前工作目录正确。

该模式同样适用于 Nova、Cohere、DeepSeek、Llama、Mistral 等支持文档输入的模型（各模型族均有同名document_understanding.py）。

6. 图像生成：InvokeModel 原生推理

图像生成类模型使用invoke_model接口，请求体是各模型的原生 JSON 结构。尽管模型不同，但整体流程一致：构造请求 → 调用 → 解析 base64 图像 → 落盘保存。

6.1 Amazon Nova Canvas

models/amazon_nova/amazon_nova_canvas/invoke_model.py：

seed = random.randint(0, 858993460) # 随机种子，范围 0 ~ 858,993,459 native_request = { "taskType": "TEXT_IMAGE", "textToImageParams": {"text": prompt}, "imageGenerationConfig": { "seed": seed, "quality": "standard", # 可选 "standard" / "premium" 等 "height": 512, "width": 512, "numberOfImages": 1, }, } request = json.dumps(native_request) response = client.invoke_model(modelId="amazon.nova-canvas-v1:0", body=request) model_response = json.loads(response["body"].read()) base64_image_data = model_response["images"][0]

6.2 Amazon Titan Image Generator

models/amazon_titan_image_generator/invoke_model.py 结构与 Nova Canvas 几乎一致（模型 ID 为amazon.titan-image-generator-v2:0），但在imageGenerationConfig中额外提供cfgScale参数（示例值为8.0，用于控制对提示词的遵循程度）：

native_request = { "taskType": "TEXT_IMAGE", "textToImageParams": {"text": prompt}, "imageGenerationConfig": { "numberOfImages": 1, "quality": "standard", "cfgScale": 8.0, "height": 512, "width": 512, "seed": seed, # seed = random.randint(0, 2147483647) }, }

6.3 Stability AI Stable Image Core

models/stability_ai/invoke_model.py 展示了与 Titan/Nova 不同的请求结构——Stability AI 使用扁平化的顶层字段而非taskType包装：

client = boto3.client("bedrock-runtime", region_name="us-west-2") model_id = "stability.stable-image-core-v1:1" seed = random.randint(0, 4294967295) native_request = { "prompt": prompt, "aspect_ratio": "1:1", # 输出画幅比例 "seed": seed, "output_format": "png", # 输出格式 }

该示例使用的区域是us-west-2，与前面文本类示例的us-east-1不同，这正体现了“不同模型在不同区域可用性不同”的事实，也呼应了 README 中“代码并非在每个区域都测试过”的提醒。

三个图像生成示例的落盘逻辑相同：先自动创建output/目录，再按nova_canvas_{i}.png、titan_{i}.png、stability_{i}.png的命名递增避免覆盖，最后通过base64.b64decode解码写入文件。

7. 文本原生推理：Amazon Titan Text

除了 Converse API，也可以通过原生结构调用文本模型。models/amazon_titan_text/invoke_model.py 使用 Titan Text Premier（amazon.titan-text-premier-v1:0）：

native_request = { "inputText": prompt, "textGenerationConfig": { "maxTokenCount": 512, "temperature": 0.5, }, } request = json.dumps(native_request) response = client.invoke_model(modelId=model_id, body=request) model_response = json.loads(response["body"].read()) response_text = model_response["results"][0]["outputText"]

与 Converse API 不同，Titan 文本模型的响应位于model_response["results"][0]["outputText"]，请求字段名为inputText/textGenerationConfig——这正是“原生推理接口的请求/响应结构与模型强相关”的典型示例。同一目录还提供了 amazon_titan_text_embeddings/invoke_model.py 用于文本向量化（Embeddings）。

8. 文本转视频：Nova Reel 异步任务

视频生成耗时较长，因此 Nova Reel 采用异步作业模式。models/amazon_nova/amazon_nova_reel/text_to_video.py 完整演示了“提交作业 → 轮询状态 → 获取结果”的全流程：

OUTPUT_S3_URI = "s3://REPLACE-WITH-YOUR-S3-BUCKET-NAME" # 必须替换为你的桶 model_input = { "taskType": "TEXT_VIDEO", "textToVideoParams": {"text": prompt}, "videoGenerationConfig": { "fps": 24, "durationSeconds": 6, "dimension": "1280x720", "seed": seed, # seed = random.randint(0, 2147483646) }, } output_config = {"s3OutputDataConfig": {"s3Uri": output_s3_uri}} response = bedrock_runtime.start_async_invoke( modelId="amazon.nova-reel-v1:0", modelInput=model_input, outputDataConfig=output_config ) invocation_arn = response["invocationArn"]

轮询部分使用get_async_invoke(invocationArn=...)查询状态，并根据job["status"]分支处理：

• Completed：从job["outputDataConfig"]["s3OutputDataConfig"]["s3Uri"]读取输出地址（视频文件为output.mp4）；
• Failed：打印failureMessage；
• 其他状态：视为进行中，每 15 秒轮询一次。

运行前必须把OUTPUT_S3_URI替换为真实的 S3 桶地址（程序启动时会检查占位符REPLACE-WITH-YOUR-S3-BUCKET-NAME并拒绝执行）。

9. 场景一：Converse API 工具调用（Tool Use）

工具调用（Tool Use）是让模型按需调用外部 API 的能力。cross-model-scenarios/tool_use_demo/tool_use_demo.py 以“天气助手”为例：模型通过调用外部天气工具（Open-Meteo API）根据用户输入返回实时天气。

9.1 支持的模型

示例用枚举定义了支持工具调用的模型列表：

class SupportedModels(Enum): CLAUDE_OPUS = "anthropic.claude-3-opus-20240229-v1:0" CLAUDE_SONNET = "anthropic.claude-3-sonnet-20240229-v1:0" CLAUDE_HAIKU = "anthropic.claude-3-haiku-20240307-v1:0" COHERE_COMMAND_R = "cohere.command-r-v1:0" COHERE_COMMAND_R_PLUS = "cohere.command-r-plus-v1:0" MODEL_ID = SupportedModels.CLAUDE_HAIKU.value

9.2 系统提示词与工具配置

示例通过系统提示词（SYSTEM_PROMPT）约束模型行为：必须使用Weather_Tool且自行推断经纬度、禁止编造数据、只回答天气相关问题等。工具配置通过工具规范注册：

self.tool_config = {"tools": [weather_tool.get_tool_spec()]}

get_tool_spec()定义在 cross-model-scenarios/tool_use_demo/weather_tool.py 中，它按 Bedrock 工具的 JSON Schema 格式描述工具的输入参数（经纬度等）。

9.3 对话循环与递归调用

主循环维护一个conversation列表，将用户输入追加为{"role": "user", "content": [{"text": ...}]}后发送给 Bedrock；随后递归处理模型响应，直到模型返回最终答复或递归次数达到上限：

MAX_RECURSIONS = 5 # 防止无限循环与性能问题 def run(self): conversation = [] user_input = self._get_user_input() while user_input is not None: message = {"role": "user", "content": [{"text": user_input}]} conversation.append(message) bedrock_response = self._send_conversation_to_bedrock(conversation) self._process_model_response(bedrock_response, conversation, max_recursion=MAX_RECURSIONS)

当模型的响应中包含toolUse块时，程序会调用真实的天气工具、把工具结果以toolResult角色回填给模型，再继续对话——这就是“模型 ↔ 工具 ↔ 应用”之间多轮协作的本质。辅助的输出格式化工具位于 tool_use_print_utils.py。该场景还有独立的 README 与pyproject.toml/requirements.txt，可单独安装运行。

10. 场景二：创建并调用托管 Prompt

托管 Prompt（Managed Prompt）是 Bedrock 的提示词管理能力。该场景位于 bedrock-agent/prompts/scenario_get_started_with_prompts.py，演示了四个步骤：

1. 创建一个托管 Prompt；
2. 为该 Prompt 创建一个版本；
3. 使用该版本调用 Prompt（即在 Bedrock Runtime 中执行）；
4. 可选地清理资源。

从bedrock-runtime目录运行：

python ../bedrock-agent/prompts/scenario_get_started_with_prompts.py

这是一个跨服务场景——托管 Prompt 的创建与管理属于 Bedrock Agent 侧能力，而“按版本调用”最终落在 Bedrock Runtime 的执行能力上，是把 Prompt 版本化管理与运行时推理打通的最佳实践示例。

11. 运行测试

运行测试同样可能产生 AWS 费用。测试统一使用仓库 Python 目录下的通用测试基础设施，运行方式参见 python/README.md 中的 Tests 部分。

本目录的测试位于 test 下：

• conftest.py：把test_tools目录加入 Python 路径，并引入test_tools/fixtures/common.py中的通用 fixture（sys.path.append("../..")指向仓库的python/example_code目录）；
• test_converse.py：验证 Converse / ConverseStream 相关逻辑；
• test_document_understanding.py：验证文档理解调用；
• test_nova_reel.py：验证 Nova Reel 异步视频作业相关逻辑。

12. 学习路径建议

1. 从文本对话入手：先运行models/anthropic_claude/converse.py，理解消息结构与响应提取；
2. 升级到流式与多模态：尝试converse_stream.py与document_understanding.py，掌握实时输出和文档输入；
3. 扩展模型覆盖面：对照第 3 节的目录清单，逐一替换模型 ID 运行同一模式的脚本，体会 Converse 的统一性与 InvokeModel 的原生差异；
4. 进入实战场景：运行 Tool Use 天气助手与托管 Prompt 场景，理解 Agent 化应用的骨架；
5. 最后做工程化：参考test/下的测试与通用 fixture，为自己的 Bedrock 集成编写可回归的测试。

掌握以上内容后，你就能基于 python/example_code/bedrock-runtime 目录中的每一份示例，快速构建自己的 Amazon Bedrock 应用——无论是聊天机器人、文档分析、图像生成，还是视频合成与工具调用型 Agent。

• 示例工程
• 教程
• 后端