把 LLM 应用的调试与线上监控放进一套自托管平台（Opik）

把一个 LLM 应用跑起来不难，难的是它上线之后出了问题怎么查。一次回答不对，可能是 prompt 改过，可能是检索召回的片段不对，也可能是 agent 在某一步工具调用上选错了参数。没有专门工具时，这些信息散在应用日志里，多步调用串不成一条链，改完 prompt 之后也说不清是变好还是变差。Opik 处理的就是这一段：把开发期的调试和生产期的监控收进同一套平台。

Opik 是 Comet 开源的 LLM 可观测与评估平台，主体用 Python 和 TypeScript 编写，接收应用的调用链与评估结果，输出 trace 树、实验指标和生产看板。

它可以整套自托管。在 Apache-2.0 许可证下，仓库里不只有客户端 SDK，还包括服务端后端、Web 应用、数据集、实验、评估、prompt 管理与在线评估等组件，团队能把数据留在自己的基础设施里。仓库地址是 https://github.com/comet-ml/opik，当前 22325 个 Star、1834 个 Fork，开放 Issue 178 个，最近一次提交是 2026-10-02。

它解决的是什么问题

没有这类平台的时候，查一个 LLM 应用的线上问题要靠应用自己的日志。多步 agent 的一次请求包含若干次模型调用和工具调用，日志里能看到的是一条条独立记录，哪一步的输出喂给了下一步、总耗时和 token 花了多少，得自己拼起来。

评估同样缺抓手。改一版 prompt 之后想知道效果，只能人工抽几条输入看输出，样本量和口径都不稳定。Opik 的做法是把调用链、评估结果和 prompt 版本都收到服务端，用同一套结构存下来，开发期和线上看到的是同一份数据。

README 给它的定位是覆盖完整生命周期，从开发阶段的第一条 trace 一直到生产监控。对已经在用它的团队来说，换环境不用换工具，这是它相比「开发时打日志、上线后接 APM」这套拼装方案省事的地方。

典型使用场景

• 写 LLM agent 的 ML 工程师：开发阶段接 Python SDK 或某个框架集成，在 trace 树里看多步 agent 的工具调用顺序和每一步的输入输出。
• 准备把原型推上线的 AI 团队：把测试用例整理成数据集，用实验对比两版 prompt，再用 PyTest 集成让评估跟着每次提交跑。
• 数据不能出内网的工程团队：自托管整套平台，包含后端与 Web 应用，不依赖托管服务。
• 负责线上值班的团队：用在线评估规则和看板盯反馈分数、trace 数量与 token 用量。

几个常见疑问

在 ARM 架构的 Docker 环境里装得上吗？

截至事实表记录，这个问题仍然待解决。有用户在 1.7.18 版本的 Python SDK 上遇到 ARM Docker 环境安装失败，Issue 下累计 14 条评论。仓库里没有说明已经修复。

用一个客户端连续发请求，成本能统计完整吗？

不一定。有用户反馈，实例化一个 google genai 客户端后连续发起多个请求，链式请求的成本追踪对不上，这条 Issue 目前也是待解决。相近的问题此前出现过一次：OpenAI TTS 模型的成本与用量无法通过 OpenAI 集成追踪，那条已经解决。

标注队列提示「所有条目都已处理」，是队列真的做完了吗？

曾经不是。有用户在不完整的标注队列上看到这条提示，Issue 拿到 18 条评论，目前标记为已解决。同一方向的需求也提过——在项目里一次选中多条 trace 批量标注，这条同样已经解决。

主要功能

• AI Agent 追踪与可观测：对 LLM 调用、会话日志和 agent 活动做深度追踪，多步 agent 与工具调用会呈现为完整的 trace 树。接入方式有两种，用 Python SDK 或 TypeScript SDK 手写埋点，或者用现成的框架集成；README 提到支持 Google ADK、Autogen、Flowise AI 等，多数主流框架有原生集成。
• LLM 评估：数据集（Datasets）与实验（Experiments）负责组织测试集和对比结果；LLM-as-a-judge 指标覆盖幻觉检测（hallucination）、moderation，以及 RAG 评估里的 Answer Relevance 与 Context Precision。
• 标注：通过 Python SDK 或 UI 给 trace 和 span 打反馈分数。UI 侧支持在项目里一次选中多条 trace 批量标注。
• Prompt Playground：在界面里试 prompt 和模型。provider 配置页可以选择 AI 服务商并填 API Key，此前只能选 OpenAI，后来 Azure OpenAI 也进了 Playground。
• 生产监控与在线评估：看板展示反馈分数、trace 数量、token 用量随时间的变化；在线评估规则把 LLM-as-a-judge 指标接到线上流量上，用来发现生产问题。README 说明这套设计面向 40M+ traces/day 的规模。
• Opik Guardrails 与 Opik Agent Optimizer：前者用于实现安全与负责任 AI 的相关实践，后者是独立的 SDK，用来优化 prompt 和 agent。
• CI/CD 评估：提供 PyTest 集成，把 LLM 流水线的评估放进每次提交。

