☰

企业官网建设流程全解析

首页 / 建站日记 / 企业官网建设流程全解析
基于 Claude 与 Amazon Bedrock 构建客户支持 Agent：claude-quickstarts 实战指南
2026/9/13 23:41:34 网站建设 项目流程

基于 Claude 与 Amazon Bedrock 构建客户支持 Agent：claude-quickstarts 实战指南

【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts

本指南以 claude-quickstarts 仓库中的customer-support-agent项目为核心，系统讲解如何基于 Claude 大模型与 Amazon Bedrock Knowledge Bases 构建一个具备知识检索、情绪识别、人工转接与高度可定制 UI 的客户支持聊天应用。读完本文，你将掌握该项目的环境配置、Bedrock RAG 知识库搭建、模型切换、结构化响应解析、AWS Amplify 部署以及按需裁剪界面的完整方案。

项目概览与核心特性

customer-support-agent是一个面向客户支持场景的聊天界面示例，核心组合是「Claude 模型对话 + Amazon Bedrock 知识检索（RAG）」。从 README 与源码可以归纳出以下核心能力：

  • AI 对话：基于 Anthropic 的 Claude 模型生成回复，由 API 路由 统一调用@anthropic-ai/sdk；
  • Bedrock RAG 检索：通过 BedrockAgentRuntimeClient 调用知识库为对话注入上下文；
  • 实时思考过程与调试信息展示：接口返回thinking、debug等字段，前端侧边栏实时渲染；
  • 知识来源可视化：RAG 检索到的来源（文件名、片段、相关性分数）通过响应头回传并展示在右侧边栏；
  • 用户情绪检测与人工转接：模型输出user_mood与redirect_to_agent，触发「转接人工」按钮；
  • 高可定制 UI：基于 shadcn/ui 组件构建，支持主题、布局灵活配置。

快速启动

按照 README 的指引，只需五步即可在本地跑起来：

  1. 克隆本仓库（claude-quickstarts）；
  2. 在customer-support-agent目录安装依赖：npm install；
  3. 配置环境变量（见下文「环境变量与密钥配置」）；
  4. 启动开发服务器：npm run dev；
  5. 浏览器打开http://localhost:3000。

需要说明的运行前提：customer-support-agent/package.json中声明了"engines": { "node": ">=18.17.0" }，建议使用 Node.js 18.17.0 及以上版本；框架为 Next.js 14.2.5（React 18），依赖中包含@aws-sdk/client-bedrock-agent-runtime、@anthropic-ai/sdk等核心库。

环境变量与密钥配置

在项目根目录创建.env.local文件，填入以下变量：

ANTHROPIC_API_KEY=your_anthropic_api_key BAWS_ACCESS_KEY_ID=your_aws_access_key BAWS_SECRET_ACCESS_KEY=your_aws_secret_key

注意 AWS 相关变量名前有一个额外的B（BAWS_*而非AWS_*）。README 明确说明这是为部署阶段准备的：AWS Amplify 不允许以AWS开头的环境变量名，因此统一加前缀规避该限制。从源码看，app/lib/utils.ts 中的 Bedrock 客户端正是通过process.env.BAWS_ACCESS_KEY_ID与process.env.BAWS_SECRET_ACCESS_KEY读取凭证：

