企业官网建设流程全解析

很多开发者第一次把 Claude API 调通时，会有一个错觉：模型能返回文本，任务就完成了。但一旦进入真实项目，你很快就会撞到一连串跟“模型能不能回答”无关的问题——请求应该同步等还是流式推？Agent 是一次调用还是一个循环？上下文是无脑塞满还是应该有预算？服务端过载时要不要重试？这些问题没有一个是模型参数能回答的，它们属于 Mode 的范畴。

这篇文章是“Claude 架构师前置技能构建”系列的第 6 篇，主题就是 Mode。我不会只讲“怎么调 API”，而是把请求模式、Agent 模式、上下文模式和错误处理模式放到一起，给你一张可以落地的决策地图。读完你至少能回答三个问题：一个生产级的 Claude API 调用应该长什么样？为什么 529、400 context length 这类报错不能靠换行重试解决？从“能跑通”到“能上线”，中间到底差在哪几步。

1. 这篇文章真正要解决的问题

先说一个我在不少项目里看到的共性现象：团队把 Claude API 当成一个普通的 HTTP 接口来用，代码里写死一个requests.post，传进去 prompt，等返回后直接渲染。Demo 阶段一切正常，因为量小、问题简单、失败概率低。可一旦进入生产，就会出现三类问题：

第一，体验问题。大模型生成速度再快，一次完整生成也要几秒到几十秒。如果前端一直转圈等同步响应，用户的耐心很快耗尽。第二，稳定性问题。大模型的 API 天然有波动，服务端过载、限流、超时都发生过。如果调用层没有任何重试和兜底策略，任何一次上游抖动都会变成用户看到的错误页。第三，上下文失控。对话越长，携带的历史越多，最终触发 400 context length 之类的报错。这不是“把 max_tokens 调大”能解决的，因为限制的是输入上下文，不是输出长度。

所以这篇文章真正要解决的问题，不是“如何让 Claude 回答得更准”，而是“如何把 Claude API 放进一个靠谱的系统架构里”。它面向的是后端工程师、AI 应用开发者、以及准备把 Agent 做到生产环境的团队。

我给出的核心判断是：从“能跑通”到“能上线”，关键不在 Prompt 写得好不好，而在 Mode 有没有想清楚。Mode 决定了你的系统是单点脚本还是可运维服务，决定了上游抖动时你是优雅降级还是直接崩溃，也决定了上下文无限膨胀时你有没有退路。

2. Mode 到底是什么：先建立一张认知地图

“Mode”这个词在不同语境下含义不同，需要先拆开讲清楚，否则后续所有讨论都会混在一起。

2.1 Mode 不是模型参数

很多人把temperature、max_tokens、top_p当成了 Mode，这是一种误解。参数控制的是“单次生成的风格和长度”，而 Mode 控制的是“整个系统以什么方式与模型交互”。参数是局部设置，Mode 是全局架构。架构师关心的是后者。

2.2 请求模式：Message 与 Stream

目前主流的 LLM API 都支持两种基本请求模式：

• 非流式：发送一次请求，等服务端把完整内容生成完再一次性返回。实现简单，调试直观，但首字延迟高，用户等待感明显。
• 流式：服务端边生成边返回内容分片，前端可以逐字展示。实现稍复杂，但体验显著提升，也是大多数真实应用的首选。

这个选择看似简单，却在第一时间决定了用户体验的上限。一个没有流式的 AI 应用，在生成较长内容时几乎必然是“白屏等待”。

2.3 Agent 模式：单轮与多轮工具循环

如果只是做聊天机器人，一次消息对应一次模型调用就够了。但一旦要做 Agent，让它执行搜索、操作数据库、调用业务系统，就必须切换成多轮模式：

1. 用户提出任务；
2. 模型返回一个意图，并请求调用某个工具；
3. 你的系统执行工具，把结果回填给模型；
4. 模型基于工具结果继续推理，决定是再次调用工具还是给出最终答案。