版本迭代节奏很快，2026-09-28 到 2026-10-01 之间连着发了 2.2.83 到 2.2.87 五个版本，改动集中在后端性能、前端修复与模型价格文件更新上。

安装与最短示例

服务端和 SDK 分开装。仓库根目录有两个安装脚本，opik.sh 面向 Linux 与 macOS，opik.ps1 面向 Windows；仓库里另有 deployment/、extensions/、scripts/ 等目录，以及一份 .env.template 环境变量模板。

# 仓库根目录
opik.sh      # Linux / macOS
opik.ps1     # Windows

本篇拿到的 README 节选没有覆盖到这两个脚本的调用方式与参数，也没有 Quick Start 里 SDK 安装命令的原文，所以这里不给出具体命令行。要看最短跑通的步骤，去官方文档的 Quick Start：https://www.comet.com/docs/opik/quickstart/ 。中文说明在仓库的 readme_CN.md，另外还有德语、西班牙语、法语、日语版本。

客户端侧分 Python SDK 与 TypeScript SDK，都放在 sdks/ 目录下。接入时要么选 SDK 自己埋点，要么选一个框架集成，完整说明在 https://www.comet.com/docs/opik/ 。

关键参数

配置分三块，节选只覆盖到第一块的存在，没有字段清单。

• 服务端环境变量：仓库根目录的 .env.template，大小 0.8 KB。节选没有列出里面的字段名。
• 部署与代码目录：deployment/、extensions/、scripts/、apps/（Web 应用）、sdks/（客户端 SDK）、tests_end_to_end/ 与 tests_load/（端到端测试与负载测试）。
• Playground 的服务商配置：在配置页选 AI 服务商并填 API Key，Azure OpenAI 已支持。

在线评估规则、Guardrails、数据集这些属于平台内的配置对象，节选没有给出字段定义，以官方文档为准。

结果在哪里看

结果主要在 Opik 的 Web 界面里，CI 场景下还要看测试输出。

• trace 页面：一条请求展开成 trace 树，逐层看 span 的输入输出。
• Dashboard：反馈分数、trace 数量、token 用量随时间的变化。
• Experiments 页面：实验之间的对比，页面上有列选择器，会显示已选列的数量。
• 标注队列：待标注的 trace 列表与完成情况。
• Prompt Playground：试 prompt 与模型的即时结果。
• CI 输出：PyTest 集成把评估结果打在测试报告里。

实际使用中的坑

Google ADK 集成里出现过断言错误。使用者在 after_agent_callback 里处理 trace_data 时报 Assert，Issue 累计 19 条评论，目前标记为已解决。这条属于框架集成的适配问题，升级 SDK 前值得先看对应 Issue。

trace 会挂到错误的 thread 上。有用户反馈 UI 里 trace 显示在不对的会话串下，15 条评论，已解决。多轮对话场景下这类问题会直接影响排查结论，遇到时先确认版本。

System Message 放在最后时，Pretty Input 渲染失败。同样是 UI 侧的问题，15 条评论，已解决。消息顺序不是常见写法时才容易撞上。

部分完成的 trace 上报时机偏晚。有用户提出希望 trace 边到边 flush，不等顶层函数结束，16 条评论，已解决。对长时运行的 agent 来说，早期版本的等待行为会让调试看到的数据滞后。

和同类的差别在哪

两点取舍要说明。团队已经在用 MLflow 管模型实验、又不打算再维护一套服务，继续用原有的评估与追踪更省事，Opik 在这里意味着额外要部署和运维的系统，这是它不如对比项的地方。反过来，愿意为 agent 的多步 trace 树、在线评估规则和整套自托管多搭一套服务，Opik 才划算；生产环境跑在 ARM 架构的 Docker 上，还要先确认安装问题是否已修掉。

合规前提

Opik 追踪的是应用内部的对话与调用数据。接入之前要确认你对自己要追踪的应用、账号与数据拥有处置权，不要把它接到未获授权的第三方系统上去采集数据。生产 trace 里往往带着真实用户的输入输出，可能包含个人信息，采集范围、留存时长和告知方式需要按你所在地区的合规要求来定。

整套平台可以自托管，数据留在自己的基础设施里，这是这类场景下比较容易过审的一种做法。自建一套评估环境也意味着运维责任落在自己这边。

自己写 LLM agent 或 RAG 应用、需要把调试与线上监控放在一套自托管平台里的工程团队，适合用 Opik；只想看线上调用量和报错、不打算做数据集与评估的个人开发者，用应用日志加一套通用 APM 就够了，不必为此再维护一套平台。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。