自学教程

Claude Agent SDK 性能调优

Claude Code 教程

简介

性能指标主要看两点：响应延迟、Token 成本。
性能瓶颈常见来源：

  1. 过长上下文，每次请求传输大量历史消息
  2. 不必要的多轮工具串行调用
  3. 并发控制不合理，频繁触发429限流
  4. System 提示词臃肿，占用大量输入token
  5. 子代理滥用，串行执行大量独立任务

调优目标：在保证Agent任务质量前提下，减少等待时间、降低token消耗，提升系统吞吐量。

前置准备

  1. Python3.10+ / Node.js18+
  2. SDK：anthropic / @anthropic-ai/sdk
  3. 监控工具：日志记录token耗时、Redis（并发限流）

一、提示词层面调优

1. 精简 System 提示词

System 在每一轮请求都会计入输入token，是持续开销。

  • 删除冗余描述、客套话，只保留角色、硬性规则、输出格式
  • 把参考文档、大段背景资料移出System，改用工具按需读取
  • 子代理使用轻量化System，子任务不需要全局完整规则

❌ 错误示例：把完整项目文档全部塞进system
✅ 正确示例：system只写规则，需要文档时调用read_file工具读取

2. 输出格式约束，减少冗余输出

在system强制固定输出结构（JSON/简短Markdown），减少模型自由发挥带来的输出token浪费，同时缩短生成时间。

输出要求：只返回JSON，禁止多余解释、前言、总结。

二、上下文（messages）调优【最高优先级】

上下文越长，请求耗时越高、token费用越高。

1. 上下文裁剪策略

  • 简单对话：保留最近N轮消息，丢弃最早历史
  • 长任务Agent：摘要压缩，定期把早期对话合并成一段摘要，替换原始消息，保留最近2~3轮完整对话（推荐用于长会话）

2. 过滤无用消息

工具调用场景：过滤掉无价值的工具返回（超长日志、重复文本），返回精简摘要给Agent。

不要把工具读取的完整大文件全部塞入messages，优先让Agent分段读取。

3. 结构化消息存储

只保留必要字段，不要把多余元数据存入messages数组，减少序列化体积。

三、工具调用流程优化

工具调用是最容易拖慢速度的环节，每一轮工具交互都要发起一次API请求。

  1. 减少工具调用轮次：在system中允许Agent一次性调用多个工具（并行工具调用），避免串行多次请求。
  2. 工具返回结果精简：工具拿到原始数据后，先做过滤摘要，再返回给Agent，不要返回原始超大文本。
  3. 限制最大工具循环次数：防止无限工具调用死循环，浪费token与时间。
【规则】最多连续调用工具3次，3次未解决任务直接返回结论。
  1. 区分工具适用场景：小信息直接内置，复杂文件/大数据才调用工具。

四、子代理并行调优

  1. 无依赖任务才并行；有依赖任务必须串行，不要强行并行。
  2. 控制并发上限：不要无限开启子代理，根据API Key的RPM设置并发池，防止429限流。

建议起步并发：2~5，根据实际RPM慢慢上调。

  1. 子代理输出摘要化：子代理不要返回完整长文本，输出精简结果给主代理汇总，降低主代理上下文压力。
  2. 一次性任务子代理：执行完成不持久化会话，节省存储和内存。

五、API 请求层面调优

1. 流式 vs 非流式选型

  • 面向用户交互（聊天、代码生成）：开启 stream=True，降低用户感知延迟
  • 后台批量任务、自动化脚本：关闭流式，减少事件解析开销，代码更简单

2. 请求超时配置

合理设置超时，避免请求长时间卡死占用连接资源

# Python
client = Anthropic(api_key=os.getenv("KEY"), timeout=20.0)

// TS
const anthropic = new Anthropic({apiKey: process.env.KEY, timeout: 20*1000})

3. 指数退避重试优化

重试只针对瞬时错误；重试次数控制在3次以内。

  • 读取 Retry-After 响应头，优先使用服务端建议等待时间
  • 不要增大重试次数，多次重试会大幅增加耗时与成本

六、并发与限流架构调优

  1. 双层限流：全局API Key总RPM + 租户独立RPM（多租户场景）
  2. 使用Redis做令牌桶/滑动窗口限流，削峰填谷
  3. 队列化任务：大量后台任务使用消息队列（MQ）异步排队，避免瞬间流量打满API配额

大批量文档解析、批量代码审查，放入任务队列，平缓消费

七、模型选型调优

根据任务选择合适模型，不要全部使用最高规格模型：

  • 复杂推理、代码重构、多工具任务：claude-3-5-sonnet
  • 简单摘要、分类、轻量文本提取：可选用轻量模型，降低成本与延迟

注意：模型切换前做业务验证，避免能力不满足需求。

八、监控指标（性能观测必备）

记录每一次SDK调用指标，方便定位瓶颈：

  1. 请求耗时（总耗时 / 模型生成耗时）
  2. input_tokens、output_tokens
  3. 工具调用次数
  4. 错误类型：429、5xx、超时占比
  5. 子代理数量

示例日志字段：

session_id,tenant_id,model,input_tokens,output_tokens,latency_ms,tool_call_count

基于指标定位：

  • 单次请求token持续暴涨 → 上下文过大，开启摘要压缩
  • 大量429错误 → 并发过高，降低并发池
  • 总耗时高但token不多 → 工具轮次太多，优化提示词减少工具调用

九、性能调优代码示例（Python 上下文摘要压缩）

import os
from anthropic import AsyncAnthropic

client = AsyncAnthropic(api_key=os.getenv("ANTHROPIC_API_KEY"))

async def compress_messages(messages: list):
    """将早期消息压缩为摘要，保留最近2轮原始消息"""
    if len(messages) <=4:
        return messages
    old_messages = messages[:-2]
    recent_messages = messages[-2:]
    prompt = f"将下面对话压缩成简短摘要，保留关键信息：\n{old_messages}"
    resp = await client.messages.create(
        model="claude-3-haiku-latest",
        max_tokens=512,
        messages=[{"role":"user","content":prompt}]
    )
    summary = resp.content[0].text
    # 替换历史为摘要
    new_messages = [{"role":"user","content":f"【历史对话摘要】：{summary}"}] + recent_messages
    return new_messages

十、常见性能坑

  1. 所有对话完整保留全部历史消息，上下文无限膨胀
  2. 工具每次返回完整超大文件内容，不做摘要过滤
  3. 大量串行工具调用，一轮一轮反复请求API
  4. 子代理无限制并发，频繁触发429限流，大量重试反而更慢
  5. System提示词堆砌大量无关参考资料，持续消耗输入token

最佳实践清单

✅ 优先优化上下文长度，这是投入产出比最高的调优手段
✅ 精简system提示词，移除非必要内容
✅ 优化工具调用逻辑，尽量合并多工具调用，减少API轮次
✅ 子代理输出摘要，减少主代理token压力
✅ 增加并发池控制，配合限流队列，防止429雪崩
✅ 埋点监控token、耗时、工具调用次数，量化调优效果
✅ 区分流式/非流式场景，合理选择请求模式

小结

Claude Agent SDK性能调优核心：控制上下文长度、减少工具调用轮次、合理管控并发。
优先优化上下文和提示词，收益最大；其次优化工具调用逻辑；多租户场景搭配限流与任务队列。同时做好指标监控，量化每次优化带来的延迟与token变化。

标签：

0 条笔记