LangChain.js 如何为 Anthropic 模型启用 anthropicPromptCachingMiddleware 配置 prompt caching【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs在 LangChain.js 中用createAgent构建基于 Anthropic 模型的 Agent 时重复的 system prompt、长系统消息或多轮对话历史会在每次请求中重复计费。langchain包内置的anthropicPromptCachingMiddleware可以解决这个问题它拦截模型请求在满足条件时自动为请求附加cache_control元数据让 Anthropic API 缓存已处理的 prompt 前缀后续相同前缀的请求直接复用。本文基于仓库源码、内置测试和官方示例说明如何启用这个中间件、如何配置参数以及如何验证缓存确实生效。以下内容对应当前仓库中langchain包版本 1.5.11的实现。前提条件你的 Agent 使用 Anthropic 模型。模型可以是ChatAnthropic实例也可以是形如anthropic:claude-sonnet-4-20250514的字符串字符串形式会创建ConfigurableModel中间件通过其modelProvider anthropic判断是否为 Anthropic 模型见 promptCaching.ts 第 196-224 行。需要createAgent与anthropicPromptCachingMiddleware两者都从langchain包导出middleware 汇总导出包入口见 index.ts。基本用法在 createAgent 中挂上中间件最短可行路径就是仓库示例 promptCaching.ts 的做法import { createAgent, HumanMessage, AIMessage } from langchain; import { anthropicPromptCachingMiddleware } from langchain; const agent createAgent({ model: anthropic:claude-sonnet-4-20250514, tools: [], middleware: [anthropicPromptCachingMiddleware({ ttl: 5m })], }); const result await agent.invoke({ messages: [/* 传入多轮对话消息 */], }); console.log(\nAgent response:, result.messages.at(-1)?.content);不传任何参数时anthropicPromptCachingMiddleware()也可用全部走默认值。源码 JSDoc 中给出的默认参数示例promptCaching.ts 第 78-90 行const agent createAgent({ model: anthropic:claude-sonnet-4-5, middleware: [ anthropicPromptCachingMiddleware() ] });配置参数与默认值中间件接受PromptCachingMiddlewareConfig类型同样从langchain导出四个选项及默认值定义在 promptCaching.ts 的contextSchema与默认常量中选项类型默认值用途enableCachingbooleantrue是否启用 prompt cachingttl5m|1h5m缓存有效期。按 Anthropic API 只支持这两个值minMessagesToCachenumber3消息数达到该值后才应用缓存unsupportedModelBehaviorignore|warn|raisewarn传入非 Anthropic 模型时的行为两个判断点直接影响缓存是否生效消息数阈值中间件统计request.state.messages.length (request.systemPrompt ? 1 : 0)即 system prompt 会被计为 1 条消息。总数低于minMessagesToCache时直接跳过、不附加缓存元数据。单元测试 promptCaching.test.ts 的 should include system message in message count 用例验证了这一点minMessagesToCache: 3、2 条用户消息加 1 条 system prompt 时缓存正常附加。参数优先级运行时上下文 中间件配置项 默认值源码注释 Prefer runtime context values over middleware options values over defaults。长 system prompt 的场景可以按需调整JSDoc 给出的客服机器人示例promptCaching.ts 第 131-152 行const supportAgent createAgent({ model: anthropic:claude-sonnet-4-5, systemPrompt: You are a customer support agent for ACME Corp. ..., tools: [searchKnowledgeBase, createTicket, checkOrderStatus], middleware: [ anthropicPromptCachingMiddleware({ ttl: 1h, // Long TTL for stable system prompt minMessagesToCache: 1 // Cache immediately due to large system prompt }) ] });在运行时关闭某次请求的缓存中间件支持按单次invoke覆盖配置。JSDoc 文档示例promptCaching.ts 第 107-129 行的写法await agent.invoke( { messages: [new HumanMessage(Process this without caching)] }, { configurable: { middleware_context: { enableCaching: false } } } );需要注意仓库单元测试 promptCaching.test.ts 中 should allow runtime context override 用例实际使用的写法是{ context: { enableCaching: false } }两处形式不一致。以你所使用版本的langchain实际行为为准该用例验证的效果是覆盖后bindTools的选项里不再包含cache_control。验证缓存生效仓库提供了两个层次的验证方式均来自实际测试代码。1. 检查发往 Anthropic 的请求体。集成测试 promptCaching.int.test.ts 通过 mock fetch 拦截真实请求断言最后一条消息的内容块包含缓存元数据expect(requestBody.messages.at(-1).content[0]).toEqual({ type: text, text: expect.stringContaining(What is the capital of France?), cache_control: { type: ephemeral, ttl: 5m, }, });同时该测试用一段很长的测试消息调用anthropic:claude-opus-4-20250514并在原始响应中检查usage.cache_read_input_tokens || usage.cache_creation_input_tokens是否大于 0。测试对该段特定长文本断言的值在 1200 到 1400 之间测试注释说明同一测试短时间内重复运行时 token 可能已处于缓存状态因此读/写两个桶都可能命中。这个数值范围只适用于该测试的特定提示词不能作为你自己应用的通用判定阈值。2. 单元层面检查bindTools的选项。单元测试用 mock 模型验证消息数达到minMessagesToCache时bindTools被调用且选项中包含cache_control: { type: ephemeral, ttl: 5m }消息数低于阈值、或enableCaching: false时bindTools选项中不含cache_control中间件不直接改写消息内容——最后一条消息的content仍是原始字符串。源码注释说明cache_control由ChatAnthropic在最终消息格式化层应用以避免流式响应重组等早期阶段对消息内容块的改动产生问题。计费说明来自源码 JSDoc 的 remarks缓存命中的 token 按基础 input token 价格的 10% 计费缓存写入按 25% 计费缓存按 API key 隔离不能跨 key 共享。排查与限制模型必须是 Anthropic。默认unsupportedModelBehavior: warn时使用其他供应商模型会在控制台输出警告PromptCachingMiddleware: Skipping caching for ${modelName}. Consider switching to an Anthropic model for caching benefits.并继续不启用缓存ignore时静默跳过raise时抛出PromptCachingMiddlewareError报错形如Unsupported model ConfigurableModel (openai). Prompt caching requires an Anthropic model (e.g., anthropic:claude-4-0-sonnet).均为 promptCaching.ts 中的实际字符串。TTL 只有5m与1h两个合法值由z.enum([5m, 1h])约束其他值不合法。未超过minMessagesToCache的请求不会附加缓存元数据这是设计行为而非 bug短对话前几轮请求不会命中缓存。仓库 CHANGELOG1.4.6 节记录后来新增的bedrockPromptCachingMiddleware接口与anthropicPromptCachingMiddleware基本一致如果你需要为 Bedrock Converse 模型启用缓存可以查看该中间件本文不再展开。仓库docs/core_docs/README.md已声明核心文档迁移到外部文档站点本仓库内的实现说明以源码 JSDoc、测试和示例为准。参考文件实现anthropicPromptCachingMiddleware可运行示例examples/src/createAgent/middleware/promptCaching.ts单元测试promptCaching.test.ts集成测试promptCaching.int.test.ts【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考