const bedrockClient = new BedrockAgentRuntimeClient({ region: "us-east-1", // Make sure this matches your Bedrock region credentials: { accessKeyId: process.env.BAWS_ACCESS_KEY_ID!, secretAccessKey: process.env.BAWS_SECRET_ACCESS_KEY!, }, });

这里有两个容易踩坑的细节：一是region硬编码为us-east-1，需要与你的 Bedrock 知识库所在区域保持一致；二是.env.local仅作用于本地开发，部署到 Amplify 时要在控制台另行配置（见部署章节）。

获取 Claude API Key

  1. 访问 Anthropic 控制台（console.anthropic.com）；
  2. 注册或登录账号；
  3. 点击 "Get API keys"；
  4. 复制密钥填入.env.local。

获取 AWS Access Key 与 Secret Key

  1. 登录 AWS 管理控制台，进入 IAM（身份与访问管理）控制台；
  2. 左侧菜单点击Users；
  3. 点击Create user创建新用户（创建用户截图）；
  4. 在 Set Permission 页面选择Attach policies directly（授权方式截图）；
  5. 权限策略选择AmazonBedrockFullAccess（策略选择截图）；
  6. 完成 Review 并创建用户；
  7. 在用户 Summary 页面点击Create access key；
  8. 选择 "Application running on an AWS compute service"，按需填写描述后创建；
  9. 页面会一次性展示 Access Key ID 与 Secret Access Key，务必妥善保存（密钥截图），因为关闭后无法再次查看；
  10. 将两个密钥填入.env.local。

安全提醒：密钥只应在创建时可见，请勿公开分享；建议为最小权限原则考虑，生产环境可用更细粒度的策略替代AmazonBedrockFullAccess。

Amazon Bedrock RAG 集成

这是项目的核心差异化能力：对话前先到 Bedrock 知识库中检索相关内容，再把检索结果拼进系统提示词，让 Claude 基于知识库内容回答。

检索链路与实现原理

前端把用户最新消息与选中的知识库 ID 通过POST /api/chat发给后端，app/lib/utils.ts 中的retrieveContext(query, knowledgeBaseId, n = 3)完成检索：

const input: RetrieveCommandInput = { knowledgeBaseId: knowledgeBaseId, retrievalQuery: { text: query }, retrievalConfiguration: { vectorSearchConfiguration: { numberOfResults: n }, }, }; const command = new RetrieveCommand(input); const response = await bedrockClient.send(command);

其关键行为包括：

  • 默认返回n = 3条向量检索结果，可按需调整召回数量；
  • 若knowledgeBaseId为空或检索抛错，会安全降级返回空上下文并置isRagWorking = false，不会中断对话（见 route.ts 的 try/catch 分支）；
  • 检索结果会被组装为RAGSource[]（含id、fileName、snippet、score），通过响应头x-rag-sources回传前端用于来源可视化；
  • 最终上下文以纯文本拼接进系统提示词：${isRagWorking ? retrievedContext : "No information found for this query."}，并在debug.context_used中记录是否实际使用了知识库上下文。

配置你的知识库

  1. 确保 AWS 账号已开通 Bedrock 访问权限；
  2. 在目标区域创建 Bedrock 知识库；
  3. 将文档/语料索引进知识库（步骤见下文）；
  4. 编辑 components/ChatArea.tsx 中的knowledgeBases数组，替换为你的知识库 ID 与名称：
const knowledgeBases: KnowledgeBase[] = [ { id: "your-knowledge-base-id", name: "Your KB Name" }, // Add more knowledge bases as needed ];

应用会在对话过程中使用这些知识库做上下文检索。前端顶栏也提供了知识库下拉选择器（与模型下拉并列），便于在多个知识库之间切换。

如何创建自己的知识库

  1. 进入 AWS 控制台选择Amazon Bedrock；
  2. 左侧菜单 "More" 下点击Knowledge base；
  3. 点击Create knowledge base（创建入口截图）；
  4. 为知识库命名，可保留 "Create a new service role" 默认选项；
  5. 选择数据源，示例中使用 Amazon S3（数据源选择截图）。若用 S3，需先创建 bucket 并上传文件，也可以在知识库创建后再上传；
  6. 点击Next；
  7. 选择数据位置：可以是 S3 bucket、文件夹甚至单个文档；
  8. 点击Next；
  9. 选择 embedding 模型，示例使用 Titan Text Embeddings 2；
  10. 选择Quick create a new vector store（快速创建向量存储）；
  11. 确认并创建知识库；
  12. 从知识库概览页获取knowledge base ID，填入knowledgeBases数组。

切换模型

项目支持多个 Claude 模型并通过下拉菜单切换。在 components/ChatArea.tsx 中，models数组定义了可用模型，仓库当前默认包含三个：

const models: Model[] = [ { id: "claude-3-haiku-20240307", name: "Claude 3 Haiku" }, { id: "claude-haiku-4-5-20251001", name: "Claude 4.5 Haiku" }, { id: "claude-3-5-sonnet-20240620", name: "Claude 3.5 Sonnet" }, ];

当前选中的模型由selectedModelstate 控制：

const [selectedModel, setSelectedModel] = useState("claude-haiku-4-5-20251001");

UI 层使用DropdownMenu组件渲染模型列表，选中后更新selectedModel，并在提交请求时通过model字段传给/api/chat，最终作为anthropic.messages.create({ model, ... })的入参。README 中给出的默认选中值为claude-3-haiku-20240307，而当前仓库源码默认值为claude-haiku-4-5-20251001，以实际代码为准；添加新模型只需向models数组追加{ id, name }即可。

后端 API 与结构化响应机制

customer-support-agent/app/api/chat/route.ts是前后端通信的核心。除了调用 Claude，它还承担了「结构化输出」的关键职责。

Zod 响应 Schema

为保证模型输出可被前端可靠解析，路由使用 Zod 定义了响应结构：

const responseSchema = z.object({ response: z.string(), thinking: z.string(), user_mood: z.enum([ "positive", "neutral", "negative", "curious", "frustrated", "confused", ]), suggested_questions: z.array(z.string()), debug: z.object({ context_used: z.boolean() }), matched_categories: z.array(z.string()).optional(), redirect_to_agent: z.object({ should_redirect: z.boolean(), reason: z.string().optional(), }).optional(), });

模型生成的内容经过sanitizeAndParseJSON清洗（把字符串值内部的换行转义为\n后再JSON.parse）后，通过该 Schema 校验，保证响应字段完整、类型正确。

系统提示词与 JSON 输出

系统提示词把检索到的上下文、支持分类列表与 JSON 输出格式一并交给模型，要求其「整个响应必须是一个合法 JSON 对象」，并给出了带转接与不带转接两种示例。值得注意的实现技巧是：请求会把消息末尾追加一个内容为{的 assistant 消息（anthropicMessages.push({ role: "assistant", content: "{" })），诱导模型从「对象起始括号」之后继续生成，随后在拼装响应时补上前缀"{"，从而显著提升 JSON 输出的稳定性。

响应头与调试信息

接口除返回 JSON body 外，还通过响应头传递辅助信息：

  • x-rag-sources：RAG 检索到的知识来源（JSON 序列化）；
  • X-Debug-Data：服务端调试信息，包含收到的消息数、最新消息长度、API Key 前缀掩码（如sk-****）与时间戳，长度限制为 1000 字符。

前端 ChatArea.tsx 会解析x-rag-sources并派发updateRagSources事件供右侧边栏展示，解析X-Debug-Data输出到控制台。服务端还通过performance.now()对「用户输入接收、RAG 开始/完成、Claude 生成、API 完成」等阶段计时并打印日志，便于定位延迟瓶颈。

支持分类（matched_categories）

分类清单定义在 app/lib/customer_support_categories.json 中，默认包含 8 个类别：account（账号）、billing（计费）、feature（功能）、internal（内部）、legal（法律）、other（其他）、technical（技术）、usage（使用），每个类别附带若干关键词。系统提示词会要求模型在回答之外，将命中类别 ID 写入matched_categories数组，多个命中可返回多个 ID，无命中返回空数组——这套机制可以支撑后续的工单自动分类与统计。

用户情绪检测与人工转接

这是该项目区别于普通聊天机器人的体验设计。模型在每次响应中输出：

  • user_mood：六档情绪标签（positive / neutral / negative / curious / frustrated / confused）；
  • redirect_to_agent：是否建议转接人工及原因；
  • suggested_questions：建议的追问问题，前端渲染为可点击的快捷按钮，点击后自动作为新消息提交。

当redirect_to_agent.should_redirect为true时，前端MessageContent会渲染UISelector组件，展示一个"Talk to a human"按钮；点击后派发humanAgentRequested自定义事件（携带 reason、mood、timestamp），方便业务方接入真实的客服排队/工单系统。服务端也会在转接触发时输出🚨 AGENT REDIRECT TRIGGERED!与原因日志。同时，系统提示词约束：当检索不到相关信息、信息与问题无关，或问题与产品无关时，应引导用户转接人工。

界面定制

项目基于 shadcn/ui 组件体系构建，定制路径清晰：

  • UI 组件：修改 components/ui 目录下的基础组件（按钮、卡片、对话框、下拉菜单、输入框、头像等）；
  • 全局样式：调整 app/globals.css 中的主题变量；
  • 页面布局：在 app/page.tsx 中调整顶层导航、左右侧边栏与聊天区的组合，侧边栏组件通过dynamic(..., { ssr: false })按需加载；
  • 主题色板：编辑 styles/themes.js，其结构如下：
// styles/themes.js export const themes = { neutral: { light: { // Light mode colors for neutral theme }, dark: { // Dark mode colors for neutral theme } }, // Add more themes here };

新增主题或调整现有主题，只需修改该文件的颜色值；主题切换由 components/theme-provider.tsx 配合next-themes完成。

使用 AWS Amplify 部署

Amplify 构建配置

  1. 进入 AWS 控制台选择Amplify；
  2. 点击Create new app；
  3. 选择 GitHub（或其他代码托管平台）作为源码来源；
  4. 选择本仓库；
  5. 将构建配置（YAML）编辑为以下内容（仓库中的 amplify.yml 即为该配置的成品版本）：
version: 1 frontend: phases: preBuild: commands: - npm ci --cache .npm --prefer-offline build: commands: - npm run build # Next.js build runs first - echo "ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY" >> .env - echo "KNOWLEDGE_BASE_ID=$KNOWLEDGE_BASE_ID" >> .env - echo "BAWS_ACCESS_KEY_ID=$BAWS_ACCESS_KEY_ID" >> .env - echo "BAWS_SECRET_ACCESS_KEY=$BAWS_SECRET_ACCESS_KEY" >> .env artifacts: baseDirectory: .next files: - "**/*" cache: paths: - .next/cache/**/* - .npm/**/*

要点说明：preBuild阶段用npm ci做可复现安装；build阶段先执行 Next.js 构建，再把 Amplify 环境变量写入.env供服务端读取（注意此处引入了 README 中提到的KNOWLEDGE_BASE_ID，即知识库 ID 在部署场景下也走环境变量注入）；cache阶段缓存.next/cache与.npm以加速后续构建。

  1. 选择新建服务角色或复用已有角色（见下文「Service Role」）；
  2. 点击Advanced settings添加环境变量：
ANTHROPIC_API_KEY=your_anthropic_api_key BAWS_ACCESS_KEY_ID=your_aws_access_key BAWS_SECRET_ACCESS_KEY=your_aws_secret_key

再次强调加B前缀的原因：AWS 不允许 Amplify 中出现以AWS开头的环境变量名，所以这里的键名沿用了BAWS_*。

  1. 点击Save and deploy开始部署。

Service Role（服务角色）

部署完成后，如果选择了新建服务角色，还需补齐 Bedrock 访问权限：

  1. 进入部署页面，选中刚创建的部署；
  2. 点击App settings；
  3. 复制Service role ARN；
  4. 到 IAM 控制台找到该角色；
  5. 为该角色附加AmazonBedrockFullAccess策略。

这样 Amplify 应用才具备与 Amazon Bedrock 交互的权限，避免部署成功但 RAG 检索全部失败。

灵活的侧边栏配置与 NPM 脚本

项目支持按需裁剪界面布局（左/右侧边栏），由根目录 config.ts 通过环境变量控制：

type Config = { includeLeftSidebar: boolean; includeRightSidebar: boolean; }; const config: Config = { includeLeftSidebar: process.env.NEXT_PUBLIC_INCLUDE_LEFT_SIDEBAR === "true", includeRightSidebar: process.env.NEXT_PUBLIC_INCLUDE_RIGHT_SIDEBAR === "true", }; export default config;

两个环境变量的含义：

  • NEXT_PUBLIC_INCLUDE_LEFT_SIDEBAR：设为"true"时包含左侧边栏（展示思考过程、情绪、匹配分类）；
  • NEXT_PUBLIC_INCLUDE_RIGHT_SIDEBAR：设为"true"时包含右侧边栏（展示 RAG 知识来源）。

package.json 预置了对应的 NPM 脚本：

npm run dev # 完整应用（双侧边栏，默认） npm run build # 构建完整应用（双侧边栏，默认） npm run dev:full # 同 npm run dev npm run dev:left # 仅左侧边栏 npm run dev:right # 仅右侧边栏 npm run dev:chat # 仅聊天区（无侧边栏） npm run build:full # 同 npm run build npm run build:left # 构建仅左侧边栏 npm run build:right # 构建仅右侧边栏 npm run build:chat # 构建仅聊天区（无侧边栏）

这些脚本通过在执行next dev/next build前设置对应环境变量来切换布局，例如dev:chat实质是NEXT_PUBLIC_INCLUDE_LEFT_SIDEBAR=false NEXT_PUBLIC_INCLUDE_RIGHT_SIDEBAR=false next dev。配合 app/page.tsx 中的条件渲染（config.includeLeftSidebar && <LeftSidebar />等），即可按测试、开发或生产需求灵活定制界面形态。当某侧边栏被禁用时，ChatArea.tsx 仍会监听对应的自定义事件（updateSidebar/updateRagSources），只是改为在控制台输出，方便你自行决定数据如何处理。

附录：原型声明

按 README 附录 的说明，本项目定位为原型（prototype），以 "as-is" 形式提供，不适用于生产或关键任务环境，可能包含缺陷与不一致之处。使用前请知悉：软件以预发布/beta/试用形态提供；开发者不对使用造成的任何问题、数据丢失或损害负责；不提供任何明示或暗示的担保；支持可能有限或不可用；使用风险自负。如需在生产环境落地，建议在充分测试、加固安全与可观测性之后再进行。项目整体作为 claude-quickstarts 仓库的一部分，旨在帮助开发者快速上手基于 Claude API 构建可部署的应用。

【免费下载链接】claude-quickstartsA collection of projects designed to help developers quickly get started with building deployable applications using the Claude API项目地址: https://gitcode.com/GitHub_Trending/an/claude-quickstarts

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

标签： 网站建设 企业官网 项目流程 UI设计 前端开发

热门文章

文章分类

标签云

网站建设 响应式设计 用户体验 SEO优化 前端开发 小程序 电商平台 性能优化

相关文章

您可能感兴趣的其他内容

Wagtail 2.11.4 维护版发布说明：别名同步发布、隐私规则与权限修复深度解析
2026/9/13 23:39:10 网站建设

Wagtail 2.11.4 维护版发布说明：别名同步发布、隐私规则与权限修复深度解析

Wagtail 2.11.4 维护版发布说明&#xff1a;别名同步发布、隐私规则与权限修复深度解析 【免费下载链接】wagtail A Django content management system focused on flexibility and user experience 项目地址: https://gitcode.com/GitHub_Trending/wa/wagtail Wagtail …...

阅读更多 →
ONNX Runtime CUDA MatMulNBits 算子深度解析：权重量化矩阵乘的分派链路、GEMV 内核与 fpA_intB 路径
2026/9/13 23:38:37 网站建设

ONNX Runtime CUDA MatMulNBits 算子深度解析：权重量化矩阵乘的分派链路、GEMV 内核与 fpA_intB 路径

ONNX Runtime CUDA MatMulNBits 算子深度解析&#xff1a;权重量化矩阵乘的分派链路、GEMV 内核与 fpA_intB 路径 【免费下载链接】onnxruntime ONNX Runtime: cross-platform, high performance ML inferencing and training accelerator 项目地址: https://gitcode.com/Git…...

阅读更多 →
self-llm 的 MiniCPM5-1B 如何启用 XML 风格工具调用与 vLLM tool-call-parser
2026/9/13 23:37:13 网站建设

self-llm 的 MiniCPM5-1B 如何启用 XML 风格工具调用与 vLLM tool-call-parser

self-llm 的 MiniCPM5-1B 如何启用 XML 风格工具调用与 vLLM tool-call-parser 【免费下载链接】self-llm 《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调&#xff08;全参数/Lora&#xff09;、部署国内外开源大模型&#xff08;LLM&#xff09;/多模态大…...

阅读更多 →

需要专业的网站建设服务？

联系我们获取免费的网站建设咨询和方案报价，让我们帮助您实现业务目标

立即咨询