文档 / 客户端 SDK 中的提示词缓存

客户端 SDK 中的提示词缓存

Langfuse 提示词在 SDK 中客户端缓存,因此首次使用后没有延迟影响,也没有可用性风险。你也可以在启动时预取提示词以填充缓存,或提供降级提示词。

缓存命中

当 SDK 缓存包含新鲜的提示词时,它会立即返回,无需任何网络请求。

mermaid

sequenceDiagram
    participant App as Application
    participant SDK as Langfuse SDK
    participant Cache as SDK Cache

    App->>SDK: getPrompt("my-prompt")
    SDK->>Cache: Check cache
    Cache-->>SDK: ✅ Fresh prompt found
    SDK-->>App: Return cached prompt

后台重新校验

当缓存 TTL 过期时,过期的提示词会立即提供,同时在后台重新校验。

mermaid

sequenceDiagram
    participant App as Application
    participant SDK as Langfuse SDK
    participant Cache as SDK Cache
    participant API as Langfuse API
    participant Redis as Redis Cache

    App->>SDK: getPrompt("my-prompt")
    SDK->>Cache: Check cache
    Cache-->>SDK: ⚠️ Stale prompt found
    SDK-->>App: Return stale prompt (instant)

    par Background refresh
        SDK->>API: GET /api/public/prompts/:name
        API->>Redis: Check Redis cache
        Redis-->>API: ✅ Prompt found
        API-->>SDK: Return prompt
        SDK->>Cache: Update cache
    end

这确保了高可用性——用户永远不必等待网络请求,同时缓存保持新鲜。

缓存未命中

当不存在缓存的提示词时(例如应用首次启动),提示词从 API 获取。API 将提示词缓存在 Redis 缓存中,以确保低延迟。

mermaid

sequenceDiagram
    participant App as Application
    participant SDK as Langfuse SDK
    participant Cache as SDK Cache
    participant API as Langfuse API
    participant Redis as Redis Cache
    participant DB as PostgreSQL

    App->>SDK: getPrompt("my-prompt")
    SDK->>Cache: Check cache
    Cache-->>SDK: ❌ No prompt found
    SDK->>API: GET /api/public/prompts/:name
    API->>Redis: Check Redis cache

    alt Redis Cache Hit
        Redis-->>API: ✅ Prompt found
        API-->>SDK: Return prompt
    else Redis Cache Miss
        API->>DB: Query prompt
        DB-->>API: Return prompt data
        API->>Redis: Store in cache
        API-->>SDK: Return prompt
    end

    SDK->>Cache: Store in cache
    SDK-->>App: Return prompt

多层降级确保了弹性——如果 Redis 不可用,数据库作为备份。

可选:预取

在应用启动期间预取提示词,确保在运行时请求之前填充缓存。

此步骤是可选的,通常没有必要。通常,服务启动后首次使用时经历的微小延迟是可以接受的。关于如何设置的示例见下文。

mermaid

sequenceDiagram
    participant App as Application
    participant SDK as Langfuse SDK
    participant Cache as SDK Cache
    participant API as Langfuse API
    participant Redis as Redis Cache

    App->>SDK: Prefetch prompts
    SDK->>API: GET /api/public/prompts/:name
    API->>Redis: Check/populate cache
    Redis-->>API: Cached prompt
    API-->>SDK: Return prompt
    SDK->>Cache: Populate cache
    Note over Cache: Cache now warm for runtime

可选:降级(Fallback)

当本地缓存为空且 Langfuse API 不可用时,可以使用降级提示词以确保 100% 可用性。

这很少必要,因为提示词 API 具有高可用性,并且我们密切监控其性能(状态页)。在短暂服务中断的情况下,SDK 级提示词缓存通常能确保应用不受影响。

mermaid

sequenceDiagram
    participant App as Application
    participant SDK as Langfuse SDK
    participant Cache as SDK Cache
    participant API as Langfuse API

    App->>SDK: getPrompt("my-prompt", fallback="fallback prompt")
    SDK->>Cache: Check cache
    Cache-->>SDK: ❌ No prompt found
    SDK->>API: GET /api/public/prompts/:name
    API-->>SDK: ❌ Network error / API unavailable

    Note over SDK: Use fallback prompt
    SDK-->>App: Return fallback prompt
    Note over App: Application continues with fallback

可选:自定义缓存时长(TTL)

如果你希望减少 Langfuse Client 的网络开销,缓存时长是可配置的。默认缓存 TTL(Time To Live)为 60 秒。TTL 过期后,SDK 会在后台重新获取提示词并更新缓存。重新获取异步完成,不会阻塞应用。

python

# Get current `production` prompt version and cache for 5 minutes
prompt = langfuse.get_prompt("movie-critic", cache_ttl_seconds=300)

import { LangfuseClient } from "@langfuse/client";

const langfuse = new LangfuseClient();

// Get current `production` version and cache prompt for 5 minutes
const prompt = await langfuse.prompt.get("movie-critic", {
  cacheTtlSeconds: 300,
});

可选:禁用缓存

你可以通过将 cacheTtlSeconds 设置为 0 来禁用缓存。这将确保每次调用都从 Langfuse API 获取提示词。这推荐用于非生产用例,你希望确保提示词始终与 Langfuse 中的最新版本保持同步。

python

prompt = langfuse.get_prompt("movie-critic", cache_ttl_seconds=0)

# Common in non-production environments, no cache + latest version
prompt = langfuse.get_prompt("movie-critic", cache_ttl_seconds=0, label="latest")

const prompt = await langfuse.prompt.get("movie-critic", {
  cacheTtlSeconds: 0,
});

// Common in non-production environments, no cache + latest version
const prompt = await langfuse.prompt.get("movie-critic", {
  cacheTtlSeconds: 0,
  label: "latest",
});

可选:保证提示词可用性

虽然通常不必要,但你可以通过在应用启动时预取提示词并提供降级提示词来确保 100% 的提示词可用性。更多信息请遵循本指南。

首次获取的性能测量

我们在完全禁用缓存的情况下测量了以下代码片段的执行时间。你可以自己运行 this notebook 来验证结果。

python

prompt = langfuse.get_prompt("perf-test", cache_ttl_seconds=0)
prompt.compile(input="test")

使用 Langfuse Cloud 的 1000 次顺序执行的结果(包含网络延迟):

性能图表

count    1000.000000
mean        0.039335 sec
std         0.014172 sec
min         0.032702 sec
25%         0.035387 sec
50%         0.037030 sec
75%         0.041111 sec
99%         0.068914 sec
max         0.409609 sec