这套循环是 Agent 区别于 Chatbot 的分水岭。架构师必须在系统设计阶段就明确：你构建的是单轮问答，还是多轮工具循环？如果是后者，谁来存储中间状态，谁来控制循环终止条件，谁来决定单次任务最多允许调用多少次工具，这些都是 Mode 层面的问题。

2.4 上下文模式：无限增长与有界管理

大模型 API 的输入有长度上限。即便某些模型支持很长的上下文窗口，也不意味着你可以无节制地往里塞内容。上下文越长，单次请求的延迟和成本越高，而且超出上限后服务端会直接拒绝请求。

因此，生产系统必须有一套“上下文管理模式”：是全部保留历史，还是窗口滑动只保留最近几轮？是直接把长文档压缩成摘要，还是开启 Prompt Caching 复用不变的系统提示词？这个模式选型，直接决定了长对话场景下系统能否稳定运行。

2.5 部署模式：脚本、服务与交互式工具

最后一种 Mode 是“形态模式”。同一个 Claude 能力，可以做成一次性脚本、常驻 API 服务、或者用 Claude Code 这类交互式开发工具来驱动。三种形态的成本结构、可观测性和迭代速度完全不同，架构师需要在项目开始前就做出取舍。

我把这几种 Mode 整理成一个表格，方便对照：

3. 环境准备与前置条件

在写代码之前，先把环境准备好。无论你后面是使用纯 API 还是 Claude Code，都需要完成以下几步。

3.1 获取 API Key

在 Anthropic 控制台注册账号后，进入 API Keys 页面创建密钥。需要注意几点：

• 密钥属于敏感凭证，不要写进代码仓库，不要放在前端代码里；
• 建议在控制台限定密钥的权限范围，生产环境使用独立密钥；
• 所有读取密钥的位置统一走环境变量，而不是散落在多个文件里。

3.2 安装 Python SDK

如果你使用 Python 开发，安装官方 SDK：

pip install anthropic

安装 SDK 后，先在命令行确认环境变量是否已经配置：

# Linux / macOS export ANTHROPIC_API_KEY="your-api-key" # Windows PowerShell $env:ANTHROPIC_API_KEY="your-api-key"

SDK 会自动读取ANTHROPIC_API_KEY环境变量，不需要在代码里硬编码密钥。

3.3 安装 Claude Code（可选）

如果你希望直接在终端里用自然语言驱动编码任务，可以安装 Claude Code。安装好后，在任何项目目录执行claude命令即可进入交互式会话：

claude --version claude

很多开发者在这一步会遇到“claude无法识别”的情况。这个问题的原因往往是 Node.js 环境没有装好、全局安装路径不在 PATH 中，或者安装命令没有执行成功。先确认 Node.js 版本和环境变量，再重装一次即可。具体的安装命令以官方文档为准。

4. 第一个示例：从单次请求理解 Message 模式

我们先写一个最基础的示例，目标是跑通“Message 模式”的最小闭环。代码很简单，但走完这一步你才能确认密钥、模型名和网络链路都正常。

# 文件路径：examples/basic_message.py import anthropic # SDK 会自动读取 ANTHROPIC_API_KEY 环境变量 client = anthropic.Anthropic() response = client.messages.create( model="YOUR_CLAUDE_MODEL", # 替换为你在控制台可用的模型名 max_tokens=1024, messages=[ {"role": "user", "content": "用一句话解释什么是幂等性，并给一个后端例子"} ] ) print(response.content[0].text)

运行方式：

python examples/basic_message.py

预期输出是一段简短的解释文本。这里有几个关键点值得说明：

model参数不能随意填写。模型名需要与你的账号权限匹配，写错会直接报模型不存在的错误。示例中YOUR_CLAUDE_MODEL需要替换为控制台实际可见的模型名。

max_tokens限制的是“输出长度”，不是“输入长度”。很多第一次接触的人会把输入太长导致的报错归咎于max_tokens太小，这是误解。超出输入上下文限制时会收到 400 类错误，错误信息会明确说明请求的 token 数超过上下文上限。

messages是对话内容。其中每一轮都要标注role是user还是assistant。注意，多轮对话时要把历史消息都传进来，模型本身不做持久化。

