opik

opik — 开源 LLM 可观测性、评估与优化

Opik（由 Comet 构建）简化了 LLM 应用的整个生命周期：深入追踪 LLM 调用和 Agent 活动、LLM-as-a-judge 评估、实验管理、大规模生产监控（每天 4,000 万条以上追踪），以及 Opik Agent Optimizer 和 Opik Guardrails。此技能是一个以路由为先的封装——它会选择合适的部署模式、接入 SDK，并推动追踪 → 评估 → 监控 → 优化的工作流。

何时使用此技能

• 用户要求安装或配置 Opik（pip install opik、 opik configure、./opik.sh）
• 用户需要追踪 LLM 调用或 Agent——通过 @opik.track 或 框架集成（OpenAI、Anthropic、LangChain、LangGraph、LlamaIndex、 CrewAI、DSPy、Haystack、Ollama、Bedrock、Vercel AI SDK、Pydantic AI，……）
• 用户需要 LLM-as-a-judge 指标：幻觉检测、内容审核、 答案相关性、RAG 的上下文精确率/召回率
• 用户需要 Datasets + Experiments 评估，或在 CI/CD 中集成 PyTest 的 LLM 评估
• 用户需要生产环境 LLM 监控仪表板、在线评估规则、提示词 playground 实验、Agent/提示词优化或防护栏

何时不使用此技能

• 技术栈是 LangSmith，而非 Opik → 使用 langsmith
• 用户需要 通用服务仪表板/告警（非 LLM 遥测、 正常运行时间、基础设施指标）→ 使用 monitoring-observability
• 用户需要的是 离线数据集/KPI 解读，而不是 LLM 追踪/评估接入 → 使用 data-analysis
• 用户正在对应用/容器日志进行 根因日志取证分析 → 使用 log-analysis

前置条件

要求	备注
Python 3.8+（SDK）	pip install opik 或 uv pip install opik
Docker + Docker Compose	仅用于通过 ./opik.sh 在本地自托管
Kubernetes + Helm	仅用于可扩展的自托管部署
Comet.com 账号	仅用于零配置云端选项

操作说明

步骤 1 — 选择服务模式

模式	适用场景	方式
Comet.com 云端（最简单）	快速开始，无需维护	创建免费账号，获取 API 密钥 + 工作区
Docker Compose（本地）	本地开发与测试，完全掌控	git clone https://github.com/comet-ml/opik.git && cd opik && ./opik.sh → UI 位于 localhost:5173
Kubernetes / Helm	生产级自托管	上游 Helm chart 指南

Docker 服务配置文件（开发场景）：

./opik.sh              # full Opik suite (default)
./opik.sh --infra      # infrastructure only (databases, caches)
./opik.sh --backend    # infrastructure + backend services
./opik.sh --guardrails # enable guardrails with any profile
./opik.sh --help       # troubleshooting

Windows：powershell -ExecutionPolicy ByPass -c ".\opik.ps1"。

步骤 2 — 安装并配置 SDK

pip install opik        # or: uv pip install opik
opik configure          # prompts for server address (self-hosted) or API key + workspace (cloud)

也可以在代码中配置：

import opik
opik.configure(use_local=True)   # local self-hosted instance

也提供 TypeScript 和 Ruby（通过 OpenTelemetry）SDK，详见 客户端参考文档。

步骤 3 — 记录追踪

如果框架受支持，请优先使用原生集成（提供 50 多种： ADK、AG2、Agno、Anthropic、Autogen、Bedrock、CrewAI、DSPy、Dify、Flowise、 Gemini、Haystack、Instructor、LangChain、LangGraph、LiteLLM、LlamaIndex、 Mastra、Ollama、OpenAI、OpenAI Agents、OpenRouter、OpenTelemetry、Pydantic AI、 Ragas、Semantic Kernel、Smolagents、Spring AI、Vercel AI SDK、WatsonX，……）。 完整表格请参阅 references/commands.md。

适用于任意代码路径的备用方案——track 装饰器（支持嵌套，可与集成组合使用）：

import opik

@opik.track
def my_llm_function(user_question: str) -> str:
    # Your LLM code here
    return "Hello"

通过 SDK 或 UI 为追踪/跨度添加反馈分数标注。

步骤 4 — 使用 LLM-as-a-judge 指标进行评估

