lilypad

背景：当 LLM 应用变得「玄学」，工程师需要什么？

想象一下这个场景：你的 AI 助手上周还能准确回答用户问题，这周突然开始「胡言乱语」。你去查日志，发现输入输出都正常；你问开发，他也不知道改了什么——代码改过、Prompt 调过、模型还升级过。问题出在哪？完全无法定位。

这就是当前 LLM 应用开发的核心痛点：非确定性（Non-deterministic）。传统软件中，相同的代码输入 → 输出是固定的；但 LLM 应用中，每次调用都可能因为一个 Prompt 参数的调整、一个模型版本的升级而产生完全不同的输出。传统调试手段（print 打印日志、breakpoint 单步调试）面对这种随机性几乎束手无策。

Lilypad 就是为解决这个痛点而生的——它将 LLM 应用开发中的「变与不变」完整记录下来，让工程师既能追踪每一次调用的来龙去脉，又能像管理代码版本一样管理 Prompt 和模型的迭代历史。

项目起源与团队背景

Lilypad 由 Mirascope 团队开发和维护，这是一家专注于 LLM 应用工程工具的公司。Mirascope 团队认为，构建 LLM 应用与构建传统软件存在本质区别：LLM 的输出具有不确定性，这意味着开发者需要一套全新的工具链来应对「非确定性」带来的挑战。他们从自己的工程实践中总结出了三个核心原则，并围绕这些原则构建了 Lilypad。

⚠️ 重要提示： Lilypad 项目本身已于 2025 年正式 deprecated（停更）。Mirascope 团队在其 GA（正式版）发布后，将核心能力迁移到了 Mirascope v2 主仓库中的 mirascope.ops 模块，以及配套的 Mirascope Cloud 平台。但 Lilypad 作为开源项目依然开放可用，只是不会再有新功能维护。

项目的 GitHub 仓库托管于 Mirascope/lilypad，支持 8 个官方主题标签（Topics）：anthropic、large-language-models、llm、openai、prompt-engineering、prompt-management、prompt-versioning，清晰地定义了项目的定位边界。

图1：Lilypad 项目概览（来源：项目 README）

核心功能：三层能力构建 LLM 可观测性

Lilypad 提供了一套完整的三层可观测性（Observability）工具链，层层递进：

第一层：版本化管理（Prompt Versioning）

在 Lilypad 中，每一个涉及 LLM 调用的代码片段（函数）都被视为一个可版本化的「制品（Artifact）」。当你修改了 Prompt 模板、调整了模型参数（如 temperature、max_tokens），或改变了结构化输出的 schema，系统会自动为这次改动创建一个新版本。这意味着你可以随时回溯到任意历史版本，精确对比两次调用的差异。

官方 UI 提供了一个 Compare（对比）按钮，允许开发者在下拉菜单中选择任意两个版本，以左右分栏的形式直观展示代码变更、Prompt 改动和模型配置的差异。这在分析「为什么这次上线后输出质量下降了」时尤为有用。

第二层：全链路追踪（Distributed Tracing）

基于 OpenTelemetry（OTEL） 标准，Lilypad 自动为每一次 LLM 调用生成完整的分布式追踪数据（Trace）。追踪记录不只包含输入（Input）和输出（Output），还记录了触发这次调用的完整代码上下文——包括函数名、调用栈、Prompt 版本、模型参数、API 响应时间等元数据。

有了全链路追踪，开发者可以回答「为什么这个用户收到了这个回答」这类问题：只需要在 UI 中点击任意一条 LLM 调用记录，即可看到完整的因果链——从最初的 API 请求到最终的模型输出，中间每一步都清晰可见。

第三层：持续评估与优化（Evaluation & Annotation）

Lilypad 支持在追踪数据上添加注释（Annotation）和标签（Tag），方便团队成员对特定调用进行标记、评论和分类。结合 Traces 数据，团队可以系统性地评估 Prompt 和模型的表现，持续优化应用质量。

技术架构：FastAPI + PostgreSQL + Kafka 的生产级设计

从代码结构看，Lilypad 采用了标准的现代化 Python 后端架构：

后端（app/ 目录）：

• FastAPI 框架提供 RESTful API 服务，入口为 lilypad/server/main.py
• PostgreSQL 作为主数据库，通过 Alembic 管理数据库迁移（migrations/ 目录）
• Kafka 作为消息队列，接收追踪数据流（kafka/ 配置），并由专门的 span 处理器异步写入数据库
• API 层采用 Pydantic schema 验证输入输出（server/schemas/），路由按功能模块划分（api/v0/ 下包含 traces、spans、functions、projects、organizations 等独立 API 文件）
• 支持 GitHub OAuth 和 Google OAuth 登录集成