这里真正容易踩坑的地方是：你以为自己在“对话”，但实际上每次调用都是无状态的。服务端不会记住上一轮内容，所有上下文都必须由调用方在每次请求中携带。这就是为什么上下文管理会成为架构问题，而不是单次请求问题。

跑通这个示例后，你只完成了 20%。接下来要进入真正影响生产质量的部分。

5. 流式模式与工具调用模式：走向真实系统

5.1 流式模式：先解决体验

基础模式适合验证，不适合产品化。体验问题决定了你必须尽快切换到流式。流式模式下，服务端会不断返回增量内容，用户看到的是逐字输出的效果，不需要干等。

# 文件路径：examples/stream_message.py import anthropic client = anthropic.Anthropic() with client.messages.stream( model="YOUR_CLAUDE_MODEL", max_tokens=1024, messages=[ {"role": "user", "content": "请分点列出设计一个 AI Agent 的 5 条注意事项"} ], ) as stream: for text in stream.text_stream: print(text, end="", flush=True)

如果不想使用高层封装，也可以用底层方式手动遍历事件：

# 文件路径：examples/stream_event_manual.py import anthropic client = anthropic.Anthropic() response = client.messages.create( model="YOUR_CLAUDE_MODEL", max_tokens=1024, stream=True, messages=[ {"role": "user", "content": "用三句话介绍流式输出"} ], ) for event in response: if event.type == "content_block_delta" and event.delta.type == "text_delta": print(event.delta.text, end="", flush=True)

流式模式带来的代价是连接管理变复杂。服务端可能因为网络断开、上游超时等原因中断流，调用方需要处理“流中途断掉”的情况，并在 UI 上给出友好的重试或重连机制。从架构角度说，流式不是把stream参数改成True就完了，配套的还有超时、断连检测和心跳策略。

5.2 工具调用模式：Agent 的能力边界

如果说流式模式解决的是“体验”，工具调用模式解决的就是“能力边界”。没有工具调用的 Claude 只能输出文字，无法影响外部世界；拥有工具调用后，它可以读取数据库、调用业务接口、查询外部服务。

工具调用的流程是一个循环，基本步骤如下：

1. 调用模型时，额外传入可用的工具定义（JSON Schema 格式）；
2. 模型判断当前任务是否需要工具，如果需要，返回一个工具调用请求；
3. 你的系统执行对应的工具，拿到结果；
4. 把工具结果作为新消息继续传给模型；
5. 循环执行，直到模型返回最终文本。

工具定义的最小示例：

{ "name": "search_products", "description": "按关键词搜索商品列表，返回商品名称与价格", "input_schema": { "type": "object", "properties": { "keyword": { "type": "string", "description": "商品关键词" } }, "required": ["keyword"] } }

循环逻辑示意（伪代码，实际实现需要处理边界条件）：

# 文件路径：examples/tool_loop_skeleton.py def run_agent(user_input, tools, max_steps=5): messages = [{"role": "user", "content": user_input}] for step in range(max_steps): response = client.messages.create( model="YOUR_CLAUDE_MODEL", max_tokens=1024, messages=messages, tools=tools, ) if response.stop_reason == "tool_use": tool_use_block = next( b for b in response.content if b.type == "tool_use" ) # 执行工具（这里需要你自己实现函数分发） result = execute_tool(tool_use_block.name, tool_use_block.input) # 把模型返回的消息和工具结果一起加入会话 messages.append({"role": "assistant", "content": response.content}) messages.append({ "role": "user", "content": [ { "type": "tool_result", "tool_use_id": tool_use_block.id, "content": str(result), } ], }) else: return response raise RuntimeError("Agent 执行超过最大步数")

从架构角度看，这个循环有四个必须关注的边界：

第一，工具执行权限。不是所有工具都应该让模型随意调用。删除、写入、变更类操作应当有权限校验和人工确认机制。

第二，循环终止条件。最多执行多少步、单次输出超时怎么办、无效循环如何识别，都要有明确规则，否则一次任务可能拖垮整个系统。

第三，工具结果长度。工具返回的内容可能很长，直接塞进上下文会迅速消耗 token。需要做截断、摘要或只提取关键字段。

