从Prompt Eval到Claude API运行：工程实践与排错指南

这次不聊泛泛的提示词技巧直接来看一条更实际的链路作为 Claude Certified Architect 前置课程的一部分你不仅要把 Prompt 写好还要能把它放进 Claude API 里跑通并且通过 Prompt Eval 评估最终把评估结果转成一个可运行、可维护的脚本或命令行工具。这里要解决的三个问题是Claude API 环境怎么准备、Prompt Eval 怎么做评测、评测通过之后怎么真正运行起来。同时我会把常见工程问题一起处理掉包括unable to connect to api: self-signed certificate、claude code waiting for api response这类让新手直接卡死的报错。文章尽量按“能跑通、能验证、能排错”的路子走适合正在准备认证、同时又要做实际 API 集成的开发者。先给结论如果你已经会调用 Claude API但缺少 Prompt 的量化评测意识或者你能写 Prompt但不知道怎么把它变成批量任务和接口调用这篇文章就值得你往下看。全程不依赖昂贵硬件普通开发机甚至低配云主机即可重点在环境变量、评测流程、API 调用和故障排查。1. 核心能力速览能力项说明项目主题Claude Certified Architect 前置课第 5 部分从 Prompt Eval 到 Claude API 实际运行最核心功能用 Claude API 完成消息调用用 Prompt Eval 评测 Prompt 质量再把评测通过的 Prompt 落到脚本、批量任务或 Claude Code 中运行需要准备Anthropic API Key、Python 3.9 或 Node.js 18、可访问 API 的网络环境启动方式Python SDK、Node SDK、Claude Code 命令行、curl 请求主要功能单轮对话、多轮对话、流式输出、批量评测、API 网关接入API 能力兼容 Anthropic Messages API支持自定义base_url指向网关或代理服务批量任务通过脚本循环调用 API适合 Prompt 批量评测和内容批量生成硬件要求无 GPU 需求普通 CPU 开发机即可主要关注网络时延和 API 配额适合场景认证备考、内部工具集成、Prompt 版本管理、API 稳定性验证需要说明Claude API 是托管式云端服务本地不跑大模型所以不存在“显存占用”的概念。你更该关心的是请求耗时、token 消耗、并发限制和网络连接稳定性这些后面会展开。2. 适用场景与使用边界2.1 适合谁正在准备 Claude Certified Architect 认证想补上“从 Prompt 到运行”这一环的开发者。负责企业内 AI 应用集成需要把 Claude 的能力接到已有系统里的后端工程师。需要对多个 Prompt 做横向评估对比输出质量后选择最优方案的算法或产品同学。想用 Claude Code 在终端里跑任务又不想踩证书和超时坑的开发者。2.2 能解决什么Prompt Eval 解决的是“这个 Prompt 到底好不好”的问题。它是把 Prompt 看成代码一样用一组输入、期望输出和评分标准去量化结果。没有评估你只能凭感觉调 Prompt有评估之后每一次修改都能看出是变好还是变差。这对架构师角色尤其重要因为你不仅要写 Prompt还要推动团队建立可持续迭代的评测机制。2.3 不适合什么Claude API 不适合做本地离线推理也不适合在无网络环境下使用。如果你需要完全本地化、离线、低延迟的模型服务应该考虑开源模型或本地部署方案。另外如果只是简单问几个问题直接用 Claude 聊天产品即可没必要上 API。API 的价值在于自动化、批量化和集成。2.4 使用边界与合规提醒使用 Claude API 前必须遵守 Anthropic 的服务条款并确保你的使用场景符合适用的法律法规。API Key 是敏感凭据不要提交到 Git 仓库不要硬编码在公开项目中。如果涉及企业数据或用户隐私要提前做数据合规评估明确哪些数据可以发送到云端 API。不要把生成内容用于侵犯他人版权、肖像权或隐私的场景。如果你在企业内网配置了 API 网关证书相关配置只能在自有可控环境内操作不要在公网环境中关闭 TLS 校验。不建议使用非官方渠道或未经授权的 API 转发服务。若因业务需要接入第三方兼容网关必须先确认服务来源和授权边界。3. 环境准备与前置条件这一节给你一份通用检查清单。这里的每个版本号都是常见稳定版本实际以你项目需求为准。检查项要求与建议操作系统Windows / macOS / Linux 均可Python3.9 及以上推荐 3.10 或 3.11Node.js18 及以上安装 Claude Code 时需要包管理工具pip、npm 或 pnpmAPI Key从 Anthropic 控制台获取网络能访问 API 端点且没有被网关、防火墙拦截CA 证书如果走企业内网网关需要准备信任的自签名证书或内部 CA命令终端bash、zsh、PowerShell 均可3.1 获取 API KeyAPI Key 一般有两种短期密钥和长期密钥。开发环境建议使用长期密钥并设置好权限范围。拿到 Key 后优先写入环境变量而不是写死在代码里。Windows PowerShell$env:ANTHROPIC_API_KEYyour-api-keymacOS / Linuxexport ANTHROPIC_API_KEYyour-api-key如果你不想每次打开终端都重新设置可以写入~/.zshrc或~/.bashrc。3.2 安装官方 SDK官方 Python SDK 包名是anthropic安装命令如下pip install anthropic如果是 Node 项目可以用 npm 安装npm install anthropic-ai/sdk3.3 安装 Claude Code可选Claude Code 是 Anthropic 推出的命令行 AI 编程工具可以在终端里直接对话、改代码、执行任务。安装方式是通过 npmnpm install -g anthropic-ai/claude-code安装完成后先确认版本claude --version如果你是第一次使用运行claude会提示登录或设置 API Key。只要环境变量里已经有ANTHROPIC_API_KEY通常可以直接进入交互界面。3.4 配置 API Base URL网关场景在一些企业中API 不是直连官方端点而是通过内部网关转发。这时可以通过环境变量指定 Base URL例如export ANTHROPIC_BASE_URLhttps://your-gateway.example.comSDK 读取该环境变量后会把所有请求发到网关地址。注意不同 SDK 对base_url的读取方式可能不同建议查阅对应版本文档。在 Python SDK 中也可以在初始化客户端时直接指定client anthropic.Anthropic( api_keyyour-api-key, base_urlhttps://your-gateway.example.com )这属于合法的 API 网关配置方式前提是这个网关是你的业务自有环境并且已经获得服务方授权。3.5 证书准备如果你用自签名证书或内部 CA 签发证书Node.js 和 Python 默认会拒绝连接并抛出self-signed certificate类错误。解决办法不是盲目关闭校验而是把证书加入系统信任链或进程环境变量。Node.js 环境变量export NODE_EXTRA_CA_CERTS/path/to/your-ca.pemPython / curl 环境变量export SSL_CERT_FILE/path/to/your-ca.pem export CURL_CA_BUNDLE/path/to/your-ca.pem设置完成后重启终端进程再测试连接。只有本地开发调试、且明确风险可控时才考虑临时关闭 TLS 校验。4. 部署与启动方式4.1 第一个 Claude API 请求先用 Python 跑通最小请求。新建test_claude.pyimport anthropic client anthropic.Anthropic() message client.messages.create( modelclaude-sonnet-4-20250514, max_tokens1024, messages[ { role: user, content: 用一句话解释什么是 Prompt Eval。 } ] ) print(message.content)注意模型名要以你的账号实际可用模型为准不同时期的模型名称可能会调整。上面的模型名是示例运行前请到官方文档确认。4.2 流式输出流式响应可以让你看到 token 逐个生成的过程适合对话式应用import anthropic client anthropic.Anthropic() with client.messages.stream( modelclaude-sonnet-4-20250514, max_tokens1024, messages[ { role: user, content: 写一段问候语不超过20个字。 } ] ) as stream: for text in stream.text_stream: print(text, end, flushTrue)流式输出的好处是用户体验好、首字延迟低但代码里要处理中断和重连逻辑。4.3 多轮对话多轮对话的关键是正确维护messages列表把历史消息按顺序传给 APIimport anthropic client anthropic.Anthropic() messages [ {role: user, content: 你是一名 Prompt 评测助手。}, {role: assistant, content: 好的请提供需要评测的 Prompt。}, {role: user, content: 帮我写一个客服回复 Prompt。} ] response client.messages.create( modelclaude-sonnet-4-20250514, max_tokens1024, messagesmessages ) print(response.content)需要留意上下文长度。消息越多、历史越长token 消耗越大同时响应等待时间也可能增加。后续可以引入消息裁剪和摘要机制来控制成本。4.4 启动 Claude Code在安装好 Claude Code 后终端执行claude如果没有额外配置Claude Code 会读取ANTHROPIC_API_KEY。进入交互界面后你可以直接提需求也可以让它读取当前目录下的代码文件。启动过程中如果长时间卡在waiting for api response请先检查网络连通性、密钥是否正确以及 API 配额是否超限。5. 功能测试与效果验证5.1 基础对话测试测试目的确认 API 密钥有效、模型可用、网络链路正常。操作步骤运行最小请求脚本。观察是否正常返回文本。打印返回的stop_reason、usage字段确认请求完成。判断成功标准response.content非空且stop_reason为end_turn。如果返回max_tokens说明输出被截断需要调大max_tokens。常见失败原因API Key 无效、模型名错误、网络不可达、余额不足或配额超限。5.2 多轮对话测试测试目的验证上下文记忆与角色设定是否生效。操作步骤先用一条系统风格消息设定角色。连续传两轮用户输入。检查第二轮回答是否基于第一轮内容。判断成功标准第二轮回答能引用第一轮的上下文信息。如果每轮回答都“失忆”说明messages列表没有正确累积。5.3 Prompt Eval 评估测试Prompt Eval 的核心是建立评测集。一个评测集可以是一个 JSON 文件里面包含多组测试用例每组有输入和可选期望输出。例如[ { id: case-001, prompt: 把下面这句话改写为正式商务语气\n{input}, input: 你们东西坏了快点处理。, expected_keywords: [抱歉, 处理, 反馈] }, { id: case-002, prompt: 总结用户反馈提取3个关键问题。\n{input}, input: 设备连接不稳定软件闪退客服响应慢。, expected_keywords: [连接, 闪退, 客服] } ]评测时脚本逐个读取用例调用 Claude API 生成输出再检查输出是否包含期望关键词、是否满足字数限制、是否偏离主题。更完整的评测会引入“评分 Prompt”让模型为输出质量打 1 到 5 分。下面是一段通用的批量评测脚本模板需要按实际环境调整import json import anthropic client anthropic.Anthropic() eval_cases [ { id: case-001, user: 把下面这句话改写为正式商务语气\n你们东西坏了快点处理。, must_contain: [处理, 反馈] } ] results [] for case in eval_cases: try: response client.messages.create( modelclaude-sonnet-4-20250514, max_tokens512, messages[{role: user, content: case[user]}] ) output_text .join(block.text for block in response.content) missing [word for word in case[must_contain] if word not in output_text] passed len(missing) 0 results.append({ id: case[id], passed: passed, missing: missing, output: output_text[:100] }) except Exception as e: results.append({ id: case[id], passed: False, error: str(e) }) print(json.dumps(results, ensure_asciiFalse, indent2))判断成功标准批量用例全部返回无报错且passed数量达到预期。如果一个用例反复失败优先看 Prompt 是否给足约束再看max_tokens是否太小。5.4 从评测到运行评测通过后把 Prompt 抽成配置而不是散落在代码里。推荐使用 YAML 或 JSON 维护 Prompt 文件system_prompt: | 你是一名专业的客服质检助手。 你需要从用户反馈中提取问题、情绪和紧急程度。 user_template: | 用户反馈内容 {input} 请输出 JSON 格式结果。运行时读取配置import yaml import anthropic with open(prompt_config.yaml, r, encodingutf-8) as f: config yaml.safe_load(f) client anthropic.Anthropic() user_content config[user_template].format(input设备连接不稳定软件闪退。) response client.messages.create( modelclaude-sonnet-4-20250514, max_tokens512, messages[ {role: user, content: user_content} ] ) print(response.content)把 Prompt 配置化之后后续做 Prompt 版本更新时只需要改配置文件不需要动业务代码。6. 接口 API 与批量任务6.1 请求参数与返回结果调用 Messages API 时最核心的参数是参数说明model模型名称max_tokens最大输出 token 数messages对话消息列表system可选系统提示词temperature可选采样温度stream是否流式返回返回结果通常包含id、type、role、content、model、stop_reason和usage等字段。usage里会有输入和输出 token 数批量任务必须记录这些数据用来估算成本和排查异常。6.2 curl 调用示例如果你不在 SDK 环境里可以先用 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: claude-sonnet-4-20250514, max_tokens: 256, messages: [ { role: user, content: 用一句话说明 Prompt Eval 的作用。 } ] }这里的anthropic-version头是 API 版本兼容所必需的实际版本号需要参考官方文档。6.3 Python 批量任务批量任务建议设计成一个函数加一个结果收集器。函数负责单次调用结果收集器负责记录全量输出和失败信息。import json import time import anthropic client anthropic.Anthropic() def call_claude(user_content, max_tokens512, retries3): for attempt in range(retries): try: response client.messages.create( modelclaude-sonnet-4-20250514, max_tokensmax_tokens, messages[{role: user, content: user_content}] ) return .join(block.text for block in response.content) except Exception as e: print(fattempt {attempt 1} failed: {e}) time.sleep(2 ** attempt) return None tasks [ 任务一总结产品需求。, 任务二生成客服回复。, 任务三提取用户情绪。 ] results {} for idx, task in enumerate(tasks, start1): output call_claude(task) results[ftask_{idx}] output time.sleep(0.5) with open(batch_results.json, w, encodingutf-8) as f: json.dump(results, f, ensure_asciiFalse, indent2)批量任务要注意三个点限速控制。不控制并发的话容易触发 API 的速率限制导致 429。失败重试。建议采用指数退避比如首次失败后等 2 秒第二次等 4 秒第三次等 8 秒。结果落盘。不要在内存里保存全量结果边跑边写文件避免程序崩溃后丢失进度。6.4 评测集与批量任务结合Prompt Eval 本质上就是一种批量任务。把评测集文件作为输入把每条用例作为一个独立请求输出为 JSON 评测报告。这样可以做到可复现同一份评测集随时可以重跑。可对比不同 Prompt 版本跑同一份评测集对比passed率。可追溯评测报告里记录模型名、时间、token 消耗。7. 资源占用与性能观察既然 Claude API 是云端服务性能观察重点就不是 CPU 或显存而是以下几项。7.1 网络时延每次请求都会产生一个网络往返时间。通过日志记录请求开始时间和结束时间可以算出 P50 和 P95 时延。如果时延波动大优先检查网络链路和代理配置而不是盲目调模型参数。7.2 Token 消耗每次调用的usage字段会返回input_tokens和output_tokens。批量任务结束后统计总 token可以估算成本。如果一个 Prompt 每次都要传入大量历史消息token 消耗会线性增加。建议不要满屏塞上下文只保留必要的历史消息。7.3 并发与配额API 调用有速率和并发限制。脚本里建议用信号量控制并发数或者直接在两次请求之间加小间隔。如果遇到 429 或者ResourceExhausted表示触发了配额限制解决办法是降低并发、增加退避时间或者申请更高的配额。7.4 连接与超时长时间waiting for api response通常不是 API 本身卡住而是网络链路或代理问题。排查路径先用 curl 测试 API 能否正常响应。检查环境变量里是否有代理设置。检查 API Endpoint 是否可达。看官方状态页是否在维护。调大超时时间给长上下文任务留足时间。8. 常见问题与排查方法问题现象可能原因排查方式解决方案unable to connect to api: self-signed certificateAPI 网关使用自签名证书或系统信任链缺失检查 NODE_EXTRA_CA_CERTS、SSL_CERT_FILE 是否设置将网关证书加入系统信任链或配置正确的 CA 证书路径claude code waiting for api response网络不稳定、代理异常、密钥没配好、配额超限先跑最小 curl 请求再查看 Claude Code 日志确认密钥、检查代理、增加超时时间、降低并发authentication_errorAPI Key 无效或已过期检查环境变量中的密钥重新生成密钥并确认没有多余空格401 / 403权限不足或请求头缺少认证信息检查请求头是否包含x-api-key给客户端明确传入api_key不要依赖环境变量覆盖404模型名不存在或接口路径错误核对官方文档的模型名使用当前账号可用的模型 ID429请求频率超过限制查看响应中的速率限制字段降低并发、指数退避、扩展配额输出被max_tokens截断max_tokens设置过小检查stop_reason是否为max_tokens调大max_tokens或拆分成多步任务批量任务跑到一半中断网络闪断、进程被杀、超时查看运行日志确认断点位置设计“断点续跑”按 ID 跳过已完成任务Node 安装 Claude Code 失败npm 源或权限问题查看 npm 错误信息使用 nvm 管理 Node 版本或切换可配置的 registry 源8.1 自签名证书问题详细处理self-signed certificate的最核心问题是客户端不信任 API 端点使用的证书。处理顺序应该是获取网关的 CA 证书文件如internal_ca.pem。将证书加入系统信任链。通过环境变量让 Node.js 或 Python 使用额外 CA。重新启动进程。只有在本地调试、明确知道风险的前提下才考虑关闭 TLS 校验。生产环境必须使用受信任证书。8.2 Claude Code 等待响应问题当claude code停在waiting for api response先分三步走确认ANTHROPIC_API_KEY已正确设置。运行curl直接请求 API观察响应速度。查看 Claude Code 的输出日志定位是哪一次请求失败。如果单个请求约 5 秒内返回而 Claude Code 一直无响应疑似客户端与当前 Node 环境存在兼容问题可以升级 Node 版本并重装 Claude Code。9. 最佳实践与使用建议9.1 密钥安全管理API Key 用环境变量或密钥管理服务保存不要写进代码和配置仓库。如果是团队协作建议每个成员使用独立 Key方便审计和回收。9.2 评测集要持续维护Prompt Eval 的一次运行只是一次快照。好的评测集应该覆盖正反案例、边界场景和崩溃场景。每次修改 Prompt 后都跑同一套评测集观察passed率变化。如果后一次评测通过率比前一次低立刻回滚 Prompt。9.3 日志和监控接入 API 的应用至少要记录以下字段请求时间。模型名。输入 token 数和输出 token 数。响应耗时。状态码。错误详情。这些日志会成为后续排查问题和成本优化的基础。9.4 批量任务的健壮性批量任务必须考虑失败重试、结果持久化和断点续跑。不要在循环里直接sleep(1)就交给生产环境要加超时控制和错误分类。网络类错误可以做退避重试认证类错误直接停止。9.5 合规与授权不要把未经脱敏的用户数据直接发给 API。如果业务涉及第三方内容或人物肖像必须确认授权。企业环境使用 API 网关时要确保符合内部安全策略。9.6 成本控制给每个批量任务设置 token 预算。可以在脚本里加一个累计 token 计数器超过预算就停止后续请求。这样即使 Prompt 设计有问题也不会产生不可控费用。10. 总结与下一步这次的核心是把“Prompt Eval 到运行”这条链路完整走通。你首先应该做的是准备一个 Claude API Key跑通最小消息请求然后建一个 5 条用例左右的评测集写一个批量评测脚本最后把评测通过的 Prompt 抽成配置文件接到你的业务脚本或 Claude Code 中。最容易踩的坑是两个一是自签名证书导致 HTTPS 握手失败这类问题方向明确优先检查 CA 信任配置二是waiting for api response长时间不返回先确认网络、密钥和配额再做代码层面的超时调整。下一步可以继续扩展的方向很多把评测报告接入 CI在每次 Prompt 修改时自动触发评测把 Claude Code 接到具体项目的 issue 处理或代码审查流程或者把 API 调用封装成微服务对外提供统一的 Prompt 执行接口。认证备考不是终点能把一条评测到运行的流水线搭出来才真正具备架构层面的落地能力。