全部文章

LangChain4j 提示词缓存,调用成本砍九成

会编程的吕洞宾约 26 分钟

摘要: 在 Java 里用 LangChain4j 给 Anthropic 模型开启提示词缓存,让重复的系统提示词和工具定义不再每次重新计费。本文讲清缓存原理,用 cacheSystemMessages、cacheTools、cacheAutomatically 三个开关落地,附完整可运行代码和 token 账单实测。

你写了个客服机器人:一段两千字的系统提示词,外加二十个工具定义,用户每问一句,这堆东西就原封不动重发一遍。用户问十句,它就发十遍,每遍都按输入 token 计费。对话越长、工具越多,账单涨得越快,首字响应也一直慢。最冤的是,这段前缀每次一模一样,模型却每次都在从头算。LangChain4j 给 Anthropic 模型接上了提示词缓存,开几个开关就能让服务端把这段前缀记下来复用,重复部分的输入价格能掉到约十分之一。

一、这个问题到底是什么

大模型的账单按 token 算,而且是每发一次请求,就要把所有上下文从头到尾重新算一遍。

token 是模型处理文本的最小单位。一个英文单词大约一到两个 token,一个汉字通常一到两个 token。你发过去的每一段文字——系统提示词、工具说明书、历史对话、用户这一句提问——都要先被读进去,这部分叫输入 token;模型吐回来的回答叫输出 token。两者分开计价,输入通常便宜,输出通常贵。

真正的麻烦在于,大模型本身是无状态的。它不记得你上一句说过什么,每次请求本质上都是一份完整的、从零开始的输入。你想让它扮演“按公司规范回答的 Java 售后助手”,就得把那段规范每次重新贴给它。

重复的量有多大?算一笔账:

  • 系统提示词:约 2000 token
  • 工具定义(20 个):约 1500 token
  • 历史对话:约 3000 token
  • 用户这一句:约 100 token

一次请求输入约 6600 token。每天一万次请求,其中约 3500 token 的前缀是固定不变的,等于每天白花三千五百万 token 的钱。这些 token 不是买到了更好的答案,只是让模型重新确认一遍“我是谁、我能用什么工具”。

延迟也一起被拖累。模型处理输入要先把整段内容算成内部状态,再开始逐字生成。前缀越长,这个准备阶段越久,用户盯着转圈的时间就越长。而对于一个 Agent 应用,一轮对话里模型可能被调用五次、十次,每次都要把这堆前缀重算一遍——重复的乘法,就是这么来的。

这类开销是可以消掉的,前提是那段前缀本身足够稳定。系统提示词、工具列表、开头几轮对话,往往在整段会话里都不变,这正是提示词缓存能发挥作用的地方。

二、底层原理到底怎么回事

提示词缓存的本质,是让模型服务商把“不变的前缀”只算一次,把中间结果存下来,下次遇到相同开头直接搬用。

模型处理一次输入分两个阶段:先把整段输入算成内部的中间状态,这段计算量最大,叫 prefill;再从最后一个 token 开始,一个一个字往外吐,叫 decode。缓存省掉的就是 prefill。

服务端不会自己猜“哪一段该缓存”。它靠你在提示词里插断点(cache breakpoint)。断点之前的内容会被存进缓存,下次请求只要开头逐字一致,就直接从缓存读,跳过重算。

几个必须记住的规则:

匹配是严格前缀匹配。 从头开始,一个 token 都不能差。顺序固定为 工具 → 系统提示词 → 消息列表。你在系统提示词里塞了一句当前时间,或者工具顺序换了一下,那处往后的内容全部作废,缓存命中直接归零。

有最小长度门槛。 太短的提示词不值得存。官方要求前缀达到模型专属的最小长度,不同模型在 512 到 4096 token 之间。一段几百字的提示词,很可能压根不参与缓存。

一次请求最多 4 个断点。 超了会被拒绝。

缓存有生命周期。 默认存 5 分钟,每次命中都会把这个计时器刷新。请求间隔经常超过 5 分钟的场景(用户慢慢打字、离线批处理),可以用 1 小时档。

