comet-ml/opik · 上手攻略

仓库：comet-ml/opik
链接：https://github.com/comet-ml/opik
分类：ai
作者：Tom
更新：2026-07-09

是什么

Opik 是由 Comet 出品的开源 LLM 应用全生命周期管理平台，覆盖从原型开发到生产监控的完整流程。它的核心功能分三大块：可观测性（Observability）、自动化评估（Evaluation）、生产监控（Production Monitoring）。

Opik 脱胎于 Comet 十年在 ML 领域积累的实验管理经验，专门面向 LLM 应用、RAG 系统和 Agentic Workflow 提供深度追踪能力。其 Python SDK 与主流框架（LangChain、OpenAI、Anthropic、Google ADK、AutoGen、Flowise AI 等）无缝集成，官方标称单实例可承载 40M+ traces/天 的生产级吞吐量。

一句话概括： 如果你在构建 LLM 应用，需要知道"模型在做什么、输出质量如何、什么时候出问题"——Opik 就是来回答这些问题的。

解决什么问题

构建 LLM 应用的团队普遍面临几个痛点：

黑盒调试：LLM 调用分散在代码各处，没有统一视图，出了问题很难定位是 prompt、model 还是 context。
质量评估靠人工：没有量化指标，每次迭代靠人肉看输出，效率低且主观。
生产环境两眼一抹黑：上线后没有监控，不知道延迟、token 消耗、错误率的趋势。
实验版本管理混乱：改了一个 prompt 后没有记录，很难对比新旧效果。

Opik 对应地提供：分布式 trace 追踪、LLM-as-a-Judge 自动评估、可配置监控 Dashboard，以及 Experiment 管理功能。

快速安装

方式一：Opik Cloud（推荐尝鲜）

注册免费账号：comet.com/opik，获取 API Key，然后：

pip install opik
opik configure   # 交互式输入 API Key

方式二：本地 Docker 部署（完全自托管）

git clone https://github.com/comet-ml/opik.git
cd opik
./opik.sh          # Linux/macOS，默认启动完整套件（前端 + 后端 + 数据库）
# Windows:
powershell -ExecutionPolicy ByPass -c ".\opik.ps1"

服务启动后访问 http://localhost:5173 即可打开 Opik Dashboard。

opik.sh 支持多种 Profile：

命令	启动内容
`./opik.sh`	完整套件（默认）
`./opik.sh --infra`	仅基础设施（数据库、缓存）
`./opik.sh --backend`	基础设施 + 后端服务
`./opik.sh --guardrails`	开启 Guardrails 安全功能

Python SDK

pip install opik

注意：Opik Python SDK 最低支持 Python 3.9（建议 3.10+）。TypeScript SDK 也可用：npm install opik。

核心用法

1. 用 `@track` 装饰器追踪函数调用（最简方式）

from opik import track

@track
def my_function(input: str) -> str:
    # 任意 LLM 调用
    return f"processed: {input}"

所有对 my_function 的调用都会自动记录为一条 Trace，嵌套调用也会保留层级结构。

2. 追踪 OpenAI 调用

from opik.integrations.openai import track_openai
from openai import OpenAI

client = OpenAI()
client = track_openai(client)  # 包装后所有调用自动记录

completion = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

3. 追踪 LangChain 链

from opik.integrations.langchain import OpikTracer

# 在 LangChain agent/chain 运行前注入
opik_tracer = OpikTracer()
# 在 chains.run() 或 agent.run() 时传入 callbacks=[opik_tracer]

4. 手动创建 Trace（高级用法）

from opik import Opik

client = Opik()

trace = client.trace(
    name="My LLM Application",
    input={"prompt": "What is the capital of France?"},
    metadata={"user_id": "123"},
)
trace.log("info", "LLM call started")
# ... 执行 LLM 调用 ...
trace.end()
await client.flush()  # 确保数据上传

5. 评估功能：Dataset + Experiment

from opik import Opik, track
from opik.evaluation.metrics import AnswerRelevance

client = Opik()
dataset = client.create_dataset(
    name="qa-eval-set",
    description="Q&A 评估数据集",
    data=[
        {"input": "法国的首都是？", "expected": "巴黎"},
        {"input": "日本的首都是？", "expected": "东京"},
    ]
)

# 运行评估
experiment = client.evaluate(
    dataset=dataset,
    task=lambda x: ask_llm(x["input"]),
    metrics=[AnswerRelevance()],
)

内置评估指标包括：Hallucination、Moderation、Answer Relevance、Context Precision 等，均基于 LLM-as-a-Judge。

6. Pytest 集成（CI/CD 场景）

# test_llm_app.py
import pytest
from opik.plugins.pytest import assert_trace

def test_llm_response_quality():
    response = ask_llm("法国的首都是？")
    assert "巴黎" in response
    assert_trace("test_llm_response_quality")  # 自动记录到 Opik

运行：pytest test_llm_app.py

典型适用场景

场景	Opik 的价值
RAG 系统调优	追踪 retrieval + generation 完整链路，定位 context 泄漏、幻觉问题
Agent 开发	记录多轮 tool calling、ReAct loop，清晰看到 agent 决策路径
Prompt 迭代	用 Experiment 对比不同 prompt 版本的得分，量化改进效果
生产监控	Dashboard 展示 token 消耗、错误率、延迟趋势，设规则触发告警
CI/CD 质量门禁	Pytest 插件让每次 PR 都跑 LLM 评估，防止质量退化

坑与注意

自托管数据库依赖：完整 Opik 部署包含 ClickHouse、Redis、PostgreSQL 等组件，./opik.sh 会通过 Docker Compose 启动，首次启动需要良好的网络连接拉取镜像。
采样率控制：生产环境 trace 量极大，建议通过 SDK 的 sample_rate 参数做采样，避免存储成本失控。官方默认全量记录，但 40M traces/天的规模需要相应存储规划。
异步_flush：Python SDK 中 await client.flush() 不是总是必需的（SDK 有后台自动 flush），但在脚本结束前主动调用是良好习惯，可以避免数据丢失。
版本兼容性：Opik 迭代较快，截至 2026 年 7 月最新版请以 Changelog 为准。Python SDK 与自托管 Opik Server 版本需大致匹配。
Guardrails 尚在完善：Opik Guardrails 功能（内容安全过滤）相对较新，复杂场景建议结合专业安全层（如 Rebuff）使用。
API Key 安全：.env 中配置 Opik API Key 时，确保 .env 已加入 .gitignore，切勿提交到代码仓库。

与同类对比

工具	定位	优势	劣势
Opik	全生命周期 LLM 平台	开源、可自托管、评估能力强、与 Comet 生态打通	相对年轻，品牌认知不及 LangSmith
LangSmith	全生命周期 LLM 平台	LangChain 官方集成、成熟度高	主要 SaaS，自托管有限制
Helicone	LLM 可观测性	轻量、代理层实现无需改代码	功能偏薄，无评估能力
Promptfoo	Prompt 评估	离线评估、测试用例驱动	非实时追踪，不适合生产监控
Phoenix (Arize)	ML/LLM 可视化	强在 tracing 和 embedding 可视化	评估能力较弱

Opik 最适合：需要开源可自托管、对 LLM 应用有完整可观测性 + 自动化评估需求的团队，尤其如果你已经在用 Comet 或想要摆脱 SaaS 锁定。

一句话推荐结论

Opik 是当前开源生态中最具性价比的 LLM 全栈可观测平台——轻量接入、评估强大、生产可用，如果你还在靠 print 调试 LLM 应用，Opik 值得今天就装起来。