第四，错误传递。工具执行失败后，是把错误信息返回给模型让它纠错，还是直接终止任务，需要提前设计。

6. 上下文管理与 Prompt Caching：从根上避开 400 错误

接入真实场景后，你迟早会遇到 400 context length 超限之类的错误。这类错误不是随机故障，而是上下文管理缺位的必然结果。例如某个模型支持大上下文窗口，但超过上限后请求会被拒绝，错误信息通常会明确提示输入超过了模型的上下文长度。

解决思路不是把限制“调大”，而是建立有预算的上下文管理模式。

6.1 估算上下文占用

每次请求前，调用方应该知道当前请求大概会吃掉多少 token。这里不一定要引入特别精确的计算库，但至少要有估算习惯。一个常见的粗估口径是：英文内容约 4 个字符一个 token，中文内容约 1 到 2 个字一个 token，具体因模型而异。更精确的做法是在代码里加一个计数函数，把系统提示、历史消息、用户输入逐段统计，超出阈值时触发截断策略。

6.2 使用 Prompt Caching 复用固定内容

很多场景下，系统提示词和用户指令是固定不变的，只有最后几轮对话在变化。如果每次请求都重新计费、重新处理这些内容，成本是浪费的。Prompt Caching 的核心思路是标记出“不常变化”的内容，让服务端做缓存，后续请求复用这一部分，从而降低时间和成本。

# 文件路径：examples/prompt_caching.py import anthropic client = anthropic.Anthropic() SYSTEM_PROMPT = """ 你是一名资深的系统架构师，负责评审后端设计方案。 在评审时，你需要重点关注：系统稳定性、数据一致性、安全边界、可观测性。 请给出具体的改进建议，而不是泛泛而谈。 """ system = [ { "type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}, } ] response = client.messages.create( model="YOUR_CLAUDE_MODEL", max_tokens=1024, system=system, messages=[ {"role": "user", "content": "请评审以下方案：订单服务使用本地事务，同时异步通知库存服务扣减库存。"} ], ) print(response.content[0].text)

在这个示例中，cache_control标记了系统提示词为可缓存内容。只有当系统提示词足够长、且多次请求复用时，缓存收益才明显。小提示词没有必要加这个标记。

架构师需要把 Prompt Caching 当成缓存策略来管理，而不是一个开关：哪些内容放缓存（系统提示、固定知识库），哪些内容不进缓存（用户私有数据、动态查询结果），这需要结合业务和安全边界来决定。

6.3 上下文压缩与滑动窗口

对多轮对话场景，另一个常用策略是“有界历史”：只保留最近 N 轮完整对话，更早的内容要么丢弃，要么在进入下一轮前先让模型生成一段摘要。滑动窗口实现简单，但可能丢失关键信息；摘要压缩保留的信息更多，但会引入额外的模型调用成本。

一个稳妥的做法是组合式管理：系统提示词走缓存，最近几轮全量保留，更早历史走摘要。这样既控制成本，又减小上下文膨胀速度。

7. 错误处理与重试架构：529 只是开始

接入过 Claude API 的开发者大概率见过这样的错误：api error: 529 overloaded. this is a server-side issue, usually temporary。这是服务端过载的信号，属于可重试错误。还有 400 类错误表示请求本身有问题，比如上下文超限、参数不合法、模型名不正确，这类错误重试一万次也没用。

所以架构师首先要做的不是写重试代码，而是给错误分类。

7.1 错误分类与处置策略

7.2 一个带重试的调用封装

真实项目里，重试逻辑不能散落在每个业务函数中，应该收敛到一个统一的客户端封装里。

# 文件路径：examples/robust_client.py import time import random import anthropic class ClaudeAPIClient: def __init__(self, api_key, model, max_retries=5): self.client = anthropic.Anthropic(api_key=api_key) self.model = model self.max_retries = max_retries def create_message(self, messages, max_tokens=1024): for attempt in range(self.max_retries): try: return self.client.messages.create( model=self.model, max_tokens=max_tokens, messages=messages, ) except anthropic.RateLimitError: wait_time = 2 ** attempt + random.random() print(f"限流，{wait_time:.1f}s 后重试...") time.sleep(wait_time) except anthropic.APIStatusError as exc: if exc.status_code == 529: wait_time = 2 ** attempt + random.random() print(f"服务端过载(529)，{wait_time:.1f}s 后重试...") time.sleep(wait_time) else: raise raise RuntimeError("重试次数用尽，任务失败")