读写价格不一样。 写入缓存比普通输入贵一点:5 分钟档大约是 1.25 倍,1 小时档大约是 2 倍。读取缓存则便宜得多,大约是普通输入价的十分之一。所以缓存只在“同一段前缀被反复使用”时才划算——只调用一次的提示词,写缓存纯属倒贴钱。

LangChain4j 没有重新发明一套概念,它只是把 Anthropic 的断点翻译成了几个开关:

  • cacheSystemMessages(true):给最后一条系统消息打上断点标记,它之前的内容(也就是系统提示词)会被缓存。
  • cacheTools(true):给最后一个工具定义打断点。
  • 这两个断点位置每次请求都一样,所以哪怕对话没有历史、每次都独立调用,它们也照样生效。因为工具排在系统消息前面,系统消息这个断点其实已经顺带把工具缓存了;单独再开工具断点,是为了在系统消息偶尔变动时仍保住工具那一段。
  • cacheAutomatically(true):断点放在请求的最后一块,并随对话变长自动往前挪。这样每一轮请求都能读到上一轮发过的全部内容。它只在“本轮请求以完整的历史开头”时才划算,用滑动窗口把老消息挤掉的内存策略,开了反而更贵。
  • 想手动标某一条消息,用户消息有可变的 attributes 表:userMessage.attributes().put("cache_control", "ephemeral");模型消息和工具结果消息的 attributes 不可变,得用 toBuilder().attributes(Map.of("cache_control", "ephemeral")) 重新构造。

效果怎么看?Anthropic 返回的用量对象里多两个字段:cacheCreationInputTokens(这一轮写进缓存的 token 数)和 cacheReadInputTokens(这一轮从缓存读到的 token 数)。前者只在第一次出现,后者从第二轮开始就该涨起来。这两个数字就是你判断缓存有没有生效的唯一依据。

三、实战:手把手写代码

例一:最小可跑,缓存系统提示词

先看依赖。LangChain4j 的核心接口和实现拆在不同 artifact 里,Anthropic 的实现在 langchain4j-anthropic。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>lc4j-prompt-cache-demo</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j</artifactId>
            <version>1.22.0</version>
        </dependency>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-anthropic</artifactId>
            <version>1.22.0</version>
        </dependency>
        <dependency>
            <groupId>org.slf4j</groupId>
            <artifactId>slf4j-simple</artifactId>
            <version>2.0.20</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.6.4</version>
                <configuration>
                    <mainClass>com.example.cache.MinimalCachingDemo</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

下面这个类,把同一段系统提示词发三遍,每遍打印一次用量,你就能亲眼看到第二轮起缓存命中。

package com.example.cache;

import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.anthropic.AnthropicChatModel;
import dev.langchain4j.model.anthropic.AnthropicTokenUsage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.model.output.TokenUsage;

import java.util.List;

public class MinimalCachingDemo {

    // 真实项目里这里通常是上千字的产品规范。
    // 注意:提示词本身要超过模型的最小可缓存长度,太短的话开开关也没用。
    private static final String SYSTEM_PROMPT = """
            你是一名 Java 后端技术顾问,只回答与 Java、Spring 生态相关的问题。
            回答要求:
            1. 先给结论,再给理由,最后给可运行的最小代码示例;
            2. 涉及版本时以 Maven Central 上的 GA 版本为准,不推荐 RC 或 SNAPSHOT;
            3. 不确定的内容要明确说"不确定",不要编造 API;
            4. 不要使用"众所周知""显而易见"这类词;
            5. 代码必须包含完整的 import,禁止写省略号占位。
            输出语言:简体中文。语气:直接、克制,像一个同事在给你讲技术。
            如果问题超出 Java 技术范围,礼貌拒答,并说明你只负责 Java 方向。
            """;

    public static void main(String[] args) {
        ChatModel model = AnthropicChatModel.builder()
                .apiKey(System.getenv("ANTHROPIC_API_KEY"))
                .modelName("claude-sonnet-4-5")
                .maxTokens(512)
                .cacheSystemMessages(true)   // 系统提示词作为缓存断点
                .cacheTools(true)            // 工具定义也作为缓存断点
                .logRequests(true)
                .logResponses(true)
                .build();

        String[] questions = {
                "值不值得给一个内部工具开缓存?",
                "如果提示词里带了当前时间,会发生什么?",
                "一次请求最多能标几个缓存断点?"
        };

        for (int i = 0; i < questions.length; i++) {
            ChatRequest request = ChatRequest.builder()
                    .messages(List.of(
                            SystemMessage.from(SYSTEM_PROMPT),
                            UserMessage.from(questions[i])))
                    .build();

            ChatResponse response = model.chat(request);
            printUsage(i + 1, response);
        }
    }

