企业官网建设流程全解析

Opik Python SDK REST API 指南：通过rest_client直接调用平台底层接口

【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm

本篇指南讲解 Opik Python SDK 的 REST API 客户端能力：如何通过opik.Opik()实例上的rest_client属性，直接调用 Opik 平台的全部底层 HTTP 接口，完成高级过滤查询、批量操作、自定义集成等高层 SDK 未覆盖的操作。读完本文，你将掌握rest_client的获取方式、Traces/Datasets/Experiments 三大高频场景的调用模式、分页响应结构与异常处理策略，并能结合源码理解其与高层 SDK 的关系及兼容性边界。

什么是rest_client

Opik 的高层 Python SDK 封装了大多数日常操作（打点追踪、数据集管理、实验评估等），但它并不是平台能力的全集。为此，SDK 在客户端对象上暴露了一个rest_client属性，直接指向底层 REST API 客户端，让进阶用户可以在需要时绕过高层封装，直接发起 API 调用，从而获得 Opik 平台全部功能的访问权限。

在源码中，该属性的定义位于 opik_client.py，其返回类型为rest_api_client.OpikApi，即 Fern 根据 Opik 的 API 定义自动生成的客户端类（定义于 rest_api/client.py）。

[!WARNING]兼容性警告：REST 客户端不保证与未来 SDK 版本向后兼容。它提供了一种便捷方式使用 Opik 当前的 REST API，但由于 Opik 的 REST API 契约可能发生变化，不建议重度依赖其接口。如果你的代码直接调用rest_client，在升级 SDK 后需要重新验证相关调用。

何时使用 REST API

根据官方文档（overview.rst），当你遇到以下场景时，REST API 客户端尤其有用：

• 执行高层 SDK 未提供的操作：例如批量删除、按环境管理、直接读取原始返回值等；
• 构建自定义集成或工具：将 Opik 能力嵌入自己的脚本、CLI 或平台；
• 使用高级过滤与查询能力：REST API 暴露了完整的过滤算子，可组合出复杂查询条件；
• 实现批量操作以提升性能：例如批量写入数据集条目、批量删除 Traces；
• 处理特定用例所需的原始 API 响应：高层 SDK 通常会做类型转换与封装，REST 客户端可以拿到更贴近接口的原始结构。

此外，从源码看，Opik 高层 SDK 自身的许多功能也正是通过rest_client实现的——例如 opik_client.py 中批量删除 Traces 使用self._rest_client.traces.delete_traces(ids=batch)，环境管理使用self._rest_client.environments.*系列方法，数据集查询也经由self._rest_client.datasets.get_dataset_by_identifier(...)（见 opik_client.py）。这意味着你直接使用rest_client时，实际上是在与高层 SDK 同一层的接口交互。

快速开始：获取 REST 客户端

使用方式非常直接：先创建一个opik.Opik()实例，再通过rest_client属性访问底层客户端：

import opik # 初始化 Opik 客户端 client = opik.Opik() # 通过 rest_client 属性访问 REST API rest_client = client.rest_client

opik.Opik()在初始化时会根据环境配置（如OPIK_API_KEY、OPIK_BASE_URL、OPIK_WORKSPACE等）自动构建底层的OpikApi实例。你也可以直接实例化OpikApi并显式传参（详见下文"构造参数与高级配置"一节）。

客户端结构全览

OpikApi客户端以"子客户端"的形式组织接口，每个子客户端对应一类平台资源。从 rest_api/client.py 的初始化代码可见，当前版本包含（部分列举）：

每个子客户端（如TracesClient）还提供一个with_raw_response属性，返回对应的原始响应客户端（RawTracesClient），用于需要直接获取 HTTP 响应头、原始状态码等场景；顶级OpikApi同样提供with_raw_response（返回RawOpikApi），以及is_alive()与version()两个全局方法，可用于健康检查与版本探测（见 client.py）。

完整的客户端目录结构参见 rest_api/client.py 及其同级目录；各模块的详细 API 文档见 rest_api/clients 目录。

实战示例：操作 Traces

按 ID 获取单条 Trace

# 获取指定 trace trace = client.rest_client.traces.get_trace_by_id("trace-id")

带过滤器搜索 Traces

# 使用过滤器搜索 traces traces = client.rest_client.traces.search_traces( project_name="my-project", filters=[{ "field": "name", "operator": "contains", "value": "important" }], max_results=100 )

filters列表中的每个过滤条件由field（字段名）、operator（算子）与value（取值）三元组构成。算子方面，search_traces的底层实现支持contains、equals、not_equals、starts_with、ends_with、greater_than、less_than等，具体算子集合以 traces 客户端文档 与后端过滤实现为准。project_name用于限定项目范围，max_results控制返回上限。

