Claude Certified Architect 的前置准备里Claude API 是最容易让人高估自己进度的一环。很多人以为把示例代码复制下来、能跑通一次就算“会用 API”了。实际上一旦进入认证备考或者真实项目环境配置、连接报错、结构化输出、批量任务一致性每一件事都会把你拉回起点。Part 4 这个阶段的核心就是通过 Claude API 搭出一套可复现的调用结构而不是停留在“能收到回复”这一步。这篇文章适合正在准备认证的人也适合刚接触 Claude API、想直接做工程集成的开发者我会按“环境 - 单次调用 - 结构化输出 - 可复用模块 - 排查验证”的顺序把整条链路拆开讲清楚。1. 前置准备要准备的不是“会用”而是“能交付”1.1 这个阶段到底在练什么Claude Certified Architect 这类认证不会只考提示词写得好不好。越是往架构师方向走越看重你能不能把一个模型能力变成产品功能。前置准备阶段的目的是把 API 调用的每个环节都跑熟包括鉴权、参数、错误处理、输出解析、成本和稳定性。从标题里的 Stru 看Part 4 的重点更偏向“结构”结构化输出、调用结构、代码目录结构。也就是说你要能设计出一个稳定的 API 调用模块让程序可以自动处理模型的返回结果而不是每次都在命令行里肉眼判断。我见过不少人在这个阶段只做一件事把官方文档里的示例跑一遍。跑通之后很开心但换一个输入就崩换一台机器就崩模型输出稍微带一点解释文字就崩。这不算准备完成。真正的完成标准是换一台干净机器照着你的说明能从头跑通并且每个环节都能说明白为什么这么配。1.2 结构能力为什么是分水岭普通调用关心的是 content 文本架构级集成关心的是 content 是否可解析、可校验、可重试。模型返回一段自然语言人看没问题程序处理却容易崩。结构化输出解决的就是接口契约问题。举个例子。你在提示词里写“请返回 JSON”模型很可能返回一段带反引号的代码块或者在 JSON 前后加几句解释。人眼能看懂但json.loads会直接报错。架构设计里不能把稳定性押在模型心情上必须用更严格的校验和更可靠的方式去约束输出。前置准备阶段把结构化输出练好后面做工具调用、多步任务、规则引擎集成都会顺很多。因为那些场景本质上都是同一个问题模型输出如何安全地进入下游系统。2. 三个高频连接问题证书、等待响应、API 网关2.1 self-signed certificate 报错通常不是模型问题本地调试时很多人会通过网关或内部服务转发 API 请求。网关为了保证通信安全可能使用自签名证书。这时 SDK 会直接报错例如“unable to connect to api: self-signed certificate”。这句话的意思很明确请求发出去了但目标服务器的证书无法被验证。常见原因有三个网关使用了自签名证书没有加入系统信任链。环境变量里没有指定 CA 证书路径。本地系统时间不对导致证书有效期判断失败。先别急着关掉证书校验。关掉确实能绕过报错但也等于把凭证和请求内容暴露在中间链路上。生产环境更不建议这么干。比较稳妥的做法是让客户端信任你的 CA 证书。以常见的语言环境为例# Node.js 环境 export NODE_EXTRA_CA_CERTS/path/to/ca.pem # Python requests / httpx 环境 export REQUESTS_CA_BUNDLE/path/to/ca.pem # 或者使用 OpenSSL 通用变量 export SSL_CERT_FILE/path/to/ca.pem配置完成后重新跑一次最小请求确认证书报错消失。如果还在报错优先看路径是否正确、证书文件是否是 PEM 格式。2.2 waiting for API response先分清是网络、请求体还是任务本身Claude Code 这类交互式工具里如果一直显示 waiting for API response很多人第一反应是模型太慢。实际上要先确认请求到底有没有发出去。排查顺序建议固定下来。先看 API 网关是否可达。网络不通的时候客户端会一直等待连接超时。再看 API key 和 base_url 是否正确鉴权失败有时会表现为长时间等待而不是立刻返回 401。接着看请求体大小。上下文越长模型处理时间越长这是正常现象。如果上下文已经好几万字等待时间变长是合理的但不代表没有别的隐藏问题。还要看日志。交互式工具一般会记录请求耗时和错误信息。如果是流式输出要检查是否一直累积内容但没有结束标记。这种问题经常被当成“模型卡住”其实是输出解析或事件流处理出了问题。如果你的任务本身需要模型多次调用工具每一次调用之间的等待时间也会累加起来。这时候不要只调大超时先确认每个步骤是否都正常结束。2.3 API 地址配置用网关统一 base_url 是常规工程做法多环境、多团队协作时把 API 请求统一指向一个网关非常常见。原因有三个统一鉴权、统一日志、统一配额。本地调试脚本里也可以通过环境变量切换 API 地址而不是改代码。常见的环境变量大概长这样export ANTHROPIC_API_KEY你的密钥 export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_AUTH_TOKEN你的令牌这里有个容易踩的坑如果你设置了ANTHROPIC_AUTH_TOKEN注意和ANTHROPIC_API_KEY的优先级差异。具体行为要看你使用的 SDK 版本。无论如何不要把密钥硬编码到代码里。放在.env文件里通过加载器注入是最低成本的正确做法。本地机器安装配置时最常见的两个问题就是API 地址填错以及证书不被信任。如果你在安装客户端后第一次连接就失败先确认这两个点再去看更深的错误。3. 结构化输出把模型的“回答”变成程序的“数据”3.1 为什么不能只靠一句“请返回 JSON”提示词可以要求 JSON但模型可能加注释、漏字段、字段类型错误甚至输出被 max_tokens 截断。架构上不能把稳定性押在提示词上至少要做三层保障请求侧明确约束输出格式并提供示例。响应侧解析 JSON 后做字段完整性校验。失败侧解析失败或校验失败时触发重试或记录现场。不同 API 版本对结构化输出的支持方式不同有的版本支持强制 JSON 模式有的版本需要用工具调用约束参数结构。具体参数要以你使用的 SDK 对应文档为准但上面三层保障思路是通用的。3.2 先有一条最小命令能跑通我建议先用 curl 做一次最小请求。目的是隔离掉代码层面的干扰确认网络和鉴权没有问题。curl https://api.anthropic.com/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: 填入你账号可用的模型ID, max_tokens: 1024, messages: [ {role: user, content: 输出一段 JSON包含 name 和 difficulty 两个字段} ] }这里几个点要说清楚。x-api-key是鉴权头anthropic-version是接口版本协商头缺少版本头在不同环境下的行为可能不一样。max_tokens要设置得够大否则输出容易在 JSON 还没结束时被截断。先跑通 curl再进入 SDK 调用。这样一旦后面出错你能快速判断问题出在网络层还是代码层。3.3 Python 示例拿到响应后先校验再使用跑通 curl 之后可以做一次最小 Python 调用。示例代码故意把校验写在最前面因为能解析 JSON 不代表内容合格。import json import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) response client.messages.create( model填入你账号可用的模型ID, max_tokens1024, system你是一个只输出 JSON 的助手不要输出任何解释。, messages[ {role: user, content: 请把这句话整理成 JSON包含 name、type、steps 三个字段。} ], ) text response.content[0].text.strip() data json.loads(text) assert {name, type, steps}.issubset(data.keys()), 字段缺失 print(data)注意两点。一是system参数是否单独传不同 SDK 版本可能有差异落地前先用官方文档确认。二是断言只是最基础的校验实际项目里可以根据业务定义更严格的结构比如字段类型、枚举值、嵌套层级。这一步跑通后你才算真正拿到“程序能直接消费的数据”而不是一段人工阅读的文字。4. 从单次脚本到可复用模块把异常处理补上4.1 单次脚本为什么不够用复制示例代码只能证明 API 通了。认证任务和真实项目通常要求可复现的结果。比如连续跑 20 个输入有的字段返回不对有的请求超时有的输出被截断。如果没有重试、日志和错误收集你无法判断是模型问题还是程序问题。单次脚本还有一个问题所有信息都打印到终端。一旦任务跑多终端刷新后现场就没了。可复用模块会把输入、输出、错误和原始响应都留下来方便复盘。4.2 一个最小可用封装下面这个封装不复杂但包含了四个关键设计环境变量注入密钥、重试机制、日志记录、JSON 解析加校验。import json import logging import os import time from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) logging.basicConfig(levellogging.INFO) def call_claude_json(prompt: str, retries: int 3): last_exc None for attempt in range(retries): try: resp client.messages.create( model模型ID, max_tokens1024, system只输出 JSON。, messages[{role: user, content: prompt}], ) text resp.content[0].text.strip() data json.loads(text) logging.info(attempt %s ok, keys%s, attempt 1, list(data.keys())) return data except Exception as exc: last_exc exc logging.warning(attempt %s failed: %s, attempt 1, exc) time.sleep(2 ** attempt) raise RuntimeError(frepeated failure: {last_exc}) if __name__ __main__: result call_claude_json(请输出一个 JSON 配置示例) print(result)这里有几个细节值得解释。重试间隔用2 ** attempt意思是第一次失败等 1 秒第二次等 2 秒第三次等 4 秒。避免瞬时故障时快速打爆网关。每次失败都记录日志不静默吞掉异常。最终失败时抛出RuntimeError调用方才知道任务没有成功。如果直接返回空值后续程序会误以为拿到了有效数据。注意重试不是万能的。如果是请求体格式错误、鉴权失败这类问题重试再多次也没有意义。所以模块里通常要先判断异常类型再决定是否重试。常见做法是只有网络超时、5xx 错误、限流错误才走重试。4.3 批量任务还要单独想输出命名和失败收集进入批量任务后不要把所有输出写到终端。建议按任务 ID 写文件错误单独写日志保留原始 prompt 和响应原文。一个简单的输出目录结构可以长这样tasks/ input/ task_001.json task_002.json output/ task_001.result.json task_002.result.json error/ task_001.error.log这样跑完一批任务后一眼就能看出哪些成功、哪些失败、失败在哪一步。如果直接把所有输出打到一个文件里排查时得人工对着行号猜非常低效。单次脚本和可复用模块的差别可以用一张表概括维度单次示例脚本可复用模块鉴权key 硬编码或写死路径环境变量加统一配置错误处理报错就退出重试、日志、异常抛出输出校验只看文本解析 JSON 加字段校验批量行为手动改输入读取任务列表、输出命名复盘能力不保留现场保留请求、响应和错误日志5. 本地环境验证顺序不要把隐患留在写代码之前5.1 建议按这个顺序跑一遍本地安装和配置阶段很多人喜欢直接启动交互式客户端结果遇到报错也不知道从哪查起。我更建议按下面的顺序走一遍。确认基础环境版本。Python 或 Node 版本太老SDK 可能直接装不上。配置环境变量。确保 API key、base_url、证书变量都已注入当前终端。先用 curl 做最小请求验证网络和鉴权。跑一次 SDK 单次调用确认代码环境正常。跑一次结构化输出确认 JSON 能稳定解析。最后再启动 Claude Code 这类交互式工具做端到端对话。这样做的原因是curl 最快把故障缩小到网络层SDK 失败通常是版本、参数或依赖问题交互式工具又在上面加了一层配置和权限逻辑。一层一层验证出错时能快速定位不用把网络、SDK、工具配置混在一起猜。5.2 一张排查表把常见现象和排查方向整理成一张表遇到问题时先对着表看一下比自己从头试高效很多。现象先看哪里常见原因建议证书报错环境变量、CA 文件网关证书未被信任配置 NODE_EXTRA_CA_CERTS 或写入系统信任链长时间等待响应网络连通性、请求体大小上下文过长、网关限流、超时太短先缩小请求体再逐步增加内容401/403API key、base_url环境变量没加载、令牌过期检查 env 注入位置和令牌有效期输出不是合法 JSON响应原文、max_tokens输出截断、提示词不收敛调大 max_tokens强化格式说明同一输入结果不稳定重试策略、校验逻辑参数波动、缺少字段校验增加校验必要时降低随机性参数5.3 Claude Code 这类交互工具要注意什么Claude Code 不是只用 API key 就行。它会读取本地配置、工作目录、工具权限和输出令牌上限。如果一直显示 waiting for API response去查它的日志目录看有没有网络超时、认证失败或长上下文被截断的记录。排查顺序仍然建议固定为输入 - 环境 - 参数。先看是不是请求体太大再看环境变量是否生效最后看参数配置。不要一上来就改超时那样可能掩盖真正的问题。6. 备考建议把这条链路做到“换个机器也能跑”6.1 主线任务是什么如果备考时间有限只练一条主线就好单次请求 - 结构化输出 - 错误重试 - 小批量任务。这四件事看起来普通但每一件都卡过不少刚起步的人。你可以给自己安排一个模拟任务准备 10 条输入文本写一个脚本批量请求 Claude API要求每条都输出指定字段的 JSON然后统计成功率和失败原因。这个小任务能把本篇文章涉及的大部分知识点串起来。做完之后你会发现真正花时间的不是写请求代码而是处理模型输出不稳定的情况。6.2 什么时候算准备到位我一般用三个标准自测。第一换一台干净机器照着你的 README 能跑通完整流程不需要口头补充。第二能解释每个参数为什么这么设而不是只会贴文档。第三遇到错误时能按网络、认证、请求体、输出校验四层定位问题。达到这三点后续做工具调用、多步智能体、系统集成都会舒服很多。6.3 几个容易忽略的边界模型 ID 会变化不要把写死的模型名当成永恒。不同账号可用的模型列表可能不一样落地时以账号实际可见的模型为准。低配置机器能跑通不代表适合跑长上下文。先用小样本验证再逐步加大输入同时观察内存和等待时间。本地能跑通也不代表生产环境能跑通。网关限流、并发策略、超时控制、敏感信息脱敏都要在生产化时重新设计。最后说一句实在话。Claude Certified Architect 考的不只是 API 的字符拼写而是你在真实环境里能不能把一个模型能力安全、稳定、可维护地交出去。前置准备阶段这些琐碎问题恰恰是最值钱的练习。