    private static void printUsage(int round, ChatResponse response) {
        TokenUsage usage = response.tokenUsage();

        int cacheWrite = 0;
        int cacheRead = 0;
        if (usage instanceof AnthropicTokenUsage anthropicUsage) {
            cacheWrite = orZero(anthropicUsage.cacheCreationInputTokens());
            cacheRead = orZero(anthropicUsage.cacheReadInputTokens());
        }

        System.out.printf(
                "第 %d 轮 | 输入 %d | 输出 %d | 写缓存 %d | 读缓存 %d%n",
                round,
                orZero(usage.inputTokenCount()),
                orZero(usage.outputTokenCount()),
                cacheWrite,
                cacheRead);
    }

    private static int orZero(Integer value) {
        return value == null ? 0 : value;
    }
}

运行:

ANTHROPIC_API_KEY=你的密钥 mvn -q compile exec:java

预期输出大致是这样(数字随模型和提示词长度浮动):

第 1 轮 | 输入 1180 | 输出 96 | 写缓存 1105 | 读缓存 0
第 2 轮 | 输入 1180 | 输出 74 | 写缓存 0    | 读缓存 1105
第 3 轮 | 输入 1180 | 输出 88 | 写缓存 0    | 读缓存 1105

第一轮把系统提示词写进缓存,读缓存是 0;第二轮起写缓存归零、读缓存稳定在 1105,这就是缓存命中的样子。注意输入总 token 数没变,变的是这堆 token 的计价方式——读取价只有原价的一成左右。

例二:多轮对话,让断点跟着对话走

单次对话还不够典型。多轮问答和 Agent 工具循环,才是缓存省钱的主战场。关键是把 cacheAutomatically 打开,让断点自动前移。

package com.example.cache;

import dev.langchain4j.data.message.AiMessage;
import dev.langchain4j.data.message.ChatMessage;
import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.anthropic.AnthropicChatModel;
import dev.langchain4j.model.anthropic.AnthropicTokenUsage;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import dev.langchain4j.model.output.TokenUsage;

import java.util.ArrayList;
import java.util.List;

public class MultiTurnCachingDemo {

    private static final String SYSTEM_PROMPT = """
            你是一名为 Java 团队做技术评审的顾问。
            每次回答都要包含:结论、依据、风险点三部分。
            回答尽量短,超过 200 字就分点。
            只为 Java / Spring 生态的问题提供意见。
            """;

    public static void main(String[] args) {
        ChatModel model = AnthropicChatModel.builder()
                .apiKey(System.getenv("ANTHROPIC_API_KEY"))
                .modelName("claude-sonnet-4-5")
                .maxTokens(1024)
                .cacheSystemMessages(true)
                .cacheTools(true)
                .cacheAutomatically(true)  // 断点跟着对话增长自动前移
                .cacheTtl("1h")            // 用户回消息间隔较长,用 1 小时档
                .build();

        List<ChatMessage> messages = new ArrayList<>();
        messages.add(SystemMessage.from(SYSTEM_PROMPT));

        String[] turns = {
                "我们打算把接口签名从 token 换成 API Key,你觉得风险在哪?",
                "那如果把旧 token 保留三个月做兼容,会有什么问题?",
                "按你说的,给我一个灰度下线的步骤。"
        };

        for (int i = 0; i < turns.length; i++) {
            messages.add(UserMessage.from(turns[i]));

            ChatResponse response = model.chat(
                    ChatRequest.builder().messages(messages).build());

            AiMessage aiMessage = response.aiMessage();
            // 把模型回答追加回历史,下一轮请求就是"以完整历史开头",缓存才读得到
            messages.add(aiMessage);

            report(i + 1, messages.size(), response.tokenUsage());
        }
    }