除上述两个方法外，TracesClient还提供delete_traces（批量删除）、add_trace_comment、update_trace、get_trace_feedback_scores等能力，完整方法清单见 traces/client.py。

实战示例：管理 Datasets

分页列出数据集

# 列出所有数据集 datasets = client.rest_client.datasets.find_datasets( page=0, size=20 )

创建数据集

# 创建新数据集 dataset = client.rest_client.datasets.create_dataset( name="my-dataset", description="A test dataset" )

批量写入数据集条目

# 向数据集添加条目 items = [ { "input": {"question": "What is AI?"}, "expected_output": {"answer": "Artificial Intelligence"} } ] client.rest_client.datasets.create_or_update_dataset_items( dataset_id=dataset.id, items=items )

值得注意，create_or_update_dataset_items采用 upsert 语义：条目中的id若已存在则更新，否则创建。另外，DatasetsClient还提供create_dataset_items_from_csv与create_dataset_items_from_json（见 datasets/client.py），可以直接从文件导入条目，适合大批量数据灌入场景。

实战示例：运行 Experiments

创建实验

# 创建实验 experiment = client.rest_client.experiments.create_experiment( name="my-experiment", dataset_name="my-dataset" )

写入实验结果

# 添加实验结果 client.rest_client.experiments.create_experiment_items( experiment_id=experiment.id, items=[{ "dataset_item_id": "item-id", "trace_id": "trace-id", "output": {"result": "success"} }] )

实验条目通过dataset_item_id关联数据集中的样本，通过trace_id关联实际运行产生的 Trace，output记录模型的输出结果，供后续评估与对比分析使用。

响应类型与分页

大多数列表操作返回分页结果，且结构保持一致。以find_datasets为例：

# 分页响应结构示例 response = client.rest_client.datasets.find_datasets(page=0, size=10) # 访问数据 datasets = response.content # 数据集对象列表 total_count = response.total # 条目总数 current_page = response.page # 当前页码 page_size = response.size # 每页条目数

分页字段语义：

• content：当前页的数据对象列表，遍历它即可处理本页结果；
• total：满足条件的条目总数，用于计算总页数或展示统计；
• page：当前页码（从 0 开始）；
• size：每页条目数，即请求时传入的size参数。

分页遍历的通用写法如下：

page, size = 0, 50 while True: response = client.rest_client.datasets.find_datasets(page=page, size=size) for item in response.content: process(item) if page * size + len(response.content) >= response.total: break page += 1

需要注意，分页字段的确切命名（page、size、total、content）以各接口返回类型为准，个别接口可能使用不同字段名；上文为官方文档明确给出的通用结构。

错误处理

REST 客户端在请求失败时会抛出特定异常，基类为ApiError。官方文档给出的统一捕获方式如下：

from opik.rest_api.core.api_error import ApiError try: trace = client.rest_client.traces.get_trace_by_id("invalid-id") except ApiError as e: if e.status_code == 404: print("Trace not found") else: print(f"API error: {e.status_code} - {e.body}")

ApiError的关键属性：

• status_code：HTTP 状态码，可用于判断错误类型（404 表示资源不存在，401 表示未授权，429 表示限流等）；
• body：服务端返回的错误响应体，通常包含更详细的错误信息。

除通用ApiError外，rest_api/errors 模块 还按 HTTP 语义细分了多种具体异常类型，可直接按需捕获：

例如，只关心"资源不存在"时可以精确捕获NotFoundError，而无需判断status_code。

构造参数与高级配置

虽然通常通过opik.Opik().rest_client间接使用，但OpikApi也可直接实例化，并支持以下构造参数（见 rest_api/client.py）：

from opik.rest_api import OpikApi client = OpikApi( api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME", timeout=30.0, )

异步版本

对于需要高并发的场景，rest_api/client.py 还提供了AsyncOpikApi，其子客户端全部为异步实现（如AsyncTracesClient），与httpx.AsyncClient配合使用：

from opik.rest_api import AsyncOpikApi import asyncio async def main(): client = AsyncOpikApi(api_key="YOUR_API_KEY", workspace_name="YOUR_WORKSPACE_NAME") await client.traces.get_trace_by_id("trace-id") await client.is_alive() asyncio.run(main())

下一步学习

• 查看 REST API 客户端参考，获取各资源模块（traces、datasets、experiments、projects、prompts 等）的详细方法文档；
• 查看 数据类型文档，了解各接口返回的数据对象结构；
• 阅读主 SDK 文档，了解更高层的封装操作，大多数场景仍应优先使用高层 API，仅在需要原始能力时再下沉到rest_client；
• 需要深入了解实现时，可直接阅读 rest_api/client.py 及各子客户端源码，或参考 overview.rst 原文。

【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm