之前准备 Claude 相关认证时发现很多同学卡在同一个地方Prompt 写得出来却不知道效果好不好效果看着不错又不知道怎么稳定地接到业务里跑起来。其实从“写 Prompt”到“跑 Prompt”之间缺的是一套可度量的工程链路。这篇文章围绕 Claude Certified Architect 的前置要求把 Claude API、Prompt Engineering、Eval评估、Running上线运行这条完整链路拆开讲清楚。如果你是正在准备认证、或者想把 Claude API 真正落地到项目的开发者这篇文章会比较适合你。1. 为什么说 Prompt、Eval、Running 是架构级前置条件1.1 从一次“看起来能用”的失误说起先看一个真实场景。很多人第一次写完 Prompt 调通 API 后会非常兴奋因为模型回答得又快又好。但一旦把同样的 Prompt 放到生产环境问题就来了用户输入稍微绕一点模型就开始“自由发挥”。返回格式偶尔不合法JSON 解析直接报错。高并发时大量请求超时重试策略写得不对直接把上游数据库打挂。Prompt 改了一个词线上效果瞬间下降却没人知道。这些问题的根因不是模型不够聪明而是整个流程缺少两个关键步骤Eval评估和工程化 Running运行。这也是 Claude 认证体系里把 API、Prompt、Eval 放在前置条件里的原因。1.2 三个概念的关系可以把这套链路理解为Prompt编写→ Eval评估→ Running运行Prompt Engineering提示工程把业务需求转成模型能理解、能稳定执行的指令。Eval评估用一批固定的测试样本量化判断 Prompt 效果是否达标防止“改坏”。Running运行把调优后的 Prompt 封装成可靠的服务处理错误、限流、日志、成本问题。一个人如果只掌握了 Prompt 编写那还是“提示词玩家”如果能把 Eval 和 Running 都做扎实才具备架构师级别的工程能力。认证考试和实际项目考察的恰恰是后者。1.3 本篇内容范围本篇会从 Claude API 基础调用开始然后讲清楚如何设计一个好的 Prompt再重点拆解 Eval 评估体系的搭建思路最后把评估通过的 Prompt 封装成可运行的服务。内容比较长建议收藏后按照章节逐步上手。2. 环境准备与 Claude API 基础调用2.1 环境清单在开始写代码之前先把运行环境准备好。以下是我的建议版本具体可以根据你的项目情况调整组件建议版本/说明操作系统Windows 10/11、macOS、Linux 均可Python3.10 及以上包管理工具pip 或 poetrySDKanthropic 官方 Python SDKIDEVS Code 或 PyCharmAPI Key在 Anthropic 官方控制台申请妥善保管安全提醒API Key 属于敏感凭证不要提交到 Git 仓库不要直接写死在代码里建议通过环境变量注入或使用密钥管理服务。2.2 安装 anthropic SDK在终端中执行pip install anthropic建议创建虚拟环境后再安装避免污染全局 Python 环境python -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate pip install anthropic2.3 第一个 Claude API 调用新建一个文件quickstart.py写入以下代码# quickstart.py import os from anthropic import Anthropic client Anthropic( api_keyos.environ.get(ANTHROPIC_API_KEY), ) response client.messages.create( model你的模型名称, # 请替换为官方文档中当前可用的模型名 max_tokens1024, messages[ { role: user, content: 请用一句话介绍你自己。 } ] ) print(response.content[0].text)运行前先配置环境变量export ANTHROPIC_API_KEYsk-ant-...Windows PowerShell 下使用$env:ANTHROPIC_API_KEYsk-ant-...然后运行python quickstart.py如果一切正常终端会输出模型生成的自我介绍文本。2.4 核心参数说明上面的代码中messages.create是最常用的接口几个参数含义如下model模型标识必须与官方文档一致不同时期可用的模型名会变化。max_tokens生成文本的最大长度单位是 token不是字符。超过这个长度会截断。messages对话消息数组按时间顺序排列。首条通常是用户消息。temperature控制随机性默认值通常合理取值范围 0 到 1。业务型任务建议调低到 0 或 0.3提高稳定性。system可选系统提示词用于设定角色和全局规则我会在下一节详细讲。先运行一次这个基础调用后不要急着写复杂的业务逻辑下一节先把 Prompt 写对。3. Prompt Engineering从“能用”到“稳定”3.1 System Prompt 与 User Prompt 的分工Claude API 的消息结构里有两种角色需要重点区分system系统级指令定义模型的身份、行为边界、输出规范。user用户实际输入的内容是每次请求中动态变化的部分。两者的核心区别是system 是“长期不变的规则”user 是“每次变化的输入”。把规则放在 system 里输入放在 user 里模型更容易理解你的意图。下面是一个典型示例import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) response client.messages.create( model你的模型名称, max_tokens512, system你是一个专业的客户反馈分类助手。 你的任务是将用户反馈分类为投诉、咨询、建议、表扬。 只输出 JSON不要输出其他内容。, messages[ { role: user, content: 你们的APP昨天闪退了三回严重影响我使用了。 } ] ) print(response.content[0].text)这条 Prompt 虽然简单但已经把“角色”“任务”“输出格式”都定义了。实际生产中Prompt 往往比这个复杂得多但结构不会变。3.2 一个高质量 Prompt 的五个要素结合 Claude API 的实际表现一个稳定的 Prompt 建议包含以下要素角色定义告诉模型“你是谁”例如“资深数据分析师”“客服主管”。任务描述一句话说清楚要做什么避免模糊动词。输入说明解释用户输入是什么有什么格式。输出约束指定返回格式例如 JSON、Markdown、纯文本。边界与兜底遇到无法处理的情况时怎么办比如“如果无法分类输出unknown”。我们可以把这些要素组合成一个模板角色你是一名严谨的客户反馈分类助手。 任务将用户反馈分类为以下四类之一投诉、咨询、建议、表扬。 约束 1. 只输出 JSON 对象不要输出多余文字。 2. JSON 结构为 {category: 类别, reason: 分类理由}。 3. 如果无法判断category 输出 unknown。 用户输入 {user_input}在代码中前面部分是 system{user_input}部分填充到 user 消息中。3.3 结构化输出让结果可被程序消费如果只是给人看模型输出什么文本都行。但一旦接入业务系统输出必须可解析。最常用的方案是要求模型输出 JSON。import json import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) response client.messages.create( model你的模型名称, max_tokens256, system( 你是客户反馈分类助手。 只输出 JSON结构为 {\category\: \投诉|咨询|建议|表扬|unknown\, \reason\: \理由\}。 ), messages[ {role: user, content: 你们的APP昨天闪退了三回严重影响我使用了。} ] ) text response.content[0].text.strip() print(模型原始输出, text) # 尝试解析为 JSON try: data json.loads(text) print(解析成功, data) except json.JSONDecodeError as e: print(解析失败, e)这里有一个实际踩过的坑模型偶尔会在 JSON 前后加反引号或说明文字导致json.loads失败。更稳妥的做法是加入“只输出 JSON”的强约束并在解析失败时做降级处理。这个降级逻辑可以理解为初级的“运行时容错”后面我会展开讲。3.4 温度参数与稳定性对于分类、抽取这类有确定答案的任务建议把temperature调低。温度越低输出越稳定但创造性也越弱。反之文案创作、头脑风暴等任务可以适当调高。业务场景下的经验参考值任务类型推荐 temperature分类、抽取、信息格式化0 ~ 0.3问答、摘要0.3 ~ 0.5文案、创意生成0.7 ~ 1.0调整方式是在messages.create中加入参数response client.messages.create( model你的模型名称, max_tokens256, temperature0.2, system..., messages[...] )需要注意的是temperature0并不代表每次输出完全一致只是随机性大幅降低。业务上不能依赖“完全相同”的假设。4. Eval给 Prompt 装上“质量仪表盘”4.1 为什么必须做 Eval很多人改 Prompt 靠感觉换一个词看一眼输出觉得不错就算完成。问题在于单次输出好不代表整体好。你可能只测了一个输入而线上有几百种输入模式。Eval 的核心思想是用一组固定且有代表性的测试数据跑一遍 Prompt用可量化的指标判断效果是否达标。这有点像软件工程里的单元测试和回归测试——保护你不把原来好用的 Prompt 改坏。4.2 构建评估数据集评估数据集不需要很大但要有代表性。以下面的“客户反馈分类”任务为例至少要覆盖明确的投诉正常的咨询委婉的建议真诚的表扬模糊的输入空内容或不可分类内容我建议用 Python 列表维护一个简单数据集# eval_dataset.py EVAL_CASES [ { input: 你们的APP昨天闪退了三回严重影响我使用了。, expected: 投诉, }, { input: 请问你们支持企业发票吗, expected: 咨询, }, { input: 希望你们能增加夜间模式对眼睛友好一些。, expected: 建议, }, { input: 这个功能太好用了已经推荐给同事, expected: 表扬, }, { input: 嗯……不太好说。, expected: unknown, }, { input: , # 空输入 expected: unknown, }, ]数据集的构建是有讲究的。选取标准不是“越多越好”而是覆盖真实业务中出现的高频分支和边界情况。可以基于线上日志抽一批真实输入再人工标注期望结果。4.3 评估指标设计对于分类任务最简单直观的指标是准确率Accuracy也就是“预测正确的条数 / 总条数”。更细致的场景还会用精确率、召回率、F1 值但第一篇可以先从准确率入手。除了准确性还要评估格式合法率模型输出能否被正确解析为 JSON。这个指标在生产中非常重要因为格式不合法直接导致程序报错。4.4 编写评估脚本下面是一个完整可运行的评估脚本# run_eval.py import json import os from anthropic import Anthropic from eval_dataset import EVAL_CASES client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) SYSTEM_PROMPT ( 你是客户反馈分类助手。 只输出 JSON结构为 {\category\: \投诉|咨询|建议|表扬|unknown\, \reason\: \理由\}。 ) def classify(text: str) - str: 调用 Claude API 对单条文本分类返回 category 字段。 response client.messages.create( model你的模型名称, max_tokens256, temperature0.2, systemSYSTEM_PROMPT, messages[{role: user, content: text}], ) raw_text response.content[0].text.strip() try: data json.loads(raw_text) return data.get(category, unknown) except json.JSONDecodeError: return parse_error def main(): total len(EVAL_CASES) correct 0 format_ok 0 for case in EVAL_CASES: user_input case[input] expected case[expected] predicted classify(user_input) if predicted expected: correct 1 if predicted ! parse_error: format_ok 1 print(f输入: {user_input!r}) print(f期望: {expected}, 实际: {predicted}) print(- * 40) accuracy correct / total * 100 format_rate format_ok / total * 100 print(f准确率: {accuracy:.1f}%) print(f格式合法率: {format_rate:.1f}%) if __name__ __main__: main()运行方式python run_eval.py预期会看到每条用例的预测结果和最后的汇总指标输入: 你们的APP昨天闪退了三回严重影响我使用了。 期望: 投诉, 实际: 投诉 ---------------------------------------- ... 准确率: 83.3% 格式合法率: 100.0%4.5 把 Eval 变成迭代工具Eval 的价值在于回归对比。每当你修改 Prompt就重新跑一遍评估脚本。如果准确率下降说明这次修改是回退如果上升说明改进有效。实际项目中我建议把数据集和评估脚本纳入 Git 管理。这样每次 Prompt 改动都能追溯和代码改动一样有记录。这个习惯比任何技巧都重要。5. 从 Eval 到 Running封装成可运行的服务评估通过后Prompt 还不能直接暴露给外部调用。缺少错误处理、重试、日志、限流的代码到生产环境一定会出问题。这里就是把“脚本”升级成“服务”的关键阶段。5.1 封装 API 客户端先把 Claude API 调用封装成一个独立模块方便复用和替换# claude_client.py import json import time import logging import os from typing import Optional from anthropic import Anthropic logger logging.getLogger(__name__) class ClaudeClassifier: 基于 Claude API 的客户反馈分类器。 SYSTEM_PROMPT ( 你是客户反馈分类助手。 只输出 JSON结构为 {\category\: \投诉|咨询|建议|表扬|unknown\, \reason\: \理由\}。 ) def __init__(self, api_key: Optional[str] None, max_retries: int 3): self.client Anthropic( api_keyapi_key or os.environ.get(ANTHROPIC_API_KEY) ) self.max_retries max_retries def classify(self, text: str) - dict: 对文本分类返回包含 category 和 reason 的字典。 payload self._build_messages(text) for attempt in range(1, self.max_retries 1): try: response self.client.messages.create(**payload) return self._parse_response(response) except Exception as e: logger.warning(第 %s 次调用失败: %s, attempt, e) if attempt self.max_retries: raise time.sleep(2 ** attempt) # 退避重试 def _build_messages(self, text: str) - dict: return { model: 你的模型名称, max_tokens: 256, temperature: 0.2, system: self.SYSTEM_PROMPT, messages: [{role: user, content: text}], } def _parse_response(self, response) - dict: raw_text response.content[0].text.strip() try: return json.loads(raw_text) except json.JSONDecodeError: return {category: unknown, reason: parse_error, raw: raw_text}这里有几个细节值得注意用logging记录失败信息方便追踪。用指数退避策略控制重试间隔避免雪崩。解析失败时返回降级结果而不是直接抛异常让上游崩溃。5.2 接入业务调用层封装完成后业务模块只需要调用一个看起来很普通的函数# service.py from claude_client import ClaudeClassifier classifier ClaudeClassifier() def handle_feedback(text: str) - dict: result classifier.classify(text) # 业务逻辑分支 if result.get(category) 投诉: result[priority] high elif result.get(category) unknown: result[priority] manual_review else: result[priority] normal return result这样做的好处是业务代码不感知 Prompt 细节也不感知 API 调用细节。未来换模型、改 Prompt、调整重试策略都只改claude_client.py一个文件。5.3 运行与验证写一个简单的测试入口# main.py from service import handle_feedback if __name__ __main__: samples [ 你们的东西质量太差了我要退货, 请问最近有什么优惠活动吗, 如果能支持离线模式就好了。, 客服态度非常好点赞, ] for s in samples: print(handle_feedback(s))运行后预期输出类似{category: 投诉, reason: 用户表达了对商品质量的不满并要求退货, priority: high} {category: 咨询, reason: 用户询问优惠活动信息, priority: normal} ...到这一步Prompt 已经从“一段文本”变成了“一个接口能力”。5.4 上线前的检查清单真正把服务发布到生产环境前建议逐项确认API Key 已通过环境变量或密钥管理注入未硬编码。评估脚本已在测试集上跑过准确率达到预期。重试和超时策略已配置。日志已接入统一的日志平台。对单用户或单 IP 有限流措施。成本预算已估算当前 Prompt 的平均 token 消耗符合预期。6. 常见问题与排查思路在整个 Prompt 到 Running 的链路中我遇到过很多报错。下面整理一份高频问题清单遇到类似现象可以直接对照排查。问题现象常见原因解决思路返回 401 鉴权失败API Key 错误或未正确注入检查环境变量是否配置、Key 是否有效返回 404 模型不存在model 参数填错或该模型名已停用查阅官方文档确认当前可用模型名返回 400 上下文长度超限messages 内容过长超过模型最大上下文对输入做截断摘要或使用更大的上下文模型返回 429 请求过密超过了账号的速率限制降低并发增加退避重试返回 529 服务过载服务端临时过载属于服务端问题退避重试不要立刻高频重发输出 JSON 解析失败Prompt 约束不够强模型输出多余内容强化“只输出 JSON”约束解析失败时降级分类结果不准数据集覆盖不足Prompt 描述不够清晰扩展评估集迭代 Prompt6.1 典型报错片段一上下文超出限制常见错误信息类似api error: 400 this models maximum context length is 1048576 tokens. however...意思是你的 messages 内容含历史对话超过了模型的最大上下文长度。解决思路对长文本做截断或摘要只保留关键部分。控制多轮对话历史长度超长时丢弃最早的消息。使用向量检索等方式把真正相关的片段拼进 Prompt。6.2 典型报错片段二529 服务过载错误信息api error: 529 overloaded. this is a server-side issue, usually temporary这是服务端临时过载不是你的代码问题。正确做法是退避重试比如第一次失败等 1 秒第二次等 2 秒第三次等 4 秒。不要并发轰炸式重试否则只会加重服务端压力。6.3 排查顺序建议如果你在开发过程中遇到了异常建议按这个顺序排查先看 API Key 是否有效。再看 model 参数是否与文档一致。然后看 messages 结构是否合法system/messages 字段是否正确。再检查输入长度是否超限。最后看是不是限流或服务端过载。大多数问题都可以通过这五步定位。7. 最佳实践与工程建议7.1 Prompt 版本管理把 Prompt 当成代码来管理。每次修改都记录变更原因并用之前的 Eval 数据集做回归验证。我习惯把不同版本的 Prompt 存入独立的 Python 常量或配置文件例如PROMPT_V1 ... PROMPT_V2 ...配合 Git 的提交记录可以随时回滚到历史版本。7.2 Eval 融入持续集成在团队协作中可以把 Eval 脚本接入 CI 流水线。每次 Prompt 或代码变更自动跑一遍评估集阻断明显回退。这能有效防止“改 A 破坏 B”的问题。7.3 安全与权限边界Claude API 调用属于外部依赖需要遵守最小权限原则API Key 只授予必要的服务角色。不要把 API Key 放到前端代码。对用户输入做基本的内容安全过滤不把敏感明文传给第三方接口。日志中不要记录完整 Prompt 和响应避免敏感信息外泄。7.4 成本控制API 调用是按 token 计费的成本控制的核心是两个方向减少不必要的 token 消耗精简 Prompt避免塞入大段无关内容。增加缓存层相同或高度相似的输入可以复用之前的分类结果减少重复调用。7.5 可维护性设计建议为每个调用场景建立独立的模块并保持接口简单。不要在一个函数里既处理 Prompt 拼接又处理 HTTP 重试又处理业务逻辑。关注点分离后后续迭代会轻松很多。8. 总结与下一步学习方向到这一步你已经掌握了一条完整的链路用 Claude API 发出第一次请求设计结构化的 Prompt用 Eval 评估 Prompt 效果最后把通过评估的 Prompt 封装成可靠的服务跑起来。这也是 Claude Certified Architect 前置要求中最核心的工程能力。接下来可以往几个方向继续深入尝试把单轮分类改成多轮对话理解 Claude API 的 messages 历史管理。研究更复杂的 Agent 场景了解 Claude Code 这类工具如何把 Prompt 变成可执行的任务循环。在 Eval 数据集中增加更多指标例如精确率、召回率、成本统计。尝试把 Prompt 模板与业务配置系统结合实现产品化配置不修改代码即可调整提示词。建议花一个下午的时间把自己手头的一个真实业务场景完整走一遍 Prompt → Eval → Running 的流程。遇到报错不要慌对照本文的排查表逐项检查你会比上一次更快地定位问题。如果这篇文章对你有帮助可以收藏备用后续系列文章会继续深入每个环节的进阶玩法。
从Prompt到Eval再到Running：Claude API工程化落地指南
之前准备 Claude 相关认证时发现很多同学卡在同一个地方Prompt 写得出来却不知道效果好不好效果看着不错又不知道怎么稳定地接到业务里跑起来。其实从“写 Prompt”到“跑 Prompt”之间缺的是一套可度量的工程链路。这篇文章围绕 Claude Certified Architect 的前置要求把 Claude API、Prompt Engineering、Eval评估、Running上线运行这条完整链路拆开讲清楚。如果你是正在准备认证、或者想把 Claude API 真正落地到项目的开发者这篇文章会比较适合你。1. 为什么说 Prompt、Eval、Running 是架构级前置条件1.1 从一次“看起来能用”的失误说起先看一个真实场景。很多人第一次写完 Prompt 调通 API 后会非常兴奋因为模型回答得又快又好。但一旦把同样的 Prompt 放到生产环境问题就来了用户输入稍微绕一点模型就开始“自由发挥”。返回格式偶尔不合法JSON 解析直接报错。高并发时大量请求超时重试策略写得不对直接把上游数据库打挂。Prompt 改了一个词线上效果瞬间下降却没人知道。这些问题的根因不是模型不够聪明而是整个流程缺少两个关键步骤Eval评估和工程化 Running运行。这也是 Claude 认证体系里把 API、Prompt、Eval 放在前置条件里的原因。1.2 三个概念的关系可以把这套链路理解为Prompt编写→ Eval评估→ Running运行Prompt Engineering提示工程把业务需求转成模型能理解、能稳定执行的指令。Eval评估用一批固定的测试样本量化判断 Prompt 效果是否达标防止“改坏”。Running运行把调优后的 Prompt 封装成可靠的服务处理错误、限流、日志、成本问题。一个人如果只掌握了 Prompt 编写那还是“提示词玩家”如果能把 Eval 和 Running 都做扎实才具备架构师级别的工程能力。认证考试和实际项目考察的恰恰是后者。1.3 本篇内容范围本篇会从 Claude API 基础调用开始然后讲清楚如何设计一个好的 Prompt再重点拆解 Eval 评估体系的搭建思路最后把评估通过的 Prompt 封装成可运行的服务。内容比较长建议收藏后按照章节逐步上手。2. 环境准备与 Claude API 基础调用2.1 环境清单在开始写代码之前先把运行环境准备好。以下是我的建议版本具体可以根据你的项目情况调整组件建议版本/说明操作系统Windows 10/11、macOS、Linux 均可Python3.10 及以上包管理工具pip 或 poetrySDKanthropic 官方 Python SDKIDEVS Code 或 PyCharmAPI Key在 Anthropic 官方控制台申请妥善保管安全提醒API Key 属于敏感凭证不要提交到 Git 仓库不要直接写死在代码里建议通过环境变量注入或使用密钥管理服务。2.2 安装 anthropic SDK在终端中执行pip install anthropic建议创建虚拟环境后再安装避免污染全局 Python 环境python -m venv venv source venv/bin/activate # Windows 使用 venv\Scripts\activate pip install anthropic2.3 第一个 Claude API 调用新建一个文件quickstart.py写入以下代码# quickstart.py import os from anthropic import Anthropic client Anthropic( api_keyos.environ.get(ANTHROPIC_API_KEY), ) response client.messages.create( model你的模型名称, # 请替换为官方文档中当前可用的模型名 max_tokens1024, messages[ { role: user, content: 请用一句话介绍你自己。 } ] ) print(response.content[0].text)运行前先配置环境变量export ANTHROPIC_API_KEYsk-ant-...Windows PowerShell 下使用$env:ANTHROPIC_API_KEYsk-ant-...然后运行python quickstart.py如果一切正常终端会输出模型生成的自我介绍文本。2.4 核心参数说明上面的代码中messages.create是最常用的接口几个参数含义如下model模型标识必须与官方文档一致不同时期可用的模型名会变化。max_tokens生成文本的最大长度单位是 token不是字符。超过这个长度会截断。messages对话消息数组按时间顺序排列。首条通常是用户消息。temperature控制随机性默认值通常合理取值范围 0 到 1。业务型任务建议调低到 0 或 0.3提高稳定性。system可选系统提示词用于设定角色和全局规则我会在下一节详细讲。先运行一次这个基础调用后不要急着写复杂的业务逻辑下一节先把 Prompt 写对。3. Prompt Engineering从“能用”到“稳定”3.1 System Prompt 与 User Prompt 的分工Claude API 的消息结构里有两种角色需要重点区分system系统级指令定义模型的身份、行为边界、输出规范。user用户实际输入的内容是每次请求中动态变化的部分。两者的核心区别是system 是“长期不变的规则”user 是“每次变化的输入”。把规则放在 system 里输入放在 user 里模型更容易理解你的意图。下面是一个典型示例import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) response client.messages.create( model你的模型名称, max_tokens512, system你是一个专业的客户反馈分类助手。 你的任务是将用户反馈分类为投诉、咨询、建议、表扬。 只输出 JSON不要输出其他内容。, messages[ { role: user, content: 你们的APP昨天闪退了三回严重影响我使用了。 } ] ) print(response.content[0].text)这条 Prompt 虽然简单但已经把“角色”“任务”“输出格式”都定义了。实际生产中Prompt 往往比这个复杂得多但结构不会变。3.2 一个高质量 Prompt 的五个要素结合 Claude API 的实际表现一个稳定的 Prompt 建议包含以下要素角色定义告诉模型“你是谁”例如“资深数据分析师”“客服主管”。任务描述一句话说清楚要做什么避免模糊动词。输入说明解释用户输入是什么有什么格式。输出约束指定返回格式例如 JSON、Markdown、纯文本。边界与兜底遇到无法处理的情况时怎么办比如“如果无法分类输出unknown”。我们可以把这些要素组合成一个模板角色你是一名严谨的客户反馈分类助手。 任务将用户反馈分类为以下四类之一投诉、咨询、建议、表扬。 约束 1. 只输出 JSON 对象不要输出多余文字。 2. JSON 结构为 {category: 类别, reason: 分类理由}。 3. 如果无法判断category 输出 unknown。 用户输入 {user_input}在代码中前面部分是 system{user_input}部分填充到 user 消息中。3.3 结构化输出让结果可被程序消费如果只是给人看模型输出什么文本都行。但一旦接入业务系统输出必须可解析。最常用的方案是要求模型输出 JSON。import json import os from anthropic import Anthropic client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) response client.messages.create( model你的模型名称, max_tokens256, system( 你是客户反馈分类助手。 只输出 JSON结构为 {\category\: \投诉|咨询|建议|表扬|unknown\, \reason\: \理由\}。 ), messages[ {role: user, content: 你们的APP昨天闪退了三回严重影响我使用了。} ] ) text response.content[0].text.strip() print(模型原始输出, text) # 尝试解析为 JSON try: data json.loads(text) print(解析成功, data) except json.JSONDecodeError as e: print(解析失败, e)这里有一个实际踩过的坑模型偶尔会在 JSON 前后加反引号或说明文字导致json.loads失败。更稳妥的做法是加入“只输出 JSON”的强约束并在解析失败时做降级处理。这个降级逻辑可以理解为初级的“运行时容错”后面我会展开讲。3.4 温度参数与稳定性对于分类、抽取这类有确定答案的任务建议把temperature调低。温度越低输出越稳定但创造性也越弱。反之文案创作、头脑风暴等任务可以适当调高。业务场景下的经验参考值任务类型推荐 temperature分类、抽取、信息格式化0 ~ 0.3问答、摘要0.3 ~ 0.5文案、创意生成0.7 ~ 1.0调整方式是在messages.create中加入参数response client.messages.create( model你的模型名称, max_tokens256, temperature0.2, system..., messages[...] )需要注意的是temperature0并不代表每次输出完全一致只是随机性大幅降低。业务上不能依赖“完全相同”的假设。4. Eval给 Prompt 装上“质量仪表盘”4.1 为什么必须做 Eval很多人改 Prompt 靠感觉换一个词看一眼输出觉得不错就算完成。问题在于单次输出好不代表整体好。你可能只测了一个输入而线上有几百种输入模式。Eval 的核心思想是用一组固定且有代表性的测试数据跑一遍 Prompt用可量化的指标判断效果是否达标。这有点像软件工程里的单元测试和回归测试——保护你不把原来好用的 Prompt 改坏。4.2 构建评估数据集评估数据集不需要很大但要有代表性。以下面的“客户反馈分类”任务为例至少要覆盖明确的投诉正常的咨询委婉的建议真诚的表扬模糊的输入空内容或不可分类内容我建议用 Python 列表维护一个简单数据集# eval_dataset.py EVAL_CASES [ { input: 你们的APP昨天闪退了三回严重影响我使用了。, expected: 投诉, }, { input: 请问你们支持企业发票吗, expected: 咨询, }, { input: 希望你们能增加夜间模式对眼睛友好一些。, expected: 建议, }, { input: 这个功能太好用了已经推荐给同事, expected: 表扬, }, { input: 嗯……不太好说。, expected: unknown, }, { input: , # 空输入 expected: unknown, }, ]数据集的构建是有讲究的。选取标准不是“越多越好”而是覆盖真实业务中出现的高频分支和边界情况。可以基于线上日志抽一批真实输入再人工标注期望结果。4.3 评估指标设计对于分类任务最简单直观的指标是准确率Accuracy也就是“预测正确的条数 / 总条数”。更细致的场景还会用精确率、召回率、F1 值但第一篇可以先从准确率入手。除了准确性还要评估格式合法率模型输出能否被正确解析为 JSON。这个指标在生产中非常重要因为格式不合法直接导致程序报错。4.4 编写评估脚本下面是一个完整可运行的评估脚本# run_eval.py import json import os from anthropic import Anthropic from eval_dataset import EVAL_CASES client Anthropic(api_keyos.environ.get(ANTHROPIC_API_KEY)) SYSTEM_PROMPT ( 你是客户反馈分类助手。 只输出 JSON结构为 {\category\: \投诉|咨询|建议|表扬|unknown\, \reason\: \理由\}。 ) def classify(text: str) - str: 调用 Claude API 对单条文本分类返回 category 字段。 response client.messages.create( model你的模型名称, max_tokens256, temperature0.2, systemSYSTEM_PROMPT, messages[{role: user, content: text}], ) raw_text response.content[0].text.strip() try: data json.loads(raw_text) return data.get(category, unknown) except json.JSONDecodeError: return parse_error def main(): total len(EVAL_CASES) correct 0 format_ok 0 for case in EVAL_CASES: user_input case[input] expected case[expected] predicted classify(user_input) if predicted expected: correct 1 if predicted ! parse_error: format_ok 1 print(f输入: {user_input!r}) print(f期望: {expected}, 实际: {predicted}) print(- * 40) accuracy correct / total * 100 format_rate format_ok / total * 100 print(f准确率: {accuracy:.1f}%) print(f格式合法率: {format_rate:.1f}%) if __name__ __main__: main()运行方式python run_eval.py预期会看到每条用例的预测结果和最后的汇总指标输入: 你们的APP昨天闪退了三回严重影响我使用了。 期望: 投诉, 实际: 投诉 ---------------------------------------- ... 准确率: 83.3% 格式合法率: 100.0%4.5 把 Eval 变成迭代工具Eval 的价值在于回归对比。每当你修改 Prompt就重新跑一遍评估脚本。如果准确率下降说明这次修改是回退如果上升说明改进有效。实际项目中我建议把数据集和评估脚本纳入 Git 管理。这样每次 Prompt 改动都能追溯和代码改动一样有记录。这个习惯比任何技巧都重要。5. 从 Eval 到 Running封装成可运行的服务评估通过后Prompt 还不能直接暴露给外部调用。缺少错误处理、重试、日志、限流的代码到生产环境一定会出问题。这里就是把“脚本”升级成“服务”的关键阶段。5.1 封装 API 客户端先把 Claude API 调用封装成一个独立模块方便复用和替换# claude_client.py import json import time import logging import os from typing import Optional from anthropic import Anthropic logger logging.getLogger(__name__) class ClaudeClassifier: 基于 Claude API 的客户反馈分类器。 SYSTEM_PROMPT ( 你是客户反馈分类助手。 只输出 JSON结构为 {\category\: \投诉|咨询|建议|表扬|unknown\, \reason\: \理由\}。 ) def __init__(self, api_key: Optional[str] None, max_retries: int 3): self.client Anthropic( api_keyapi_key or os.environ.get(ANTHROPIC_API_KEY) ) self.max_retries max_retries def classify(self, text: str) - dict: 对文本分类返回包含 category 和 reason 的字典。 payload self._build_messages(text) for attempt in range(1, self.max_retries 1): try: response self.client.messages.create(**payload) return self._parse_response(response) except Exception as e: logger.warning(第 %s 次调用失败: %s, attempt, e) if attempt self.max_retries: raise time.sleep(2 ** attempt) # 退避重试 def _build_messages(self, text: str) - dict: return { model: 你的模型名称, max_tokens: 256, temperature: 0.2, system: self.SYSTEM_PROMPT, messages: [{role: user, content: text}], } def _parse_response(self, response) - dict: raw_text response.content[0].text.strip() try: return json.loads(raw_text) except json.JSONDecodeError: return {category: unknown, reason: parse_error, raw: raw_text}这里有几个细节值得注意用logging记录失败信息方便追踪。用指数退避策略控制重试间隔避免雪崩。解析失败时返回降级结果而不是直接抛异常让上游崩溃。5.2 接入业务调用层封装完成后业务模块只需要调用一个看起来很普通的函数# service.py from claude_client import ClaudeClassifier classifier ClaudeClassifier() def handle_feedback(text: str) - dict: result classifier.classify(text) # 业务逻辑分支 if result.get(category) 投诉: result[priority] high elif result.get(category) unknown: result[priority] manual_review else: result[priority] normal return result这样做的好处是业务代码不感知 Prompt 细节也不感知 API 调用细节。未来换模型、改 Prompt、调整重试策略都只改claude_client.py一个文件。5.3 运行与验证写一个简单的测试入口# main.py from service import handle_feedback if __name__ __main__: samples [ 你们的东西质量太差了我要退货, 请问最近有什么优惠活动吗, 如果能支持离线模式就好了。, 客服态度非常好点赞, ] for s in samples: print(handle_feedback(s))运行后预期输出类似{category: 投诉, reason: 用户表达了对商品质量的不满并要求退货, priority: high} {category: 咨询, reason: 用户询问优惠活动信息, priority: normal} ...到这一步Prompt 已经从“一段文本”变成了“一个接口能力”。5.4 上线前的检查清单真正把服务发布到生产环境前建议逐项确认API Key 已通过环境变量或密钥管理注入未硬编码。评估脚本已在测试集上跑过准确率达到预期。重试和超时策略已配置。日志已接入统一的日志平台。对单用户或单 IP 有限流措施。成本预算已估算当前 Prompt 的平均 token 消耗符合预期。6. 常见问题与排查思路在整个 Prompt 到 Running 的链路中我遇到过很多报错。下面整理一份高频问题清单遇到类似现象可以直接对照排查。问题现象常见原因解决思路返回 401 鉴权失败API Key 错误或未正确注入检查环境变量是否配置、Key 是否有效返回 404 模型不存在model 参数填错或该模型名已停用查阅官方文档确认当前可用模型名返回 400 上下文长度超限messages 内容过长超过模型最大上下文对输入做截断摘要或使用更大的上下文模型返回 429 请求过密超过了账号的速率限制降低并发增加退避重试返回 529 服务过载服务端临时过载属于服务端问题退避重试不要立刻高频重发输出 JSON 解析失败Prompt 约束不够强模型输出多余内容强化“只输出 JSON”约束解析失败时降级分类结果不准数据集覆盖不足Prompt 描述不够清晰扩展评估集迭代 Prompt6.1 典型报错片段一上下文超出限制常见错误信息类似api error: 400 this models maximum context length is 1048576 tokens. however...意思是你的 messages 内容含历史对话超过了模型的最大上下文长度。解决思路对长文本做截断或摘要只保留关键部分。控制多轮对话历史长度超长时丢弃最早的消息。使用向量检索等方式把真正相关的片段拼进 Prompt。6.2 典型报错片段二529 服务过载错误信息api error: 529 overloaded. this is a server-side issue, usually temporary这是服务端临时过载不是你的代码问题。正确做法是退避重试比如第一次失败等 1 秒第二次等 2 秒第三次等 4 秒。不要并发轰炸式重试否则只会加重服务端压力。6.3 排查顺序建议如果你在开发过程中遇到了异常建议按这个顺序排查先看 API Key 是否有效。再看 model 参数是否与文档一致。然后看 messages 结构是否合法system/messages 字段是否正确。再检查输入长度是否超限。最后看是不是限流或服务端过载。大多数问题都可以通过这五步定位。7. 最佳实践与工程建议7.1 Prompt 版本管理把 Prompt 当成代码来管理。每次修改都记录变更原因并用之前的 Eval 数据集做回归验证。我习惯把不同版本的 Prompt 存入独立的 Python 常量或配置文件例如PROMPT_V1 ... PROMPT_V2 ...配合 Git 的提交记录可以随时回滚到历史版本。7.2 Eval 融入持续集成在团队协作中可以把 Eval 脚本接入 CI 流水线。每次 Prompt 或代码变更自动跑一遍评估集阻断明显回退。这能有效防止“改 A 破坏 B”的问题。7.3 安全与权限边界Claude API 调用属于外部依赖需要遵守最小权限原则API Key 只授予必要的服务角色。不要把 API Key 放到前端代码。对用户输入做基本的内容安全过滤不把敏感明文传给第三方接口。日志中不要记录完整 Prompt 和响应避免敏感信息外泄。7.4 成本控制API 调用是按 token 计费的成本控制的核心是两个方向减少不必要的 token 消耗精简 Prompt避免塞入大段无关内容。增加缓存层相同或高度相似的输入可以复用之前的分类结果减少重复调用。7.5 可维护性设计建议为每个调用场景建立独立的模块并保持接口简单。不要在一个函数里既处理 Prompt 拼接又处理 HTTP 重试又处理业务逻辑。关注点分离后后续迭代会轻松很多。8. 总结与下一步学习方向到这一步你已经掌握了一条完整的链路用 Claude API 发出第一次请求设计结构化的 Prompt用 Eval 评估 Prompt 效果最后把通过评估的 Prompt 封装成可靠的服务跑起来。这也是 Claude Certified Architect 前置要求中最核心的工程能力。接下来可以往几个方向继续深入尝试把单轮分类改成多轮对话理解 Claude API 的 messages 历史管理。研究更复杂的 Agent 场景了解 Claude Code 这类工具如何把 Prompt 变成可执行的任务循环。在 Eval 数据集中增加更多指标例如精确率、召回率、成本统计。尝试把 Prompt 模板与业务配置系统结合实现产品化配置不修改代码即可调整提示词。建议花一个下午的时间把自己手头的一个真实业务场景完整走一遍 Prompt → Eval → Running 的流程。遇到报错不要慌对照本文的排查表逐项检查你会比上一次更快地定位问题。如果这篇文章对你有帮助可以收藏备用后续系列文章会继续深入每个环节的进阶玩法。