这个封装里有两个关键设计：

一是退避策略。初始等待时间短，随着失败次数增加指数增长，同时加入随机抖动，避免多个请求在同一时刻重试形成“重试风暴”。

二是只对可重试错误重试。400、401 这类错误直接抛出，避免无效重试浪费时间和配额。

需要说明的是，重试不是万能的。如果服务端持续过载，或者业务对响应时间有严格要求，架构上还要准备降级方案，比如提示用户稍后重试、切换其他模型、或者走本地缓存返回兜底结果。

8. 面向架构师的 Mode 决策清单

把前文的内容收敛成一份可以直接用于技术方案评审的清单。每一条都不是理论，而是生产环境中需要明确回答的问题。

8.1 请求模式决策

你的业务是实时聊天还是离线处理？实时场景必须考虑流式输出。如果只是后台批量生成摘要，非流式也可以接受。流式模式下要配套处理连接中断、超时和前端重连逻辑。

8.2 Agent 模式决策

你的系统是单轮问答还是多轮工具循环？如果是后者，必须明确：工具由谁批准执行、单次任务最大步数、工具结果长度限制、循环终止条件。缺少任何一环，Agent 在生产环境的稳定性都不可控。

8.3 上下文模式决策

每次请求携带什么内容？系统提示词是否可以缓存？历史消息是全量保留还是滑动窗口？长文档是否需要先做压缩？建议在代码里埋入 token 估算日志，让上下文策略可观测、可调优。

8.4 错误处理决策

哪些错误可重试、哪些不可重试？重试策略怎么配？有没有降级方案？建议统一收敛到客户端封装，而不是让业务代码到处处理异常。

8.5 安全与成本决策

API Key 是否全部走环境变量和密钥管理？日志中是否打印了完整的请求和响应内容？工具调用是否做了权限校验？每次请求的 token 消耗是否有监控？成本失控通常不是模型贵，而是上下文管理失控导致的重复计费。

8.6 可观测性决策

请求延迟、token 消耗、错误率、重试次数，这几个指标应该从一开始就埋点。生产环境里最怕的不是出错，而是出错了无法定位。建议至少记录每次请求的模型名、输入 token 数、输出 token 数、耗时和错误类型。

9. 常见问题与排查方法

根据我在社区和实践中看到的高频问题，整理了下面这张排查表。

排查时有个通用原则：先看错误类型，再看请求参数，最后看网络和环境。很多问题在日志里已经有明确提示，只是被忽略了。建议把每次请求的 model、messages 长度、错误码都打出来，排查速度会快很多。

10. 总结与后续学习方向

这篇文章从 Mode 的视角，把 Claude API 在生产环境中的关键问题串了一遍：请求模式决定了体验，工具调用模式决定了 Agent 的能力边界，上下文管理模式决定了长对话的稳定性，错误处理模式决定了系统的可用性上限。你可能已经发现，这些内容没有一条是“提示词技巧”，而全部是工程决策。这恰恰是架构师前置技能的核心：不是让模型表现更好，而是让系统在真实环境里稳定运行。

如果你刚接触 Claude，建议按这个顺序实践：先用第 4 节的基础示例跑通调用链路，再切换到流式模式，然后接入一个最小的工具调用循环，最后补上重试和上下文管理。每一步都跑通后，再去尝试多 Agent 编排、上下文压缩和评估体系，这样会比较稳。

给准备做生产项目的团队一个提醒：不要把“能跑通的 Demo”当成“可上线的系统”。Demo 只看模型能力，生产系统看的是对 Mode 的管理能力。建议在项目初期就把请求模式、Agent 边界、上下文预算、重试策略和可观测性列进技术方案评审，后面会省去大量返工的麻烦。