SDK（sdks/python/ 目录）：

• 面向开发者提供的 Python SDK，通过 lilypad-sdk[openai] 等 extra 依赖安装
• 底层对接 mirascope 核心库（支持 OpenAI、Anthropic、Azure、AWS Bedrock、Google、Mistral、Cohere、Groq、xAI、LiteLLM 等 10+ 模型提供商）
• SDK 通过装饰器或上下文管理器自动完成追踪数据的上报

部署架构：

• Dockerfile 采用了多阶段构建（Multi-stage Build），基于 ghcr.io/astral-sh/uv:python3.10-bookworm-slim 镜像，利用 uv 包管理器安装依赖
• docker-compose.yml 定义了完整的本地开发环境：postgres + kafka + lilypad 三个服务一键启动
• 前端 UI 集成在后端服务中（LILYPAD_SERVE_FRONTEND=true），无需单独部署前端服务

使用门槛：从零开始的上手路径

Lilypad 提供两种使用模式：

模式一：使用 Lilypad Cloud（托管版） 适合快速验证和团队协作，无需自己运维。步骤：

1. 在 https://lilypad.mirascope.com 注册账号
2. 在组织设置中创建项目和 API Key
3. 在代码中安装 SDK：uv add "lilypad-sdk[openai]"
4. 在代码中配置 LILYPAD_PROJECT_ID 和 LILYPAD_API_KEY 环境变量
5. 运行代码，自动开始追踪

模式二：本地自托管（Self-hosted） 适合对数据安全有要求或需要深度定制的团队。通过 docker-compose up 一键启动完整环境，可参考官方文档 https://lilypad.so/self-hosting。

上手门槛评估： 中等。Lilypad 的核心概念（版本化、追踪、可观测性）对 LLM 应用开发者来说是自然延伸，但需要理解 OTEL 追踪模型和分布式系统的基本概念。SDK 的集成相对简洁，有 mirascope 使用经验的开发者会感到非常熟悉。

局限与风险：不回避的问题清单

尽管 Lilypad 设计优秀，但以下几点值得潜在用户知悉：

1. 项目已停止维护：Mirascope 团队明确表示 Lilypad 已 deprecated，核心能力迁移到 mirascope 主仓库。长期依赖 Lilypad 的团队需要考虑迁移路径。

2. 自托管有一定运维复杂度：依赖 Kafka 消息队列，对没有分布式系统运维经验的团队来说，学习曲线较陡。

3. 不支持流式输出（Streaming）追踪：Playground 环境的依赖表明系统主要处理结构化的请求-响应数据，对于 LLM 流式输出场景的追踪支持有限。

4. 数据隐私考量：追踪数据中包含完整的 Prompt 内容（可能包含用户隐私数据），自托管时需要配置 LILYPAD_SECRET_MANAGER_TYPE（支持 Supabase Vault 或 AWS Secrets Manager）来妥善管理敏感信息。

行业意义：LLM 工程化工具链的一个范式

Lilypad 出现在 2024-2025 年 LLM 应用井喷的时间节点，正好填补了「Prompt 版本化管理」这一细分领域的空白。它的核心贡献在于：

• 将 Prompt 视为一等公民（First-class Citizen）：传统开发中，代码是版本化的，配置是版本化的，但 Prompt 往往是「硬编码」或「随口改」的状态。Lilypad 改变了这一点。
• 推动了 LLM 可观测性（Observability）理念：借鉴了分布式系统监控领域的 OTEL 标准，将其引入 LLM 应用开发，这种思路已经被 OpenAI、Anthropic 等厂商广泛采纳。
• 开源 vs. 商业化的平衡：Lilypad 开源核心能力，Mirascope Cloud 提供付费托管服务，这种模式为 LLM 工具类项目提供了可参考的商业化路径。

快速上手建议

如果你是 LLM 应用开发者，正在管理多个 Prompt 版本或多模型切换，推荐：

• 从 Lilypad Cloud 入手，5 分钟体验核心能力
• 有深度定制需求时，使用 Docker Compose 本地部署
• 关注 Mirascope 主仓库的 mirascope.ops 模块，作为 Lilypad 的官方继承者