opik

Opik SDK 参考

Opik 是一个开源的 LLM 可观测性平台。本技能是 SDK 的参考资料。如需逐步为代码库添加检测（检测框架、添加配置、发出并验证跟踪记录），请使用面向任务的 opik-instrument 技能。

核心概念

跟踪记录是一条执行路径（一个请求 → 一个响应）。跨度是其中的操作，并构成层级结构。

跨度类型——唯一有效的值

类型	用途
general	编排、Agent 入口点
llm	模型调用
tool	工具、检索、API / DB 调用
guardrail	安全 / 验证检查

请勿使用 retrieval 或任何其他值。

Python — 跟踪

import opik

@opik.track(name="agent", type="general")
def agent(query: str) -> str:
    return generate(retrieve(query))

@opik.track(type="tool")
def retrieve(query): ...

@opik.track(type="llm")
def generate(ctx): ...

opik.flush_tracker()   # required in scripts

TypeScript — 跟踪

import { Opik } from "opik";
const client = new Opik({ projectName: "my-project" });

const trace = client.trace({ name: "agent", input: { query } });
const span = trace.span({ name: "llm-call", type: "llm" });
span.end({ output });
trace.end({ output });
await client.flush();

框架集成

优先使用集成，而不是手动使用 @opik.track——集成会自动采集 token、模型和成本。模式（完整列表见 references/integrations.md）：

• 包装客户端 — track_openai(OpenAI())、track_anthropic(...)
• 全局启用 — track_crewai(crew=crew)
• 回调 — dspy.configure(callbacks=[OpikCallback()])
• 跟踪器 — 用于 LangChain / LangGraph / LlamaIndex 的 OpikTracer()
• 特定 Agent — track_adk_agent_recursive(agent, OpikTracer())

@opik.track 中的 LiteLLM（常见陷阱）

如果代码使用 litellm，并且你添加了 @opik.track，请在每次 completion 调用中通过 metadata 传递 current_span_data——否则 OpikLogger 会发出孤立的顶层跟踪记录，而不会嵌套在你的跨度下。

from opik.opik_context import get_current_span_data

@opik.track
def call_llm(messages):
    return litellm.completion(
        model="gpt-4o", messages=messages,
        metadata={"opik": {"current_span_data": get_current_span_data()}},
    )

线程（对话）

使用 thread_id 对轮次分组——一个轮次 = 一条跟踪记录，共享 thread_id = 一个线程。用于聊天 / 多轮对话；单次调用则无需使用。

@opik.track(entrypoint=True)
def handle(session_id: str, message: str) -> str:
    opik.update_current_trace(thread_id=session_id)
    return reply(message)

提示词库

使用 client.get_prompt / create_prompt 为提示词创建版本（聊天变体： get_chat_prompt / create_chat_prompt）。将模型和 temperature 存储在提示词的 metadata 中，使其随文本一起进行版本管理。在 @opik.track 函数内部调用 get_prompt，这样该版本就会关联到跟踪记录。

@opik.track(entrypoint=True)
def run(question: str) -> str:
    p = client.get_prompt(name="system") or client.create_prompt(
        name="system",
        prompt="You help with {{product}}.",
        metadata={"model": "gpt-4o", "temperature": 0.7},
    )
    return llm(p.format(product="Opik"), model=p.metadata["model"])

项目运行状况

连接 MCP 后，请从项目开始，而不是从其跟踪记录开始：

read("project", "<project name or id>")

一次调用会返回最近 7 天与之前 7 天的数据对比——跟踪记录数量、错误率、平均时长、总成本，仅包含 SDK 流量；这正是 Logs 页面上四张卡片显示的内容——此外还会返回项目实际记录的评分名称和用量键，以及该项目中最新的实验、数据集、提示词版本和优化运行记录。since/until 可选择其他时间范围；UI 打开时使用的是 since="30d"。如果某个时间范围内没有跟踪记录，速率或平均值会返回 null，而不是 0，因为没有样本时速率未定义，而且“错误率为 0%”可能会被人当作建议并据此采取行动。

接下来分析变化的原因，而不是简单复述变化：

list("project_metric", project_name="<project>", metric_type="trace_cost")
list("project_metric", project_name="<project>", metric_type="span_count",
     breakdown="model", since="30d")

行表示时间分桶，而不是记录——interval 可取 hourly/daily/weekly/total，且不适用 page/size/sort。schema("list.project_metric") 会列出指标、各指标的含义，以及各指标接受哪些分组方式；其中七个指标不接受任何分组。概览返回的评分名称是值得筛选的名称，而 list("score_name", project_name=…) 可获取其余名称。

搜索跟踪记录

一种筛选语法 OQL 同时适用于托管 MCP 的 list 工具，以及 SDK 的 search_traces / search_spans / search_threads：

<field>[.<key>] <op> <value> [AND ...]
ops: = != > >= < <= contains not_contains starts_with ends_with is_empty is_not_empty in not_in

字符串使用双引号，数字不加引号，duration 的单位为毫秒，日期使用带时区的 ISO-8601 时间点（"2026-09-08T10:00:00Z"）。分数和字典使用键：feedback_scores.accuracy < 0.5、 metadata.environment = "prod"。唯一的连接符是 AND。

error_info is_not_empty AND duration > 5000
type = "llm" AND usage.total_tokens > 10000            # spans
feedback_scores.hallucination > 0.5 AND start_time >= "2026-09-08T00:00:00Z"

连接 MCP 后，建议使用 list — 它还支持排序（sort="duration desc"）、 时间范围（since="1h"、"7d"）和全文搜索（search="order-42"）：

list(entity_type="trace", project_name="<project>", since="1h",
     filters="error_info is_not_empty", sort="duration desc")

跟踪记录、跨度和线程列表默认添加 source = "sdk"，除非你指定了 source，因此评估器、游乐场和实验跟踪记录不会干扰视线。筛选条件被拒绝时，响应会说明如何修正；schema("list.trace")（或 list.span、 list.thread、list.experiment）提供完整的字段和运算符参考。

不使用 MCP 时，将同一字符串传给 SDK：

client.search_traces(project_name="<project>", filter_string="error_info is_not_empty")

反模式

反模式	修正方法
跨度类型为 retrieval / 自定义类型	使用 tool（或 general）
在 @opik.track 外调用 get_prompt	在内部获取 — 否则没有跟踪记录链接
已弃用的 opik.Prompt / opik.Config	使用 client.get_prompt / 配置文件
litellm 未使用 current_span_data	传入它 — 否则会产生孤立的跟踪记录
脚本中未执行 flush	opik.flush_tracker() / await client.flush()

参考资料

主题	文件
Python SDK（异步、分布式、上下文）	references/tracing-python.md
TypeScript SDK	references/tracing-typescript.md
REST API	references/tracing-rest-api.md
所有集成	references/integrations.md
核心概念（跟踪记录、跨度、线程）	references/observability.md
最佳实践（生命周期、监控、反模式）	references/best-practices.md
Agent 架构、可靠性、安全性	references/agent-patterns.md
生产监控、告警、防护机制	references/production.md
评估数据集和测试套件（参考资料）	references/evaluation-datasets.md、references/evaluation-test-suites.md

要构建并运行评估，请使用 opik-evaluate skill。要对仓库进行插桩和配置，请使用 opik-instrument skill。