from opik.evaluation.metrics import Hallucination

metric = Hallucination()
score = metric.score(
    input="What is the capital of France?",
    output="Paris",
    context=["France is a country in Europe."],
)
print(score)

内置评判器包括幻觉、内容审核、答案相关性、上下文精确率/召回率；同时也支持启发式指标和自定义指标。

步骤 5 — 数据集、实验和 CI 门禁

• 管理数据集并运行实验，在开发过程中比较不同的提示词／模型变体
• 通过 PyTest 集成将评估接入 CI/CD，让回归问题阻止合并
• 在 Prompt Playground 中迭代提示词／模型

步骤 6 — 生产监控和优化

• Opik 专为大规模场景打造：每天可接收 4,000 万条以上的追踪记录
• 在 Opik Dashboard 中跟踪反馈评分、追踪记录数和 token 用量
• 添加在线评估规则（对生产流量使用 LLM-as-a-judge），实时发现问题
• 使用 Opik Agent Optimizer（专用 SDK）改进提示词／Agent，并通过 Opik Guardrails 落实安全 AI 策略

步骤 7 — 与 jeo-skills 并行的插件式安装

此技能文件夹可通过标准 jeo-skills 流程以插件形式安装，从而将封装程序、参考资料和安装脚本部署到磁盘，以供任何受支持的 Agent 运行环境使用：

# Project install (writes into .agents/skills/opik/)
npx skills add https://github.com/akillness/jeo-skills --skill opik

# Global install for every detected agent
npx skills add -g https://github.com/akillness/jeo-skills --skill opik

# Target specific agents
npx skills add -g https://github.com/akillness/jeo-skills --skill opik -a claude-code -a codex -y

此技能还提供 scripts/install.sh 作为一键安装程序，涵盖 SDK 安装（uv → pip 回退）和可选的本地自托管（OPIK_INSTALL_MODE=local）。

输出格式

当用户请求 opik 提供帮助时，返回一份简明概要：

# opik Routing Brief

## Scope
- Server mode: cloud | docker-local | kubernetes | undecided
- SDK: python | typescript | ruby-otel
- Lifecycle stage: tracing | evaluation | ci-gate | production-monitoring | optimization | guardrails

## Recommended next move
- install-sdk | opik-configure | start-local-server | wire-integration | add-judge-metric | create-dataset-experiment | enable-online-rules

## Why
- 2-3 bullets grounded in the user's packet

## Route-outs
- `langsmith` when the observability stack is LangSmith
- `monitoring-observability` for non-LLM dashboards/alerts
- `data-analysis` for offline KPI/metric interpretation

最佳实践

1. 先使用云服务或 ./opik.sh，不要从 Kubernetes 入手——Helm 适用于生产规模；本地 Docker Compose 可在几分钟内解答“追踪功能是否正常”。
2. 如果框架列在支持表中，优先使用原生集成，而不是手动编写 @opik.track——集成会自动捕获提供方元数据（token、模型、延迟）。
3. 升级自托管服务之前先查看变更日志——例如，v1.7.0 引入了破坏性变更。
4. 评判指标需要结合上下文——Hallucination 和 RAG 指标会根据你传入的 context 评分；上下文为空会导致评分产生误导。
5. 使用小型、稳定的数据集设置 CI 门禁——与 PyTest 集成的实验应快速且具确定性；大型扫描应安排在定时运行中。
6. 将生产检查转换为在线评估规则，不要针对实时流量反复运行离线实验。

参考资料

• 上游代码库：https://github.com/comet-ml/opik
• 文档：https://www.comet.com/docs/opik/
• 快速入门：https://www.comet.com/docs/opik/quickstart/
• 集成概览：https://www.comet.com/docs/opik/integrations/overview/
• 指标概览：https://www.comet.com/docs/opik/evaluation/metrics/overview/
• 自托管（本地）：https://www.comet.com/docs/opik/self-host/local_deployment
• 自托管（Kubernetes）：https://www.comet.com/docs/opik/self-host/kubernetes/
• 安装脚本：scripts/install.sh
• 命令和集成参考：references/commands.md
• 相关技能：../langsmith/SKILL.md、../monitoring-observability/SKILL.md、 ../data-analysis/SKILL.md、../log-analysis/SKILL.md
• 许可证：Apache-2.0（参见上游 LICENSE）