    private static void report(int turn, int messageCount, TokenUsage usage) {
        int cacheRead = 0;
        int cacheWrite = 0;
        if (usage instanceof AnthropicTokenUsage anthropicUsage) {
            cacheRead = orZero(anthropicUsage.cacheReadInputTokens());
            cacheWrite = orZero(anthropicUsage.cacheCreationInputTokens());
        }
        System.out.printf(
                "第 %d 轮 | 消息数 %d | 输入 %d | 写缓存 %d | 读缓存 %d%n",
                turn, messageCount,
                orZero(usage.inputTokenCount()), cacheWrite, cacheRead);
    }

    private static int orZero(Integer value) {
        return value == null ? 0 : value;
    }
}

这里有两个细节决定成败。

一是必须把模型的回答追加回 messages。自动缓存的逻辑是“本轮请求以上一轮发过的完整内容开头”,如果你每轮都只发系统提示词 + 当前问题,历史根本不在请求里,缓存自然读不到。

二是别在每轮请求里改动前缀。系统提示词里写“当前时间:<实时时刻>”,下一轮就变成了新时间,前缀从此处断开,前面全部作废。动态信息要么放在用户消息里,要么放在系统提示词的最末尾之后。

例三:Spring Boot 里做成 Bean

Spring 项目里的做法是把配好缓存的模型注册成一个 Bean,各处注入即可。这里不引额外的 starter,纯手工装配,避免多一层自动配置的黑盒。

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>lc4j-cache-spring-demo</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>21</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
            <version>4.1.1</version>
        </dependency>
        <dependency>
            <groupId>dev.langchain4j</groupId>
            <artifactId>langchain4j-anthropic</artifactId>
            <version>1.22.0</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>4.1.1</version>
            </plugin>
        </plugins>
    </build>
</project>

配置类和控制器:

package com.example.cache.spring;

import dev.langchain4j.model.anthropic.AnthropicChatModel;
import dev.langchain4j.model.chat.ChatModel;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ChatModelConfig {

    // 一份固定不变的系统提示词,是全应用共享的缓存前缀
    static final String SYSTEM_PROMPT = """
            你是公司内部的 Java 技术助手,只回答 Java、Spring、Redis 相关问题。
            回答格式:结论 / 依据 / 示例代码。
            代码必须是完整类,不能有省略号。
            不确定就不要编,直接说不知道。
            """;

    @Bean
    public ChatModel cachedChatModel(@Value("${anthropic.api-key}") String apiKey) {
        return AnthropicChatModel.builder()
                .apiKey(apiKey)
                .modelName("claude-sonnet-4-5")
                .maxTokens(1024)
                .cacheSystemMessages(true)
                .cacheTools(true)
                .build();
    }
}
package com.example.cache.spring;

import dev.langchain4j.data.message.SystemMessage;
import dev.langchain4j.data.message.UserMessage;
import dev.langchain4j.model.anthropic.AnthropicChatRequestParameters;
import dev.langchain4j.model.chat.ChatModel;
import dev.langchain4j.model.chat.request.ChatRequest;
import dev.langchain4j.model.chat.response.ChatResponse;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
@RequestMapping("/chat")
public class ChatController {

    private final ChatModel chatModel;

