Pezzo：开源提示词管理平台

为什么需要 Pezzo：提示词散落在代码里 → 提示词全生命周期管理

多数 LLM 应用把提示词硬编码在业务代码中。改一句系统指令要改代码、走评审、构建镜像、重新发布；同一个提示词在开发、预发、生产环境之间没有隔离机制；线上效果变差只能靠翻日志猜测原因，难以定位是「哪一版提示词」导致的问题。团队中多个成员各自维护 prompt 字符串，合并冲突不断，提示词的迭代速度被应用发版节奏牢牢卡住。

Pezzo 把提示词作为独立的受管对象。控制台内创建项目与开发、预发、生产环境；每次编辑生成新版本；测试通过后把版本「提升」到目标环境。应用通过 @pezzo/client SDK 在运行时按环境拉取并执行提示词——服务端拿到模板与变量后调用模型并回传结果。提示词变更即刻生效，代码零改动。每次执行记录都携带版本号、token、成本与延迟，质量回溯有据可查。

与同类工具的气质差异在于切入点：LangSmith 从「可观测与评估」切入，Pezzo 从「提示词文件管理」切入，先解决提示词的版本与发布，再附带执行观测。Pezzo 不绑定 LangChain，可以与任意 Node.js 应用直接集成，架构决策更轻。

安装与环境配置：5 步就绪

前置条件：Node.js 16+、Docker。以下步骤覆盖自托管（Self-hosted）完整流程，使用 Pezzo Cloud 时跳过第 2、3 步。

1. 初始化：执行 npx pezzo@latest init，按提示选择 Self-hosted（自托管）或 Cloud（托管云）。

2. 生成配置：初始化脚本自动生成 docker-compose.yml 与 .env 文件。

3. 启动服务：执行 docker compose up -d，服务端 API 与控制台随之启动。

4. 验证：浏览器访问控制台默认地址 http://localhost:4200（以 .env 中实际配置为准），注册组织账号后进入工作台，能看到项目与环境管理界面。

5. 安装 SDK：在应用项目里安装客户端包，并在 .env 中配置 PEZZO_API_KEY 与 PEZZO_SERVER_URL。

使用 Pezzo Cloud 时只需在官网创建组织、获取 API Key，并把 SDK 的 serverUrl 指向云地址，无需本地容器。

# 1. 初始化（生成 docker-compose.yml 与 .env）npx pezzo@latest init # 2. 后台启动服务端与控制台docker compose up -d # 3. 应用侧安装客户端 SDKnpm install @pezzo/client

快速上手：15 分钟跑通第一个受管提示词

核心流程是「建项目 → 写提示词 → 测试 → 用 SDK 调用」，全程与业务代码解耦。按以下步骤操作：

1. 打开控制台，创建项目（如 my-app），系统预置 Development、Staging、Production 三个环境；

2. 在 Projects → my-app → Prompts 中点击 Create New Prompt，命名为 hello-prompt；

3. 选择模型服务商（OpenAI、Azure OpenAI、Anthropic 等）与模型，并在服务端配置对应的 Provider API Key；

4. 在编辑器中编写模板：你是一个客服助手，请回答：{{input}}；

5. 点击测试按钮，填写 input 变量的值并发送，查看模型回复、token 用量与成本估算；

6. 在应用侧安装 SDK，填入控制台 Settings → API Keys 生成的 Key 与服务端地址，调用 hello-prompt。

运行后，在控制台的执行记录（Executions）中能看到本次调用的完整元数据。进阶用法：多步骤场景可用 Trigger 把多个提示词串联成流水线，前一步的输出作为后一步的输入，适合需要「先总结、再生成」的复合任务。

import { Pezzo } from "@pezzo/client"; const pezzo = new Pezzo({  apiKey: process.env.PEZZO_API_KEY,        // 控制台 Settings → API Keys 生成  serverUrl: process.env.PEZZO_SERVER_URL,  // 自托管默认为 http://localhost:3000}); const result = await pezzo.prompts.run("hello-prompt", {  environment: "Production",  variables: { input: "你好，介绍一下你们" },}); console.log(result.data); // 模型最终回复

核心能力详解：4 大支柱

支柱一：版本与环境管理。每个提示词保存即产生新版本，可对任意历史版本回看、对比与恢复。「提升（Promote）」操作把指定版本发布到目标环境，应用侧无需发版即切换到新版本。多环境隔离避免生产提示词被误改，也保证开发调试不消费生产版本。

支柱二：在线测试工作台。控制台内置测试面板，直接填写变量并发送，实时返回模型输出、耗时、token 与成本。发布前即可评估提示词质量，也让非开发角色（运营、标注人员）能参与提示词迭代，无需接触代码仓库。

支柱三：执行可观测与成本追踪。每次 SDK 调用的执行记录进入控制台，包含提示词名称、版本、环境、模型、延迟、token 与成本。按时间与环境筛选后，可快速定位「哪一次提示词变更导致效果下降」，成本异常也能追溯到具体提示词，这是纯代码管理方式做不到的。

支柱四：团队协作与密钥隔离。采用组织-项目两级结构，API Key 分环境使用，生产 Key 不暴露给开发环境；模型服务商凭据只保存在服务端，客户端无需也不应持有 OpenAI 等第三方密钥，降低泄露风险。

生产部署与监控：从上线到运维

部署方式一：自托管（Self-hosted）。生产环境建议把 init 生成的默认数据库配置替换为独立托管的 PostgreSQL（带持久化卷），并妥善保管 .env 中的密钥。对外提供服务时加反向代理与 HTTPS，防止明文流量。升级通过 git pull 拉取新版本后执行 docker compose up -d --build 完成。

部署方式二：Pezzo Cloud。官方托管，免运维。将 SDK 的 serverUrl 指向云地址，API Key 在云端控制台统一管理，适合没有专职运维的团队，先跑通业务再评估是否迁回自托管。

可观测性：以控制台执行记录为运维入口，建立三类检查：调用成功率（出现异常时作为版本回滚依据）、单次成本与 token 趋势（用于预算告警）、延迟异常（定位模型或网络问题）。任何生产提示词变更前后，对比同环境的执行指标即可判断「变好还是变坏」，形成发布-观测-回滚的闭环。

<p class="para-label">避坑清单：</p>

<ul class="dash-list"><li>坑 1：包名混淆——pezzo 是 CLI（初始化/本地开发），@pezzo/client 是应用内 SDK，装错包轻则命令无效、重则运行时报错。</li><li>坑 2：端口与地址以 init 生成的 .env 为准——默认控制台 4200、服务端 3000，但被占用或自定义后会变化，拼接 serverUrl 时以实际配置为准。</li><li>坑 3：生产环境必须换独立数据库——init 自带的默认 Postgres 适合试用，容器重建即丢数据；生产请使用托管数据库并开启持久化与备份。</li><li>坑 4：变量未替换会静默发给模型——模板 {{input}} 与调用时 variables 字段必须同名，漏传时占位符原样进入模型，输出质量莫名下降，排查时先检查这里。</li></ul>

AI 应用场景

常见误区

面试题

参考来源

• webpagePezzo 官网产品介绍与托管云入口