pezzolabs/pezzo · 上手攻略

  • 仓库：pezzolabs/pezzo
  • 链接：https://github.com/pezzolabs/pezzo
  • 分类：llmops · observability · prompt-management
  • 作者：Tom
  • 更新：2026-08-19

是什么

Pezzo 是一个开源的、开发者优先的 LLMOps 平台，旨在简化 AI 应用开发中的提示词设计、版本管理、即时发布、协作、问题排查和可观测性。核心价值是帮助开发团队在生产环境中高效管理 AI 提示词的生命周期，同时通过缓存等机制节省成本（官方称最高节省 90%）。

平台分为两部分：Pezzo Console（Web UI 控制台）和 Pezzo Client（SDK，Node.js / Python）。底层依赖 PostgreSQL + ClickHouse + Redis + Supertokens，全栈开源。

⚠️ 当前 GitHub README 较简，完整功能文档见 https://docs.pezzo.ai/

解决什么问题

  • 提示词散落：提示词分散在代码各处，无版本管理，改动风险高
  • 发布周期长：改一个提示词要重新发版，不能即时生效
  • 可观测性缺失：Prompt 执行情况（耗时、费用、成功率）无法追踪
  • 调试困难：Prompt 执行失败后无法回溯当时的输入/输出做调试
  • 成本不透明：不知道每个 Prompt 调用花了多少钱

快速安装

方式一：Docker Compose 一键启动（推荐）

# 克隆仓库
git clone https://github.com/pezzolabs/pezzo.git
cd pezzolabs/pezzo

# 启动基础设施（PostgreSQL + ClickHouse + Redis + Supertokens）
docker-compose -f docker-compose.infra.yaml up -d

# 部署 Prisma 迁移
npx dotenv-cli -e apps/server/.env -- npx prisma migrate deploy --schema apps/server/prisma/schema.prisma

# 启动服务端
npx nx serve server

# 启动 Pezzo Console（另一个终端）
npx nx serve console

服务启动后： - Console UI：http://localhost:4200 - API 健康检查：http://localhost:3000/api/healthz

方式二：开发模式（修改源码）

前置依赖：Node.js 18+、Docker

git clone https://github.com/pezzolabs/pezzo.git
cd pezzolabs/pezzo
npm install

# 启动基础设施
docker-compose -f docker-compose.infra.yaml up

# 部署迁移
npx dotenv-cli -e apps/server/.env -- npx prisma migrate deploy --schema apps/server/prisma/schema.prisma

# 启动服务端
npx nx serve server

# GraphQL 类型自动生成（另一终端）
npm run graphql:codegen:watch

# 启动 Console
npx nx serve console

⚠️ 需要配置 .env 文件（参考 .env.example）；Docker 部署还需额外创建 .env.docker。

核心用法

安装 Client SDK

Node.js：

npm install @pezzo/client

Python（⚠️ pip 安装包名需确认，官方 README 链接 https://pypi.org/ 但未给完整包名，推测为 pezzo）：

pip install pezzolabs-pezzo  # ⚠️ 建议 pip install pezzolabs-pezzo 前先查 pypi.org 确认准确包名

提示词管理（核心功能）

在 Pezzo Console（http://localhost:4200）里：

  1. 创建 Prompt：在 UI 上写提示词模板，支持变量插值
  2. 版本管理：每次修改自动版本化，可回滚
  3. 即时发布：改动无需发版，立即生效（通过 Client SDK 拉取）
  4. 测试：Console 内直接跑测试，验证 Prompt 效果

可观测性

Client SDK 自动上报每次 Prompt 调用的：

  • 请求/响应内容
  • 执行耗时（duration）
  • Prompt 费用（prompt cost）
  • 完成费用（completion cost）
  • 总费用

在 Console 的 Observability 面板可看到所有调用记录，支持时间线回溯和成本分析。

缓存

Pezzo 内置 Prompt 缓存能力（特性表里 Node.js/Python 客户端均标记 ✅），通过内容哈希去重相同 Prompt 调用，减少 API 消耗。

与 LangChain 集成

⚠️ GitHub issue #180 提及 LangChain 集成，具体实现方式需参考文档或 LangChain 官方 Pezzo 集成页面。

典型适用场景

  1. 团队 Prompt 管理：多个开发者共用一套提示词资产，避免散落代码各处
  2. 快速迭代：Prompt 调优不需要重新部署，通过 Console 即时生效
  3. 成本审计：想知道哪个 Prompt 最贵、调用频率如何，做精细化成本管理
  4. 问题排查：Prompt 执行失败后，从 Pezzo 历史记录里找回当时的完整 I/O 上下文
  5. 多模型切换：同一套 Prompt 通过 Pezzo 管理，通过 Client 配置切换不同的 LLM Provider

坑与注意

  • ⚠️ README 信息量有限：GitHub README 只有基础安装步骤，完整功能说明需查阅 https://docs.pezzo.ai/
  • ⚠️ Python Client 包名不确定：README 未明确 Python 包名，建议 pip install 前先去 pypi.org 搜索 "pezzo" 确认
  • ⚠️ 本地开发环境依赖多：需要 Node.js 18+、Docker、Prisma CLI 等，对新手有一定门槛
  • ⚠️ LangChain 集成状态未知：GitHub issue #180 开放中，LangChain 集成可能尚不稳定
  • 需要自备 PostgreSQL / ClickHouse / Redis，生产部署有一定运维成本
  • ⚠️ v0.3.9 版本号存疑：DSH Desktop 那边看到的 v0.3.9 与 Pezzo 无关，此处 Pezzo 最新版本请以 GitHub Releases 为准

与同类对比

Pezzo PromptLayer Helicone Agenta
提示词管理 ✅ 版本+即时发布 ✅ ❌ ✅
可观测性 ✅ ✅ ✅ ✅
缓存 ✅ ❌ ✅ ❌
成本追踪 ✅ ✅ ✅ ✅
开源 ✅ Apache 2.0 ❌ 闭源 SaaS ❌ 部分开源 ✅
Client SDK Node.js + Python Python + 其他 Proxy 层 Python
自托管 ✅ 完整开源 ❌ SaaS only Proxy 可自托管 ✅

Pezzo 的差异化是完全开源可自托管 + 提示词版本管理与即时发布，对比 PromptLayer 这类闭源 SaaS 在数据自主上有明显优势。

一句话推荐结论

需要团队级提示词版本管理+即时发布+完整可观测性，且希望完全自托管？Pezzo 是目前开源 LLMOps 里功能最完整的选项之一，Docker 一键部署即可开始。

  • 来源：https://github.com/pezzolabs/pezzo（README）· https://docs.pezzo.ai/（官方文档）
  • ⚠️ 版本标注：本文基于 GitHub README（未标注版本号）；建议 clone 前查看 GitHub Releases 确认最新版本
  • ⚠️ Python 包名：pip 安装前请在 pypi.org 搜索 "pezzo" 确认官方包名