bug: impossible to remove prompt labels using Python SDK or API

问题场景

用户有一个 Prompt（my-prompt），某个版本（version 3）带有 ["latest", "candidate"] 标签。在与生产版本做对比后，希望把该版本提升为生产版，并去掉 candidate 标签，但保留该版本的其他标签。尝试了两种方式：一是调用 langfuse.update_prompt(name="my-prompt", version=3, new_labels=["production"])；二是直接向 /api/public/v2/prompts/my-prompt/versions/3 发 PATCH 请求，body 为 {"newLabels": ["production"]}。两种方式都没有移除 candidate。

报错原文

bug: impossible to remove prompt labels using Python SDK or API

原因分析

Issue 讨论已确认：后端 updatePrompts.ts 的逻辑会把请求中的 newLabels 与当前版本已有的标签取并集，而不是用新列表替换旧列表。因此无论你在请求中是否省略 candidate，后端都会把旧标签重新合并回去，导致自定义标签无法被“单独移除”。这是后端实现限制，不是 SDK 参数缺失或请求格式错误。latest 标签由系统内部管理，本就不允许手动改动，但该合并逻辑同样作用于自定义标签。

环境排查

• 确认使用的 Langfuse 是否为自托管，以及镜像版本是否与 Issue 中的 langfuse/langfuse:3@sha256:08ed... 一致或相近，避免误判为已修复版本。
• 确认调用的是 update_prompt 的官方参数名（name、version、new_labels），以及 PATCH 请求字段名为 newLabels，区分 SDK 层与 API 层的命名差异。
• 确认目标版本号正确（本例为 version 3），避免 PATCH 打到了别的版本上。
• Issue 未记录 Python SDK 版本、Python 版本、依赖版本，排查时请自行核对当前 SDK 版本是否与部署的服务端版本匹配。

解决步骤

1. 先确认当前版本的实际标签，记录下包含 candidate 的目标版本号，用于复现和验证。
2. 按 Issue 证据，通过 Python SDK 或 PATCH API 提交仅包含目标标签（如 ["production"]）的请求，观察返回结果。若返回结果里 candidate 仍在，即命中本 Issue 的合并逻辑。
3. 不要尝试通过重复发送不同的 newLabels 或空列表来“覆盖”已有标签；讨论已确认后端取并集，这种方式不会移除任何标签。
4. 当前没有可用的 SDK/API 移除手段，只能等待后端支持移除自定义标签的能力（例如 Issue 中建议的 remove_labels 参数）。在此期间，可在需要时把该标签迁移到其他版本，或新建一个干净的版本并只标注期望的标签，作为临时规避。
5. 关注 Issue 进展，确认发布版本中是否引入了标签移除逻辑后再升级服务端。

验证方法

对目标版本重新查询标签，确认返回的标签列表中不再包含 candidate，且 production 等期望标签仍然存在。若仍包含 candidate，说明仍受本 Issue 的合并逻辑限制。注意：仅以请求返回 200 判断“已移除”不充分，必须以实际标签列表为准。

参考来源

langfuse/langfuse #9278

AI 工具推荐

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

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

了解 GamsGo AI

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