bug: prompt cache returns wrong version when numeric label matches version number

快速结论：当通过 Langfuse SDK 调用 prompt 缓存时，如果你给 prompt 设置的标签（label）是纯数字字符串（例如 "3"），并且正好与某个 prompt 版本号（version=3）相同，系统会错误地将标签当作版本号处理，导致返回错误的缓存内容。优先检查你是否为 prompt 设置了与版本号数值相同的纯数字标签。

问题场景

用户在使用 Langfuse 的 Prompt Management 功能（feat-prompt-management）时，通过 SDK 或 API 创建或更新 prompt，并为其指定了一个 label。当 label 值为纯数字字符串（如 "3"）且该数字恰好匹配某个已存在的版本号（如 version=3）时，后续通过 label 获取 prompt 缓存的请求会返回错误版本。

报错原文

In getCacheKey where params.version ?? params.label produces the same Redis key for version=N and label="N"

原因分析

问题出在 getCacheKey 函数的实现。该函数使用 params.version ?? params.label 来生成 Redis 缓存键。当 params.version 存在时，它总是优先使用版本号，忽略 params.label。对于 label 为纯数字字符串（如 "3"）且与版本号相同的场景，由于 ?? 运算符无法区分传入的是 label 还是 version（因为此时 params.version 的值与 label 对应的 version 值完全一样），导致两个不同意图的请求共用同一个 Redis 键，出现缓存冲突。

环境排查

Langfuse 版本：该问题在 Langfuse Cloud 及 self-hosted 环境中均可复现，具体触发版本未知，但建议确认当前部署版本。
SDK 版本：如果使用官方 SDK（如 JavaScript 或 Python SDK），请确认 SDK 版本是否包含此问题的修复。

解决步骤

避免使用纯数字 label：在现存的工作流中，如果 prompt 的 label 是纯数字，请修改 label 示例，添加前缀或非数字字符（如 "v3" 替代 "3"），以规避与版本号冲突。
升级到修复版本：根据 Issue 讨论，社区计划采用类型前缀方案（type-prefix approach），例如在 Redis key 中使用 version:3 和 label:3 来明确区分。可优先尝试升级到包含此修复的 Langfuse 最新版本。
手动检查缓存键：如果无法升级，可以检查 Redis 中的缓存键，确认 version:N 和 label:N 是否被错误合并为同一个键，并手动清理冲突缓存。

验证方法

修复后，分别使用纯数字 label（如 "3"）和匹配的版本号（如 3）发起两次不同的 prompt 缓存请求，确认返回的内容不一致，且分别对应 label 和 version 所指向的正确 prompt 版本。

参考来源

langfuse/langfuse #14852

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。

bug: prompt cache returns wrong version when numeric label matches version number