aws-samples/sample-amazon-bedrock-for-beginners

# Amazon Bedrock 入门指南 —— 从首次提示到 AI Agent YouTube 视频和博客的配套代码库：**Amazon Bedrock 入门指南 —— 从首次提示到 AI Agent** 本代码库包含的代码示例将带你从首次调用 Bedrock API，一步步构建一个功能完备的 AI agent。最终，你将构建一个大学 FAQ 聊天机器人，它使用 Knowledge Base 进行 RAG，使用 Guardrails 保障内容安全，包含用于课程查询的自定义工具，并使用 Strands Agents SDK 将这一切串联起来。 ## 前置条件 - Python 3.12+ - 一个已[在本地配置好凭证](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)的 AWS 账户 - **注意：** 你需要在你的账户中创建一个 IAM Role 或用户才能继续操作，你不能使用 root 用户完成本教程。 ## 第 1 步：安装依赖 创建一个虚拟环境并安装所需的包： ``` python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ## 项目结构 ``` ├── bedrock-examples/ # All runnable code examples │ ├── converse_api.py # Converse API basics + system prompts │ ├── multi_turn.py # Multi-turn conversation history │ ├── tool_use.py # Tool use (function calling) │ ├── knowledge_base_query.py # RAG with Knowledge Bases │ ├── guardrails.py # Guardrails + Knowledge Base │ └── strands_agent.py # Capstone: university chatbot agent │ ├── knowledge_base_docs/ # FAQ documents for the Knowledge Base │ ├── 01_academic_calendar.txt │ ├── 02_financial_aid.txt │ ├── 03_computer_science.txt │ ├── 04_admissions.txt │ ├── 05_housing.txt │ ├── 06_dining_services.txt │ ├── 07_registration.txt │ ├── 08_library.txt │ ├── 09_career_services.txt │ └── 10_parking_transportation.txt │ ├── requirements.txt └── README.md ``` ## 运行示例 请按顺序完成这些示例。每个示例都建立在之前的概念之上。 ### 1. Converse API —— 你的第一次 API 调用 ``` python3 bedrock-examples/converse_api.py ``` 使用 Converse API 调用 Amazon Nova Lite。演示了系统提示词、消息格式、推理参数（temperature、maxTokens）以及 token 用量。 ### 2. 多轮对话 ``` python3 bedrock-examples/multi_turn.py ``` 一个 3 轮的烹饪助手对话。展示了如何手动维护对话历史，因为模型是无状态的——每次 API 调用都需要重新发送完整的历史记录。 ### 3. 工具使用（函数调用） ``` python3 bedrock-examples/tool_use.py ``` 定义一个本地的 `get_weather` 函数，将其描述为一个工具 schema，并演练完整的工具使用循环：模型请求工具 → 你的代码运行它 → 将结果返回给模型。 ### 4. Knowledge Base (RAG) 此步骤需要先在 Bedrock 控制台中创建一个 Knowledge Base。请按照以下步骤操作。 #### 步骤 4a：将 FAQ 文档上传到 S3 1. 前往 [S3 控制台](https://console.aws.amazon.com/s3/) 2. 点击 **Create bucket** 3. 将其命名为类似 `bedrock-university-faq-` 的名称（例如，`bedrock-university-faq-jd`） 4. 保持默认设置并点击 **Create bucket** 5. 打开该存储桶并点击 **Upload** 6. 上传本代码库中 `knowledge_base_docs/` 文件夹内的全部 10 个文件 7. 点击 **Upload** #### 步骤 4b：创建 Knowledge Base 1. 前往 [Bedrock 控制台](https://console.aws.amazon.com/bedrock/) → **Knowledge bases**（左侧导航栏的 "Orchestration" 下） 2. 点击 **Create knowledge base** 3. 为其命名，例如 `university-faq-kb` 4. 在 **IAM permissions** 下，选择 **Create and use a new service role** 5. 点击 **Next** #### 步骤 4c：配置数据源 1. 对于 **Data source name**，输入类似 `university-faq-s3` 的名称 2. 在 **S3 URI** 下，点击 **Browse S3** 并选择你在步骤 4a 中创建的存储桶 3. 保持默认的分块策略（对于 FAQ 文档，Fixed size chunking 即可） 4. 点击 **Next** #### 步骤 4d：配置 Embeddings 和向量存储 1. 对于 **Embeddings model**，选择 **Titan Text Embeddings V2** 2. 对于 **Vector database**，选择 **Amazon S3 Vectors** - 这是最简单且最具成本效益的选项——无需管理单独的向量数据库 3. 系统会提示你创建或选择一个 S3 Vectors 存储桶。让 Bedrock 为你创建一个即可 4. 点击 **Next** 5. 检查你的设置并点击 **Create knowledge base** #### 步骤 4e：同步数据源 1. 创建 Knowledge Base 后，你会进入其详情页 2. 在 **Data sources** 下，选择你的数据源 3. 点击 **Sync**——这将摄取你的 FAQ 文档，对其进行分块，生成 embeddings，并存储向量 4. 等待同步状态显示为 **Completed**（对于这些小文件通常需要 1-2 分钟） #### 步骤 4f：复制 Knowledge Base ID 1. 在 Knowledge Base 详情页上，找到 **Knowledge Base ID**（类似于 `ABCDEFGHIJ`） 2. 打开 `bedrock-examples/knowledge_base_query.py` 3. 将 `KNOWLEDGE_BASE_ID` 的值替换为你的 ID #### 步骤 4g：运行 ``` python3 bedrock-examples/knowledge_base_query.py ``` 这会使用 "When is spring break this year?" 查询 Knowledge Base，并基于 FAQ 文档返回答案以及来源引用。 ### 5. Guardrails + Knowledge Base 此步骤向 Knowledge Base 查询添加了 Guardrail，以阻止不当请求。 #### 步骤 5a：创建 Guardrail 1. 前往 [Bedrock 控制台](https://console.aws.amazon.com/bedrock/) → **Guardrails**（左侧导航栏的 "Safeguards" 下） 2. 点击 **Create guardrail** 3. 为其命名，例如 `university-chatbot-guardrail` 4. 添加描述，例如 "Content safety for university FAQ chatbot" 5. 点击 **Next** #### 步骤 5b：配置内容过滤器 1. 在 **Content filters** 下，启用以下过滤器： - Hate（仇恨）：**Medium** - Insults（侮辱）：**Medium** - Sexual（色情）：**High** - Violence（暴力）：**Medium** - Misconduct（不当行为）：**Medium** 2. 可选择启用 **Prompt attack** 过滤器以阻止越狱尝试 3. 点击 **Next** #### 步骤 5c：添加拒绝主题 1. 点击 **Add denied topic** 2. Name（名称）：`Academic dishonesty` 3. Description（描述）：`Requests for help cheating on exams, plagiarizing assignments, hacking university systems, or any form of academic dishonesty` 4. 添加示例短语： - "How can I cheat on my final exam?" - "Write my essay for me so I can submit it as my own" - "How do I hack into the grading system?" 5. 点击 **Next** #### 步骤 5d：配置其余设置 1. **Sensitive information filters** —— 可选择启用 PII 检测（电子邮件、电话、SSN）。在本演示中你可以跳过此项 2. **Word filters** —— 暂时跳过 3. 点击 **Next**，检查你的设置，然后点击 **Create guardrail** #### 步骤 5e：创建版本 1. 在 guardrail 详情页上，点击 **Create version** 2. 这将发布你的 guardrail 的 `1` 版本 3. 复制 **Guardrail ID**（类似于 `abc123def456`） #### 步骤 5f：更新脚本 1. 打开 `bedrock-examples/guardrails.py` 2. 将 `GUARDRAIL_ID` 替换为你的 guardrail ID 3. 将 `KNOWLEDGE_BASE_ID` 替换为步骤 4 中相同的 KB ID 4. 确保 `GUARDRAIL_VERSION` 为 `"1"`（如果你跳过了创建版本，则为 `"DRAFT"`） #### 步骤 5g：运行 ``` python3 bedrock-examples/guardrails.py ``` 默认提示词是 "How can I cheat on my finals this year?"——guardrail 应该会阻止它。将 `question` 变量更改为 "When is the add/drop deadline?" 等内容，以查看正常响应通过的情况。 ### 6. 毕业项目 —— 大学聊天机器人 Agent (Strands) 这将使用 Strands Agents SDK 把所有内容组合成一个交互式 agent。 #### 步骤 6a：安装 Strands ``` pip install strands-agents strands-agents-tools ``` #### 步骤 6b：更新配置 打开 `bedrock-examples/strands_agent.py` 并更新： - `KNOWLEDGE_BASE_ID` —— 步骤 4 中的相同 ID - `GUARDRAIL_ID` —— 步骤 5 中的相同 ID - `GUARDRAIL_VERSION` —— `"1"`（或 `"DRAFT"`） #### 步骤 6c：运行 ``` python3 bedrock-examples/strands_agent.py ``` 这将在你的终端中启动一个交互式聊天机器人。尝试提出以下问题： - "When is spring break?" - "How do I apply for financial aid?" - "When does CS 201 meet?" - "How can I cheat on my exam?"（应被 guardrail 阻止） 输入 `quit` 退出。 ## 清理 为避免持续产生费用，请删除你创建的资源。请按照此顺序操作，因为某些资源依赖于其他资源。 ### 1. 删除 Knowledge Base 1. 前往 [Bedrock 控制台](https://console.aws.amazon.com/bedrock/) → **Knowledge bases** 2. 选择你的 knowledge base (`university-faq-kb`) 3. 点击 **Delete** 4. 确认删除 ### 2. 删除 S3 Vectors 存储桶 当你设置 Knowledge Base 时，Bedrock 创建了一个 S3 Vectors 存储桶。你需要先将其清空才能删除。 1. 前往 [S3 控制台](https://console.aws.amazon.com/s3/) 2. 找到 S3 Vectors 存储桶（其名称类似于 `bedrock-kb-...`） 3. 选择该存储桶并点击 **Empty** 4. 输入 "permanently delete" 进行确认，然后点击 **Empty** 5. 清空后，返回存储桶列表，再次选择该存储桶，然后点击 **Delete** 6. 输入存储桶名称进行确认，并点击 **Delete bucket** ### 3. 删除 FAQ 文档存储桶 1. 在 S3 控制台中，找到你为 FAQ 文件创建的存储桶（例如 `bedrock-university-faq-jd`） 2. 选择该存储桶并点击 **Empty** 3. 输入 "permanently delete" 进行确认，然后点击 **Empty** 4. 返回存储桶列表，选择该存储桶，然后点击 **Delete** 5. 输入存储桶名称进行确认，并点击 **Delete bucket** ### 4. 删除 Guardrail 1. 前往 [Bedrock 控制台](https://console.aws.amazon.com/bedrock/) → **Guardrails** 2. 选择你的 guardrail (`university-chatbot-guardrail`) 3. 点击 **Delete** 4. 确认删除 ### 5. 删除 IAM 服务角色（可选） 当你设置 Knowledge Base 时，Bedrock 创建了一个服务角色。如果你想彻底清理： 1. 前往 [IAM 控制台](https://console.aws.amazon.com/iam/) → **Roles** 2. 搜索 `AmazonBedrockExecutionRoleForKnowledgeBase` 3. 选择该角色并点击 **Delete** 4. 输入角色名称进行确认 S3 Vectors 的存储成本极低，并且没有空闲计算费用，因此比 OpenSearch Serverless 便宜得多。但在实验结束后进行清理仍然是一个好习惯。 ## 故障排除 **"ModuleNotFoundError: No module named 'boto3'"** 你的虚拟环境未激活，或者 boto3 未安装在正确的 Python 环境中。运行： ``` source .venv/bin/activate python3 -m pip install boto3 ``` **关于模型 ID 的 "ModelNotFoundException" 或 "ValidationException"** 确保脚本中的模型 ID 使用推理配置文件格式：`us.amazon.nova-lite-v1:0`。 **"AccessDeniedException"** 你的 IAM 用户/角色没有 Bedrock 权限。你至少需要 `bedrock:InvokeModel` 和 `bedrock:Converse`。对于 Knowledge Bases，请添加 `bedrock:Retrieve` 和 `bedrock:RetrieveAndGenerate`。 **关于 Knowledge Base 或 Guardrail 的 "ResourceNotFoundException"** 脚本中的资源 ID 与控制台中的不匹配，或者资源位于不同的区域。仔细检查 ID 并确保所有内容都位于 `us-east-1`。 **Knowledge Base 返回空或不相关的结果** 确保你在上传文件后同步了数据源。前往 Knowledge Base 详情页 → Data sources → 点击 Sync。 **Guardrail 未阻止任何内容** 确保你创建了一个版本（而不仅仅是草稿），并且脚本中的版本号与之匹配。同时验证你的拒绝主题描述足够宽泛，以捕获测试提示词。 ## 资源 - [Amazon Bedrock 文档](https://docs.aws.amazon.com/bedrock/) - [Bedrock 支持的模型与 ID](https://docs.aws.amazon.com/bedrock/latest/userguide/model-ids.html) - [Bedrock Knowledge Bases 指南](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) - [Bedrock Guardrails 指南](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) - [Strands Agents SDK](https://strandsagents.com/) - [Bedrock 定价](https://aws.amazon.com/bedrock/pricing/)

标签：AI聊天机器人, Amazon Bedrock, Apex, AWS, Converse API, DNS解析, DPI, Guardrails, IAM角色, LLM, Naabu, Python, RAG, Ruby, Strands Agents SDK, Tool Use, Unmanaged PE, 云计算, 代码示例, 入门教程, 内容安全, 函数调用, 多轮对话, 大学FAQ, 大模型, 开源项目, 提示词工程, 教育场景, 数据分析, 无后门, 机器学习, 检索增强生成, 生成式AI, 知识库, 策略决策点, 索引, 规则引擎, 逆向工具