foglamp-labs/foglamp

解決的問題

Foglamp 為 Vercel AI SDK 提供專用的可觀測性層。透過可視化複雜多步驟代理工作流程中傳送到模型的精確提示與回應、實際成本、延遲時間、以及令牌使用量，解決了 AI 代理的「黑箱」問題。

如何運作

Foglamp 透過一個遙測收集器整合至 TypeScript 應用。呼叫 registerTelemetry(foglamp()) 後，它會自動追蹤每次 generateText 和 streamText 的呼叫。

此系統由三個主要元件組成：

• SDK：客戶端程式庫，用於捕捉跨度（如 LLM 步驟或工具呼叫等單位工作）與追蹤（頂層呼叫）。
• 輸入 API：一個寫入密集型服務，負責驗證請求，使用 OpenRouter 價格在輸入時計算成本，並將資料批量插入 ClickHouse。
• 儀表板：一個基於 Next.js 的 Web 應用，從 ClickHouse 和 Postgres 讀取資料，顯示性能指標、瀑布式追蹤檢視與成本分解。

適用對象

使用 TypeScript 和 Vercel AI SDK（版本 4 到 7）並需要監控其 AI 代理在生產環境中的效能與財務成本的開發者。

主要亮點

• 詳細成本追蹤：按令牌維度（提示、完成、快取等）計算成本，並支援自訂價格覆蓋。
• 分散式追蹤：提供代理步驟與工具呼叫的瀑布視圖，包含每個跨度的精確輸入與輸出。
• 效能監控：追蹤 p50/p95/p99 延遲與首次令牌時間（TTFT）。
• 可自托管：可透過 Docker Compose 使用 Postgres、ClickHouse 和 Redis 完全部署。
• 整合告警：基於閾值的成本、延遲、錯誤率與令牌使用量的電子郵件通知。