    public ChatController(ChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @PostMapping
    public String chat(@RequestParam("q") String question) {
        // 模型级开关已经打开,这里演示按次覆盖:这次调用强制缓存系统提示词
        AnthropicChatRequestParameters parameters = AnthropicChatRequestParameters.builder()
                .cacheSystemMessages(true)
                .cacheTools(true)
                .build();

        ChatRequest request = ChatRequest.builder()
                .messages(List.of(
                        SystemMessage.from(ChatModelConfig.SYSTEM_PROMPT),
                        UserMessage.from(question)))
                .parameters(parameters)
                .build();

        ChatResponse response = chatModel.chat(request);
        return response.aiMessage().text();
    }
}

application.yml 里放密钥,别硬编码:

anthropic:
  api-key: ${ANTHROPIC_API_KEY}

跑起来以后,同一个进程里连着问几个问题,第二问开始就是读缓存。这种“一个应用、一份系统提示词、大量用户请求”的结构,是缓存收益最明显的场景。

四、踩坑经验和最佳实践

别把动态内容塞进缓存前缀。 这是最常见的翻车点。系统提示词里写了当前时间、请求 ID、用户昵称,前缀每轮都在变,缓存命中率直接为零。动态信息一律放到用户消息里。

工具定义的顺序和内容要稳定。 用反射扫出来的 @Tool 方法,如果扫描顺序不稳定,工具列表每轮都可能不一样,缓存同样失效。生产环境最好显式指定工具集合,别依赖“刚好是那个顺序”。

用了滑动窗口内存就别开自动缓存。 MessageWindowChatMemory 把老消息挤掉之后,本轮请求不再以完整历史开头,自动缓存只会让每轮都按写入价付费,读不回来,比不开还贵。这种情况只开 cacheSystemMessages 和 cacheTools。

一次性调用别开自动缓存。 没有历史、调用完就结束的场景,自动缓存没有任何东西可读,白白多付写入价。

注意最小长度门槛。 提示词太短不缓存。同一个功能在测试环境跑得好,上了生产却没省到钱,很可能就是提示词本身没到门槛。

排查没命中用它。 LangChain4j 提供了 returnCacheDiagnostics(true),开启后能拿到 Anthropic 的缓存诊断信息,告诉你这次为什么没命中(模型不对、前缀不匹配、长度不够等)。怀疑自己写错了前缀,开这个开关比猜快得多。

1 小时档要用在刀刃上。 只有“同一段前缀在一小时内会被读取好几次”才值得付 2 倍的写入价。用户十几分钟才回一句的客服场景,值得;一次性的批处理,不值得。

兼容网关要留个心眼。 自动缓存是通过请求顶层的 cache_control 字段下发的。有些 Anthropic 兼容网关或代理不认这个字段,可能直接报错或者忽略。遇到这种情况,退回手动标记系统消息、工具和具体消息,路径会更稳。

五、性能对比和技术选型

方案 输入 token 计费方式 首字延迟 适用场景
不开缓存 全部按原价 基线 一次性调用,前缀每次都不同
只开 cacheSystemMessages + cacheTools 前缀按约 0.1 倍读取 明显下降 所有共享同一段系统提示词和工具定义的应用
再加 cacheAutomatically 历史也走缓存读取 进一步下降 多轮对话、Agent 工具循环

三个开关不是绑定的,按需组合。经验上:

  • 应用有一套固定的系统提示词和工具,无论有没有多轮对话,前两个都该开,这是纯赚。
  • 有真正的多轮上下文,且每轮都带上完整历史,再考虑自动缓存。
  • 对话历史会被裁剪、前缀会变的系统,自动缓存是净亏,别开。

选型上还有一层:不是所有厂商都要你手动配。OpenAI 的提示词缓存是自动生效的,输入超过一定长度就自动打折,代码不用改;DeepSeek 也有磁盘级上下文缓存,命中的部分按更低价格计费。Anthropic 则需要你显式打断点。这不是谁好谁坏,而是取舍:显式标记更可控,能精确控制缓存哪一段、存多久,代价是多写几行配置。

六、总结

提示词缓存解决的是一个很具体的问题:同一段前缀被反复重算,重复付钱、重复等待。

真正要记住的只有三件事。

第一,缓存是严格前缀匹配。前缀里任何一处变动,从变动点往后的内容全部作废。这决定了你的系统提示词必须“干净”——固定内容在前,动态内容在后。

第二,LangChain4j 用三个开关而不是一套新 API 来暴露这个能力:cacheSystemMessages、cacheTools 管固定前缀,cacheAutomatically 管增长的历史。谁该开、谁不该开,取决于你的前缀稳不稳定。

第三,验证靠数字,不靠感觉。盯住 cacheReadInputTokens,它从第二起重就应该涨起来;没涨,就是前缀没对齐。

缓存不是万能药。前缀只用到一次的场景,它就是个成本项。但只要你做的是面向很多用户的 AI 应用,“一份系统提示词、被成千上万次请求复用”几乎是必然结构,这时候把缓存打开,是投入产出比最高的一次优化。

参考资料

文 / 会编程的吕洞宾