用 FastAPI+Next.js+Postgres+Redis+Celery 自托管 AI Agent 全链路追踪与评估平台

方案简介

PandaProbe 是一个面向 AI Agent 工程的开源平台，目标是帮助团队协作地追踪（trace）、评估（evaluate）、监控（monitor）和调试（debug）AI Agent。

项目提供两种使用方式：

• PandaProbe Cloud：官方托管，提供免费档，无需信用卡。
• Self-host：用户自行在自己的基础设施上部署运行，适合对数据合规、私有部署有要求的团队。

整套系统采用前后端分离 + 异步任务总线的经典微服务架构：前端是基于 Next.js 的 Dashboard，后端是 FastAPI 应用服务，配合 PostgreSQL 持久化、Redis 作为 Celery 的 broker 与缓存、Celery Worker 处理异步摄取与评估任务，并通过 LiteLLM 抽象层调用 LLM 作为评估裁判（LLM-as-a-judge）。整体通过 Docker Compose 一键拉起，适合希望开箱即用地获得 Agent 可观测性与评估能力的中小团队。

亮点与能力

根据仓库材料，PandaProbe 自托管版本提供以下能力：

• 一键自托管部署：通过 git clone + ./start.sh 即可在本地拉起完整平台，前提是已安装并运行 Docker。
• Web Dashboard：内置基于 Next.js 的可视化面板，运行在 http://localhost:3000。
• OpenAPI/Scalar API 文档：FastAPI 服务暴露在 http://localhost:8000/scalar 供调试与集成。
• Agent 调用链路追踪（Tracing）：通过 SDK/HTTP Client 上报 trace 和 span，异步落入 Postgres 持久化。
• Agent 自动评估（Evaluation）：通过 LLM-as-a-judge 方式调用 LiteLLM 统一接口的模型，对 Agent 输出进行评分与裁决。
• 会话与多维过滤查询：支持按 sessions、traces 进行分页查询与过滤。
• 管理面与数据面双认证：管理操作使用 IdP Bearer Token（Supabase/Firebase），数据上报使用 API Key + Project Name。
• 多组织/多项目（Org/Project）模型：支持用户归属组织，组织下再细分为项目，便于团队协作与资源隔离。
• 客户端 SDK 与集成：官方提供 Python PyPI 包 pandaprobe，并提供与多种框架的 integrations 文档。
• CI/CD 工作流完备：仓库内置 build、lint、unit test、integration test、CodeQL 等 GitHub Actions 工作流。

组成与分工

仓库 Services 表格与 Architecture 序列图明确给出了整套自托管栈的组成与分工：

• frontend（Next.js）：Web Dashboard，端口 3000，提供可视化追踪、评估与监控界面。
• app（FastAPI）：核心 API 服务，端口 8000，对外同时承担 Management Plane（Bearer Token）与 Data Plane（API Key + Project）两类入口，负责 /traces、/sessions、/evaluations 等路由。
• worker（Celery Worker）：后台消费者，从 Redis 拉取 ingestion 与 eval 任务，把 trace/span 与评估结果写回 Postgres，并通过 LiteLLM 调用 LLM 作为 judge。
• beat（Celery Beat）：Celery 定时调度器，配合 worker 处理周期任务。
• postgres（PostgreSQL 16）：端口 5432，主数据存储，承载用户/组织/项目/trace/span/evaluation 等结构化数据。
• redis（Redis 7）：端口 6379，兼作 Celery 的 broker 与应用缓存，负责异步任务入队。
• Auth Service / IdP（Supabase 或 Firebase）：外部身份提供商，管理面使用其颁发的 Bearer Token 完成认证。
• Identity Service：组织与项目上下文解析层，把用户、org、project 三层关系落到 Postgres。
• Trace Service：管理 trace/span 的写入与查询；写入路径走 Redis 异步消费，读取路径走 Postgres 直接查询。
• Eval Service：触发与编排评估任务，调度 worker 通过 LiteLLM 调用 LLM 完成 LLM-as-a

实施步骤

1. 克隆仓库并进入目录

按 README 提供的脚本直接执行：

git clone https://github.com/chirpz-ai/pandaprobe.git
cd pandaprobe
./start.sh

2. 等待 Docker Compose 拉起全部服务

./start.sh 会通过 Docker Compose 启动以下容器：frontend（Next.js Dashboard）、app（FastAPI）、worker（Celery Worker）、beat（Celery Beat）、postgres（PostgreSQL 16）、redis（Redis 7）。

3. 打开 Dashboard 与 API 文档验证启动

• Dashboard — http://localhost:3000
• API reference — http://localhost:8000/scalar

4. 配置 IdP 与组织/项目

按照架构图，管理面（Management Plane）的 Authorization: Bearer 需要先由外部 IdP（Supabase 或 Firebase）签发；之后通过 /user、/organizations、/projects 等端点创建组织与项目上下文。

5. 在客户端启用 SDK 上报 trace

数据面（Data Plane）使用 X-API-Key + X-Project-Name 调用：

• POST /traces：SDK 异步上报 trace 与 span，API 会把任务丢到 Redis，由 Worker 持久化到 Postgres，HTTP 立即返回 202 Accepted。
• GET /traces, /sessions：同步查询 Postgres，支持分页与过滤。
• POST /evaluations：触发 LLM-as-a-judge 评估，结果由 Worker 通过 LiteLLM 调用模型后写回 Postgres。

如需进一步使用，可参考官方文档的 quickstart 与 integrations 章节完成客户端 SDK 接入。

优缺点

• ✓ Docker 一键启动，自托管门槛低
• ✓ 管理面与数据面双认证清晰
• ✕ 依赖外部 IdP（Supabase/Fi
• ✕ LLM judge 评估需自行接入模型

出处

本方案挖掘自开源项目 chirpz-ai/pandaprobe，方案内容与实施命令均来自其 README 原文。